@suaveplan/react-control-surface - React 19 atomic-control surface renderer for @suaveplan/control-surface-schema. Foundation chunk: error codes, telemetry, skin contract, binding registry + handlers, grouping primitives, and the simple atomic controls (TextLabel, Image, LED, Switch2, Switch3, ButtonMomentary, ButtonLatching).

React 19 atomic-control surface renderer for @suaveplan/control-surface-schema.

This is the foundation chunk of the package — it lands the package scaffolding (error codes, telemetry, skin contract, binding registry + handlers, grouping primitives) and the seven simple atomic controls:

<TextLabel> — decorative read-only text.
<Image> — decorative image element.
<LED> — boolean/0..1 brightness indicator.
<Switch2> — two-state toggle (role="switch").
<Switch3> — three-state toggle.
<ButtonMomentary> — press-and-hold trigger.
<ButtonLatching> — sticky toggle.

The remaining controls (knob, sliders, displays, meters, XY pad, jog wheel, piano key, drum pad) and the <Surface> runtime walker land in follow-up chunks.

Documentation tree

button-latching — <ButtonLatching> is the sticky toggle: a click latches the button on, the next click latches it off. It is the counte…
- button-latching — <ButtonLatching> is the sticky toggle: a click latches the button on, the next click latches it off. It is the counte…
button-momentary — <ButtonMomentary> is the press-and-hold trigger control. Pressing it emits max into onChange; releasing it emits…
- button-momentary — <ButtonMomentary> is the press-and-hold trigger control. Pressing it emits max into onChange; releasing it emits…
digital-display — Read-only 7-segment / LCD-style readout for the control surface. The component is a typed information sink: it accepts…
- digital-display — Read-only 7-segment / LCD-style readout for the control surface. The component is a typed information sink: it accepts…
drum-pad — Velocity-sensitive drum pad. Maps a pointer or keyboard press to a velocity 0..1 then through [min, max] so the same…
- drum-pad — Velocity-sensitive drum pad. Maps a pointer or keyboard press to a velocity 0..1 then through [min, max] so the same…
image — <Image> is the decorative image control. Like <TextLabel>, it appears in the closed ControlKind enumeration so a…
- image — <Image> is the decorative image control. Like <TextLabel>, it appears in the closed ControlKind enumeration so a…
jog-wheel — <JogWheel> is an endless rotary control inspired by DJ-deck jog wheels. Unlike a knob, it does not have an absolute v…
- jog-wheel — <JogWheel> is an endless rotary control inspired by DJ-deck jog wheels. Unlike a knob, it does not have an absolute v…
knob — Rotary knob control — the cornerstone interaction primitive for the 2D control surface. Renders an SVG circle with a ro…
- knob — Rotary knob control — the cornerstone interaction primitive for the 2D control surface. Renders an SVG circle with a ro…
led — <LED> is the output indicator control. It accepts a numeric value in the standard BoundControlProps domain and rend…
- led — <LED> is the output indicator control. It accepts a numeric value in the standard BoundControlProps domain and rend…
meter-peak — <MeterPeak> is a digital-style peak meter that shows the instantaneous input level alongside a held-then-decaying pea…
- meter-peak — <MeterPeak> is a digital-style peak meter that shows the instantaneous input level alongside a held-then-decaying pea…
meter-spectral — <MeterSpectral> renders a real-time bar graph of magnitude bins. Each bin is drawn as a vertical bar whose height is…
- meter-spectral — <MeterSpectral> renders a real-time bar graph of magnitude bins. Each bin is drawn as a vertical bar whose height is…
meter-vu — <MeterVU> renders a single-channel level meter with the classic analogue VU response defined by IEC 60268-10: a 300 m…
- meter-vu — <MeterVU> renders a single-channel level meter with the classic analogue VU response defined by IEC 60268-10: a 300 m…
piano-key — A single piano key. Two visual kinds (white / black) and three visual states (idle / pressed / highlighted).…
- piano-key — A single piano key. Two visual kinds (white / black) and three visual states (idle / pressed / highlighted).…
slider-h — Horizontal slider control — the X-axis counterpart of <SliderV>. Every behavioural decision is delegated to the share…
- slider-h — Horizontal slider control — the X-axis counterpart of <SliderV>. Every behavioural decision is delegated to the share…
slider-v — Vertical slider control. Pointer interaction sets the value directly from clientY against the rendered track rect — d…
- slider-helpers — Shared pure functions for both <SliderV> and <SliderH> so that value resolution, detent snapping, and keyboard step…
- slider-v — Vertical slider control. Pointer interaction sets the value directly from clientY against the rendered track rect — d…
switch-2 — <Switch2> is the two-position toggle control. It implements the WAI-ARIA "switch" pattern (role="switch" + `aria-ch…
- switch-2 — <Switch2> is the two-position toggle control. It implements the WAI-ARIA "switch" pattern (role="switch" + `aria-ch…
switch-3 — <Switch3> is the three-position toggle, modelling the kind of "down-centre-up" or "low-mid-high" switch found on outb…
- switch-3 — <Switch3> is the three-position toggle, modelling the kind of "down-centre-up" or "low-mid-high" switch found on outb…
text-label — <TextLabel> is the decorative read-only control that renders a static text string. It is included in the `ControlKind…
- text-label — <TextLabel> is the decorative read-only control that renders a static text string. It is included in the `ControlKind…
xy-pad — <XYPad> is an accessible 2-axis touch surface that emits normalised { x, y } coordinates as the user drags a pointe…
- xy-pad — <XYPad> is an accessible 2-axis touch surface that emits normalised { x, y } coordinates as the user drags a pointe…
error-codes — The error-codes module owns the stable, namespaced registry of every error code that `@suaveplan/react-control-surfac…
- error-codes — The error-codes module owns the stable, namespaced registry of every error code that `@suaveplan/react-control-surfac…
group — <Group> is the layout primitive used for internal nodes of a control surface tree. It accepts a layout descriptor (CS…
- group — <Group> is the layout primitive used for internal nodes of a control surface tree. It accepts a layout descriptor (CS…
panel — <Panel> is the labelled grouping primitive that wraps a group of controls in a titled box, optionally with collapse-t…
- panel — <Panel> is the labelled grouping primitive that wraps a group of controls in a titled box, optionally with collapse-t…
rack — <Rack> is the grouping primitive that models a hardware-rack frame — a horizontal (default) or vertical sequence of f…
- rack — <Rack> is the grouping primitive that models a hardware-rack frame — a horizontal (default) or vertical sequence of f…
runtime — <Surface> is the runtime that turns a validated ControlSurface document into a live React DOM tree. It performs a d…
- binding-registry — BindingRegistry is the discriminated dispatcher that links every bound control on a surface to the consumer-side logi…
  - compound — The compound handler is the binding-registry slot responsible for fanning a single control's value out to multiple le…
  - dmx — The dmx handler is the binding-registry slot reserved for DMX universe / channel updates. The @suaveplan/react-dmx…
  - midi-in — The midiIn handler is the binding-registry slot that hosts an inbound MIDI subscription — a control bound this way re…
  - midi-out — The midiOut handler is the binding-registry slot that converts a control's value into an outbound MIDI Control Change…
  - plugin-param — The pluginParam handler is the binding-registry slot that dispatches a control's value to a plugin parameter via `use…
  - transport — The transport handler is the binding-registry slot that dispatches a control's value to the audio transport — play/st…
  - binding-registry — BindingRegistry is the discriminated dispatcher that links every bound control on a surface to the consumer-side logi…
- surface — <Surface> is the runtime that turns a validated ControlSurface document into a live React DOM tree. It performs a d…
skin — <SurfaceSkinProvider> is the single React boundary that activates a skin for every atomic control inside its subtree.…
- surface-skin-provider — <SurfaceSkinProvider> is the single React boundary that activates a skin for every atomic control inside its subtree.…
telemetry — The telemetry module is the single owner of every OpenTelemetry instrument emitted by `@suaveplan/react-control-surfa…
- telemetry — The telemetry module is the single owner of every OpenTelemetry instrument emitted by `@suaveplan/react-control-surfa…

Bindings

BindingRegistry discriminates on Binding["kind"] (defined by @suaveplan/control-surface-schema) and dispatches to the registered handler. Built-in handlers integrate with sibling packages:

pluginParam — bridges to useParameter from @suaveplan/react-audio.
transport — bridges to useTransport from @suaveplan/react-audio.
midiOut — bridges to useMidiOutput from @suaveplan/react-midi.
midiIn — bridges to useMidiInput from @suaveplan/react-midi.
dmx — throws REACT_CONTROL_SURFACE.BINDING_HANDLER_MISSING until the @suaveplan/react-dmx integration arrives in a later chunk.
compound — fans out to every leaf in registration order.

Every handler is invoked through the same BoundControlBinder shape so the runtime never special-cases binding kinds.

Skin contract

<SurfaceSkinProvider id="skin-id" vars={...}> injects CSS variables on a wrapping <div> — every atomic control reads its visual styling exclusively through CSS variable resolution. JS-level skin dispatch is forbidden by the spec: changing the skin is a pure CSS-variable swap.

Telemetry

control_surface_interactions_total{kind} — counter incremented on every user-driven onChange from an atomic control.
control_surface_render_duration_ms — histogram recorded by the runtime per surface render commit (registered for future chunks).