[mattcosta7]

Summary

Safari has no native requestIdleCallback, so apply() installs this polyfill there. Today each callback runs as a setTimeout(0) with a 50 ms budget counted from when it was scheduled, so "idle" work can run between an event handler and the next paint. Event Timing reports that time as INP presentation delay.

GitHub RUM (macOS desktop, 14 days): Safari INP p90 is 159 ms vs Chrome 88 ms. This polyfill explains part of that tail, not all of it.

After this PR: callbacks run after the next paint, each in its own MessageChannel task, within a shared 10 ms budget per frame.

Native implementations, the exports and apply() are unchanged.

What changes for consumers

	Before	After
When callbacks run	0 ms timer, can land before paint	After the next paint (requestAnimationFrame, then a task)
Idle time per frame	Unbounded	10 ms of wall-clock time, shared by all pending callbacks
Yielding	n/a	One callback per task, so input, rendering, timers and promise continuations run between callbacks
timeRemaining()	50 ms from scheduling	Time left in a 5 ms slice (or the 10 ms period if shorter). Never more than 5 ms
options.timeout	didTimeout always true when no timeout was set	didTimeout: true and timeRemaining() === 0 if the timeout fires first, otherwise false
Hidden tabs	n/a	No rAF, so periods are posted as timer tasks at least 100 ms apart
rAF never arrives (for example a display:none cross-origin iframe)	n/a	After 250 ms the period is posted as a task
null options	threw	Accepted, like native

One spec deviation: callbacks queued during a period run in a later task of the same 10 ms budget, not the next period. Otherwise a self-rescheduling queue gets one callback per frame (measured 0.4-0.5x throughput, no INP gain).

Safari has no scheduler.postTask, scheduler.yield or isInputPending (MDN browser-compat-data), so rAF, MessageChannel and setTimeout are all that's available. If Safari ships postTask, a background-priority backend would be better.

Evidence

Real Safari 27.2 (safaridriver, in-page synthetic clicks, 3 x 25 per cell). Percentage of frames over 20 ms:

Shape	No idle queue	Base	This PR
100 ms click handler	9.8%	58.8%	9.4%
Heavy layout	6.7%	76.9%	2.1%
Many short-timeout callbacks	0.2%	18.4%	17.4%

Also in real Safari: microtask order matches native (A A-micro B), and idle time per frame is 9 ms (base: up to 98 ms). A backgrounded tab running a self-requeuing queue was busy for 1.9 s of a ~3.5 s window before the 100 ms hidden gap and 171 ms after (base: 21 ms).

Playwright WebKit (click INP with a background idle queue, measured on 1106ad1, not re-run on this head): no queue 16 ms, old polyfill 64 ms, this design 16 ms. With competing foreground work, a 40 x 5 ms task chain finished in about 300 ms vs 1400-2100 ms with the old polyfill.

Tests: npm test passes (lint, tsc, 126 tests, about 50 for this polyfill), stable over repeated runs. Tests drive animation frames by hand and use microtask probes to prove callbacks run in separate tasks. A second-model review plus browser probes of an earlier revision drove the one-callback-per-task, 250 ms fallback, late-request and Symbol timeout fixes, each covered by a test.

Tradeoffs and risks

• Throughput: on Safari, idle work completes at about 52-69% of the old polyfill's rate (measured on 1106ad1). The old one got its throughput by not being idle. Consumers with a lot of idle work will finish later, and idle work waits for the next frame (about 16 ms at 60 Hz).
• Smaller budget: timeRemaining() is at most 5 ms. Loops that check it stay correct. Code that does fixed-size work regardless can overrun, as with native. A callback that defers whenever timeRemaining() <= 5 always defers.
• Timeouts are not budgeted: a callback whose timeout expires runs in its own timer task, as native does, so queues of short-timeout callbacks still delay frames. This PR is no better than base there. Don't use short timeouts for non-urgent work.
• Cheap self-requeuing callbacks run hundreds of times per frame (about 400 in Chromium, about 26 in WebKit), and a throwing self-requeuer fires far more error events than before.
• Stalled-frame fallback: 250 ms is a guess at "rAF is not coming". It is exercised in Chromium only. WebKit and real Safari ran these cases within 1 ms either way.
• Not tested: iOS Safari, real pointer input through WebDriver (too unreliable to use), and production traffic. Watch Safari INP p75/p90, presentation delay and request-to-run delay after release. Rollback is a revert and re-release.

Not in this PR

• Version bump and release.
• Consumer-side changes such as moving telemetry flushes off idle callbacks.

[Copilot]

🟡 Changes recommended

A native-only assertion fails in targeted WebKit environments without requestIdleCallback, while timeout handling can strand callbacks and scheduling can violate FIFO ordering.

4 open issues

• Skip the native-only test when requestIdleCallback is absent · New
• Stop the period at the oldest unpainted request · New
• Normalize and cap timeouts before registering callbacks · New
• Avoid assuming multiple callbacks fit in one frame · New

What changed in this PR

Reworks the requestIdleCallback polyfill to reduce pre-paint idle work in browsers without native support, particularly Safari. Native implementations remain unchanged.

Changes:

• Schedules callbacks in separate tasks after a frame, sharing a 10 ms wall-clock budget with 5 ms callback deadlines.
• Adds timeout management, cancellation across scheduling stages, and fallbacks for hidden documents or stalled frames.
• Expands tests for scheduling, deadlines, callback ordering, cancellation, and fallback behavior.

File	Description
test/​requestidlecallback.js	Adds manual-frame controls and extensive scheduling, timeout, cancellation, and fallback tests.
src/​requestidlecallback.ts	Implements shared idle periods, task-based callback execution, and scheduling fallbacks.

_{Review effort: Max}