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 it is smooth there, it is smooth everywhere. Rules in short: donts.md.

Budgets

Idle means idle. 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 on a window nobody is touching.

How rendering stays cheap

• cx.notify() re-renders one view. Its child entities are boundaries and stay as they were. Cost is the size of the dirty view, never the window, so split a busy screen into views along the lines where state changes: the sidebar, the list, the editor, 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 needed is not.
• Lists render the rows near the viewport. With set_items_versioned, an owner re-render reuses every row whose version did not change. Prove it in tier 1 with 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. Anything that can take more than a frame goes elsewhere:

• Network, disk, parsing, decoding: nd::system::spawn(future, |result, cx| ..). The future runs on a worker; the closure brings the result back to the main thread.
• 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.
• No blocking calls in a handler: no std::fs::read of a large file, no synchronous HTTP, 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, 240 Hz and 144 Hz side by side on g815. A window dragged to another display switches clocks. So:

• Animate against time, never frame counts: sample window.now() and let the frame clock decide how often that is.
• Use the theme's motion.{fast, normal, slow} and motion.spring. They also honour 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 no more than 2 missed frames with p95 within 1.25 display periods. On the GPUI hosts ND_ANIMATE=<seconds> re-renders every window every frame for that long and prints the frame line, which is how a heavy view shows its cost. Measure on the slowest machine you have, from a release build, before and after the change, and put the number in the commit or the README.