124 lines
3.2 KiB
Markdown
124 lines
3.2 KiB
Markdown
# 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`.
|