Initial Commit

packages/ui/react/react-control-surface/src/runtime/binding-registry/handlers/dmx.md

@@ -0,0 +1,54 @@
+# `dmx` handler
+
+## Purpose
+
+The `dmx` handler is the binding-registry slot reserved for DMX universe /
+channel updates. The `@suaveplan/react-dmx` integration has not yet shipped,
+so this default throws `REACT_CONTROL_SURFACE.BINDING_HANDLER_MISSING`
+unconditionally. When the DMX integration lands the production handler will
+replace this default with a closure that writes the scaled value into the
+named universe/channel via the DMX transport.
+
+Throwing here is doubly important: stage-lighting bindings tend to be
+load-bearing in live performance, and a silent drop of a DMX update can
+plunge a stage into darkness mid-cue. Failing loud at the default ensures
+operators see the gap before they take the surface live.
+
+## Features
+
+- Strongly-typed signature `(binding: DmxBinding, value: number) => never`.
+- Error context preserves `universe`, `channel`, and the dropped `value`.
+- Default behaviour matches the other unwired handlers for uniform
+  error-handling at the call site.
+
+## Usage: Basic
+
+```ts
+import { BindingRegistry } from "@suaveplan/react-control-surface/runtime/binding-registry";
+
+const registry = new BindingRegistry({
+    dmx: (binding, value) =>
+        dmxTransport.send(binding.universe, binding.channel, value),
+});
+```
+
+## Usage: Advanced
+
+```ts
+import { dmxHandler } from "@suaveplan/react-control-surface/runtime/binding-registry";
+
+expect(() =>
+    dmxHandler({ kind: "dmx", universe: 1, channel: 33 }, 0.75)
+).toThrow(/BINDING_HANDLER_MISSING/);
+```
+
+## API Reference
+
+- `dmxHandler(binding: DmxBinding, value: number): never`
+  — always throws with code `REACT_CONTROL_SURFACE.BINDING_HANDLER_MISSING`.
+
+## Implementation Notes
+
+DMX traffic must be ordered and rate-limited; the production handler will
+need to coalesce rapid drag-driven updates. None of that is the default's
+problem — the default's only job is to refuse to silently drop traffic.