This pull request refactors the throttle utility in packages/utils/src/lib/throttle.ts, used in throttleToNextFrame.

Fixes a case where the timeout could fire too often (or irregularly) due to the saving up of overflow ms.
Fixes a case where the timeout could fire too late due to a second raf.

How it works

Overflow

Previously, when tick recognized that 16ms or more of time had elapsed since the previous tick, it would stash any additional ms for next time. So for example a frame with a 18ms would cause the tick to run, with the "extra" 2ms stashed for next time, so that a following frame at 14ms would cause the tick to run again. This is intended to make the tick more regular, however it can also produce ticks that, being too close together, seemed to lead to make long frames harder to recover from. I think it's more important that ticks are no less than 16ms apart.

Double frames

The throttleToNextFrame helper could previously double-raf its callback.

Previously, the tick function puts its flush call behind a raf so that it occurs on the next frame. However, combined with the logic for enforcing the FPS, this meant that tick() could be delayed first by "too soon" raf, then again by the "next frame" raf, even though the "too soon" raf also would satisfy the "are we on the next frame" requirement.

Normal healthy behavior :

frame 1, 0ms = tick, raf for flush
frame 2, 8ms =  flush

Problem behavior. Because tick2 was "between ticks", it got delayed to frame 3, and then again to frame 4; from the perspective of its called, it should have run on frame 3.

frame 1, 0ms = tick1, raf for flush1
frame 2, 8ms =  flush1, tick2 (too soon), raf for tick3
frame 3, 16ms = tick3 from raf, raf for flush2
frame 4, 24ms = flush2

This is presuming that throttleToNextFrame is really about the next frame and not about the next tick, which I think is correct.

But why

I was looking at how tldraw recovered from long frames, and digging deeper into the performance tab, I was seeing ticks where I wasn't expecting them: either adjacent to other ticks (with less than 16ms between them) and then not in other places.

Change type

• bugfix

Test plan

• Unit tests
• End to end tests

Release notes

• Improved the timer to create more reliable frame updates