Files
gods-eye-view/src/loadingFeedback.js
T
Sameh Khamis 0ed6cde956 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.
2026-11-16 14:10:01 -08:00

505 lines
16 KiB
JavaScript

import { installationFeedback } from './data/installationFeedback.js';
export const LOADING_REVEAL_DELAY_MS = 160;
export const LOADING_TERMINAL_DWELL_MS = 2200;
export const LOADING_FAILURE_DWELL_MS = 5000;
export const LOADING_LONG_THRESHOLD_MS = 30000;
export const TRAFFIC_SYNC_CONFIRM_MS = 1500;
/** Layer statuses that are user guidance, not feed faults (see manager.js layerFeedState). */
export const GUIDANCE_STATUSES = Object.freeze(['zoom-in', 'empty', 'idle']);
function finiteCount(value) {
const number = Number(value);
return Number.isFinite(number) && number >= 0 ? number : 0;
}
/** Normalize one manager layer into a small loading-feedback record. */
export function normalizeLayerLoading(layer = {}) {
const stats = layer.stats || {};
const lifecycleState = String(
layer.lifecycleState || (layer.enabled ? 'enabled' : 'disabled'),
);
const status = String(stats.status || '').toLowerCase();
const disabling = lifecycleState === 'disabling';
const loading =
lifecycleState === 'enabling' ||
disabling ||
stats.loading === true ||
stats.refreshing === true;
const count = finiteCount(stats.count);
const stoppingInstallations =
['military-installations', 'alpr-cameras'].includes(layer.id) && disabling;
// Guidance statuses ask the user to act (zoom in, run a search). They are
// normal operation, never a batch failure — mirrors layerFeedState's carve-out
// so a prompt stored alongside the status cannot turn the chip red.
const guidance = GUIDANCE_STATUSES.includes(status);
const error = stoppingInstallations
? null
: (!guidance && stats.error) ||
stats.lastError ||
stats.managerRefreshError ||
null;
const unavailable =
!stoppingInstallations &&
(stats.unavailable === true ||
stats.available === false ||
['unavailable', 'offline', 'down', 'error'].includes(status));
const keyRequired = stats.keyRequired === true || stats.missingKey === true;
const degraded = stats.degraded === true || Boolean(error);
const accepted = Boolean(stats.lastUpdate) || count > 0;
return {
id: String(layer.id || ''),
label: String(layer.name || layer.id || 'Layer'),
loading,
disabling,
refresh:
loading && layer.enabled && (stats.refreshing === true || accepted),
lifecycleState,
count,
accepted,
error,
unavailable,
keyRequired,
degraded,
cameraRetry:
layer.id === 'alpr-cameras' && layer.enabled && !disabling
? {
retryAt: Number(stats.retryAt) || 0,
retrying: stats.retrying === true,
error,
}
: null,
installationRetry:
layer.id === 'military-installations' && layer.enabled && !disabling
? {
retryAt: Number(stats.retryAt) || 0,
retrying: stats.retrying === true,
failureReason: stats.failureReason,
loading,
status: stats.status,
}
: null,
};
}
/**
* A batch's ending from its layers' stats: a layer that failed fails it; a
* layer only waiting for its provider key (whose error is that missing key)
* ends it KEY REQUIRED, which asks the user to act rather than reporting a
* fault.
*/
function terminalFromParticipantStats(summary, participantIds) {
if (!participantIds?.length) return null;
const participants = new Set(participantIds);
let keyRequired = false;
for (const record of summary.records) {
if (!participants.has(record.id)) continue;
if (record.keyRequired) keyRequired = true;
else if (record.error || record.unavailable) return 'error';
}
return keyRequired ? 'key-required' : null;
}
/** Aggregate all manager layers without changing their lifecycle authority. */
export function aggregateLayerLoading(layers = []) {
const records = layers.map(normalizeLayerLoading);
const active = records.filter((record) => record.loading);
const disabling =
active.length > 0 && active.every((record) => record.disabling);
return {
records,
active,
activeIds: active.map((record) => record.id),
disabling,
refresh:
!disabling &&
active.length > 0 &&
active.every((record) => record.refresh),
};
}
export function createLoadingFeedbackState() {
return {
phase: 'idle',
visible: false,
startedAt: 0,
showAt: 0,
hideAt: 0,
activeIds: [],
batchOutcome: null,
terminal: null,
operation: null,
};
}
/** Create a top-center status notice, optionally persistent until explicitly cleared. */
export function createGlobalStatusNotice(
message,
nowMs = 0,
{ state = 'error', detail = '', persistent = false } = {},
) {
const label = String(message || '').trim();
if (!label) return null;
return {
state,
label,
detail: String(detail || '').trim(),
persistent: !!persistent,
dwellMs: persistent ? null : LOADING_FAILURE_DWELL_MS,
// A finite notice starts its dwell only when it first wins presentation.
// Otherwise a higher-priority manager failure could consume the whole
// deadline while this notice remained queued and invisible.
hideAt: null,
};
}
/** Present a top-center status notice until its deadline or explicit clearing. */
export function presentGlobalStatusNotice(notice, nowMs = 0) {
const now = Number.isFinite(nowMs) ? nowMs : 0;
if (!notice?.label) return null;
if (!notice.persistent && !Number.isFinite(notice.hideAt)) {
notice.hideAt =
now +
(Number.isFinite(notice.dwellMs)
? notice.dwellMs
: LOADING_FAILURE_DWELL_MS);
}
if (Number.isFinite(notice.hideAt) && now >= notice.hideAt) return null;
return {
state: notice.state || 'error',
label: notice.label,
detail: notice.detail || '',
};
}
/** Whether deferred notice work still owns the current presentation epoch. */
export function canPresentDeferredStatusNotice(
expectedGeneration,
currentGeneration,
disposed = false,
) {
return (
!disposed &&
Number.isSafeInteger(expectedGeneration) &&
expectedGeneration === currentGeneration
);
}
/**
* Present the shared status surface without allowing a persistent notice to
* hide a terminal manager failure. Failure dwell starts when the manager
* reports it, so it must remain the highest-priority presentation while live.
*/
export function presentGlobalLoadingStatus(
notice,
loadingState,
summary,
nowMs = 0,
) {
const loadingPresentation = presentLoadingFeedback(
loadingState,
summary,
nowMs,
);
if (['error', 'retry'].includes(loadingPresentation?.state))
return loadingPresentation;
return presentGlobalStatusNotice(notice, nowMs) || loadingPresentation;
}
/** Create the sampled Street Traffic chip state. */
export function createTrafficSyncFeedbackState() {
return {
busy: false,
visible: false,
confirmationUntil: 0,
label: '',
progressText: '',
};
}
/**
* Reduce one sampled Street Traffic status without extending completion on
* every animation-loop poll. Coverage describes accepted data, not work.
*/
export function reduceTrafficSyncFeedback(
previous,
{ enabled = false, stats = {}, forceShow = false } = {},
nowMs = 0,
) {
const state = previous || createTrafficSyncFeedbackState();
const now = Number.isFinite(nowMs) ? nowMs : 0;
if (!enabled) return createTrafficSyncFeedbackState();
const hasProgress = Number.isFinite(stats.phaseProgressPct);
const progressPct = hasProgress
? Math.max(0, Math.min(100, Math.round(stats.phaseProgressPct)))
: stats.loading
? 1
: 100;
const busy =
stats.loading === true ||
stats.worldJumping === true ||
(hasProgress && (progressPct < 100 || (stats.prewarmQueueDepth ?? 0) > 0));
const label = String(stats.phaseLabel || stats.loadingLabel || '').trim();
if (busy) {
return {
busy: true,
visible: true,
confirmationUntil: 0,
// Neutral default: the layer always supplies its own LIVE/SIMULATED
// label, and a fallback string must never claim a live feed on a
// keyless build.
// i18n-ignore: translated in src/ui/shellFeedback.js
label: label || 'syncing road network',
progressText: hasProgress ? `${progressPct}%` : '...',
};
}
const existingConfirmation =
state.confirmationUntil > now ? state.confirmationUntil : 0;
const confirmationUntil =
existingConfirmation ||
(state.busy || forceShow ? now + TRAFFIC_SYNC_CONFIRM_MS : 0);
const visible =
confirmationUntil > now && progressPct >= 100 && Boolean(label);
return {
busy: false,
visible,
confirmationUntil: visible ? confirmationUntil : 0,
label: visible ? label : '',
// The settled flash carries NO progress number. A settled chip is 100% by
// definition — the value never varied — and printing it beside a label
// that already ends in a real measurement produced the self-contradicting
// "LIVE · TomTom flow · 0% cov 100%". Coverage is the honest number, so
// it is the only one left standing; the progress slot belongs to work in
// flight.
progressText: '',
};
}
/**
* A lifecycle event's ending. A layer that failed only for want of its
* provider key (its stats say `keyRequired`) ends KEY REQUIRED on every
* load or refresh, not just the first.
*/
function terminalFromEvent(event, summary) {
const type = String(event?.type || '');
if (type === 'visibility-failed' || type === 'refresh-failed' || event?.error)
return summary?.records?.some(
(record) => record.id === event?.layerId && record.keyRequired,
)
? 'key-required'
: 'error';
if (type === 'visibility-cancelled' || event?.cancelled) return 'cancelled';
if (type === 'visibility' || type === 'refresh') return 'complete';
return null;
}
function mergeTerminalOutcome(current, next) {
const severity = { complete: 1, cancelled: 2, 'key-required': 3, error: 4 };
if (!next) return current || null;
if (!current || severity[next] > severity[current]) return next;
return current;
}
/** Reduce a sampled manager summary into delayed, non-flashing UI state. */
export function reduceLoadingFeedback(previous, summary, nowMs, event = null) {
const state = previous || createLoadingFeedbackState();
const now = Number.isFinite(nowMs) ? nowMs : 0;
if (summary.active.length) {
const beginning = state.phase !== 'loading';
const startedAt = beginning ? now : state.startedAt;
const priorParticipants = beginning ? [] : state.activeIds;
const activeIds = [
...new Set([...priorParticipants, ...summary.activeIds]),
];
const eventLayerId = String(event?.layerId || '');
const eventParticipates = eventLayerId && activeIds.includes(eventLayerId);
const batchOutcome = mergeTerminalOutcome(
mergeTerminalOutcome(
beginning ? null : state.batchOutcome,
terminalFromParticipantStats(summary, activeIds),
),
eventParticipates ? terminalFromEvent(event, summary) : null,
);
return {
phase: 'loading',
visible: !beginning && now >= state.showAt,
startedAt,
showAt: beginning ? now + LOADING_REVEAL_DELAY_MS : state.showAt,
hideAt: 0,
activeIds,
batchOutcome,
terminal: null,
operation: summary.disabling
? 'disabling'
: summary.refresh
? 'refresh'
: 'loading',
failedEventIds: [
...new Set([
...(beginning ? [] : state.failedEventIds || []),
...(eventParticipates && terminalFromEvent(event, summary) === 'error'
? [eventLayerId]
: []),
]),
],
};
}
if (state.phase === 'loading') {
const eventLayerId = String(event?.layerId || '');
const eventParticipates =
eventLayerId && state.activeIds.includes(eventLayerId);
const terminal =
mergeTerminalOutcome(
mergeTerminalOutcome(
state.batchOutcome,
terminalFromParticipantStats(summary, state.activeIds),
),
eventParticipates ? terminalFromEvent(event, summary) : null,
) || 'complete';
const wasVisible = state.visible || now >= state.showAt;
if (!wasVisible && terminal === 'complete')
return createLoadingFeedbackState();
const dwell =
terminal === 'error' || terminal === 'key-required'
? LOADING_FAILURE_DWELL_MS
: LOADING_TERMINAL_DWELL_MS;
return {
...state,
phase: 'terminal',
visible: true,
hideAt: now + dwell,
batchOutcome: terminal,
terminal,
failedEventIds: [
...new Set([
...(state.failedEventIds || []),
...(eventParticipates && terminalFromEvent(event, summary) === 'error'
? [eventLayerId]
: []),
]),
],
};
}
if (state.phase === 'terminal' && now < state.hideAt) return state;
return createLoadingFeedbackState();
}
/** Build the user-facing status copy for the current loading state. */
export function presentLoadingFeedback(state, summary, nowMs) {
const camera = summary.records.find(
(record) => record.cameraRetry?.retryAt > 0,
);
const otherCameraFailure =
summary.records.some(
(record) =>
record.id !== 'alpr-cameras' &&
(state?.activeIds || []).includes(record.id) &&
(record.error || record.unavailable || record.keyRequired),
) || (state?.failedEventIds || []).some((id) => id !== 'alpr-cameras');
if (camera && !summary.active.length && !otherCameraFailure) {
const seconds = Math.max(
0,
Math.ceil((camera.cameraRetry.retryAt - Date.now()) / 1000),
);
return {
state: 'retry',
// i18n-ignore: translated in src/ui/shellFeedback.js
label: (
camera.cameraRetry.error || 'Overpass temporarily unavailable'
).toUpperCase(),
detail: `ALPR cameras · ${seconds ? `retrying in ${seconds}s` : 'retry pending'}`,
};
}
const site = summary.records.find(
(record) => record.installationRetry?.retryAt > 0,
);
const otherFailure =
summary.records.some(
(record) =>
record.id !== 'military-installations' &&
(state?.activeIds || []).includes(record.id) &&
(record.error || record.unavailable || record.keyRequired),
) ||
(state?.failedEventIds || []).some((id) => id !== 'military-installations');
// Keep the actual retry visible between attempts, without hiding another
// participant's failure or pretending that a scheduled retry is fetching.
if (site && !summary.active.length && !otherFailure) {
const message = installationFeedback(site.installationRetry);
const [label, detail] = message.split(' — ');
return { state: 'retry', label: label.toUpperCase(), detail: detail || '' };
}
if (!state?.visible) return null;
if (state.phase === 'terminal') {
const labels = {
complete: 'LOAD COMPLETE',
cancelled: 'LOAD CANCELLED',
'key-required': 'KEY REQUIRED',
error: 'LOAD FAILED',
};
const label =
state.operation === 'disabling' && state.terminal === 'complete'
? 'LIVE DATA OFF'
: state.terminal === 'complete' &&
state.activeIds?.length === 1 &&
state.activeIds[0] === 'military-installations'
? 'MAPPED SITES LOADED'
: labels[state.terminal] || 'LOAD COMPLETE';
return { state: state.terminal, label, detail: '' };
}
const active = summary.active;
if (active.length === 1 && active[0].cameraRetry && !summary.disabling) {
return {
state: 'loading',
// i18n-ignore: translated in src/ui/shellFeedback.js
label: active[0].cameraRetry.retrying
? 'RETRYING ALPR CAMERAS'
: 'FETCHING ALPR CAMERAS',
detail: 'OpenStreetMap · Overpass',
};
}
if (
active.length === 1 &&
active[0].installationRetry &&
!summary.disabling
) {
return {
state: 'loading',
// i18n-ignore: translated in src/ui/shellFeedback.js
label: active[0].installationRetry.retrying
? 'RETRYING MAPPED SITES'
: 'FETCHING MAPPED SITES',
detail: 'OpenStreetMap · Overpass',
};
}
const elapsed = Math.max(0, nowMs - state.startedAt);
const label = summary.disabling
? 'TURNING OFF LIVE DATA'
: summary.refresh
? 'REFRESHING LIVE DATA'
: 'LOADING LIVE DATA';
const names = active
.slice(0, 2)
.map((record) => record.label)
.join(' · ');
const suffix = active.length > 2 ? ` +${active.length - 2}` : '';
return {
state:
elapsed >= LOADING_LONG_THRESHOLD_MS
? 'long'
: summary.disabling
? 'disabling'
: summary.refresh
? 'refresh'
: 'loading',
label,
detail: `${names}${suffix}`,
};
}