suaveplan/openspec/archive/2026-05-23-enterprise-react-control-surface/tasks.md

Tasks — enterprise-react-control-surface

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 Account for every .claude/worktrees/* entry; prune stale ones via bun scripts/worktree-prune.ts --remove.
• 0.3 Confirm MANIFEST.md matches find packages -maxdepth 3 -name package.json | wc -l.

1. Spec authoring

• 1.1 Draft proposal.md, tasks.md, specs/react-control-surface/spec.md

2. Implementation — atomic controls (each: .tsx, .types.ts, .test.tsx, .stories.tsx, .md)

• 2.1 src/controls/knob/
• 2.2 src/controls/slider-v/ + slider-h/
• 2.3 src/controls/button-momentary/ + button-latching/
• 2.4 src/controls/switch-2/ + switch-3/
• 2.5 src/controls/led/
• 2.6 src/controls/digital-display/
• 2.7 src/controls/meter-vu/ + meter-peak/
• 2.8 src/controls/meter-spectral/
• 2.9 src/controls/xy-pad/
• 2.10 src/controls/jog-wheel/
• 2.11 src/controls/piano-key/
• 2.12 src/controls/drum-pad/
• 2.13 src/controls/text-label/ + image/

3. Grouping + runtime

• 3.1 src/grouping/group/, rack/, panel/
• 3.2 src/runtime/surface.tsx — <Surface schema bindings /> walks + renders
• 3.3 src/runtime/binding-registry/binding-registry.ts — discriminated dispatcher
• 3.4 src/runtime/binding-registry/handlers/{plugin-param, transport, midi-out, midi-in, dmx, compound}.ts

4. Skin contract + accessibility

• 4.1 src/skin/surface-skin-provider.tsx
• 4.2 src/skin/skin.types.ts + default CSS-var palette
• 4.3 Accessibility audit per control: keyboard ops, ARIA, prefers-reduced-motion

5. Error codes + telemetry

• 5.1 src/error-codes.ts — REACT_CONTROL_SURFACE.{UNKNOWN_KIND, BINDING_HANDLER_MISSING, INVALID_SCHEMA} via defineCodes
• 5.2 src/telemetry/telemetry.ts — counter control_surface_interactions_total{kind}, histogram control_surface_render_duration_ms

6. Tests

• 6.1 Per-control .test.tsx covering pointer + keyboard + aria-attribute coverage
• 6.2 tests/runtime.test.tsx — render a 4-pad drum surface from JSON, assert handler invocation on press
• 6.3 tests/binding-fanout.test.tsx — compound binding fires every handler
• 6.4 tests/accessibility.test.tsx — @testing-library/jest-dom aria + role assertions on every control
• 6.5 Every it(...) carries { timeout: 5000 } (30000 async)

7. Documentation

• 7.1 Sibling .md per .tsx/.ts (≥200 words, basic + advanced examples)
• 7.2 README with ## Atomic controls + ## Runtime + bindings + 3 example surfaces (drum machine, mixer, piano)

8. Pre-archive verification

• 8.1 bunx turbo lint typecheck test --filter=@suaveplan/react-control-surface — green
• 8.2 bunx turbo test:coverage --filter=@suaveplan/react-control-surface — 100/100/100/100
• 8.3 bunx turbo build --filter=@suaveplan/react-control-surface — green

9. Archive

• 9.1 Fold spec delta → openspec/specs/react-control-surface/spec.md
• 9.2 Move folder → openspec/archive/<yyyy-mm-dd>-enterprise-react-control-surface/
• 9.3 Refresh MANIFEST.md
• 9.4 Prune worktree