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

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