[SPIKE] settled(): await settledness instead of polling for it

addon/src/settled.ts

@@ -1,15 +1,55 @@
-// @ts-ignore: this is private API. This import will work Ember 5.1+ since it
-// "provides" this public API, but does not for earlier versions. As a result,
-// this type will be `any`.
-import { _backburner } from '@ember/runloop';
+import {
+  macroCondition,
+  dependencySatisfies,
+  importSync,
+} from '@embroider/macros';
 import { Test } from 'ember-testing';
 
 import { nextTick } from './-utils.ts';
-import waitUntil from './wait-until.ts';
 import { hasPendingTransitions } from './setup-application-context.ts';
-import { hasPendingWaiters } from '@ember/test-waiters';
+import { buildWaiter, hasPendingWaiters } from '@ember/test-waiters';
+import * as testWaiters from '@ember/test-waiters';
 import type DebugInfo from './-internal/debug-info.ts';
 import { TestDebugInfo } from './-internal/debug-info.ts';
+import renderSettled from './-internal/render-settled.ts';
+
+// This is private API. Runloop-less builds of ember-source (the RFC 957
+// spikes) do not export `_backburner` at all, so it is read off the module
+// namespace -- a missing export degrades to `undefined` here instead of a
+// build-time missing-export error in consuming apps.
+const _backburner: any = (importSync('@ember/runloop') as any)._backburner;
+
+// Ember builds that schedule rendering without the runloop report the
+// EDGES of rendering work (pending / complete) rather than exposing a
+// pollable flag. Bridging those edges into a test waiter folds rendering
+// into the same settledness protocol as every other async source: it
+// needs no clause of its own in `isSettled` below, and a render that
+// never completes is reported by name in test-waiter debug output.
+const renderWaiter = buildWaiter('@ember/test-helpers:render');
+let renderWaiterToken: unknown = null;
+
+const usesRenderWaiter = (() => {
+  if (macroCondition(dependencySatisfies('ember-source', '>=4.5.0-beta.1'))) {
+    const renderer = importSync('@ember/renderer') as any;
+
+    if (typeof renderer._onRenderSettledChange === 'function') {
+      renderer._onRenderSettledChange((pending: boolean) => {
+        if (pending) {
+          renderWaiterToken ??= renderWaiter.beginAsync();
+        } else if (renderWaiterToken !== null) {
+          const token = renderWaiterToken;
+
+          renderWaiterToken = null;
+          renderWaiter.endAsync(token);
+        }
+      });
+
+      return true;
+    }
+  }
+
+  return false;
+})();
 
 let requests: XMLHttpRequest[];
 const checkWaiters = Test.checkWaiters;
@@ -139,15 +179,17 @@ export interface SettledState {
   @returns {Object} object with properties for each of the metrics used to determine settledness
 */
 export function getSettledState(): SettledState {
-  const hasPendingTimers = _backburner.hasTimers();
-  const hasRunLoop = Boolean(_backburner.currentInstance);
+  const hasPendingTimers = _backburner ? _backburner.hasTimers() : false;
+  const hasRunLoop = _backburner ? Boolean(_backburner.currentInstance) : false;
   const hasPendingLegacyWaiters = checkWaiters();
   const hasPendingTestWaiters = hasPendingWaiters();
   const pendingRequestCount = pendingRequests();
   const hasPendingRequests = pendingRequestCount > 0;
-  // TODO: Ideally we'd have a function in Ember itself that can synchronously identify whether
-  // or not there are any pending render operations, but this will have to suffice for now
-  const isRenderPending = !!hasRunLoop;
+  // On runloop-driven builds, a pending render is observable as backburner's
+  // autorun instance. Scheduler-driven builds report render edges into the
+  // render waiter above, so a pending render is already counted in
+  // `hasPendingTestWaiters` -- reporting it here too would double-count it.
+  const isRenderPending = usesRenderWaiter ? false : !!hasRunLoop;
 
   return {
     hasPendingTimers,
@@ -209,6 +251,91 @@ export function isSettled(): boolean {
   @public
   @returns {Promise<void>} resolves when settled
 */
-export default function settled(): Promise<void> {
-  return waitUntil(isSettled, { timeout: Infinity }).then(() => {});
+/**
+ * Waiter completion is announced by `@ember/test-waiters` versions that
+ * export `waitersSettled`; older ones are pull-only, and the fallback
+ * tick below drives the loop instead.
+ *
+ * @private
+ */
+const maybeWaitersSettled = (
+  testWaiters as unknown as { waitersSettled?: () => Promise<unknown> }
+).waitersSettled;
+
+const waitersSettled: (() => Promise<unknown>) | null =
+  typeof maybeWaitersSettled === 'function' ? maybeWaitersSettled : null;
+
+/**
+ * How long the fallback tick waits.
+ *
+ * When waiters announce completion, this tick is a safety net for the
+ * sources that cannot: `Waiter` implementations written against the
+ * interface directly, legacy `Ember.Test.registerWaiter` callbacks, and
+ * request counters. It must then comfortably exceed a frame, because a
+ * render tick can be frame-paced -- at 10ms it beat rendering to the
+ * race often enough to decide a quarter of all iterations (measured 30
+ * of 117), costing an extra pass each time; at 50ms it decided 1 of 92.
+ *
+ * Without waiter notification it is the loop's only clock, so it stays
+ * at the cadence the previous `waitUntil`-based implementation used.
+ *
+ * @private
+ */
+const FALLBACK_MS = waitersSettled === null ? 10 : 50;
+
+function fallbackTick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, FALLBACK_MS));
+}
+
+/**
+ * Resolves when no waiter is pending, on versions that can tell us.
+ * Otherwise never resolves, leaving the fallback tick to drive.
+ *
+ * @private
+ */
+function waitersQuiet(): Promise<unknown> {
+  return waitersSettled === null ? new Promise(() => {}) : waitersSettled();
+}
+
+/**
+ * Yields to the task queue, so quiet is observed from a macrotask.
+ *
+ * @private
+ */
+function macrotask(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+export default async function settled(): Promise<void> {
+  // Settledness is awaited rather than polled: rendering resolves
+  // `renderSettled()` when it completes, and waiters resolve
+  // `waitersSettled()` from the operations' own completion promises. The
+  // fallback tick is raced alongside them only to cover sources that
+  // cannot announce completion -- when everything announces, it never
+  // decides anything.
+  //
+  // Two properties this loop must preserve:
+  //
+  // 1. Quiet is confirmed FROM A MACROTASK. Task sources that are
+  //    already queued (worker messages, zero-delay timers) may register
+  //    waiters or dirty tracked state, and an observation made in
+  //    microtask context would win the race against them and settle
+  //    early. The previous waitUntil-based implementation imposed this
+  //    boundary implicitly by scheduling every check via setTimeout.
+  //
+  // 2. It re-checks. Completing the work that was pending can start
+  //    more of it, so one pass proves nothing; the loop runs until a
+  //    pass observes everything quiet.
+  for (;;) {
+    await Promise.race([
+      Promise.all([renderSettled(), waitersQuiet()]),
+      fallbackTick(),
+    ]);
+
+    await macrotask();
+
+    if (isSettled()) {
+      return;
+    }
+  }
 }