Initial Commit

openspec/changes/enterprise-r3f-dmx/proposal.md

@@ -0,0 +1,123 @@
+# 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`.