fix(dispatcher): count low and idle work in the render budget - #24040

GitHub Issue: closes #24032

PR Type:

🐞 Bugfix

What changed? 🚀

Current behavior. NativeDispatcher.DispatchItems consults TryGetRenderAction() before it scans the four priority queues, so a pending render action outranks every queued item. The only anti-starvation guard, normalItemsToProcessBeforeNextRenderAction, was seeded from the Normal queue alone (:216) and decremented only when a Normal item was dispatched (:156). With the Normal queue empty — the ordinary state on a settled visual tree — the budget was re-seeded to 0 on every render, so the next render action was immediately eligible again and Low and Idle never got a turn. Anything awaiting CoreDispatcher.RunIdleAsync therefore never resumed.

Hosts that pace their frames rarely notice: Win32 (Win32RenderPacer.cs) and X11 (FramePacer) produce frames on a separate paced thread, so a render action is pending only briefly. macOS has neither — MacOSWindowHost.InvalidateRender() is a bare uno_window_invalidate → needsDisplay = YES and AppKit draws on the dispatcher's own thread — so a render action is pending on nearly every turn and the starvation is total.

Change. Repair the accounting at the mutation point rather than guarding downstream:

• seed the budget from Normal.Count + min(Low.Count + Idle.Count, 2) (GetItemsToProcessBeforeNextRenderAction)
• decrement it on every non-High dispatch
• rename normalItemsToProcessBeforeNextRenderAction → itemsToProcessBeforeNextRenderAction, since it is no longer Normal-only

High is excluded deliberately: the render pipeline posts CompositionTarget.RaiseRendering at High priority on every frame, so counting it would let rendering consume the budget that exists to yield to the other queues. Normal stays uncapped, leaving today's Normal-vs-render pacing bit-for-bit unchanged.

Why not the simpler options. Widening the budget to all queues while leaving the decrement in the _currentPriority == Normal branch deadlocks rendering — once Normal drains, the budget never returns to 0. An earlier "let one queued item through after K consecutive renders" floor was also drafted and rejected: RaiseRendering regenerates a High item each frame and consumes exactly the slot the floor releases, so Idle still starves. The When_Render_Loop_Is_Active_Then_Idle_Work_Runs test below fails against that design.

Invariants. budget ≤ Normal.Count + Low.Count + Idle.Count holds at every mutation, so budget > 0 implies some non-High queue is non-empty; the scan that follows always dequeues, and the still-pending render keeps _globalCount > 0 so EnqueueNative always re-posts — no lost wakeup. Renders are deferred by at most Normal.Count + 2 items plus the one outstanding RaiseRendering, and no new render work is produced while renders are deferred — no render starvation in the other direction.

WinUI parity

WinUI does not schedule rendering through CoreDispatcher's priority queues at all — the compositor rasterizes off-thread and CompositionTarget.Rendering is a vsync-paced UI-thread callback, so a running animation or a scrolling ScrollViewer can never prevent an idle callback from firing. Total idle starvation has no WinUI analogue and is plainly wrong against RunIdleAsync's contract, so this moves Uno toward parity. Routing renders through the dispatcher is Uno-specific (CompositionTarget.RenderScheduling.skia.cs:172), so this is a repair of an Uno invariant rather than a port of a WinUI mechanism — the genuinely WinUI-faithful fix is macOS frame pacing, tracked separately.

One bounded divergence is introduced knowingly: a frame can now be deferred behind up to 2 Low/Idle items, which WinUI would not do. That is why the share is capped rather than counting the whole backlog; a 2-item frame delay is far closer to WinUI than indefinite idle starvation. Once macOS frame pacing lands the budget rarely binds at all.

Blast radius

The changed region is inside #if __ANDROID__ || __WASM__ || __SKIA__ || __APPLE_UIKIT__ || IS_UNIT_TESTS, so it compiles for the maintenance-only native targets too. EnqueueRender has exactly one production caller (CompositionTarget.RenderScheduling.skia.cs:172, a .skia.cs file); on native Android, native iOS and native WASM _compositionTargets is never populated, TryGetRenderAction returns null immediately and the budget can never leave 0, so the change is inert there. Observable pacing change is concentrated on the unpaced hosts: macOS, FrameBuffer, Headless.

Validation

• Runtime (macOS Skia, SamplesApp.Skia.Generic, local): Given_NativeDispatcher.When_Render_Requested_Continuously_Then_Idle_Work_Runs fails on master, passes with the fix. Given_SystemFocusVisual (one of the classes that stalls in CI) passes 5/5.
• Runtime (unit tests): both new tests fail on master — "Idle work never ran (100 render actions over 100 dispatcher turns)" and "Idle work was starved by rendering (0 idle items, 30 renders)" — and pass with the fix.
• Compile: Uno.UI.Dispatching Skia, Wasm and Reference flavors clean. netcoremobile was not built locally; relying on CI.
• A full local macOS runtime-suite pass was not obtained — the run aborts in the HotReload tests because the spawned secondary app fails to load libicudata on this machine, unrelated to this change. Relying on CI for full-suite coverage; please check the macOS leg before merging.

PR Checklist ✅

• 🧪 Added Runtime tests, UI tests, or a manual test sample (for bug fixes / features, if applicable)
• 📚 Docs have been added/updated following the documentation template (for bug fixes / features)
• 🖼️ Validated PR Screenshots Compare Test Run results.
• ❗ Contains NO breaking changes
• 👀 Reviewed 2 other open pull requests (optional but appreciated!)