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

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

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.

3.2 KiB Raw Permalink Blame History Unescape Escape