From f3928d53e5992e65a1e79eedc87439e45a1f69dc Mon Sep 17 00:00:00 2001 From: ZhuchkaTriplesix Date: Sun, 26 Jul 2026 23:30:38 +0300 Subject: [PATCH] docs(perf): document theme cross-fade rebuild cost and default-off Confirm Animate theme stays opt-in; call out app-wide InheritedTheme cost at 120 Hz in motion and perf-baseline docs. Closes #361 Co-authored-by: Cursor --- docs/motion-and-high-refresh.md | 10 +++++++--- docs/perf-baseline.md | 1 + 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/motion-and-high-refresh.md b/docs/motion-and-high-refresh.md index 53f41973..78801a0f 100644 --- a/docs/motion-and-high-refresh.md +++ b/docs/motion-and-high-refresh.md @@ -137,7 +137,11 @@ Suggested order: A1 → A2 → A3 in parallel with A4; then A5; A6 closes the mi --- -## 7. Review rule — no magic UI durations +## 7. Theme morph cost + +`AnimatedQueryaTheme` / `ShadcnAnimatedTheme` notify **app-wide** theme dependents on every animation tick. That is acceptable only as an **opt-in** Preference (`themeAnimationEnabled`, default **false**) and only when Motion is Full. Motion Off / preference off must snap. Do not enable theme animation by default without a profiled 120 Hz pass ([perf-baseline.md](perf-baseline.md) §14). + +## 8. Review rule — no magic UI durations When reviewing PRs that touch animation: @@ -149,7 +153,7 @@ When reviewing PRs that touch animation: Checklist for 120 Hz verification: [perf-baseline.md](perf-baseline.md) § Fluid shell. -## 8. References +## 9. References - Flutter engine — high refresh rate gap: `flutter/flutter#160952`, `#90675` (ProMotion scrolling), `#94508` (`CADisableMinimumFrameDurationOnPhone` default). - `refresh_rate` package (query/unlock/overlay/benchmark, all platforms): https://pub.dev/packages/refresh_rate @@ -160,7 +164,7 @@ Checklist for 120 Hz verification: [perf-baseline.md](perf-baseline.md) § Fluid --- -## 9. Measured results (0.4.4) +## 10. Measured results (0.4.4) The table below shows the measured refresh rates and frame times on target monitors before and after the 0.4.4 implementation (using a profile build, measured with DevTools and `QUERYA_REFRESH_OVERLAY=true`): diff --git a/docs/perf-baseline.md b/docs/perf-baseline.md index 2593c25f..f504a0b5 100644 --- a/docs/perf-baseline.md +++ b/docs/perf-baseline.md @@ -36,4 +36,5 @@ Repeat on a **120 Hz** display (budget **≤ 8.3 ms** build+raster). Prefer prof 12. **Results modes**: idle → run (spinner) → grid; force an error — mode keys morph; scrolling the grid must not fade rows. 13. **Dialog / dropdown**: open/close `showAppDialog` and a `QueryaDropdown` — enter fade-slide, exit uses exit curve; Motion Off snaps. 14. **Theme cross-fade**: Preferences → enable Animate theme + Motion Full; switch dark/light — shadcn + `AnimatedQueryaTheme` lerp. Repeat with Motion Off (snap). + **Cost note:** theme morph rebuilds app-wide InheritedTheme dependents every tick — keep **Animate theme** **off by default** (`ThemeController`); only enable for demos/profile. Never ship it default-on without a 120 Hz timeline. 15. **Split settle**: drag the connections sidebar handle and the SQL/results vertical split with a fling — mid-drag stays 1:1; release may soft-settle. Focus the handle — ring uses motion tokens (not mid-drag animation).