Performance

Budgets on the slowest machine, per-view rendering, and keeping the main thread free.

The reference machine is e1504g: an Intel Core i3-N305 laptop with an integrated GPU and a 60 Hz panel. If an app is smooth there, it's smooth everywhere. For the short list of rules, see donts.md.

Budgets

A still window does no work. No frame runs unless a view is dirty or an animation is live, so a timer that polls or a view that notifies itself every frame shows up as CPU use on a window that nobody is touching.

How rendering stays cheap

• cx.notify() re-renders one view. Its child entities are boundaries and stay as they were. The cost is the size of the dirty view, never the window, so split a busy screen into views along the lines where state changes (for example, the sidebar, the list, the editor, and the status bar).
• nd compares the new element tree with the retained one and sends only changed properties to the backend. Building the same tree again is cheap. Building a bigger tree than you need isn't.
• Lists render the rows near the viewport. With set_items_versioned, a re-render of the owner reuses every row whose version didn't change. To prove it in tier 1, call cx.render_count(..) on a row view before and after an unrelated update.

Keep the main thread free

The main thread runs input, layout, and every frame. Move anything that can take more than a frame somewhere else:

• For network, disk, parsing, and decoding, use nd::system::spawn(future, |result, cx| ..). The future runs on a worker, and the closure brings the result back to the main thread.
• For images, image(..) decodes at display size on worker threads, newest request first, with an LRU in memory and a disk cache for downloads. Never decode a full-size image in render.
• Don't make blocking calls in a handler: no std::fs::read of a large file, no synchronous HTTP, and no thread::sleep (clock-in-ui catches the last one).

Frame timing and monitors

Each window has its own frame clock at its display's refresh rate: 60 Hz on e1504g, 120 Hz ProMotion on a MacBook, and 240 Hz and 144 Hz side by side on g815. A window that you drag to another display switches clocks. So:

• Animate against time, never frame counts. Sample window.now(), and let the frame clock decide how often that happens.
• Use the theme's motion.{fast, normal, slow} and motion.spring. They also respect the user's reduced-motion setting.
• An animation re-renders its view every frame while it runs, so keep animated content in its own small view.

Measuring

nd diag scroll --rows 100000          # scroll a virtual list every frame, check the frame budget
cargo build --release                 # budgets are release numbers; debug builds are not comparable

nd diag scroll passes at 2 or fewer missed frames, with p95 within 1.25 display periods. On the GPUI hosts, ND_ANIMATE=<seconds> re-renders every window every frame for that many seconds and prints the frame line, which shows what a heavy view costs. Measure on the slowest machine that you have, from a release build, before and after the change. Put the number in the commit or the README.