Improve frame timing fidelity

[mattcosta7]

Summary

• calibrate frame budgets from stable RAF intervals across 60, 120, 144 Hz, and other displays
• report observed intervals separately from inferred dropped frames while retaining the deprecated droppedFrames alias
• exclude inactive or throttled iframe gaps and recalibrate after visibility or collection resumes
• expose refresh-rate estimates and adaptive budgets in the panel and public metadata

Stacked on draft PR #162.

Validation

• 870 browser tests passed across Chromium, Firefox, and WebKit
• focused synthetic tests cover 60/120/144 Hz, fractional intervals, hidden transitions, throttled gaps, reset, and resume
• npm run tsc
• npm run lint (no errors; one unrelated existing warning)
• npm run build (attw and publint passed)
• Changesets reports one minor addon bump
• focused read-only review completed and its inference-rounding finding was fixed

[Copilot]

Pull request overview

Improves frame-timing accuracy with refresh-rate calibration, adaptive budgets, and clearer public metrics while preserving the deprecated alias from PR #162.

Changes:

• Calibrates frame budgets from RAF intervals and infers missed refreshes.
• Excludes presumed inactive gaps and resets calibration across lifecycle transitions.
• Exposes refresh estimates, interval counts, metadata, UI details, tests, and documentation.

Show a summary per file

File	Description
.changeset/improve-frame-fidelity.md	Records the minor release.
packages/storybook-addon-performance-panel/README.md	Documents adaptive frame metrics.
packages/storybook-addon-performance-panel/react/performance-decorator.tsx	Updates decorator documentation.
packages/storybook-addon-performance-panel/performance-panel.tsx	Displays calibrated timing metrics.
packages/storybook-addon-performance-panel/core/performance-types.ts	Adds public metrics and metadata.
packages/storybook-addon-performance-panel/collectors/README.md	Documents collector behavior.
packages/storybook-addon-performance-panel/collectors/frame-timing-collector.ts	Implements calibration and inference.
packages/storybook-addon-performance-panel/collectors/constants.ts	Defines calibration bounds and windows.
packages/storybook-addon-performance-panel/collectors/collector-manager.ts	Publishes new metrics and alias.
packages/storybook-addon-performance-panel/collectors/__tests__/performance-types.browser.test.ts	Tests metadata and aliases.
packages/storybook-addon-performance-panel/collectors/__tests__/frame-timing-collector.browser.test.ts	Tests calibration and lifecycle behavior.
packages/storybook-addon-performance-panel/collectors/__tests__/collector-manager.browser.test.ts	Tests metric propagation.
packages/storybook-addon-performance-panel/__tests__/performance-panel.browser.test.tsx	Tests panel presentation.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Suppressed comments (2)

packages/storybook-addon-performance-panel/collectors/frame-timing-collector.ts:175

• When calibration first succeeds, this backfill only visits calibration-eligible intervals. Any earlier valid long frame between FRAME_INTERVAL_MAX_MS and FRAME_INACTIVE_GAP_MS was counted as observed but is permanently omitted from inferred drops; e.g. a 50 ms frame followed by eight steady 60 Hz intervals yields zero drops. Retain all pending observed intervals while uncalibrated and backfill those once a budget is available.

        this.#inferredDroppedFrames += this.#calibrationIntervals.reduce(
          (total, interval) => total + this.#inferDroppedFrames(interval),
          0,
        )

packages/storybook-addon-performance-panel/collectors/frame-timing-collector.ts:165

• This rolling lower-quartile window adapts asymmetrically when moving between displays. After a populated 120 Hz window moves to 60 Hz, the old 8.33 ms samples remain the lower quartile for about 22 new frames, so every normal 16.67 ms interval is added as one inferred drop before the budget finally changes. Detect a sustained refresh-rate shift and enter recalibration without counting those transition samples.

    if (delta >= FRAME_INTERVAL_MIN_MS && delta <= FRAME_INTERVAL_MAX_MS) {
      addToWindow(this.#calibrationIntervals, delta, FRAME_RATE_CALIBRATION_WINDOW)
      this.#updateFrameBudget()

• Files reviewed: 13/13 changed files
• Comments generated: 1
• Review effort level: Balanced