feat(live): flights, military and vessels follow the world clock when their source declares a timeline

A live source may now declare a timeline: it can answer a snapshot at a
given time (source.timeline = { coverage(), stepMs, subscribe? }, read by
readSnapshotTimeline). While such a layer is on it follows the world clock
and registers the coverage. At the live edge it polls exactly as before;
away from it the layer asks for getSnapshot({ ...query, atMs }) at the step
at or before the clock time and shows that snapshot instead of polling.

src/time/snapshotTimeline.js owns the following: a seek, time going
backwards or leaving live replaces every contact with the snapshot at the
new time (play waits on it, for at most 8 s); playing on keeps one
snapshot ahead and gates play on it, applying those snapshots as polls so
contacts move smoothly; outside coverage the layer is empty; back at live
it is cleared and polls at once. One load at a time, and a load the
source drops for a newer one is not a failure.

While following, aircraft are drawn at the clock time with no render
delay, records and absences are judged at the clock, track requests carry
atMs, and vessels move between fixes along the great circle. The world
clock counts jumps (seeks and returns to live) in getState().

A source with no timeline never follows the clock, and every layer stays
live, unchanged.
This commit is contained in:
Sameh Khamis committed 2026-11-10 18:12:53 -08:00
1 parent 962f7293c6
commit 57ff81f723
49 files changed
+2185 -239

No files matched your search

+37
View File
@@ -8,6 +8,15 @@
* getTrack(reference, { signal }). References are opaque to consumers.
* Snapshots describe coverage and completeness independently of freshness.
* Records contain observation data only, with no scene objects or transport data.
*
* A source may also declare a timeline (see readSnapshotTimeline): it can
* answer a snapshot at a given time, so the layer follows the world clock.
* The query then carries `atMs` (absent while the clock is live, so a live
* request is unchanged), and the snapshot is the world as it stood at that
* time: `observedAtMs` <= `atMs`, no record observed later than `atMs`,
* freshness and staleness judged against `atMs`, and `atMs` echoed back. A
* vessel snapshot at a time reports `transportStatus: 'live'`. getTrack then
* receives `{ signal, atMs }` and returns only points at or before `atMs`.
*/
// Messages are English data (AI tools read them too); the Layers panel shows
// them translated by their shape (translateFeedError in src/ui/statusText.js),
@@ -140,3 +149,31 @@ export function httpError(response, source) {
},
);
}
/**
* The timeline a source declares, or null when it has none or it is
* malformed: `{ coverage(), stepMs, subscribe? }`. `coverage()` returns the
* span `{start, end}` (epoch ms) the source can answer a snapshot for, or
* null while it does not know yet; `stepMs` is the spacing of its snapshots;
* the optional `subscribe(listener)` tells of a change in coverage and
* returns the unsubscribe.
* @param {object|null|undefined} source
* @returns {{coverage: () => ({start: number, end: number}|null),
* stepMs: number, subscribe: ((listener: () => void) => () => void)|null}|null}
*/
export function readSnapshotTimeline(source) {
const timeline = source?.timeline;
if (!timeline || typeof timeline !== 'object') return null;
if (typeof timeline.coverage !== 'function') return null;
const stepMs = timeline.stepMs;
if (!Number.isFinite(stepMs) || stepMs <= 0) return null;
if (timeline.subscribe != null && typeof timeline.subscribe !== 'function')
return null;
return {
coverage: () => timeline.coverage(),
stepMs,
subscribe: timeline.subscribe
? (listener) => timeline.subscribe(listener)
: null,
};
}