# react-control-surface spec delta

## ADDED Requirements

### Requirement: BoundControlProps contract

Every atomic control component SHALL accept `BoundControlProps`: `{ value, onChange, min, max, step?, default?, disabled?, label?, ariaLabel?, renderHint? }`. No control reads from React context or runs side-effects beyond `onChange`. Pure value-in / value-out.

#### Scenario: Knob fires onChange on drag

- **WHEN** a `<Knob value={0.5} min={0} max={1} onChange={spy} />` receives a pointer-down + pointer-move 100 px upward
- **THEN** `spy` is called with a value > 0.5

#### Scenario: Slider fires onChange on keyboard arrow

- **WHEN** a `<SliderV value={0.5} step={0.1} onChange={spy} />` is focused and ArrowUp is pressed
- **THEN** `spy` is called with `0.6`

**Verified by:** `src/controls/knob/knob.test.tsx`, `src/controls/slider-v/slider-v.test.tsx`

### Requirement: 18 atomic controls

The package SHALL export 18 atomic controls covering every `ControlKind` in `@suaveplan/control-surface-schema`: `Knob`, `SliderV`, `SliderH`, `ButtonMomentary`, `ButtonLatching`, `Switch2`, `Switch3`, `LED`, `DigitalDisplay`, `MeterVU`, `MeterPeak`, `MeterSpectral`, `XYPad`, `JogWheel`, `PianoKey`, `DrumPad`, `TextLabel`, `Image`.

#### Scenario: Every kind is exported

- **WHEN** the package barrel is imported
- **THEN** every name in the closed `ControlKind` list resolves to a React component

**Verified by:** `tests/exports.test.tsx`

### Requirement: Surface runtime walks the schema

`<Surface schema={ControlSurface} bindings={BindingRegistry} />` SHALL DFS-walk the schema and render each node via the appropriate atomic component for its `kind`. Unknown kinds throw `ReactControlSurfaceError("REACT_CONTROL_SURFACE.UNKNOWN_KIND")`.

#### Scenario: 4-pad drum surface renders 4 buttons

- **WHEN** a surface with a 4-grid Group containing 4 `drum-pad` Controls is rendered
- **THEN** the DOM contains 4 `[role="button"]` elements with the proper labels

#### Scenario: Unknown kind throws

- **WHEN** a surface contains a Control with `kind: "not-a-thing"` (forced past schema validation in a test)
- **THEN** rendering throws `UNKNOWN_KIND`

**Verified by:** `tests/runtime.test.tsx`

### Requirement: BindingRegistry dispatch

`BindingRegistry` SHALL dispatch each binding kind (`pluginParam`, `transport`, `midiOut`, `midiIn`, `dmx`, `compound`) to its registered handler. Missing handlers throw `BINDING_HANDLER_MISSING`.

#### Scenario: pluginParam binding drives onChange to the param hook

- **WHEN** a knob with binding `{ kind: "pluginParam", pluginId: "p1", paramPath: "vol" }` is dragged and the `pluginParam` handler is a spy
- **THEN** the spy is called with `{ pluginId: "p1", paramPath: "vol", value }` matching the knob's emitted value

#### Scenario: compound binding fans out

- **WHEN** a knob has `{ kind: "compound", bindings: [pluginParam, midiOut] }`
- **THEN** every drag invokes both handlers, in registration order

**Verified by:** `tests/binding-fanout.test.tsx`

### Requirement: Accessibility — every control is operable without a mouse

Every control SHALL be focusable via Tab, operable via arrow keys, expose `aria-valuemin` / `aria-valuemax` / `aria-valuenow` / `aria-valuetext` where applicable, respect `prefers-reduced-motion`, and have a non-empty `aria-label` derived from `label` or explicitly passed.

#### Scenario: Knob aria attributes

- **WHEN** a `<Knob value={0.5} min={0} max={1} label="Volume" />` is rendered
- **THEN** the rendered DOM has `role="slider"`, `aria-valuemin="0"`, `aria-valuemax="1"`, `aria-valuenow="0.5"`, `aria-label="Volume"`

**Verified by:** `tests/accessibility.test.tsx`

### Requirement: Skin contract via CSS variables

`<SurfaceSkinProvider id="skin-id" vars={overrides} />` SHALL inject `--cs-knob-track-color`, `--cs-knob-indicator-color`, `--cs-slider-thumb-color`, etc., consumable by every atomic control via standard CSS variable resolution. No JS-level skin dispatch.

#### Scenario: Skin overrides take effect

- **WHEN** a `<SurfaceSkinProvider id="nki" vars={{ "--cs-knob-track-color": "#ff8800" }}>` wraps a `<Knob>`
- **THEN** the knob's computed `--cs-knob-track-color` is `#ff8800`

**Verified by:** `src/skin/surface-skin-provider.test.tsx`

### Requirement: OTel instrumentation

Every control interaction SHALL increment `control_surface_interactions_total{kind}`. Every `<Surface>` render commit SHALL record `control_surface_render_duration_ms`.

#### Scenario: Counter increments on press

- **WHEN** a `<ButtonMomentary>` is pressed 5 times against an in-memory `MeterProvider`
- **THEN** the snapshot shows `control_surface_interactions_total{kind=button-momentary}=5`

**Verified by:** `src/telemetry/telemetry.test.ts`

### Requirement: MeterSpectral consumes analysis-spectrum output

`<MeterSpectral>` SHALL accept a `Float32Array` of magnitude bins (or an `AsyncIterable<Float32Array>` for streaming) and render the bins as a bar graph. The component does NOT import `@suaveplan/audio-analysis-spectrum` directly — it accepts pre-computed bins, keeping it tier-pure (no analysis dependency).

#### Scenario: Bin array renders bars

- **WHEN** `<MeterSpectral bins={new Float32Array([0.1, 0.5, 0.9, 0.3])} />` is rendered
- **THEN** the DOM contains 4 bar elements with heights proportional to the bins

**Verified by:** `src/controls/meter-spectral/meter-spectral.test.tsx`