Initial Commit

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

@@ -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/`.