Initial Commit
This commit is contained in:
123
openspec/changes/enterprise-r3f-dmx/proposal.md
Normal file
123
openspec/changes/enterprise-r3f-dmx/proposal.md
Normal file
@@ -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`.
|
||||
81
openspec/changes/enterprise-r3f-dmx/tasks.md
Normal file
81
openspec/changes/enterprise-r3f-dmx/tasks.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# Tasks: enterprise-r3f-dmx
|
||||
|
||||
**Change ID**: enterprise-r3f-dmx
|
||||
**Package**: `@suaveplan/r3f-dmx`
|
||||
**Target path**: `r3f/media/r3f-dmx`
|
||||
**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create directory tree per `proposal.md`.
|
||||
- [ ] `package.json` at `0.1.0`, `"sideEffects": false`, exports `"."` + component + hook + utils subpaths.
|
||||
- [ ] Same dep stack as other r3f packages (R3F + React + OTel + zod + error).
|
||||
- [ ] `tsconfig.json` extending `react-library.json`; `vitest.config.ts` with jsdom, `pool: 'forks'`, `fileParallelism: false`.
|
||||
- [ ] Scripts: `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`.
|
||||
|
||||
## 2. Types and errors
|
||||
|
||||
- [ ] Define all interfaces and Zod schemas (`FixtureDefinitionSchema`, `FixtureChannelMapSchema`) in `src/types/r3f-dmx.types.ts`.
|
||||
- [ ] Write `r3f-dmx.types.md` (≥200 words).
|
||||
- [ ] `src/error-codes.ts`: `R3F_DMX_INVALID_ADDRESS`, `R3F_DMX_CHANNEL_OUT_OF_RANGE`; eager registration.
|
||||
|
||||
## 3. Color mixer utility
|
||||
|
||||
- [ ] Implement `src/utils/color-mixer/color-mixer.ts`:
|
||||
- `mixRgb(r, g, b, dimmer): THREE.Color` — scale by dimmer/255.
|
||||
- `mixRgbw(r, g, b, w, dimmer): THREE.Color` — blend white channel additively.
|
||||
- `mixCmy(c, m, y, dimmer): THREE.Color` — subtractive CMY to RGB.
|
||||
- All channel values 0–255 inputs.
|
||||
- [ ] Write `color-mixer.test.ts`: full red (255,0,0), white mix, dimmer scaling, CMY → RGB known values.
|
||||
- [ ] Write `color-mixer.md` (≥200 words).
|
||||
|
||||
## 4. Pan/tilt calculator
|
||||
|
||||
- [ ] Implement `src/utils/pan-tilt-calc/pan-tilt-calc.ts`:
|
||||
- `channelToDegrees(value: number, range: number): number` — maps 0–255 to ±(range/2) degrees.
|
||||
- `panTiltToRotation(pan: number, tilt: number): THREE.Euler` — convert DMX pan/tilt degrees to Three.js Euler.
|
||||
- [ ] Write `pan-tilt-calc.test.ts`: mid value → 0°; min/max values → ±range/2.
|
||||
- [ ] Write `pan-tilt-calc.md` (≥200 words).
|
||||
|
||||
## 5. useDmxChannel hook
|
||||
|
||||
- [ ] Implement `useDmxChannel(universeId, channel): [value, setValue]`:
|
||||
- Read from a React Context provided by `DmxUniverse`.
|
||||
- `setValue` dispatches channel update to context; triggers re-render.
|
||||
- [ ] Write `use-dmx-channel.test.ts`: returns current value; setValue updates; out-of-range throws.
|
||||
- [ ] Write `use-dmx-channel.md` (≥200 words).
|
||||
|
||||
## 6. Components
|
||||
|
||||
For each of DmxBeam, DmxFixture, DmxUniverse, DmxStage:
|
||||
|
||||
- [ ] Implement R3F component:
|
||||
- `DmxBeam`: `<SpotLight>` + cone `<CylinderGeometry>` with emissive material; colour from `colorMixer`; visible when dimmer > 0.
|
||||
- `DmxFixture`: renders the appropriate light type (PAR = `<PointLight>`, moving head = `<SpotLight>` with pan/tilt rotation, strobe = flicker animation); uses `colorMixer` and `panTiltCalc`.
|
||||
- `DmxUniverse`: provides `DmxContext` with `Uint8Array(512)` state; renders all `FixtureDefinition` as `DmxFixture` components.
|
||||
- `DmxStage`: canvas wrapper with floor plane, grid helper, lighting rigs, and all fixtures from the universe.
|
||||
- [ ] Write `.test.tsx` for each: renders; channel update changes fixture colour; click fires callback; `{ timeout: 5000 }`.
|
||||
- [ ] Write `.stories.tsx` for each: default + playground + fixture-type variants.
|
||||
- [ ] Write `.md` per component (≥200 words).
|
||||
|
||||
## 7. OTel
|
||||
|
||||
- [ ] Counter `r3f_dmx.channel_updates_total`; histogram `r3f_dmx.render_duration_ms`.
|
||||
|
||||
## 8. Docs + verify + publish
|
||||
|
||||
- [ ] Root `README.md`: quick-start stage setup, fixture definition JSON, channel update example, API table.
|
||||
- [ ] `bunx turbo lint --filter=@suaveplan/r3f-dmx` — zero errors.
|
||||
- [ ] `bunx turbo typecheck --filter=@suaveplan/r3f-dmx` — zero errors.
|
||||
- [ ] `bunx turbo test --filter=@suaveplan/r3f-dmx` — all pass.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/r3f-dmx` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/r3f-dmx`.
|
||||
- [ ] Update `CLAUDE.md`; archive to `openspec/archive/2026-04-24-enterprise-r3f-dmx/`.
|
||||
Reference in New Issue
Block a user