Desktop performance and animation: the baseline (2026-09-28)

Part of #62, the desktop performance and animation audit. This file records what the app does with animation today, read off the code, and the baseline numbers that could be taken on this host: the app’s own frame instrumentation in a profile build, and the two integration tests that already drive the real app on Linux.

It is the reliable half of the audit, written down first. The per-scenario driver #62’s “Measure” list asks for is not in this pass — it is named at the end of this file as the follow-up, with what it would have to drive.

The machine

The XWayland detail matters for what follows: the app’s frames are handed to a compositor, so a raster number here is not a raster number on a native X11 or a Windows desktop.

How the numbers were taken

• The app’s own instrumentation — lib/src/core/frame_cost.dart (the [edit]/[read]/[shell] per-region frame lines), lib/src/core/frame_log.dart (logNextFrame, FrameProbe) and _reportSlowFrames (lib/main.dart), all behind --dart-define=NIMAN_FRAMES=true, in a profile build of the testing channel:

  flutter build linux --profile \
    --dart-define=NIMAN_FRAMES=true --dart-define=APP_CHANNEL=testing
  ./build/linux/x64/profile/bundle/niman        # DISPLAY=:0
  

  The app mirrors its log to ~/.local/share/dev.niman.niman-testing/niman-log.txt; the numbers below are read from that file (2026-09-28 15:19:19 run; a second sample from the 11:26 run in the same file).

• The integration tests, which drive the real app on Linux:

  flutter test integration_test/app_boot_test.dart -d linux
  flutter test integration_test/sync_e2e_test.dart -d linux
  

Baseline: cold start to usable

A profile build (AOT), the library on disk resumed at startup — 7 files, 5 directories. The wall clock is from process exec (the shell’s clock) to the line the app wrote itself:

So: the library is usable 0.72 s after the process starts, and with a 931 945-character note open in it the whole cold start reaches its first painted note at 0.78 s and the read pane’s first content at 0.88 s, on this host — 0.53 s of the 0.72 s being the engine and the Dart VM, which is not the app’s work.

[session] index warm-up: 88 ms, the tree’s first flatten 13 ms for 9 rows, hunspell’s dictionary 17 ms, and the note’s 931 945 characters read in 13 ms are on the startup path as well; the earlier run in the same log read the same library with a colder cache and had 109 ms for the tree’s flatten against today’s 13 ms, which is what a first-time cost looks like.

Baseline: frames

The app logs a line only for frames that miss the 16 ms budget (_reportSlowFrames, and FrameCost’s per-region lines for the frames a pane’s own share misses) — it deliberately logs nothing about the frames that are fine, because a line per frame charges the frames it measures and fills the log buffer in minutes. What follows is therefore the jank, not the frame rate.

In the 15:19 run, the whole 31-second life of the process:

The largest frame of the run is 112.1 ms, 105.4 ms of it the UI isolate’s build — 6.7× the 16.7 ms frame — and it lands on the cold start, not on an animation and not while the app is in use. The pane lines in the same second are the read pane’s first content: [edit] frame: edit 0.0 ms, build 0.0 ms, layout 42.3 ms, paint 0.2 ms (42.5 ms here).

A second run, written into the same log file earlier the same day (11:26, a second note of 668 characters open beside the geometry one), read three slow frames: 22.3, 64.9 and 166.8 ms, all in the opening second. Both runs agree on the shape — a handful of long frames while the library and its notes are read and laid out, then nothing.

Two things this baseline is not:

• It is not per scenario. It says the cold start has one big frame in it; it does not say what a tab switch, a scroll or search-as-you-type cost, which is exactly what #62’s measure list asks for (see The follow-up).
• It is a profile build’s numbers and a single run each. The engine’s timings arrive in batches and a cold process plans differently from a warm one.

Baseline: the integration tests

Both run the real app on a real device, debug builds:

The 2 s and the 18 s include the app’s own boot, its databases, the UI’s first frames and, in the sync case, a loopback WebDAV server in the same process. The sync test needs a display; here it runs against DISPLAY=:0 with the session’s XAUTHORITY. Neither test reads the frame instrumentation, so neither says what its frames cost — the flow, not the frame data.

The animation inventory

Every animated transition in the app, from the code. file:line is the site; the duration and curve are the ones written there. The rating is what the code and the numbers above let me say, and “a guess” says so: no scenario here was measured per animation, so a rating is a reading of the code, not a measurement, unless the row says otherwise.

30 places, of which 29 are animations and one (#29) is the deliberate absence of one.

What snaps today

Snapping is the app’s default, and for the big surfaces it is deliberate — tab_body_stack.dart says why in so many words (“switching tabs only flips visibility and fades the incoming body in, instead of disposing one State and inflating another mid-animation”). Everything below changes in one frame, with no animation at all, and it is verified in the code:

• A tab switch on the desktop. The wide layout’s slots are Offstage (shell.dart:2490), so Search, Settings, Todo and Files appear instantly; the fade at #1 belongs to the phone’s stack. The tab body changes and only the incoming one is drawn, in that frame.
• The editor ↔ preview flip (note_view.dart:2265): both panes stay mounted and one is Offstage; the preview appears in the frame the flag flips, keeping its parse and its scroll position.
• source ↔ live (note_view.dart:2269): a different KeyedSubtree key in the same slot — an instant remount of the pane.
• One note for another in a pane, and the pane’s own memento restore.
• The tree: selecting a row, expanding a folder, the rows a scan refreshes, the sort flip’s content. (The chevron animates; the rows under it do not.) The first flatten of 9 rows took 13 ms here and 109 ms on the colder run — the rows arrive, they do not animate in, and when the arrival itself is late an entry animation would only make it later.
• Search results, tags, the outline, the history list, the todo rows: the list appears when the (debounced, 150 ms) query returns.
• The sidebar toggle, the dock panes (outline, tags, history) opening, Zen mode — pane geometry changes in one frame; there is no AnimatedSize/AnimatedContainer anywhere in shell.dart.
• A theme change — light/dark or a new palette rebuilds MaterialApp, and no AnimatedTheme is in the tree: the whole window changes colour in one frame.
• A window resize, and the phone/desktop breakpoint crossing.
• The caret (markdown/render/source_view.dart:2698): a 550 ms timer toggles it, so it blinks by snapping, not by fading.
• Table hover (source_view.dart:3132, :3140): the table’s handles are put on the pointer’s table and cleared 200 ms after it leaves — both in one frame, no fade.
• Drag and drop of a note or a tab: the feedback follows the pointer and the drop marker appears; the only animated part is the list row’s tint (#9).
• The dialog, the sheet, the menu and the page push are the framework’s own (#28) — the app adds no animation to them and no override of them.

The policy — a proposal for the maintainer

Not a decision taken; a reading of the code and the numbers above. The issue asks which interactions should animate and which should stay instant:

1. Anything that changes what the page is stays instant: a tab switch (desktop), the editor ↔ preview flip, source ↔ live, one note for another, the dock panes, the sidebar, Zen, a theme change. All of them are the writer’s own act, the content that arrives is the feedback, and a 100–450 ms wait between the intention and the page is a tax charged on every use of the app’s most-used controls.
2. Animation is for the small, self-contained change, where it says what happened without the page waiting: a glyph inside a button (FAB, audio), a row stepping aside, a chip revealed in a row, a menu, a palette or a dialog appearing at ≤150 ms, the sort chevron, the typewriter glide. That is what most of the inventory above already is — the policy mostly describes what is there.
3. Nothing animates a big list, and no long surface animates its arrival. The animation is where the jank would live, and the tree’s first flatten (13–109 ms) shows the arrival is the part worth fixing.
4. No animation inside a frame’s layout of a whole pane. Every existing one animates a transform, an opacity or one row’s height; #6, the scrim, is the only one that repaints a full-screen area, and #28, the zoom page push, is the only one that rasterises a whole page.
5. Reduced motion is honoured, and only twice — the marquee and the spinning sync icon read MediaQuery.disableAnimationsOf. The implicit animations (FAB, menu, tab fade) do not. Whatever policy is taken, that should read the same everywhere.
6. The instrumentation stays: NIMAN_FRAMES off in a release build, the [frames]/[shell]/pane lines as they are, and every new animation measured with the scenario driver below before it is called smooth.

What was not measured

• Windows. No host here. #62 asks for it; it did not happen in this pass.
• DevTools. Not attached: the app’s own timings (NIMAN_FRAMES) were used instead, which report the engine’s FrameTiming breakdown (build/raster/vsync) but no raster-level detail, no shader compilation trace and no per-frame widget rebuild counts.
• The scenario list of #62, one by one: library open/reindex at the 1M notes target, open + scroll of a novel-length note in source and live, tab switch, list scroll, search-as-you-type, the spell-check panel, the preview of a big note. None of these was driven and timed; the cold-start numbers are the only frame data here.
• Any animation, individually. No row of the inventory is a measurement. Every rating marked “a guess” is a reading of the code; the ones not marked are the ones whose own code or doc says why they are short.
• The 246 MB note (huge-notes.md’s Quicknote.md): not on this host in this pass.
• live at scale, and the row-wise reveal that mode still owes.
• hunspell was present — hunspell ready: …/.local/share/hunspell/en_US.dic in 17 ms — so the spell-check path had a real dictionary; but the spell-check panel itself was not driven.
• Android, macOS, and any phone.
• The animation perception the issue is really about: whether 450 ms of zoom on a settings push feels slow, and whether an instant tab switch feels abrupt, are questions about a person’s hand, not about a frame log. The numbers here constrain the answer; they do not give it.

The follow-up (what this pass does not have)

A per-scenario driver. One scripted run, on a real desktop device, that drives each item of #62’s measure list in turn — with enough quiet between two actions for the engine’s batched frame timings to belong to the action that caused them (frame_log.dart says why: a window shorter than that latency reads the previous action’s frames) — and reads the app’s own lines for each: [frames] slow frame for the whole frame, [shell], [edit] and [read] for the region that spent it, and FrameProbe’s per-action summary (frame_log.dart), which already wraps a tab switch (shell.dart:627) and a preview open (note_view.dart:761) and can be pointed at a scroll and at search-as-you-type with the same one call.

Without it, this file answers “what animates and what snaps” from the code and gives the cold start a shape. With it, each animation in the table above gets the rating it is owed, and #45’s fixes get a baseline to beat.

Edit this page on GitHub