@m4l-jweb/surface 1.3.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/surface",
-  "version": "1.3.0",
+  "version": "1.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",
@@ -15,6 +15,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./store": "./src/store.ts",
+    "./pads": "./src/pads.ts",
     "./react": "./src/react.tsx",
     "./dev": "./src/dev.tsx"
   },
@@ -24,7 +25,7 @@
   ],
   "peerDependencies": {
     "react": ">=18",
-    "@m4l-jweb/bridge": "1.3.0"
+    "@m4l-jweb/bridge": "1.6.0"
   },
   "peerDependenciesMeta": {
     "react": {

package/src/controls.ts

@@ -0,0 +1,495 @@
+/**
+ * controls.ts - declare what a device claims on the CONTROL SURFACE, once, as code.
+ *
+ * The fourth sibling of `defineSurface`, `defineWatch` and `defineFiles`, and the
+ * one that reaches the sixty-four pads. `defineSurface` already gives a device the
+ * eight Push encoders - declare a parameter and it is on the hardware, labelled,
+ * banked, automatable. It gives you nothing on the grid, and this closes that:
+ *
+ *   grid.draw()   a frame buffer you paint
+ *   grid.onPad()  an event stream you handle
+ *
+ * ------------------------------------------------------------------------------
+ * WHAT THE HARDWARE ACTUALLY DOES, because five of these contradict the obvious
+ * guess and every one of them fails silently. All measured on a Push 3 with the
+ * `push-probe` device; the evidence is doc/MAX-FACTS.md, "Grabbing a Push control".
+ *
+ *  1. A control is grabbed BY NAME. A bare LOM id is rejected; the two-atom
+ *     `id <n>` works and buys nothing over the name. The id is wanted for exactly
+ *     one thing - building the observer.
+ *  2. A REJECTED CALL REPORTS NOTHING. `LiveAPI.call` does not throw when Live
+ *     refuses it: it posts a console line and returns normally. There is no success
+ *     to branch on, so nothing here can verify its own grab. `controls_role` reports
+ *     the one failure that IS visible - a role this hardware does not have.
+ *  3. Y COUNTS FROM THE TOP on the wire and from the BOTTOM in this API, and the
+ *     flip lives in ONE place (`usePadGrid`). Get it wrong anywhere else and every
+ *     device on the grid is mirrored, with nothing to report it.
+ *  4. THE FIRST FRAME AFTER A GRAB IS LOST. Live's own surface script repaints the
+ *     matrix just after handing it over, so the wrapper defers its first paint and
+ *     treats the hardware as unknown until then.
+ *  5. ROLES RESOLVE AT RUNTIME. A Push 3 answers `get_control_names` with 176 names
+ *     and they are not the Push 2 set, so the role table below is CANDIDATES, tried
+ *     in order against that answer. A candidate that is not on the connected
+ *     hardware is never called - which is what turns rule 2's silence into a
+ *     reportable `controls_role <key> 0`.
+ *  6. THE ENCODERS ARE GRABBABLE, and grabbing one takes it: with `Track_Controls`
+ *     held, the dials stop moving their parameters entirely. That costs automation,
+ *     MIDI mapping and the automation lane - everything the parameter path exists
+ *     for - so those roles are REFUSED here, at declaration time.
+ *  7. CLAIMING THE MATRIX TAKES THE PADS OFF THE NOTE PATH. No MIDI notes and no
+ *     MPE while `Button_Matrix` is held, even on a device that declares `mpe`.
+ *     Claiming a non-matrix control (the scene column, the jog wheel) costs nothing
+ *     on the note path, which is why a mixed declaration is allowed rather than
+ *     refused.
+ *  8. A CONTROL IS NOT ALWAYS A GRID OR A BUTTON. A jog wheel is a STREAM, so there
+ *     is a third shape here rather than a fourth one bolted on later.
+ * ------------------------------------------------------------------------------
+ *
+ * Like its three siblings the checks run HERE, at call time, and throw - the build
+ * imports this declaration to emit the chain and the wrapper's spec, so a bad
+ * declaration fails `pnpm build` and CI rather than the hardware going quiet.
+ */
+
+/* ------------------------------------------------------------------ *
+ * The roles, and the names they resolve to
+ * ------------------------------------------------------------------ */
+
+/**
+ * The role vocabulary. A device names a ROLE, never a Max name: the name is a
+ * per-generation fact the library owns, and CLAUDE.md's first hard rule is that a
+ * name Max looks up and does not recognise is not an error - it is a feature that
+ * silently does nothing.
+ */
+export type ControlRole =
+  // Grids
+  | "matrix"
+  | "scene_launch"
+  | "track_state"
+  // Buttons
+  | "shift"
+  | "select"
+  | "delete"
+  | "duplicate"
+  | "new"
+  | "undo"
+  | "capture"
+  | "record"
+  | "play"
+  | "loop"
+  | "left"
+  | "right"
+  | "up"
+  | "down"
+  | "octave_up"
+  | "octave_down"
+  | "layout"
+  | "note_mode"
+  | "session_mode"
+  // Streams
+  | "jogwheel"
+  | "touch_strip";
+
+/**
+ * Role -> the control names to TRY, in order, on whatever is plugged in.
+ *
+ * Two sources, and neither is complete: the 176 names a Push 3 returned from
+ * `get_control_names`, and the names a shipping third-party takeover device
+ * addresses (a Push 2-era set - several of them do not exist on a Push 3, which has
+ * `Left_Arrow`/`Right_Arrow` and `Layout` where the older set has `Left_Button`,
+ * `Right_Button` and `Layout_Button`). Both are in doc/MAX-FACTS.md.
+ *
+ * A candidate is only ever used if it appears in the connected hardware's own
+ * `get_control_names` answer, so a wrong guess here costs a `controls_role <key> 0`
+ * and not a silent no-op. That is the whole reason resolution is a runtime list
+ * rather than a compile-time name.
+ */
+export const ROLE_NAMES: Record<ControlRole, readonly string[]> = {
+  matrix: ["Button_Matrix"],
+  scene_launch: ["Scene_Launch_Buttons"],
+  track_state: ["Track_State_Buttons"],
+  shift: ["Shift_Button"],
+  select: ["Select_Button"],
+  delete: ["Delete_Button"],
+  duplicate: ["Duplicate_Button"],
+  new: ["New_Button"],
+  undo: ["Undo_Button"],
+  capture: ["Capture_Button"],
+  record: ["Record_Button"],
+  play: ["Play_Button"],
+  loop: ["Loop_Button"],
+  left: ["Left_Arrow", "Left_Button"],
+  right: ["Right_Arrow", "Right_Button"],
+  up: ["Up_Arrow", "Up_Button"],
+  down: ["Down_Arrow", "Down_Button"],
+  octave_up: ["Octave_Up_Button"],
+  octave_down: ["Octave_Down_Button"],
+  layout: ["Layout", "Layout_Button"],
+  note_mode: ["Note_Mode_Button"],
+  session_mode: ["Session_Mode_Button"],
+  jogwheel: ["Jogwheel"],
+  touch_strip: ["Touch_Strip_Control"],
+};
+
+/**
+ * The roles a declaration may NOT claim, and why - the message is what the author
+ * reads, so it says what grabbing one costs rather than "not allowed".
+ *
+ * They are perfectly grabbable. That is the problem: measured, with two dials
+ * declared so Push had something to map, the encoders moved their parameters
+ * normally and stopped dead the moment `Track_Controls` was grabbed.
+ */
+export const REFUSED_ROLES: Record<string, string> = {
+  Track_Controls:
+    "the eight encoders are grabbable, and grabbing them TAKES them: the dials stop moving their parameters, " +
+    "which costs automation, MIDI mapping and the automation lane. Declare the values as parameters in surface.ts instead.",
+  Global_Param_Controls: "same as Track_Controls - an encoder belongs to the parameter path, not to a takeover.",
+};
+
+/** Which roles are grids, and the dimensions each one is. */
+const GRID_SHAPE: Partial<Record<ControlRole, { rows: number; cols: number }>> = {
+  // The only one measured: 8x8, y from the top, one control and one id - not 64.
+  matrix: { rows: 8, cols: 8 },
+  // UNMEASURED SHAPES. Both resolve on a Push 3 and both are grabbable (the scene
+  // column was grabbed and released during the spike, and the MPE stream survived
+  // it), but what their `value` carries and what `send_value` wants have not been
+  // read off the hardware. Declaring one is allowed and reports its resolution;
+  // trusting its payload without looking is not.
+  scene_launch: { rows: 8, cols: 1 },
+  track_state: { rows: 1, cols: 8 },
+};
+
+/** The roles that are a single button. */
+const BUTTON_ROLES: ControlRole[] = [
+  "shift",
+  "select",
+  "delete",
+  "duplicate",
+  "new",
+  "undo",
+  "capture",
+  "record",
+  "play",
+  "loop",
+  "left",
+  "right",
+  "up",
+  "down",
+  "octave_up",
+  "octave_down",
+  "layout",
+  "note_mode",
+  "session_mode",
+];
+
+/** The roles that are a continuous stream rather than a gate. */
+const STREAM_ROLES: ControlRole[] = ["jogwheel", "touch_strip"];
+
+/* ------------------------------------------------------------------ *
+ * The control kinds
+ * ------------------------------------------------------------------ */
+
+/**
+ * What every control kind carries.
+ *
+ * `names` is FILLED IN BY `defineControls()`, from ROLE_NAMES above - it is not
+ * something a device writes. The build reads the declaration as plain data (it
+ * cannot call back into this module: `packages/build` is .mjs and this is the
+ * bundled TypeScript it imported), so the candidate list has to travel ON the
+ * declaration rather than be looked up again on the other side. Two lookups of one
+ * table is exactly how a role table drifts.
+ */
+export interface ControlBase {
+  role: ControlRole;
+  /** The control names to try, in order. Written by defineControls; do not set it. */
+  names?: readonly string[];
+}
+
+/** A rectangle of pads you paint and read. */
+export interface GridControlSpec extends ControlBase {
+  kind: "grid";
+  rows: number;
+  cols: number;
+}
+
+/** One button: a boolean, live. The degenerate case of a grid. */
+export interface ButtonControlSpec extends ControlBase {
+  kind: "button";
+}
+
+/**
+ * A continuous control - the jog wheel, the touch strip.
+ *
+ * NOTHING HERE IS MEASURED YET. Whether either emits a usable stream under a grab,
+ * and whether the jog wheel reports a DELTA or an absolute position, is doc/TODO.md
+ * doc/TODO.md - one button press in `push-probe`, and it gates the DJ surface in
+ * PUSH-USECASES.md. The shape exists so that answering the question does not force
+ * an API change; it does not claim the answer.
+ */
+export interface StreamControlSpec extends ControlBase {
+  kind: "stream";
+}
+
+export type ControlSpec = GridControlSpec | ButtonControlSpec | StreamControlSpec;
+
+/**
+ * A rectangle of pads. `rows` and `cols` are stated by the caller and checked
+ * against the role, rather than defaulted from it: a device that writes
+ * `rows: 8, cols: 8` is a device whose layout code you can read without knowing the
+ * role table.
+ */
+export const grid = (spec: { role: ControlRole; rows: number; cols: number }): GridControlSpec => ({ kind: "grid", ...spec });
+
+/**
+ * One button.
+ *
+ * NOT `button()` - that name already belongs to `defineSurface`'s `live.text`
+ * parameter, and a device declaring both would import two different things called
+ * the same word. PUSH-USECASES.md writes `button({ role: "shift" })`; this is that,
+ * renamed for the collision.
+ */
+export const padButton = (spec: { role: ControlRole }): ButtonControlSpec => ({ kind: "button", ...spec });
+
+/** One continuous control. See StreamControlSpec - the hardware question is open. */
+export const padStream = (spec: { role: ControlRole }): StreamControlSpec => ({ kind: "stream", ...spec });
+
+/* ------------------------------------------------------------------ *
+ * The palette
+ * ------------------------------------------------------------------ */
+
+/**
+ * The 128 pad colours, as Live itself holds them.
+ *
+ * READ OUT OF LIVE, not off a photograph. Live 12 drives Push from
+ * `Program/Push/python/Push2/colors.pyc`, whose `COLOR_TABLE` is 128 entries and whose
+ * `push_color_index_to_pad_rgb(i)` returns `COLOR_TABLE[i]` split into bytes. These are
+ * those values: `PUSH_PAD_RGB[i]` is `0xRRGGBB` for palette index `i`, so what a device
+ * draws on screen and what the pad shows come from one number.
+ *
+ * It agrees with the hardware. Painting a known pattern on a Push 3 and photographing it
+ * matched this table across the greys, the pastels and the primaries, and it explains the
+ * two errors the photographs had made - see doc/MAX-FACTS.md, "Live holds the pad palette,
+ * and the photographs were a page upside down".
+ *
+ * The greys and the pure primaries are at the END: 118 grey, 119 near-black, 120 white,
+ * 122 light grey, 123 dark grey, 125 blue, 126 green, 127 red. Indices 65 to 117 are the
+ * dim and shaded variants, which is why so much of that range photographs as mud.
+ */
+export const PUSH_PAD_RGB: readonly number[] = [
+  0x000000, 0xff4032, 0x800400, 0xc93c00, 0xac1f00, 0x8c5018, 0x491804, 0xfadc3b, // 0-7
+  0xffc516, 0xb6ff0e, 0x79ff18, 0x34c216, 0x4f8a04, 0x62ff55, 0x297d53, 0x269e72, // 8-15
+  0x31adff, 0x3663fc, 0x1a34ff, 0x1c0ce6, 0x153999, 0x3937ff, 0x5722ff, 0x972bff, // 16-23
+  0x852178, 0xff1032, 0xff2bd4, 0xa63421, 0x995628, 0x876700, 0x90821f, 0x4a8700, // 24-31
+  0x007f12, 0x1853b2, 0x624bad, 0x733a67, 0xf8bcaf, 0xff9b76, 0xffbf5f, 0xd9af71, // 32-39
+  0xfff480, 0xbfba69, 0xbccc88, 0xaeff99, 0x7cdd9f, 0x89b47d, 0x80f3ff, 0x7acefc, // 40-47
+  0x68a1d3, 0x858fc2, 0xbbaaf2, 0xcdbbe4, 0xef8bb0, 0x859d8c, 0x6b756e, 0x84909b, // 48-55
+  0x6a7075, 0x88859d, 0x6c6a75, 0x9d859c, 0x746a74, 0x9c9d85, 0x74756a, 0x9d8484, // 56-63
+  0x756a6a, 0x661914, 0x210806, 0x460300, 0x280000, 0x5d1700, 0x200d00, 0x470c00, // 64-71
+  0x1c0800, 0x3b2b14, 0x1c130a, 0x250e05, 0x0d0602, 0x645817, 0x201c07, 0x664e08, // 72-79
+  0x211902, 0x486605, 0x172101, 0x306609, 0x0f2103, 0x144d08, 0x061902, 0x1f3701, // 80-87
+  0x0a1100, 0x276622, 0x0c210b, 0x143e29, 0x081910, 0x004d36, 0x00180e, 0x134566, // 88-95
+  0x061621, 0x152764, 0x070c20, 0x0a1466, 0x030621, 0x0b045c, 0x03011d, 0x0a1c4c, // 96-103
+  0x040b1e, 0x161666, 0x070721, 0x220d66, 0x0b0421, 0x3c1166, 0x130521, 0x350d30, // 104-111
+  0x11040f, 0x660614, 0x210206, 0x661154, 0x21051b, 0x000000, 0x595959, 0x1a1a1a, // 112-119
+  0xffffff, 0x595959, 0xcccccc, 0x404040, 0x141414, 0x0000ff, 0x00ff00, 0xff0000, // 120-127
+];
+
+/** `0xRRGGBB` as a CSS colour, so a screen can mirror a pad exactly. */
+export function rgbCss(value: number): string {
+  return `rgb(${(value >> 16) & 255}, ${(value >> 8) & 255}, ${value & 255})`;
+}
+
+/**
+ * Colour NAMES, resolved to hardware palette indices by the library.
+ *
+ * A device that writes `36` is a device nobody can read. Every index below was chosen
+ * because `PUSH_PAD_RGB` says it IS that colour, so the name and the light agree.
+ *
+ * These are a legible subset, not the whole palette. A device that wants an index the
+ * names do not cover reads `PUSH_PAD_RGB` and picks one.
+ */
+export const PUSH_PALETTE = {
+  black: 0,
+  /** 0xff0000. The pure primaries live at the top of the table. */
+  red: 127,
+  orange: 3,
+  amber: 8,
+  yellow: 7,
+  lime: 9,
+  green: 11,
+  spring: 13,
+  turquoise: 15,
+  mint: 44,
+  sky: 16,
+  cyan: 46,
+  ocean: 33,
+  blue: 18,
+  violet: 22,
+  purple: 23,
+  magenta: 26,
+  rose: 25,
+  pink: 52,
+  peach: 36,
+  tan: 39,
+  gold: 38,
+  pale_blue: 47,
+  pale_pink: 51,
+  /** The greys, which the photographs never found. */
+  grey: 118,
+  dark_grey: 123,
+  light_grey: 122,
+  white: 120,
+} as const;
+
+/** A colour a device may name. */
+export type PadColour = keyof typeof PUSH_PALETTE;
+
+/**
+ * What each name looks like on a screen mirroring the hardware.
+ *
+ * DERIVED, never typed by hand: one table, so a name cannot drift from its light.
+ */
+export const PALETTE_CSS: Record<PadColour, string> = Object.fromEntries(
+  (Object.keys(PUSH_PALETTE) as PadColour[]).map((name) => [name, rgbCss(PUSH_PAD_RGB[PUSH_PALETTE[name]]!)]),
+) as Record<PadColour, string>;
+
+/** The index the hardware wants for a named colour. An unknown name is OFF, not a guess. */
+export function paletteIndex(colour: string): number {
+  const i = (PUSH_PALETTE as Record<string, number>)[colour];
+  return typeof i === "number" ? i : 0;
+}
+
+/** ...and back, for a screen mirroring the hardware. Any of the 128, named or not. */
+export function cssForPaletteIndex(index: number): string {
+  const rgb = PUSH_PAD_RGB[index];
+  return rgb === undefined ? rgbCss(0) : rgbCss(rgb);
+}
+
+
+/* ------------------------------------------------------------------ *
+ * The declaration
+ * ------------------------------------------------------------------ */
+
+/** When an enabled device actually HOLDS the controls it declared. */
+export type FocusPolicy = "Device" | "Track" | "Always";
+
+export const FOCUS_OPTIONS: readonly FocusPolicy[] = ["Device", "Track", "Always"];
+
+export interface ControlsDef<C extends Record<string, ControlSpec>> {
+  /** Which hardware family the roles are resolved against. */
+  surface: "push";
+  controls: C;
+  /**
+   * What `focus` starts at. `Track` is the default because two of these devices in
+   * one set is the normal case, not the edge: `Always` means the last one loaded
+   * wins the grid forever, which reads as the first one being broken.
+   */
+  defaultFocus?: FocusPolicy;
+}
+
+export interface Controls<C extends Record<string, ControlSpec> = Record<string, ControlSpec>> extends ControlsDef<C> {
+  /**
+   * Declaration order - the order the build emits CONTROLS_SPEC and the chain wires
+   * observers.
+   *
+   * Deliberately `string[]` and not `Extract<keyof C, string>[]`. Naming the keys
+   * here would make `Controls<C>` INVARIANT in C, and a `Controls<{ pads: ... }>`
+   * would then not be assignable to the `Controls` a surface declares - which reads,
+   * at the call site, as "property 'pads' is missing in Record<string, ControlSpec>".
+   * The precise key union is where it is useful anyway: on `usePadGrid`, which takes
+   * it from `keyof C` directly.
+   */
+  readonly keys: readonly string[];
+  readonly defaultFocus: FocusPolicy;
+}
+
+/**
+ * The parameter ids `defineControls` contributes to a device's Surface.
+ *
+ * They are REAL Live parameters, so the user can switch takeover off, automate it,
+ * put it on an encoder and see it in the device view. `takeover` defaults OFF: a
+ * device that seizes the pads of every set it lands in is a device people uninstall.
+ */
+export const TAKEOVER_PARAM = "takeover";
+export const FOCUS_PARAM = "focus";
+
+/**
+ * Declare what this device claims on the control surface.
+ *
+ * ```ts
+ * export default defineControls({
+ *   surface: "push",
+ *   controls: { pads: grid({ role: "matrix", rows: 8, cols: 8 }) },
+ * });
+ * ```
+ */
+export function defineControls<const C extends Record<string, ControlSpec>>(def: ControlsDef<C>): Controls<C> {
+  if (def.surface !== "push") {
+    throw new Error(`controls: surface "${def.surface}" is not a family this library resolves roles for (push)`);
+  }
+  const keys = Object.keys(def.controls) as Extract<keyof C, string>[];
+  if (!keys.length) throw new Error(`controls: declare at least one control - a device that claims nothing should not declare controls at all`);
+
+  const claimed = new Map<ControlRole, string>();
+  for (const key of keys) {
+    // The key becomes the selector `pad_<key>`, and Max splits a message on
+    // whitespace: a key with a space in it would arrive as two atoms and dispatch to
+    // a handler nobody wrote.
+    if (/\s/.test(key)) throw new Error(`controls: key "${key}" has whitespace - it becomes the selector pad_${key}, which Max would split`);
+    const spec = def.controls[key];
+    const role = spec.role as ControlRole;
+
+    if (!(role in ROLE_NAMES)) {
+      throw new Error(`controls: "${key}" claims role "${role}", which is not in the vocabulary (${Object.keys(ROLE_NAMES).join(", ")})`);
+    }
+    for (const name of ROLE_NAMES[role]) {
+      if (REFUSED_ROLES[name]) throw new Error(`controls: "${key}" claims "${role}", which this library refuses - ${REFUSED_ROLES[name]}`);
+    }
+    const already = claimed.get(role);
+    if (already) throw new Error(`controls: "${key}" and "${already}" both claim role "${role}" - one control cannot be grabbed twice`);
+    claimed.set(role, key);
+
+    if (spec.kind === "grid") {
+      const shape = GRID_SHAPE[role];
+      if (!shape) {
+        throw new Error(`controls: "${key}" declares role "${role}" as a grid, but that role is not a grid (it is a ${describeRole(role)})`);
+      }
+      if (spec.rows !== shape.rows || spec.cols !== shape.cols) {
+        throw new Error(
+          `controls: "${key}" declares role "${role}" as ${spec.rows}x${spec.cols}; on this hardware it is ${shape.rows}x${shape.cols}`,
+        );
+      }
+    }
+    if (spec.kind === "button" && !BUTTON_ROLES.includes(role)) {
+      throw new Error(`controls: "${key}" declares role "${role}" as a button, but that role is a ${describeRole(role)}`);
+    }
+    if (spec.kind === "stream" && !STREAM_ROLES.includes(role)) {
+      throw new Error(`controls: "${key}" declares role "${role}" as a stream, but that role is a ${describeRole(role)}`);
+    }
+  }
+
+  // Stamp the candidate names onto each control, so the build reads one table
+  // rather than reimplementing it. See ControlBase.
+  const resolved = {} as C;
+  for (const key of keys) {
+    const spec = def.controls[key];
+    (resolved as Record<string, ControlSpec>)[key] = { ...spec, names: ROLE_NAMES[spec.role as ControlRole] };
+  }
+
+  return { ...def, controls: resolved, keys, defaultFocus: def.defaultFocus ?? "Track" };
+}
+
+function describeRole(role: ControlRole): string {
+  if (GRID_SHAPE[role]) return "grid";
+  if (STREAM_ROLES.includes(role)) return "stream";
+  return "button";
+}
+
+/** How many cells one declared control carries. A button and a stream are one. */
+export function controlSize(spec: ControlSpec): number {
+  return spec.kind === "grid" ? spec.rows * spec.cols : 1;
+}
+
+/** The candidate names one declared control resolves against, in order. */
+export function controlNames(spec: ControlSpec): readonly string[] {
+  return ROLE_NAMES[spec.role as ControlRole] ?? [];
+}

package/src/dev.tsx

@@ -26,8 +26,8 @@
  * tests/bundle.test.mjs asserts HARNESS_MARKER is absent from the built ui.html.
  */
 import { useEffect, useRef, useState } from "react";
-import { simulate, tapMessages, type BridgeMessage } from "@m4l-jweb/bridge";
-import { BANK_SIZE, formatValue, type ParamSpec, type Surface } from "./index";
+import { CONTROLS_IN, CONTROLS_OUT, padSelector, simulate, tapMessages, type BridgeMessage } from "@m4l-jweb/bridge";
+import { BANK_SIZE, cssForPaletteIndex, formatValue, TAKEOVER_PARAM, type ControlSpec, type Controls, type ParamSpec, type Surface } from "./index";
 import { useSurface } from "./react";
 
 /**
@@ -113,6 +113,8 @@ export function DevHarness({ surface }: { surface?: AnySurface | null }) {
         </>
       )}
 
+      {surface?.controls && <PadMock surface={surface} controls={surface.controls} />}
+
       <section style={S.section}>
         <div style={S.row}>
           <h2 style={S.h2}>messages</h2>
@@ -198,6 +200,107 @@ function Params({ surface }: { surface: AnySurface }) {
   );
 }
 
+/**
+ * THE PADS, MOCKED - the 8x8 grid, before there is any hardware in the room.
+ *
+ * WHY IT EXISTS AT ALL, and why it was built before the first real device: without
+ * it, every iteration on a grid device is a rebuild, a reinstall, a re-drag (Live
+ * embeds a COPY of a device in the set, so instances already on tracks do not
+ * update) and a squint at sixty-four LEDs to work out whether a cell is one column
+ * off. Here it is a browser tab.
+ *
+ * It is driven by the REAL contract, in both directions, and that is the whole
+ * point of putting it on the bridge tap rather than on the store:
+ *
+ *   paint   every `controls_frame <key> <64 indices>` the app sends is rendered,
+ *           palette index by palette index, in the same hardware order the wrapper
+ *           would receive - so a y flip that is wrong shows up here as an upside-down
+ *           picture, which is exactly what it would be on the hardware.
+ *   press   a click fakes `pad_<key> <velocity> <x> <yFromTop>` inbound, the shape a
+ *           `[live.observer]` actually emits, and a release on mouse-up.
+ *
+ * THE HONEST LIMIT is the usual one: it is the message-level contract, not the
+ * hardware. It cannot tell you about pad latency, about a grab Live rejected without
+ * saying so, or about what a palette index really looks like under a camera. Keep
+ * "look at the Push" for those.
+ *
+ * `controls_held` is driven from the `takeover` parameter alone. The real answer
+ * also depends on `focus` and on what Live has selected, which a mock has no way to
+ * know - so this deliberately answers the easy half and a device should still be
+ * tried with two instances in one set.
+ */
+function PadMock({ surface, controls }: { surface: AnySurface; controls: Controls }) {
+  const [values] = useSurface(surface);
+  const keys = controls.keys as readonly string[];
+  const specs = controls.controls as Record<string, ControlSpec>;
+  const [frames, setFrames] = useState<Record<string, number[]>>({});
+
+  // Every declared role "resolves" on a mock. Sent once, so a device that renders
+  // usePadRoles() shows the same thing it would with the hardware plugged in.
+  useEffect(() => {
+    for (const key of keys) simulate(CONTROLS_IN.controls_role, key, 1);
+    // The declaration does not change at runtime.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const held = Boolean(values[TAKEOVER_PARAM]);
+  // The reason travels with it, as it does from the wrapper - the mock only ever has
+  // the two easy answers, because it cannot know what Live has selected.
+  useEffect(() => simulate(CONTROLS_IN.controls_held, held ? 1 : 0, held ? "held" : "off"), [held]);
+
+  useEffect(
+    () =>
+      tapMessages((m) => {
+        if (m.direction !== "out") return;
+        if (m.selector === CONTROLS_OUT.controls_refresh) return setFrames({});
+        if (m.selector !== CONTROLS_OUT.controls_frame) return;
+        const [key, ...cells] = m.args;
+        setFrames((prev) => ({ ...prev, [String(key)]: cells.map(Number) }));
+      }),
+    [],
+  );
+
+  return (
+    <section style={S.section}>
+      <div style={S.row}>
+        <h2 style={S.h2}>pads (mocked)</h2>
+        <span style={S.bankName}>{held ? "held" : "released"}</span>
+      </div>
+      {keys.map((key) => {
+        const spec = specs[key];
+        const rows = spec.kind === "grid" ? spec.rows : 1;
+        const cols = spec.kind === "grid" ? spec.cols : 1;
+        const cells = frames[key] ?? [];
+        return (
+          <div key={key}>
+            <div style={S.padLabel}>
+              {key} · {spec.role}
+            </div>
+            <div style={{ ...S.padGrid, gridTemplateColumns: `repeat(${cols}, 1fr)` }}>
+              {Array.from({ length: rows * cols }, (_, i) => {
+                // Row 0 is the TOP, on the wire and here - the mock renders exactly
+                // what was sent, so a device that flipped y twice looks wrong.
+                const x = i % cols;
+                const y = Math.floor(i / cols);
+                return (
+                  <button
+                    key={i}
+                    title={`x ${x} y ${rows - 1 - y}`}
+                    style={{ ...S.pad, background: cssForPaletteIndex(cells[i] ?? 0), opacity: held ? 1 : 0.35 }}
+                    onMouseDown={() => simulate(padSelector(key), 100, x, y, 1)}
+                    onMouseUp={() => simulate(padSelector(key), 0, x, y, 1)}
+                    onMouseLeave={(e) => e.buttons === 1 && simulate(padSelector(key), 0, x, y, 1)}
+                  />
+                );
+              })}
+            </div>
+          </div>
+        );
+      })}
+    </section>
+  );
+}
+
 /**
  * THE PUSH PREVIEW - what a performer will actually be looking at.
  *
@@ -308,6 +411,9 @@ const S: Record<string, React.CSSProperties> = {
   },
   bankName: { color: "#7d8694", marginLeft: "auto" },
   push: { display: "grid", gridTemplateColumns: "repeat(4, 1fr)", gap: 2 },
+  padLabel: { color: "#7d8694", margin: "4px 0 3px" },
+  padGrid: { display: "grid", gap: 3 },
+  pad: { aspectRatio: "1", border: "1px solid #262a31", borderRadius: 3, padding: 0, cursor: "pointer" },
   cell: { background: "#0e1013", border: "1px solid #262a31", borderRadius: 2, padding: "4px 5px", overflow: "hidden" },
   cellName: { color: "#7d8694", fontSize: 10, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" },
   cellValue: { color: "#8fd0a4", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" },

package/src/index.ts

@@ -30,6 +30,16 @@
  * and Push shows every parameter.
  */
 
+import { FOCUS_OPTIONS, type Controls, type FocusPolicy } from "./controls";
+
+/**
+ * The CONTROL SURFACE declaration lives in its own file and is re-exported here, so
+ * a device imports `defineSurface` and `defineControls` from one place. See
+ * controls.ts - the hardware behaviour it is shaped around is measured, and five
+ * parts of it contradict the obvious guess.
+ */
+export * from "./controls";
+
 /* ------------------------------------------------------------------ *
  * Parameter kinds
  * ------------------------------------------------------------------ */
@@ -400,6 +410,17 @@ export interface SurfaceDef<
   state?: S;
   /** Which parameters render as native Max objects in the device view. */
   layout?: { native?: NativeLayout<Extract<keyof P, string>> };
+  /**
+   * What this device claims on the CONTROL SURFACE - `defineControls()`.
+   *
+   * It lives on the Surface rather than beside it because it CONTRIBUTES two real
+   * Live parameters (`takeover`, `focus`): the user must be able to switch a
+   * takeover off, automate it and see it on Push, and the only thing Push sees is a
+   * Live parameter. So the declaration that claims the pads and the declaration that
+   * generates the dials are one declaration, and the two parameters are typed into
+   * this surface exactly as if they had been written out by hand.
+   */
+  controls?: Controls;
 }
 
 export interface Surface<
@@ -411,6 +432,41 @@ export interface Surface<
   readonly ids: readonly Extract<keyof P, string>[];
 }
 
+/**
+ * The two parameters `defineControls()` adds to the Surface that carries it.
+ *
+ * `takeover` is off by default and `focus` decides WHEN an enabled device actually
+ * holds what it declared - see controls.ts. They are spelled out as a type so that
+ * `useParam(surface, "takeover")` is typed like any other declared parameter, with
+ * nothing to cast and nothing to remember.
+ */
+export interface ControlParams {
+  takeover: ToggleSpec;
+  focus: MenuSpec<FocusPolicy>;
+}
+
+/**
+ * `P` with the takeover pair folded in, FLATTENED.
+ *
+ * A plain `P & ControlParams` is an intersection, and an intersection of two object
+ * types has no index signature even when both halves would satisfy one - so
+ * `useParam(surface, ...)` fails to infer `P extends Record<string, ParamSpec>` and
+ * the device sees a wall of "index signature is missing". Mapping over the keys
+ * produces an ordinary object type again, which infers exactly as a hand-written
+ * params block does.
+ */
+export type WithControlParams<P extends Record<string, ParamSpec>> = {
+  [K in keyof (P & ControlParams)]: (P & ControlParams)[K];
+};
+
+/** The two parameter specs themselves, so the build and the app agree on one object. */
+export function controlParams(controls: Controls): ControlParams {
+  return {
+    takeover: toggle({ default: false, short: "Takeovr" }),
+    focus: menu({ options: FOCUS_OPTIONS, default: controls.defaultFocus, short: "Focus" }),
+  } as ControlParams;
+}
+
 /** Push has eight encoders per page. A ninth parameter in a bank is not an error in Max - it just never appears. */
 export const BANK_SIZE = 8;
 
@@ -426,11 +482,28 @@ 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>,
+  const S extends Record<string, StateSpec>,
+  const W extends Record<string, WindowSpec>,
+>(def: SurfaceDef<P, S, W> & { controls: Controls }): Surface<WithControlParams<P>, S, W>;
+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>;
 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> {
+  // A declared takeover contributes two REAL Live parameters, and it does so HERE
+  // rather than in the build: they have to be in `ids` for the codegen to emit the
+  // objects, in `banks` for Push to page them, and in the app's store for
+  // `useParam(surface, "takeover")` to work. One merge, before every check below
+  // runs, so the generated pair is validated exactly like a hand-written one.
+  if (def.controls) def = mergeControlParams(def);
+
   const ids = Object.keys(def.params) as Extract<keyof P, string>[];
 
   for (const id of ids) {
@@ -503,6 +576,46 @@ export function defineSurface<
   return { ...def, ids };
 }
 
+/**
+ * Fold `defineControls()`'s two parameters into the declaration.
+ *
+ * THE BANK MATTERS AS MUCH AS THE PARAMETER. Push shows a device eight encoders per
+ * page and nothing else, so a `takeover` toggle that exists but is in no bank is a
+ * switch the user can only reach by opening the device view - which is the one place
+ * a Push user is not looking. A surface that declares banks therefore gets the pair
+ * appended to the first page with room, and a page of its own only if every declared
+ * bank is full.
+ *
+ * A surface with NO banks is left alone: Live falls back to declaration order, and
+ * the two land at the end of it either way.
+ */
+function mergeControlParams<
+  P extends Record<string, ParamSpec>,
+  S extends Record<string, StateSpec>,
+  W extends Record<string, WindowSpec>,
+>(def: SurfaceDef<P, S, W>): SurfaceDef<P, S, W> {
+  const extra = controlParams(def.controls!) as unknown as P;
+  for (const id of Object.keys(extra)) {
+    if (def.params[id]) {
+      throw new Error(
+        `surface: "${id}" is generated by defineControls() - remove it from params, or the takeover would have two dials and one name`,
+      );
+    }
+  }
+
+  const params = { ...def.params, ...extra };
+  if (!def.banks?.length) return { ...def, params };
+
+  const ids = Object.keys(extra) as Extract<keyof P, string>[];
+  const banks = def.banks.map((b) => ({ name: b.name, params: [...b.params] as Extract<keyof P, string>[] }));
+  for (const id of ids) {
+    const room = banks.find((b) => b.params.length < BANK_SIZE);
+    if (room) room.params.push(id);
+    else banks.push({ name: "Takeover", params: [id] });
+  }
+  return { ...def, params, banks };
+}
+
 /**
  * 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

package/src/pads.ts

@@ -0,0 +1,267 @@
+/**
+ * pads.ts - the state behind usePadGrid(), with no React in it.
+ *
+ * The twin of store.ts, and separate from it for the same reason store.ts is
+ * separate from react.tsx: everything subtle here is testable without a DOM. What
+ * is subtle is not the binding - it is the two things this file owns and nothing
+ * else may:
+ *
+ * ------------------------------------------------------------------------------
+ * 1. THE Y FLIP, IN ONE PLACE.
+ *
+ * The hardware counts rows from the TOP (a press on the bottom-left pad reports
+ * y = 7) and `defineControls`' API counts them from the BOTTOM, which is the
+ * orientation every layout in PUSH-USECASES.md is drawn in. Both directions are
+ * converted HERE, on the way out of `draw()` and on the way in from `pad_<key>`,
+ * and nowhere else. Do it twice and it cancels; do it in a device and every OTHER
+ * device on the grid is mirrored vertically with nothing to report it. That misread
+ * cost two rounds of the spike, because a wrong reading of the same payload
+ * collapsed four corners onto two cells and looked like a hardware fault.
+ *
+ * ------------------------------------------------------------------------------
+ * 2. THE FRAME IS WHOLE, AND SENT ONLY WHEN IT CHANGED.
+ *
+ * `draw()` takes a FRAME, not a pad: a device describes the entire grid every time
+ * and this works out whether anything moved. The callback fills an off-screen
+ * buffer of palette indices; if it is identical to the last buffer sent, nothing
+ * crosses the bridge at all. So a device may redraw on every tick and every state
+ * change - which is what makes `pads.draw(frame)` on a worker message a reasonable
+ * thing to write - and a still grid costs nothing.
+ *
+ * The wrapper diffs a second time, per CELL, against what the HARDWARE last
+ * received. That is not the same buffer: Live repaints the matrix as it hands it
+ * over, so after a grab the hardware's state is unknown and the wrapper has to
+ * repaint everything even though the app's frame did not change. Two diffs, two
+ * questions: this one is "did the device change its mind", the wrapper's is "does
+ * the pad already show this".
+ */
+import { bindInlet, outlet, padSelector, CONTROLS_IN, CONTROLS_OUT } from "@m4l-jweb/bridge";
+import { controlSize, paletteIndex, type ControlSpec, type Controls } from "./controls";
+
+/** One event off a grabbed control. */
+export interface PadEvent {
+  /** 0 .. cols-1, left to right. */
+  x: number;
+  /** 0 .. rows-1, BOTTOM to top - flipped from the wire here and nowhere else. */
+  y: number;
+  /** The raw value: a velocity on a press, 0 on a release. */
+  value: number;
+  /** `value > 0` - the check nine handlers in ten want. */
+  down: boolean;
+  /**
+   * The wire's fourth atom, passed through unnamed.
+   *
+   * It has been `1` on every event observed on a Push 3, press and release alike,
+   * and naming a field after a guess is how a guess becomes a fact by repetition.
+   */
+  extra: number;
+}
+
+/** The painting surface `draw()` hands you. Coordinates are bottom-up. */
+export interface PadFrame {
+  readonly rows: number;
+  readonly cols: number;
+  /** Fill every cell. */
+  clear(colour: string): void;
+  /** One cell. Out-of-range coordinates are ignored rather than thrown - a game's cursor may walk off the edge. */
+  set(x: number, y: number, colour: string): void;
+  /** A whole row, bottom-up. */
+  row(y: number, colour: string): void;
+  /** A whole column. */
+  col(x: number, colour: string): void;
+  /** A rectangle, from its bottom-left corner. */
+  rect(x: number, y: number, w: number, h: number, colour: string): void;
+}
+
+/**
+ * Why this device is or is not holding what it declared.
+ *
+ * `held` is the only one that is not a complaint. The other four are why the pads are
+ * dark, and they are worth distinguishing precisely because the hardware cannot: a
+ * Push with `takeover` off, a Push that is not plugged in, and a Push another instance
+ * of the device is holding all look identical.
+ */
+export type PadHoldReason = "held" | "off" | "no_surface" | "unresolved" | "not_focused";
+
+export type PadHandler = (e: PadEvent) => void;
+/** A `stream` control's raw atoms, exactly as the hardware sent them. Nothing is measured about their meaning yet. */
+export type StreamHandler = (atoms: number[]) => void;
+
+export interface PadStore {
+  /** Paint the whole of one control. Nothing crosses the bridge if the frame is unchanged. */
+  draw(key: string, fill: (f: PadFrame) => void): void;
+  /** Force the next `draw` to be sent even if it is identical, and tell the wrapper to repaint the hardware. */
+  refresh(): void;
+  onPad(key: string, fn: PadHandler): () => void;
+  onStream(key: string, fn: StreamHandler): () => void;
+  /** Do we hold the declared controls right now? */
+  held(): boolean;
+  /**
+   * WHY, when we do not - `off`, `no_surface`, `unresolved`, `not_focused`, `held`.
+   *
+   * On the hardware all four look the same: a dark Push. And a rejected LiveAPI call
+   * reports nothing, so the wrapper cannot say whether Live accepted a grab - only
+   * what it DECIDED, which is this.
+   */
+  reason(): PadHoldReason;
+  /** Which declared roles resolved on the connected hardware. A key absent from this map has not been answered for yet. */
+  roles(): Record<string, boolean>;
+  subscribe(fn: () => void): () => void;
+}
+
+const stores = new WeakMap<object, PadStore>();
+
+/**
+ * The store for one `defineControls()` declaration - created once, never torn down.
+ *
+ * Same rule as paramStore: the bridge holds ONE handler per selector, so a second
+ * `bindInlet("pad_pads", ...)` would silently replace the first and one of the two
+ * components would never see another press. Bind once, fan out.
+ */
+export function padStore<C extends Record<string, ControlSpec>>(controls: Controls<C>): PadStore {
+  const existing = stores.get(controls);
+  if (existing) return existing;
+
+  const keys = controls.keys as readonly string[];
+  const specs = controls.controls as Record<string, ControlSpec>;
+
+  /** The last frame SENT for each control, in hardware order. Null means "nothing sent yet". */
+  const sent = new Map<string, number[]>();
+  const padHandlers = new Map<string, Set<PadHandler>>();
+  const streamHandlers = new Map<string, Set<StreamHandler>>();
+  const listeners = new Set<() => void>();
+
+  let heldNow = false;
+  let reasonNow: PadHoldReason = "off";
+  let roleMap: Record<string, boolean> = {};
+
+  const notify = () => {
+    for (const fn of listeners) fn();
+  };
+
+  for (const key of keys) {
+    const spec = specs[key];
+    const rows = spec.kind === "grid" ? spec.rows : 1;
+    const cols = spec.kind === "grid" ? spec.cols : 1;
+
+    bindInlet(padSelector(key), (...args) => {
+      const atoms = args.map(Number);
+
+      // `live.observer` emits the property's CURRENT value the moment it is pointed
+      // at an object - for a control nobody has touched that is a bang, which
+      // arrives here as no arguments at all. It is an attach notification, not a
+      // press, and forwarding it is a press at (undefined, undefined).
+      if (!atoms.length) return;
+
+      const streams = streamHandlers.get(key);
+      if (streams) for (const fn of streams) fn(atoms);
+      if (spec.kind === "stream") return;
+
+      const handlers = padHandlers.get(key);
+      if (!handlers?.size) return;
+
+      // MEASURED on a Push 3: `<velocity> <x> <yFromTop> <1>`. A button carries one
+      // atom (unmeasured - no button but the matrix has been grabbed), so its
+      // coordinates are the only cell it has.
+      const value = atoms[0];
+      const hx = atoms.length >= 3 ? atoms[1] : 0;
+      const hy = atoms.length >= 3 ? atoms[2] : 0;
+      const e: PadEvent = { x: hx, y: rows - 1 - hy, value, down: value > 0, extra: atoms.length >= 4 ? atoms[3] : 0 };
+      if (e.x < 0 || e.x >= cols || e.y < 0 || e.y >= rows) return;
+      for (const fn of handlers) fn(e);
+    });
+  }
+
+  bindInlet(CONTROLS_IN.controls_held, (v, why) => {
+    const next = Number(v) === 1;
+    const nextReason = (why === undefined ? (next ? "held" : "off") : String(why)) as PadHoldReason;
+    if (next === heldNow && nextReason === reasonNow) return;
+    reasonNow = nextReason;
+    if (next === heldNow) {
+      // The reason moved without the grab moving - `off` to `not_focused`, say. The
+      // page still wants to know, and the frame cache is still valid.
+      notify();
+      return;
+    }
+    heldNow = next;
+    // The hardware is repainted by Live as it hands the controls over, so what we
+    // last sent is no longer what is lit. Forget it either way, and the next draw
+    // is a whole frame rather than a no-op against a stale cache.
+    sent.clear();
+    notify();
+  });
+
+  bindInlet(CONTROLS_IN.controls_role, (key, ok) => {
+    const next = { ...roleMap, [String(key)]: Number(ok) === 1 };
+    roleMap = next;
+    notify();
+  });
+
+  const store: PadStore = {
+    draw(key, fill) {
+      const spec = specs[key];
+      if (!spec) return;
+      const rows = spec.kind === "grid" ? spec.rows : 1;
+      const cols = spec.kind === "grid" ? spec.cols : 1;
+      const cells = new Array<number>(controlSize(spec)).fill(0);
+
+      // Hardware order: row 0 is the TOP. The flip is here, and only here.
+      const at = (x: number, y: number) => (rows - 1 - y) * cols + x;
+      const put = (x: number, y: number, colour: string) => {
+        if (x < 0 || x >= cols || y < 0 || y >= rows) return;
+        cells[at(x, y)] = paletteIndex(colour);
+      };
+
+      const frame: PadFrame = {
+        rows,
+        cols,
+        clear: (colour) => cells.fill(paletteIndex(colour)),
+        set: put,
+        row: (y, colour) => {
+          for (let x = 0; x < cols; x++) put(x, y, colour);
+        },
+        col: (x, colour) => {
+          for (let y = 0; y < rows; y++) put(x, y, colour);
+        },
+        rect: (x, y, w, h, colour) => {
+          for (let dx = 0; dx < w; dx++) for (let dy = 0; dy < h; dy++) put(x + dx, y + dy, colour);
+        },
+      };
+      fill(frame);
+
+      const last = sent.get(key);
+      if (last && last.length === cells.length && last.every((c, i) => c === cells[i])) return;
+      sent.set(key, cells);
+      // ONE message carrying the whole grid, not one per cell: [js] is a control
+      // plane, and sixty-four messages a frame is a data plane. The per-cell diff
+      // that decides what the hardware is actually told happens in the wrapper.
+      outlet(CONTROLS_OUT.controls_frame, key, ...cells);
+    },
+    refresh() {
+      sent.clear();
+      outlet(CONTROLS_OUT.controls_refresh);
+    },
+    onPad(key, fn) {
+      let set = padHandlers.get(key);
+      if (!set) padHandlers.set(key, (set = new Set()));
+      set.add(fn);
+      return () => set!.delete(fn);
+    },
+    onStream(key, fn) {
+      let set = streamHandlers.get(key);
+      if (!set) streamHandlers.set(key, (set = new Set()));
+      set.add(fn);
+      return () => set!.delete(fn);
+    },
+    held: () => heldNow,
+    reason: () => reasonNow,
+    roles: () => roleMap,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+  };
+
+  stores.set(controls, store);
+  return store;
+}

package/src/react.tsx

@@ -18,8 +18,9 @@
  */
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { describeParam, onParamRange, outlet } from "@m4l-jweb/bridge";
-import type { ParamSpec, ParamValue, StateSpec, StateValue, Surface, Watch, WatchSpec, WatchValue, WindowSpec } from "./index";
+import type { ControlSpec, Controls, ParamSpec, ParamValue, StateSpec, StateValue, Surface, Watch, WatchSpec, WatchValue, WindowSpec } from "./index";
 import { JWEB_VARNAME } from "./index";
+import { padStore, type PadFrame, type PadHandler, type PadHoldReason } from "./pads";
 import { paramStore, stateStore, watchStore } from "./store";
 
 /**
@@ -159,6 +160,127 @@ export function useStateSync<
   return [values[id] as StateValue<S[K]>, set];
 }
 
+/* ------------------------------------------------------------------ *
+ * The control surface - the pads, declared with defineControls()
+ * ------------------------------------------------------------------ */
+
+/** One declared control, bound to React. */
+export interface PadGrid {
+  /** Rows of the control, as declared. */
+  rows: number;
+  /** Columns of the control, as declared. */
+  cols: number;
+  /**
+   * Paint the WHOLE control. Coordinates are bottom-up.
+   *
+   * Redraw as freely as you like - on every worker frame, on every state change.
+   * The frame is diffed against the last one sent and an unchanged grid crosses the
+   * bridge not at all, so the cost of a still picture is one array comparison.
+   */
+  draw: (fill: (f: PadFrame) => void) => void;
+  /**
+   * Handle presses and releases. Returns an unsubscribe function, so it is written
+   * as the body of an effect: `useEffect(() => pads.onPad(fn), [pads])`.
+   */
+  onPad: (fn: PadHandler) => () => void;
+  /** Repaint the hardware from scratch, discarding what we believe is lit. */
+  refresh: () => void;
+  /** Did this control's role resolve on the connected hardware? `false` until the wrapper has answered. */
+  resolved: boolean;
+}
+
+/**
+ * A declared control, as a frame buffer and an event stream.
+ *
+ * ```tsx
+ * const pads = usePadGrid(controls, "pads");
+ * pads.draw((f) => { f.clear("black"); f.set(3, 4, "green"); });
+ * useEffect(() => pads.onPad((e) => e.down && turn()), [pads]);
+ * ```
+ *
+ * `x` is 0..cols-1 left to right and `y` is 0..rows-1 BOTTOM to top, in both
+ * directions - the Push's own orientation and the one every layout in
+ * PUSH-USECASES.md is written in. The wire counts y from the top; the flip lives in
+ * pads.ts and nowhere else.
+ */
+export function usePadGrid<C extends Record<string, ControlSpec>, K extends Extract<keyof C, string>>(controls: Controls<C>, key: K): PadGrid {
+  const store = useMemo(() => padStore(controls), [controls]);
+  const roles = useSyncExternalStore(store.subscribe, store.roles, store.roles);
+  const spec = controls.controls[key] as ControlSpec;
+  const rows = spec.kind === "grid" ? spec.rows : 1;
+  const cols = spec.kind === "grid" ? spec.cols : 1;
+
+  const draw = useCallback((fill: (f: PadFrame) => void) => store.draw(key, fill), [store, key]);
+  const onPad = useCallback((fn: PadHandler) => store.onPad(key, fn), [store, key]);
+  const refresh = useCallback(() => store.refresh(), [store]);
+
+  return useMemo(() => ({ rows, cols, draw, onPad, refresh, resolved: roles[key] === true }), [rows, cols, draw, onPad, refresh, roles, key]);
+}
+
+/**
+ * A declared BUTTON, as a live boolean.
+ *
+ * The degenerate grid: one cell, so `usePadGrid` would work and read badly.
+ * UNMEASURED - the only control grabbed on hardware so far is `Button_Matrix`, and
+ * what a single button's `value` carries has not been read off a Push. The first
+ * atom is taken as the value, which is what the matrix does.
+ */
+export function usePadButton<C extends Record<string, ControlSpec>, K extends Extract<keyof C, string>>(controls: Controls<C>, key: K): boolean {
+  const store = useMemo(() => padStore(controls), [controls]);
+  const [down, setDown] = useState(false);
+  useEffect(() => store.onPad(key, (e) => setDown(e.down)), [store, key]);
+  return down;
+}
+
+/**
+ * A declared STREAM's raw atoms - the jog wheel, the touch strip.
+ *
+ * Deliberately not decoded, and now for a measured reason (doc/MAX-FACTS.md). Both stream
+ * continuously under a grab, and NEITHER carries a position: the jog wheel sends a delta
+ * of one detent as a signed 7-bit step, and the touch strip sends a byte that counts in
+ * 64s and wraps. A hook that returned "the position" would be inventing one. This hands
+ * over what arrived, and the device decides what it means.
+ */
+export function usePadStream<C extends Record<string, ControlSpec>, K extends Extract<keyof C, string>>(controls: Controls<C>, key: K): number[] {
+  const store = useMemo(() => padStore(controls), [controls]);
+  const [atoms, setAtoms] = useState<number[]>([]);
+  useEffect(() => store.onStream(key, setAtoms), [store, key]);
+  return atoms;
+}
+
+/**
+ * Do we own the declared controls RIGHT NOW?
+ *
+ * Not the same question as "is `takeover` on": `focus` decides whether an enabled
+ * device holds them while another track or device is selected, and two of these in
+ * one set is the normal case.
+ */
+export function usePadsHeld<C extends Record<string, ControlSpec>>(controls: Controls<C>): boolean {
+  const store = useMemo(() => padStore(controls), [controls]);
+  return useSyncExternalStore(store.subscribe, store.held, store.held);
+}
+
+/**
+ * ...and WHY NOT, when we do not.
+ *
+ * Worth rendering, because the hardware cannot show the difference: `takeover` off, no
+ * Push connected, a Push whose control names this role is not among, and another
+ * instance holding the grid are four different problems that all look like a dark
+ * Push. And they cannot be told apart by asking Live either - a rejected grab is a
+ * console line and a normal return - so this is the wrapper reporting what it DECIDED,
+ * which is the half it does know.
+ */
+export function usePadsReason<C extends Record<string, ControlSpec>>(controls: Controls<C>): PadHoldReason {
+  const store = useMemo(() => padStore(controls), [controls]);
+  return useSyncExternalStore(store.subscribe, store.reason, store.reason);
+}
+
+/** Which declared roles resolved on the connected hardware - the one failure this API can report. */
+export function usePadRoles<C extends Record<string, ControlSpec>>(controls: Controls<C>): Record<string, boolean> {
+  const store = useMemo(() => padStore(controls), [controls]);
+  return useSyncExternalStore(store.subscribe, store.roles, store.roles);
+}
+
 /* ------------------------------------------------------------------ *
  * Borrowing from a native knob pool
  * ------------------------------------------------------------------ */