perf(controls): coalesce pointer interactions and eliminate drag-time render churn

[codeacme17]

Parent

#114

Summary

Coalesce high-frequency pointer interactions and remove drag-time rendering churn across Input, Knob, Slider, and Envelope.

Synthetic tests showed that Input, Knob, and Slider each queued 500 animation-frame callbacks for 500 synchronous move events. Envelope additionally rebuilds SVG nodes and bindings during controlled drag feedback. These components should share one interaction model with predictable frame, cleanup, and final-value semantics.

Scope

Shared pointer behavior

• Use Pointer Events and pointer capture for mouse, touch, and pen input.
• Store only the latest pointer coordinates while a frame is pending.
• Allow at most one pending animation-frame callback per active control.
• Cancel pending work on pointer end, pointer cancellation, lost capture, disabled state, and unmount.
• Remove document-level listeners and other global resources during cleanup.
• Publish at most one intermediate change per frame.
• Commit the final clamped value reliably when interaction ends.
• Preserve keyboard interaction and accessibility behavior.

Input

• Remove render-time state updates used to derive direction or styling.
• Derive drag direction and value from the current interaction state once.
• Preserve horizontal, vertical, bilateral, step, min, max, and controlled behavior.

Knob

• Derive value, rotation, and interaction direction without effect-driven render waterfalls.
• Migrate dragging to the coalesced pointer path.
• Preserve group inheritance and controlled/uncontrolled behavior.

Slider

• Move high-frequency visual updates away from layout-heavy properties when practical.
• Avoid unnecessary axis reconstruction during drag.
• Preserve horizontal, vertical, bilateral, range, step, and controlled behavior.

Envelope

• Reuse path, control-point, and drag geometry.
• Avoid removing and recreating all SVG nodes during controlled feedback.
• Avoid rebinding drag handlers on every value change.
• Keep transient pointer coordinates outside React when they are not render state.
• Publish at most one intermediate envelope change per frame and commit normalized data on drag end.

Acceptance criteria

• A synchronous burst of 500 pointer moves creates no more than one pending animation-frame callback per control.
• Intermediate onChange calls are limited to one per animation frame.
• The final change callback receives the final clamped or normalized value.
• No pointer listener, capture, timer, or animation-frame callback survives unmount.
• Pointer cancellation and lost capture leave the component in a valid state.
• No component calls a state setter during render.
• Dragging Input, Knob, or Slider does not require an effect-driven second render to derive presentation.
• Envelope does not recreate its complete SVG structure for every controlled drag update.
• Mouse, touch, pen, and keyboard behavior are covered where supported.
• Existing controlled and uncontrolled APIs remain compatible.
• Horizontal, vertical, bilateral, stepped, bounded, and group-controlled configurations are regression tested.

Out of scope

• Audio-driven animation scheduling.
• Waveform hover and seeking behavior.
• General visual redesign of the controls.
• Changing callback semantics without an explicit compatibility decision.

Validation

• Run automated RAF-coalescing and cleanup tests for all four components.
• Test slow drags, pointer bursts, leaving bounds, cancellation, disabled transitions, and unmount mid-drag.
• Verify final values at min, max, step boundaries, and bilateral center.
• Compare React commits and layout work with the baseline.

Dependencies

Blocked by: #115.