todo-app/docs
Krzysztof kuhy Rudnicki 7a7a7e7e99 Document why the Linux desktop build must move off Flutter's embedder
The desktop app is unusably slow at 4K while the phone is fine. Measured it
rather than guessing, and the cause is not what the previous session assumed.

Flutter's Linux embedder has two independent defects, neither fixable in app
code:

- It schedules frames at a fixed 60 FPS regardless of the monitor
  (flutter/flutter#183703, P2, no PR).
- Far worse, at 3840x2160 it achieves 18.6 fps while each frame costs only
  ~3ms of a 16.7ms budget -- ~50ms per frame is dead time in the presentation
  path. This is the lag actually being reported.

The stock `flutter create` counter app collapses identically (20.5 fps vs
todo's 20.6 at 4K), and todo's own build time is 0.1-0.4ms everywhere, so no
application-level change can help. Impeller does not help either: it changes
rasterisation, not presentation.

The same Dart code as a web build hits 142.9 fps at the same 4K size on the
same machine -- a 7x difference -- so the fix is to drop the Linux desktop
embedder, not Flutter or Dart.

Also records the agreed migration plan and the Xephyr -glamor test harness,
including the two measurement mistakes made along the way (synthetic xdotool
input never reached the app; software Xephyr dominated an early 4K run) so the
numbers here can be trusted and reproduced.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-20 12:48:38 +02:00
..
explanations Add change explanation: surface sync outcomes 2026-07-16 18:08:39 +02:00
desktop-performance-findings.md Document why the Linux desktop build must move off Flutter's embedder 2026-07-20 12:48:38 +02:00
initial_design.md Initial commit: offline-first CRDT notes app (capture + GitHub sync) 2026-06-14 14:20:19 +02:00