suaveplan/openspec/archive/2026-05-23-enterprise-react-midi/proposal.md

@suaveplan/react-midi — Web MIDI API React adapter

• Target path: packages/ui/react/react-midi/
• Tier: browser/react
• Date: 2026-05-23
• Status: PROPOSED

Why

@suaveplan/midi ships universal-tier MIDI types and a MidiPortLike structural contract but never touches the platform. To consume MIDI in a browser app, React components need:

1. Permission gating (navigator.requestMIDIAccess({ sysex })) with promise-shaped state for Suspense + ErrorBoundary integration.
2. Port enumeration with live add/remove (devices plug/unplug at runtime).
3. Per-port input/output hooks that wire into the universal decoder/encoder and surface typed MidiMessage events.
4. SysEx opt-in (separate permission scope).
5. Safe StrictMode behaviour (double-mount + cleanup must not double-bind).

This package owns the Web MIDI bridge so every downstream React surface (control-surface runtime, react-control-surface editor, react-audio-player's hardware-controller integration) shares one set of hooks instead of reimplementing permission/state plumbing.

What changes

1. NEW package @suaveplan/react-midi at packages/ui/react/react-midi/.
2. <MidiProvider> — context provider that triggers navigator.requestMIDIAccess exactly once (StrictMode-safe), exposes the MIDIAccess state, supports sysex: boolean prop, surfaces permission denial as a typed MidiPermissionError.
3. Hooks:
   • useMidi() — returns { access, status: "loading"|"granted"|"denied"|"unsupported", inputs: MidiPortLike[], outputs: MidiPortLike[] }.
   • useMidiInput(portId | "first"): MidiPortLike | null — picks a single input; subscribers receive parsed MidiMessage events via port.onMessage.
   • useMidiOutput(portId | "first"): MidiPortLike | null — sends bytes via the universal encodeMessage.
   • useMidiMessages(portId, filter?) — returns the most recent N messages (ring buffer) filtered by message type. For UI display.
   • useMidiDevices() — returns the live { inputs, outputs } array, re-renders on statechange.
   • useNRPN(portId) / useRPN(portId) / useCC14(portId) — high-resolution-controller reducers exposed as React hooks.
4. <MidiDeviceList> + <MidiActivityIndicator> — small UI primitives for picker / activity visualisation. Each is composable; consumers pass their own renderProps for custom styling.
5. Connect-state events — fires onDeviceAdd / onDeviceRemove via context, plus per-port state reads.
6. Error codes — REACT_MIDI.{ACCESS_DENIED, UNSUPPORTED_PLATFORM, PORT_NOT_FOUND, SYSEX_NOT_PERMITTED} via defineCodes.
7. OTel instrumentation — counter react_midi_messages_received_total{port}, counter react_midi_messages_sent_total{port}.

Impact

• New package depending on @suaveplan/midi@workspace:^ and React 19 peer dep.
• Browser-tier — uses navigator.requestMIDIAccess. Falls back gracefully (status: "unsupported") on platforms that lack Web MIDI (Safari without flag, Firefox, sandboxed contexts).
• Unblocks @suaveplan/react-control-surface (CC bindings drive plugin parameters via useParameter from @suaveplan/react-audio).