Contacts move back as smoothly as they move on

A snapshot timeline may declare spanMs: each record of a snapshot at a
time then carries its own fixes from spanMs before the time to spanMs
after it. Flights, military flights and vessels following the clock are
placed on those fixes, so a seek or a move back within the fixes loaded
is no jump: nothing is cleared and play does not wait. The step there is
asked for once and stands in for every contact; those it has keep their
place. Fixes are merged across snapshots at least 20 s apart, at most
240 a contact, and a contact is not drawn more than a minute before its
first fix.
This commit is contained in:
Sameh Khamis committed 2026-11-15 09:27:31 -08:00
1 parent b8a320edce
commit 2b5fb51684
27 files changed
+1377 -182

No files matched your search

+117 -10
View File
@@ -1,4 +1,5 @@
import { readSnapshotTimeline } from '../sources/live/contract.js';
import { TIMELINE_HELD_MS } from './timelineFixes.js';
/** The longest play waits on a snapshot before it goes on without it. */
export const SNAPSHOT_WAIT_MS = 8_000;
@@ -23,6 +24,16 @@ export const SNAPSHOT_RETRY_MS = 5_000;
* 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.
* - When the source's timeline declares `spanMs`, its records carry their
* fixes from `spanMs` before a snapshot's time to `spanMs` after it, and
* the layer places each contact on them by the clock. A seek or a move
* back that stays within the fixes the loaded snapshots carry is then no
* jump: nothing is cleared, play does not wait, and contacts move to the
* time smoothly. A move to a step before the newest loaded asks for that
* step once (`replace: true`): it brings back the contacts that left
* after it and drops those not there yet, while those it has keep their
* place, as their fixes put them. Paused, a time nearing the end of the
* fixes after the newest asks for the snapshot there (`replace: false`).
* - 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.
@@ -61,8 +72,11 @@ export function createSnapshotTimeline({
// 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.
// The times of the newest and oldest snapshots applied since the last jump.
let lead = null;
let base = null;
// The step a move back last asked for, until a newer snapshot applies.
let scrubbed = null;
// Cleared for a time outside coverage, so it is not cleared again.
let empty = false;
let waiting = null;
@@ -135,23 +149,27 @@ export function createSnapshotTimeline({
clear();
};
function request(atMs, replace) {
// `quiet`: a move within the loaded fixes, which shows the contacts
// already: play does not wait for it, and its failure clears nothing.
function request(atMs, replace, quiet = false) {
// 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 };
inflight = { atMs, controller, quiet };
const failed = () => {
inflight = null;
// A time that could not be shown shows nothing, not another time.
if (replace) clearOnce();
if (replace && !quiet) clearOnce();
// Asked again once the retry is due.
if (quiet) scrubbed = null;
capped = false;
stopWaiting();
failedUntil = now() + SNAPSHOT_RETRY_MS;
stopRetry();
retryTimer = setTimeout(() => {
retryTimer = null;
if (started) follow(clock.getState());
resume();
}, SNAPSHOT_RETRY_MS);
};
// The source dropped this request for a newer one of its own: nothing
@@ -159,10 +177,11 @@ export function createSnapshotTimeline({
// as the clock next moves, or shortly.
const superseded = () => {
inflight = null;
if (quiet) scrubbed = null;
stopRetry();
retryTimer = setTimeout(() => {
retryTimer = null;
if (started) follow(clock.getState());
resume();
}, SNAPSHOT_RETRY_MS);
};
Promise.resolve()
@@ -175,7 +194,7 @@ export function createSnapshotTimeline({
return;
}
inflight = null;
lead = atMs;
held(atMs, replace);
empty = false;
capped = false;
stopWaiting();
@@ -193,10 +212,87 @@ export function createSnapshotTimeline({
);
}
// The snapshot at `atMs` is applied: the stretch of snapshot times loaded
// (`base` to `lead`) takes it in. One the stretch does not reach with its
// fixes (play went on without waiting, far past the newest) starts it
// afresh: the contacts have no fixes for the time between. The stretch is
// kept to TIMELINE_HELD_MS, from the end just loaded, which every
// contact's fixes still cover.
function held(atMs, replace) {
const reach = 2 * (timeline.spanMs || 0);
scrubbed = null;
if (
replace ||
lead === null ||
atMs > lead + reach ||
atMs < base - reach
) {
lead = atMs;
base = atMs;
return;
}
lead = Math.max(lead, atMs);
base = Math.min(base, atMs);
if (lead - base <= TIMELINE_HELD_MS) return;
if (atMs === lead) base = lead - TIMELINE_HELD_MS;
else lead = base + TIMELINE_HELD_MS;
}
// Ask again for what the time needs, after a failure or a dropped load:
// a time within the loaded fixes may still need a snapshot near their end.
function resume() {
if (!started) return;
const state = clock.getState();
if (!state.live && wasActive && heldAt(state.timeMs))
scrubTo(state.timeMs, state);
else follow(state);
}
// Whether the fixes of the snapshots loaded since the last jump span the
// time, so contacts can be placed there without a jump.
const heldAt = (timeMs) =>
timeline.spanMs > 0 &&
lead !== null &&
base !== null &&
timeMs >= base - timeline.spanMs &&
timeMs <= lead + timeline.spanMs;
// The clock moved to a time the loaded fixes span: contacts move there as
// they are. A step before the newest loaded is asked for once, in place
// of every contact; paused, a time in the outer half of the fixes after
// the newest asks for the snapshot at its step, which brings those beyond.
function scrubTo(timeMs, state) {
const covered = span();
if (!covered) return;
if (!within(timeMs, covered)) {
cancel();
lead = null;
base = null;
setGate(null);
clearOnce();
return;
}
const half = timeline.spanMs / 2;
const step = Math.max(covered.start, stepAtOrBefore(timeMs));
if (step < lead) {
if (step !== scrubbed && now() >= failedUntil) {
scrubbed = step;
if (inflight?.atMs !== step) request(step, true, true);
}
return;
}
if (!playsOn(state) && timeMs > lead + half && step > lead) {
if (inflight?.atMs !== step && now() >= failedUntil) request(step, false);
return;
}
keepUp(timeMs, state);
}
// Show the time afresh: the snapshot at its step replaces every contact.
function jumpTo(timeMs) {
cancel();
lead = null;
base = null;
setGate(null);
const covered = span();
if (!covered) return;
@@ -215,12 +311,14 @@ export function createSnapshotTimeline({
if (!within(timeMs, covered)) {
cancel();
lead = null;
base = null;
setGate(null);
clearOnce();
return;
}
if (inflight) {
if (playsOn(state) && timeMs >= inflight.atMs) startWaiting();
if (playsOn(state) && timeMs >= inflight.atMs && !inflight.quiet)
startWaiting();
return;
}
if (now() < failedUntil) return;
@@ -246,7 +344,10 @@ export function createSnapshotTimeline({
return;
}
setGate(capped ? null : next);
request(next, false);
// Past what the loaded fixes reach (play went on without waiting), the
// contacts have no fixes for the time between: the step stands in for
// them all.
request(next, timeline.spanMs > 0 && next > lead + 2 * timeline.spanMs);
}
function follow(state) {
@@ -259,6 +360,7 @@ export function createSnapshotTimeline({
cancel();
setGate(null);
lead = null;
base = null;
empty = false;
failedUntil = -Infinity;
clear();
@@ -266,6 +368,8 @@ export function createSnapshotTimeline({
return;
}
const timeMs = state.timeMs;
// Away from live already: a move may stay within the loaded fixes.
const wasFollowing = wasActive;
const jumped =
!wasActive ||
state.jumps !== lastJumps ||
@@ -273,7 +377,8 @@ export function createSnapshotTimeline({
wasActive = true;
lastJumps = state.jumps;
lastTimeMs = timeMs;
if (jumped) {
if (jumped && wasFollowing && heldAt(timeMs)) scrubTo(timeMs, state);
else if (jumped) {
failedUntil = -Infinity;
jumpTo(timeMs);
} else keepUp(timeMs, state);
@@ -303,6 +408,7 @@ export function createSnapshotTimeline({
lastJumps = null;
lastTimeMs = null;
lead = null;
base = null;
empty = false;
failedUntil = -Infinity;
gated = undefined;
@@ -330,6 +436,7 @@ export function createSnapshotTimeline({
setGate(null);
wasActive = false;
lead = null;
base = null;
for (const release of releases.splice(0).reverse()) release();
timeline = null;
},