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

+329
View File
@@ -0,0 +1,329 @@
import { readSnapshotTimeline } from '../sources/live/contract.js';
/** The longest play waits on a snapshot before it goes on without it. */
export const SNAPSHOT_WAIT_MS = 8_000;
/** How long a snapshot that failed to load waits before it is asked again. */
export const SNAPSHOT_RETRY_MS = 5_000;
/**
* Let a layer of live contacts (flights, military aircraft, vessels) follow
* the world clock when, and only when, its source declares a timeline: it can
* answer a snapshot at a given time (see readSnapshotTimeline). With no
* timeline this does nothing at all: the layer never follows the clock and
* stays live.
*
* While the layer is on, it follows the clock. At the live edge the layer
* polls as it always has. Away from it the layer is `active()`: it stops
* polling and shows the snapshots this asks for.
*
* - A jump (a seek, time going backwards, leaving live) drops what loads,
* holds play, and asks for the snapshot at the step at or before the time;
* `load(atMs, {signal, replace: true})` puts it in place of every contact.
* - Playing on, it stays a snapshot ahead of the time: it asks for the next
* step as the clock nears the newest it has, and play does not pass a
* snapshot still loading (for at most SNAPSHOT_WAIT_MS). Those snapshots
* are applied as polls are (`replace: false`), so contacts move on smoothly.
* - Outside the source's coverage the layer is `clear()`ed and nothing loads;
* while the coverage is not known yet nothing loads and nothing is cleared.
* - Back at live, the layer is `clear()`ed and `resumeLive()` polls at once.
*
* `load` resolves true once the snapshot is applied and false (or rejects)
* when it could not be; it must not apply anything once `signal` aborts. A
* rejection named AbortError is a request the source dropped for a newer
* one: it is not a failure, and nothing is cleared.
*
* @param {{id: string, clock: ReturnType<typeof import('./worldClock.js').createWorldClock>,
* source: () => object|null,
* load: (atMs: number, options: {signal: AbortSignal, replace: boolean}) => Promise<boolean>,
* clear: () => void, resumeLive: () => void,
* now?: () => number, setTimeout?: typeof globalThis.setTimeout,
* clearTimeout?: typeof globalThis.clearTimeout}} options `source`
* returns the layer's current source; it is read when the layer starts.
*/
export function createSnapshotTimeline({
id,
clock,
source,
load,
clear,
resumeLive,
now = () => globalThis.performance.now(),
setTimeout = globalThis.setTimeout,
clearTimeout = globalThis.clearTimeout,
}) {
let timeline = null;
let releases = [];
let started = false;
// Whether the layer was away from live when it last heard of the clock.
let wasActive = false;
let lastJumps = null;
let lastTimeMs = null;
// Each request's number; an answer to an older one is dropped.
let sequence = 0;
let inflight = null;
// The time of the newest snapshot applied since the last jump.
let lead = null;
// Cleared for a time outside coverage, so it is not cleared again.
let empty = false;
let waiting = null;
let waitTimer = null;
// Play waited its longest on the snapshot loading: it goes on without it.
let capped = false;
let gated;
let failedUntil = -Infinity;
let retryTimer = null;
const span = () => {
let covered;
try {
covered = timeline.coverage();
} catch (error) {
console.error(`Snapshot coverage failed: ${id}`, error);
return null;
}
return covered &&
Number.isFinite(covered.start) &&
Number.isFinite(covered.end) &&
covered.end >= covered.start
? covered
: null;
};
const within = (timeMs, covered) =>
timeMs >= covered.start && timeMs <= covered.end;
const stepAtOrBefore = (timeMs) =>
Math.floor(timeMs / timeline.stepMs) * timeline.stepMs;
const playsOn = (state) => state.playing && !state.stepping;
const setGate = (ms) => {
if (ms === gated) return;
gated = ms;
clock.gate(id, ms);
};
const stopWaiting = () => {
const release = waiting;
waiting = null;
if (waitTimer !== null) clearTimeout(waitTimer);
waitTimer = null;
release?.();
};
const startWaiting = () => {
if (waiting || capped) return;
waiting = clock.wait(id);
waitTimer = setTimeout(() => {
waitTimer = null;
capped = true;
stopWaiting();
setGate(null);
}, SNAPSHOT_WAIT_MS);
};
const stopRetry = () => {
if (retryTimer !== null) clearTimeout(retryTimer);
retryTimer = null;
};
// Drop what loads; nothing that answers afterwards applies.
const cancel = () => {
sequence += 1;
inflight?.controller.abort();
inflight = null;
capped = false;
stopWaiting();
stopRetry();
};
const clearOnce = () => {
if (empty) return;
empty = true;
clear();
};
function request(atMs, replace) {
// One load at a time: an older one is dropped before a newer starts.
inflight?.controller.abort();
const mine = ++sequence;
const controller = new AbortController();
inflight = { atMs, controller };
const failed = () => {
inflight = null;
// A time that could not be shown shows nothing, not another time.
if (replace) clearOnce();
capped = false;
stopWaiting();
failedUntil = now() + SNAPSHOT_RETRY_MS;
stopRetry();
retryTimer = setTimeout(() => {
retryTimer = null;
if (started) follow(clock.getState());
}, SNAPSHOT_RETRY_MS);
};
// The source dropped this request for a newer one of its own: nothing
// failed, so nothing is cleared or held back; the time is asked for again
// as the clock next moves, or shortly.
const superseded = () => {
inflight = null;
stopRetry();
retryTimer = setTimeout(() => {
retryTimer = null;
if (started) follow(clock.getState());
}, SNAPSHOT_RETRY_MS);
};
Promise.resolve()
.then(() => load(atMs, { signal: controller.signal, replace }))
.then(
(applied) => {
if (mine !== sequence || controller.signal.aborted) return;
if (applied === false) {
failed();
return;
}
inflight = null;
lead = atMs;
empty = false;
capped = false;
stopWaiting();
follow(clock.getState());
},
(error) => {
if (mine !== sequence || controller.signal.aborted) return;
if (error?.name === 'AbortError') {
superseded();
return;
}
console.warn(`Snapshot at ${atMs} failed: ${id}`, error);
failed();
},
);
}
// Show the time afresh: the snapshot at its step replaces every contact.
function jumpTo(timeMs) {
cancel();
lead = null;
setGate(null);
const covered = span();
if (!covered) return;
if (!within(timeMs, covered)) {
clearOnce();
return;
}
startWaiting();
request(Math.max(covered.start, stepAtOrBefore(timeMs)), true);
}
// The time moved on by itself, or nothing moved: load what it now needs.
function keepUp(timeMs, state) {
const covered = span();
if (!covered) return;
if (!within(timeMs, covered)) {
cancel();
lead = null;
setGate(null);
clearOnce();
return;
}
if (inflight) {
if (playsOn(state) && timeMs >= inflight.atMs) startWaiting();
return;
}
if (now() < failedUntil) return;
if (lead === null) {
jumpTo(timeMs);
return;
}
if (!playsOn(state)) {
setGate(null);
return;
}
const step = timeline.stepMs;
if (lead - timeMs >= step) {
setGate(lead);
return;
}
const next = Math.min(
covered.end,
Math.max(lead + step, stepAtOrBefore(timeMs) + step),
);
if (next <= lead) {
setGate(null);
return;
}
setGate(capped ? null : next);
request(next, false);
}
function follow(state) {
if (!started) return;
if (state.live) {
lastJumps = state.jumps;
lastTimeMs = null;
if (!wasActive) return;
wasActive = false;
cancel();
setGate(null);
lead = null;
empty = false;
failedUntil = -Infinity;
clear();
resumeLive();
return;
}
const timeMs = state.timeMs;
const jumped =
!wasActive ||
state.jumps !== lastJumps ||
(lastTimeMs !== null && timeMs < lastTimeMs);
wasActive = true;
lastJumps = state.jumps;
lastTimeMs = timeMs;
if (jumped) {
failedUntil = -Infinity;
jumpTo(timeMs);
} else keepUp(timeMs, state);
}
return {
/** The source's timeline while the layer follows the clock, else null. */
get timeline() {
return started ? timeline : null;
},
/** Whether the layer shows the snapshots this loads instead of polling. */
active: () => started && !clock.isLive(),
/** The layer is on: follow the clock if its source declares a timeline. */
start() {
if (started) return;
timeline = readSnapshotTimeline(source());
if (!timeline) return;
started = true;
wasActive = false;
lastJumps = null;
lastTimeMs = null;
lead = null;
empty = false;
failedUntil = -Infinity;
gated = undefined;
releases = [
clock.hold(id),
clock.register({ id, coverage: () => span() }),
clock.subscribe(follow),
];
const unsubscribe = timeline.subscribe?.(() => clock.coverageChanged());
if (typeof unsubscribe === 'function') releases.push(unsubscribe);
follow(clock.getState());
},
/** Load the time shown afresh, as when the area the layer asks for moved. */
reload() {
if (!started || clock.isLive()) return;
failedUntil = -Infinity;
jumpTo(clock.getState().timeMs);
},
/** The layer is off: stop following and drop what loads. */
stop() {
if (!started) return;
started = false;
cancel();
setGate(null);
wasActive = false;
lead = null;
for (const release of releases.splice(0).reverse()) release();
timeline = null;
},
};
}
+304
View File
@@ -0,0 +1,304 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createWorldClock } from './worldClock.js';
import {
createSnapshotTimeline,
SNAPSHOT_RETRY_MS,
SNAPSHOT_WAIT_MS,
} from './snapshotTimeline.js';
const STEP = 10_000;
const WALL = Date.UTC(2026, 10, 1, 12);
function harness({ timeline = true, coverage } = {}) {
const t = {
wall: WALL,
mono: 1_000,
timers: new Map(),
nextId: 1,
};
const clock = createWorldClock({
now: () => t.wall,
monotonicNow: () => t.mono,
setInterval: () => 0,
clearInterval: () => {},
requestFrame: null,
cancelFrame: null,
});
let span =
coverage === undefined ? { start: WALL - 3_600_000, end: WALL } : coverage;
const coverageListeners = new Set();
const source = {
getSnapshot() {},
...(timeline && {
timeline: {
coverage: () => span,
stepMs: STEP,
subscribe(listener) {
coverageListeners.add(listener);
return () => coverageListeners.delete(listener);
},
},
}),
};
const calls = [];
const pending = [];
const timers = {
setTimeout: (fn, ms) => {
const id = t.nextId++;
t.timers.set(id, { fn, at: t.mono + ms });
return id;
},
clearTimeout: (id) => t.timers.delete(id),
};
const follower = createSnapshotTimeline({
id: 'flights',
clock,
source: () => source,
load: (atMs, { signal, replace }) =>
new Promise((resolve, reject) => {
calls.push({ type: 'load', atMs, replace });
pending.push({ atMs, replace, signal, resolve, reject });
}),
clear: () => calls.push({ type: 'clear' }),
resumeLive: () => calls.push({ type: 'live' }),
now: () => t.mono,
...timers,
});
return {
t,
clock,
follower,
calls,
pending,
setCoverage(next) {
span = next;
for (const listener of coverageListeners) listener();
},
coverageListeners,
advance(ms) {
t.wall += ms;
t.mono += ms;
for (const [id, timer] of [...t.timers]) {
if (timer.at > t.mono) continue;
t.timers.delete(id);
timer.fn();
}
},
async answer(index = 0, value = true) {
pending.splice(index, 1)[0].resolve(value);
await flush();
},
};
}
const flush = () => new Promise((resolve) => setImmediate(resolve));
const loads = (calls) => calls.filter((call) => call.type === 'load');
test('a source with no timeline never follows the clock nor asks for a time', async () => {
const h = harness({ timeline: false });
h.follower.start();
assert.equal(h.follower.timeline, null);
assert.equal(h.clock.follows('flights'), false);
assert.equal(h.clock.coverage(), null);
h.clock.seek(WALL - 600_000);
h.clock.play();
h.advance(30_000);
h.clock.goLive();
await flush();
assert.equal(h.follower.active(), false);
assert.deepEqual(h.calls, []);
h.follower.stop();
});
test('at the live edge a layer with a timeline only follows and registers', async () => {
const h = harness();
h.follower.start();
await flush();
assert.equal(h.clock.follows('flights'), true);
assert.deepEqual(h.clock.coverage(), {
start: WALL - 3_600_000,
end: WALL,
marks: [],
});
assert.equal(h.follower.active(), false);
assert.deepEqual(h.calls, []);
h.follower.stop();
assert.equal(h.clock.follows('flights'), false);
assert.equal(h.clock.coverage(), null);
});
test('a seek asks for the step at or before the time, holding play while it loads', async () => {
const h = harness();
h.follower.start();
const at = WALL - 600_000 + 4_321;
h.clock.seek(at);
await flush();
assert.equal(h.follower.active(), true);
assert.deepEqual(loads(h.calls), [
{ type: 'load', atMs: WALL - 600_000, replace: true },
]);
h.clock.play();
h.advance(2_000);
assert.equal(h.clock.now(), at, 'play waits on the snapshot');
assert.equal(h.clock.getState().buffering, true);
await h.answer();
assert.equal(h.clock.getState().buffering, false);
h.follower.stop();
});
test('a seek back replaces the contacts and an older answer is dropped', async () => {
const h = harness();
h.follower.start();
h.clock.seek(WALL - 600_000);
await flush();
const first = h.pending[0];
h.clock.seek(WALL - 1_200_000);
await flush();
assert.equal(first.signal.aborted, true, 'the older load is cancelled');
first.resolve(true);
await flush();
assert.deepEqual(
loads(h.calls).map(({ atMs, replace }) => [atMs, replace]),
[
[WALL - 600_000, true],
[WALL - 1_200_000, true],
],
);
await h.answer(1);
// Going backwards in time is a jump too, even without a seek.
h.clock.seek(WALL - 1_300_000);
await flush();
assert.equal(loads(h.calls).at(-1).replace, true);
h.follower.stop();
});
test('playing on asks for the next step and play does not pass it unloaded', async () => {
const h = harness();
h.follower.start();
const at = WALL - 600_000;
h.clock.seek(at);
await flush();
await h.answer();
h.clock.play();
h.advance(100);
// A tick: the clock tells its listeners as play goes on.
h.clock.coverageChanged();
await flush();
assert.deepEqual(loads(h.calls).at(-1), {
type: 'load',
atMs: at + STEP,
replace: false,
});
h.advance(STEP * 2);
assert.equal(h.clock.now(), at + STEP, 'gated at the step still loading');
h.clock.coverageChanged();
assert.equal(h.clock.getState().buffering, true);
await h.answer(h.pending.length - 1);
assert.equal(h.clock.getState().buffering, false);
assert.deepEqual(loads(h.calls).at(-1), {
type: 'load',
atMs: at + 2 * STEP,
replace: false,
});
// A step that never comes holds play for at most SNAPSHOT_WAIT_MS.
h.advance(STEP * 2);
h.clock.coverageChanged();
assert.equal(h.clock.getState().buffering, true);
h.advance(SNAPSHOT_WAIT_MS);
assert.equal(h.clock.getState().buffering, false);
h.advance(1_000);
assert.ok(h.clock.now() > at + 2 * STEP, 'play went on without it');
h.follower.stop();
});
test('a failed snapshot clears the time and is asked again later', async () => {
const h = harness();
h.follower.start();
h.clock.seek(WALL - 600_000);
await flush();
await h.answer(0, false);
assert.deepEqual(h.calls.at(-1), { type: 'clear' });
assert.equal(loads(h.calls).length, 1);
h.advance(SNAPSHOT_RETRY_MS);
await flush();
assert.equal(loads(h.calls).length, 2);
assert.equal(loads(h.calls)[1].replace, true);
h.follower.stop();
});
test('outside coverage the layer is cleared and nothing loads; unknown coverage waits', async () => {
const h = harness({ coverage: null });
h.follower.start();
h.clock.seek(WALL - 600_000);
await flush();
assert.deepEqual(h.calls, [], 'no coverage yet: nothing loads or clears');
h.setCoverage({ start: WALL - 3_600_000, end: WALL });
await flush();
assert.deepEqual(loads(h.calls), [
{ type: 'load', atMs: WALL - 600_000, replace: true },
]);
await h.answer();
h.clock.seek(WALL - 7_200_000);
await flush();
assert.deepEqual(h.calls.at(-1), { type: 'clear' });
assert.equal(loads(h.calls).length, 1);
h.follower.stop();
assert.equal(h.coverageListeners.size, 0);
});
test('back at live the layer is cleared and polls at once', async () => {
const h = harness();
h.follower.start();
h.clock.seek(WALL - 600_000);
await flush();
const inflight = h.pending[0];
h.clock.goLive();
await flush();
assert.equal(inflight.signal.aborted, true);
assert.deepEqual(h.calls.slice(-2), [{ type: 'clear' }, { type: 'live' }]);
assert.equal(h.follower.active(), false);
h.follower.stop();
});
test('a load the source drops for a newer one is no failure: nothing clears, it is asked again', async () => {
const h = harness();
h.follower.start();
h.clock.seek(WALL - 600_000);
await flush();
h.pending
.shift()
.reject(new DOMException('Superseded by a newer request', 'AbortError'));
await flush();
assert.equal(
h.calls.some((call) => call.type === 'clear'),
false,
'the layer keeps what it shows',
);
assert.equal(loads(h.calls).length, 1);
h.advance(SNAPSHOT_RETRY_MS);
await flush();
assert.equal(loads(h.calls).length, 2, 'the time is asked for again');
assert.equal(loads(h.calls)[1].replace, true);
h.follower.stop();
});
test('a layer never has two loads out: the older is aborted before a newer starts', async () => {
const h = harness();
h.follower.start();
const live = () => h.pending.filter(({ signal }) => !signal.aborted).length;
h.clock.seek(WALL - 600_000);
await flush();
await h.answer();
h.clock.play();
await flush();
assert.equal(live(), 1, 'the next step loads');
h.follower.reload();
await flush();
assert.equal(live(), 1, 'a reload drops it first');
h.clock.seek(WALL - 900_000);
await flush();
assert.equal(live(), 1, 'a seek drops it first');
assert.equal(h.pending.length, 3);
h.follower.stop();
assert.equal(live(), 0);
});
+14 -4
View File
@@ -8,8 +8,10 @@
* clock holds a cursor, fixed or playing. Only the layers that follow the clock
* move with the cursor; the rest keep reading the live edge through
* `timeFor(id)`. On the page's clock the layers whose data has a time of its
* own (the sky, satellites, launches and weather) follow it; live feeds such
* as flights and vessels have no time to move to and stay live.
* own (the sky, satellites, launches and weather) follow it. Flights,
* military aircraft and vessels follow it only when their source declares a
* timeline, that is, can answer a snapshot at a given time (see
* src/time/snapshotTimeline.js); otherwise they stay live.
*
* Playback is continuous (`cursor + elapsed × rate`) unless a driver takes
* it: weather replay steps its observed frames itself and moves the clock as
@@ -64,6 +66,9 @@ export function createWorldClock({
let anchorMono = 0;
let rate = 1;
let playing = false;
// How many times the cursor has jumped (a seek, a return to live), so a
// layer can tell a jump from the cursor playing on.
let jumps = 0;
// The driver handle stepping the clock, or null.
let active = null;
let ticker = null;
@@ -118,6 +123,7 @@ export function createWorldClock({
buffering: continuous() && buffering(),
following: followedIds(),
supported: isSupported(),
jumps,
});
// Each listener hears the state as it is when called. A change made from
// inside a listener notifies everyone afresh, and the outer round stops, so
@@ -182,6 +188,7 @@ export function createWorldClock({
live = false;
cursorMs = ms;
anchorMono = monotonicNow();
jumps += 1;
changed();
},
/** Back to the wall clock; playback stops and its rate goes back to 1. */
@@ -193,6 +200,7 @@ export function createWorldClock({
playing = false;
active = null;
rate = 1;
jumps += 1;
// Its driven(false) finds nothing left to stop.
stepping?.driver.pause();
changed();
@@ -300,8 +308,10 @@ export function createWorldClock({
active = handle;
playing = true;
live = false;
if (Number.isFinite(atMs)) cursorMs = atMs;
else cursorMs ??= now();
if (Number.isFinite(atMs)) {
cursorMs = atMs;
jumps += 1;
} else cursorMs ??= now();
anchorMono = monotonicNow();
if (previous && previous !== handle) previous.driver.pause();
changed();
+21
View File
@@ -387,3 +387,24 @@ test('playing, listeners hear of the time every animation frame', () => {
clock.pause();
assert.equal(frames.size, 0);
});
test('a seek or a return to live counts as a jump; play does not', () => {
const t = fakeTime();
const clock = createWorldClock(t.options);
assert.equal(clock.getState().jumps, 0);
clock.seek(t.wall - 60_000);
assert.equal(clock.getState().jumps, 1);
clock.seek(t.wall - 60_000);
assert.equal(clock.getState().jumps, 1, 'the same paused time is no jump');
clock.play();
t.advance(1_000);
t.timers.forEach(({ fn }) => fn());
assert.equal(clock.getState().jumps, 1, 'playing on is no jump');
clock.pause();
clock.setRate(4);
assert.equal(clock.getState().jumps, 1);
clock.goLive();
assert.equal(clock.getState().jumps, 2);
clock.goLive();
assert.equal(clock.getState().jumps, 2, 'already live is no jump');
});