How would you set and enforce a frame-time budget for a Flutter team's app that ships to both 60 Hz and 120 Hz devices?

## Why a budget needs deciding "Keep it at 60 fps" was an adequate rule when every phone refreshed at 60 Hz. Many current devices run at 90 or 120 Hz, where Flutter tries to match the display. The budget per frame shrinks from about 16.7 ms to 8.3 ms, and a screen that was smooth on one phone stutters on another. A team needs an explicit, measurable definition of "fast enough". Choosing it is a judgement call. ## Defining the budget - **Per thread.** UI and raster run as a pipeline, so each must fit the frame on its own. A budget on their sum is too strict for missed frames and says nothing about which thread to fix. - **Per refresh rate.** Express it as `1000 / X` ms of the display rate, rather than a fixed 16 ms. This is the rule `FrameTiming`'s own docs use. - **With headroom.** Aim below the limit, because the same code runs slower on older devices and when the OS is busy. How much headroom is a product decision. - **Per journey.** A settings page and a photo editor do not deserve the same scrutiny. Name the journeys that matter, such as app open, the main feed scroll and the heaviest editor, and budget those. - **With latency in mind.** When UI plus raster exceeds one frame, frames still arrive on time but input lags. For drag-heavy or drawing screens, also track `totalSpan`. ## Measuring in the lab 1. Choose **reference devices** that include the slowest one you support and a high refresh rate phone. 2. Run journeys in **profile mode**. Debug numbers are not comparable, and emulators do not reflect real GPUs. 3. Keep **baseline traces** per release, so a new trace can be compared with the last good one. 4. Automate the recording where possible, so it does not depend on someone remembering. Recording timelines from automated tests has its own tooling. ## Measuring in the field `SchedulerBinding.instance.addTimingsCallback` works in release builds with negligible overhead, so the real distribution can be measured: | Metric | From | Why | |---|---|---| | share of frames with `buildDuration` over budget | UI thread | Dart-side regressions | | share of frames with `rasterDuration` over budget | raster thread | scene-cost regressions | | p90 / p99 of each duration per screen | both | tail behaviour users notice | | `totalSpan` over budget on interactive screens | both | input latency | Segment by **refresh rate**, **device class** and **app version**, or improvements on flagships will hide regressions on low-end phones. Aggregate on the device and send summaries. ## Enforcing it - **Gate on trends and percentiles**, not single frames. The first frame of a route and one-off shader work will always produce outliers. - **Compare against a baseline.** A 15 % increase in over-budget frames on a journey is a signal even if the absolute value still passes. - **Give each journey an owner**, so a regression has someone to act on it. - **Budget the fix, too.** Sometimes the answer is to accept a looser target on a rarely used screen and spend the effort where users spend their time. ## Judgement calls a lead owns - Whether 120 Hz smoothness is a promise or a best effort. - Which devices define the floor. Supporting very old phones may cost more than it earns. - How much engineering time performance work gets against features, and when a regression blocks a release. - Whether lab numbers or field numbers win when they disagree. Field data reflects real use; lab data is reproducible.