test(perf): establish reproducible performance budgets and regression coverage

[codeacme17]

Parent

#114

Summary

Establish a reproducible performance test harness and explicit budgets for Echo UI before changing package structure or runtime behavior.

The current audit has useful point-in-time measurements, but the repository does not yet have an automated way to detect the same regressions. This issue creates the measurement layer that every subsequent performance issue will use for acceptance.

Baseline

The audit recorded the following package results:

Consumer scenario	Minified JavaScript	Gzip
Full distributed ESM artifact	213,766 B	56,341 B
Button, with React external	474,811 B	115,244 B
Card, with React external	474,809 B	115,242 B
One icon, with React external	475,427 B	115,583 B
Button, with React and Tone external	183,492 B	50,830 B

A production browser scenario containing one Waveform, one Oscilloscope, and two Spectrogram instances produced the following over three seconds:

• 5,611 DOM mutation records
• 905 removed nodes
• 1,810 added nodes
• 1,810 SVG path-attribute changes
• Approximately 1.07 seconds of main-thread task time
• Approximately 0.78 seconds of script time

Synthetic drag tests also showed that 500 move events queued 500 animation-frame callbacks in Input, Knob, and Slider.

Scope

• Add focused consumer build fixtures for:
  • A single icon
  • A basic control
  • Card
  • An audio hook
  • A visualization component
  • The package root
• Measure minified and gzip output and identify whether unrelated heavy dependencies are retained.
• Add production-browser performance scenarios for:
  • Idle components
  • Active real-time visualizers
  • Multiple simultaneous visualizers
  • High-frequency pointer input
  • Long-audio waveform preprocessing
  • Document visibility changes
• Capture the metrics needed by the remaining sub-issues:
  • Pending animation-frame callbacks
  • React commit counts where practical
  • DOM child-list and attribute mutations
  • Long tasks and script time
  • Main-thread processing time
• Define stable budgets and tolerances that can run in CI without excessive timing flakiness.
• Store before/after results as test artifacts or machine-readable output.
• Document how contributors can run the same measurements locally.

Acceptance criteria

• One documented command runs the package-size checks locally.
• One documented command runs the browser performance checks locally.
• CI runs deterministic performance checks or a stable regression-focused subset.
• Focused consumer fixtures resolve the same published entry points used by real consumers.
• Package checks fail when a focused import exceeds its approved gzip budget.
• Package checks detect when a basic component unexpectedly retains Tone.js or visualization-only dependencies.
• Browser checks can detect unbounded animation-frame scheduling and per-frame child-list reconstruction.
• Pointer instrumentation can prove whether a burst of 500 move events creates more than one pending frame per control.
• The harness includes a representative multi-instance visualization scenario.
• Timing-based thresholds include documented tolerances and do not depend on a single exact machine speed.
• The current baseline and target budgets are recorded for comparison in the final integration issue.

Initial package budgets

Import category	Target gzip budget
Single icon	Less than 2 kB
Basic control	Less than 20 kB
Card	Less than 20 kB
Audio hook, excluding its Tone peer/runtime	Less than 10 kB
Visualization component	A component-specific budget established by the fixture

Out of scope

• Changing package exports or build output.
• Refactoring component rendering behavior.
• Optimizing individual audio hooks or visualizers.
• Treating raw frame rate as the only performance signal.

Validation

• Run the existing unit tests, typecheck, lint, package build, and example production build.
• Run each new fixture twice and verify that results stay within documented tolerance.
• Introduce a temporary local regression to confirm that each budget can fail for the intended reason.

Dependencies

Blocked by: None.