Idle frame rate in the app, timed line batching, KEY REQUIRED status

Three fixes to how the globe draws and reports loading.

**The idle frame rate is the app's rule.** The Cesium frame port capped the loop at `IDLE_FRAME_RATE` whenever nothing held it, so the rule lived inside the renderer. The render governor now sets the rate: the display's own while the loop is held, `IDLE_FRAME_RATE` while not. The frame port gains `onHeldChange(cb)`, which says when its first hold is taken and its last released (animated visual styles included), so the governor hears every hold. The quality setting's frame-rate cap is kept apart from the governor's rate, and the loop draws at the lower of the two, so neither overwrites the other.

**Line batching is timed.** A line set waited 30 drawn frames before its unchanged lines settled into a static batch (300 for the long wait), so the batch built twice as fast at 120 Hz as at 60 Hz, and took seconds at the idle rate. It now waits `SETTLE_MS` (500 ms) and `LONG_SETTLE_MS` (5 s), and moved shapes go back into their batches on the same timing.

**KEY REQUIRED.** A layer that cannot load without a provider key ended the global status chip LOAD FAILED. The chip now has a KEY REQUIRED outcome, ranked below a real failure: a layer whose stats say `keyRequired` ends KEY REQUIRED, any other failure still ends LOAD FAILED. Vessels report a missing AISStream key as `keyRequired` and name the key in the panel; a later outage clears it, as it is no longer the key that is missing.

Checked: the full suite (new tests for `onHeldChange`, the quality cap against the governor's rate, timed settling, and the chip with and without a key), format, boundaries, build, the stub renderer boot and the Cesium conformance run; in the browser, the idle and held frame rates; and the first-run check now asserts that with no keys set the chip never says LOAD FAILED.
This commit is contained in:
Sameh Khamis committed 2026-11-16 14:10:01 -08:00
1 parent 84d3e7b5ce
commit 0ed6cde956
33 files changed
+629 -179

No files matched your search

+27 -7
View File
@@ -29,12 +29,15 @@
* short stable strings ('flights', 'traffic', 'style-anim', …) so the
* diagnostics read like a story.
*
* Frame rate: in continuous mode the loop draws at the display's own
* refresh rate. In idle mode the renderer's frame port ticks it at most at
* IDLE_FRAME_RATE, because Cesium still ticks the clock, data sources and
* every pre/post-update listener once per animation frame even when it skips
* the draw. Camera movement takes a 'camera' hold from `moveStart` to
* `moveEnd`, so drags and flights run at the full rate too.
* Frame rate: while the loop is held it draws at the display's own refresh
* rate; while nothing holds it, the governor caps it at IDLE_FRAME_RATE,
* because Cesium still ticks the clock, data sources and every
* pre/post-update listener once per animation frame even when it skips the
* draw. The frame port says when its first hold is taken and its last
* released (`onHeldChange`), the renderer's own holds included (animated
* visual styles), so those draw at the full rate too. Camera movement takes
* a 'camera' hold from `moveStart` to `moveEnd`, so drags and flights run at
* the full rate as well.
*
* The governor is O(1) passive: no per-frame work of its own, ever.
*/
@@ -50,6 +53,13 @@ let _frame = null;
const _holds = new Map();
/** Removes the camera move listeners added at install. */
let _removeCameraListeners = null;
/** Stops hearing the installed port's holds. */
let _offHeldChange = null;
/** The loop's rate: the display's while held, IDLE_FRAME_RATE while not. */
function applyRate(held) {
_frame?.setTargetFps(held ? 0 : IDLE_FRAME_RATE);
}
/** Debug trail of the most recent one-shot render requests (idle mode only). */
const _recentRequests = [];
@@ -163,14 +173,20 @@ export function installRenderGovernor(
clearTimeout: unschedule = globalThis.clearTimeout,
} = {},
) {
if (typeof frame?.holdContinuous !== 'function')
if (
typeof frame?.holdContinuous !== 'function' ||
typeof frame.onHeldChange !== 'function'
)
throw new TypeError('installRenderGovernor requires a frame port');
_removeCameraListeners?.();
_removeCameraListeners = null;
releaseContinuousRender('camera');
if (_frame !== frame) {
if (_frame) releaseFrameHolds();
_offHeldChange?.();
_frame = frame;
_offHeldChange = frame.onHeldChange(applyRate);
applyRate(frame.diagnostics().holds.length > 0);
for (const ownerId of _holds.keys()) holdOnFrame(ownerId);
}
_removeCameraListeners = watchCameraMotion(camera, { schedule, unschedule });
@@ -247,6 +263,8 @@ export function uninstallRenderGovernor(frame) {
_removeCameraListeners?.();
_removeCameraListeners = null;
releaseFrameHolds();
_offHeldChange?.();
_offHeldChange = null;
_frame = null;
_holds.clear();
_recentRequests.length = 0;
@@ -256,6 +274,8 @@ export function uninstallRenderGovernor(frame) {
export function _resetRenderGovernorForTest() {
_removeCameraListeners?.();
_removeCameraListeners = null;
_offHeldChange?.();
_offHeldChange = null;
_frame = null;
_holds.clear();
_recentRequests.length = 0;