# OpenSpec Change: enterprise-r3f-dmx

- **Change ID**: enterprise-r3f-dmx
- **Package**: `@suaveplan/r3f-dmx`
- **Category**: r3f/media
- **Target path**: `r3f/media/r3f-dmx`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/r3f-dmx.md`

---

## Summary

Deliver `@suaveplan/r3f-dmx` on the genesis branch from scratch at enterprise quality. The package provides DMX512 lighting control visualisation using React Three Fiber. It ships `<DmxFixture />`, `<DmxStage />`, `<DmxBeam />`, `<DmxUniverse />`, and a `useDmxChannel` hook. The `DmxUniverse` component drives a 512-channel universe with real-time channel value updates. Individual fixtures render as coloured point lights or spotlights with cone beams, accurate colour mixing from RGB/RGBW/CMY channels, pan/tilt simulation, and gobo projection. Storybook stories; Vitest component tests.

---

## Current-state audit (genesis)

Does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

Same R3F + React stack as other r3f packages.

---

## Public API surface

```tsx
function DmxStage(props: DmxStageProps): JSX.Element
function DmxUniverse(props: DmxUniverseProps): JSX.Element
function DmxFixture(props: DmxFixtureProps): JSX.Element
function DmxBeam(props: DmxBeamProps): JSX.Element
function useDmxChannel(universeId: string, channel: number): [number, (value: number) => void]

interface DmxUniverseProps {
  id: string
  channels?: Uint8Array    // 512 values 0–255; if omitted → zeroed
  fixtures: FixtureDefinition[]
  onChannelChange?: (channel: number, value: number) => void
}

interface FixtureDefinition {
  id: string
  label: string
  type: 'par' | 'moving-head' | 'beam' | 'led-bar' | 'strobe'
  position: [x: number, y: number, z: number]
  baseAddress: number           // DMX start address 1–512
  channelMap: FixtureChannelMap
}

interface FixtureChannelMap {
  red?: number    // offset from baseAddress
  green?: number
  blue?: number
  white?: number
  dimmer?: number
  pan?: number
  tilt?: number
  gobo?: number
  strobe?: number
}

interface DmxFixtureProps {
  definition: FixtureDefinition
  channels: Uint8Array
  selected?: boolean
  onClick?: () => void
}

interface DmxStageProps {
  universeId: string
  width?: number
  depth?: number
  height?: number
  fixtures: FixtureDefinition[]
  initialChannels?: Uint8Array
  showGrid?: boolean
  cameraControls?: boolean
}
```

---

## File layout

```text
r3f/media/r3f-dmx/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    types/
      r3f-dmx.types.ts
      r3f-dmx.types.md
    components/
      dmx-stage/ (tsx + md + types + test + stories + index)
      dmx-universe/ ...
      dmx-fixture/ ...
      dmx-beam/ ...
    hooks/
      use-dmx-channel/
        use-dmx-channel.ts / .md / .test.ts / index.ts
    utils/
      color-mixer/
        color-mixer.ts / color-mixer.md / color-mixer.test.ts / index.ts
      pan-tilt-calc/
        pan-tilt-calc.ts / pan-tilt-calc.md / pan-tilt-calc.test.ts / index.ts
```

---

## Impact

Downstream: live events, stage lighting design tools.

**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`.