82 lines
4.5 KiB
Markdown
82 lines
4.5 KiB
Markdown
# 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/`.
|