test(perf): verify the integrated performance envelope and document results

[codeacme17]

Parent

#114

Summary

Verify the integrated Echo UI performance envelope, publish before/after results, and document the budgets that future contributions must preserve.

This is the final convergence issue for the performance program. It does not introduce a new optimization area; it validates that all preceding changes work together in production builds without shifting cost to another component, breaking supported consumers, or weakening runtime behavior.

Scope

• Run the complete package, browser, compatibility, and lifecycle validation matrix.
• Measure the final package output using focused consumer imports and the package root.
• Measure active and idle real-time visualizers individually and together.
• Measure mono and stereo VU Meter scenarios, including high instance counts.
• Measure long-audio waveform preprocessing, cache reuse, progress, hover, resize, and cancellation.
• Measure high-frequency Input, Knob, Slider, and Envelope interaction.
• Test document visibility changes, viewport changes where supported, errors, cancellation, and unmount.
• Compare final values with the original audit baseline and approved budgets.
• Investigate any metric that improves locally but regresses in a combined scenario.
• Update contributor and consumer documentation with:
  • Focused import guidance
  • Performance budgets
  • Real-time update-rate defaults
  • Visibility and lifecycle behavior
  • Audio caching behavior
  • Long-audio waveform behavior
  • Guidance for pages with multiple simultaneous visualizers
• Record any observable compatibility change in release notes.

Required validation matrix

• TypeScript typecheck
• Lint with zero unexpected warnings
• Existing unit tests
• New performance regression tests
• Package artifact verification
• Example production build
• Documentation production build
• React 18 consumer smoke test
• React 19 consumer smoke test
• Supported Tailwind consumer paths
• Tone browser smoke tests
• Focused ESM imports
• Supported CommonJS or legacy resolution path
• Root-package import

Browser scenarios

• One active Oscilloscope.
• One active Spectrogram with shadow.
• One mono VU Meter.
• One stereo VU Meter.
• Waveform playback, progress, hover, seeking, and resize.
• Two Spectrograms, one Oscilloscope, and one Waveform running together.
• Twenty simultaneous VU Meters.
• Rapid Input, Knob, Slider, and Envelope interaction.
• Components mounting and unmounting while work is pending.
• Document visibility switching between visible and hidden.
• Long audio processing followed by cached reuse.
• Runtime error and cancellation paths.

Acceptance criteria

• A basic control import does not include Tone.js.
• A basic control import does not include visualization-only dependencies.
• Focused imports meet their approved gzip budgets.
• Stable audio frames cause no visualization child-list reconstruction.
• Grid and axis layers are not rebuilt by ordinary audio-frame updates.
• Each pointer burst creates at most one pending frame per active control.
• Controlled value changes require no more than one necessary component commit.
• No state setter runs during render.
• Runtime errors and unmount stop all owned frame, observer, timer, Worker, request, and document-listener work.
• Hidden-document behavior matches the documented contract.
• Long waveform preprocessing stays within the approved main-thread long-task budget.
• Repeated audio resources reuse in-flight and decoded work as documented.
• Multi-visualizer mutation, script-time, and task-time measurements show a material improvement over baseline.
• React 18, React 19, package, example, documentation, Tailwind, and Tone compatibility checks pass.
• Before/after results and exact reproduction commands are included in the final pull request.
• All performance budgets are documented and enforced by CI.

Results table

Complete this table with final measurements:

Metric	Baseline	Final	Target
Basic control consumer gzip, React external	115.24 kB	TBD	Less than 20 kB
Basic control consumer gzip, React and Tone external	50.83 kB	TBD	Less than 20 kB
Full ESM gzip	56.34 kB	TBD	No unapproved regression
Four active visualizers: DOM mutations over 3 seconds	5,611	TBD	No per-frame child replacement
Four active visualizers: task time over 3 seconds	1.07 s	TBD	Material reduction
Four active visualizers: script time over 3 seconds	0.78 s	TBD	Material reduction
Input pending RAF callbacks for 500 moves	500	TBD	At most 1
Knob pending RAF callbacks for 500 moves	500	TBD	At most 1
Slider pending RAF callbacks for 500 moves	500	TBD	At most 1

Out of scope

• Adding unrelated components or features.
• Relaxing budgets merely to make CI pass without documented evidence.
• Replacing functional or accessibility validation with performance-only checks.

Dependencies

Blocked by: #116, #118, #119, #120, and #121.