Merge origin/main: shipwrecks, news, transit fronts, signal-lost trails and uncredited photos on the renderer's ports

Upstream's layers and changes are carried onto the ports, with no Cesium
outside src/render and no reach into the viewer:

- Shipwrecks draw as one icon set, clicked through the input dispatcher.
- News draws through draw sets, the camera port and the input dispatcher;
  its beacons pulse each frame through the frame port.
- The scene occlusion probe moves into src/render/cesium and reaches
  detection through a new application hook, createOcclusionProbe; its
  private Cesium reads go through internals.js.
- Flight and military trails, the stale and SIGNAL LOST cue, coasting and
  following the world clock run on the draw and frame ports. GPU icons
  follow the scene clock while the world clock is followed, and fade when
  stale. A report that holds is not planned again every tick.
- Vessels are keyed by their record id.

The stub boot now enables military, shipwrecks and news as well.
This commit is contained in:
Sameh Khamis committed 2026-11-10 20:03:28 -08:00
commit a755f63638
331 files changed
+40654 -1666

No files matched your search

+337
View File
@@ -0,0 +1,337 @@
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);
}
/** Load the time shown afresh. */
function reloadShown() {
if (!started || clock.isLive()) return;
failedUntil = -Infinity;
jumpTo(clock.getState().timeMs);
}
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),
];
// A source tells of new coverage, or of a better answer for times it
// has answered; paused, a time already shown is loaded again.
const unsubscribe = timeline.subscribe?.(() => {
clock.coverageChanged();
if (!clock.isPlaying() && lead !== null && !inflight) reloadShown();
});
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: () => reloadShown(),
/** 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;
},
};
}
+336
View File
@@ -0,0 +1,336 @@
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);
});
test('a source that tells of a better answer has the paused time loaded again, not a playing one', async () => {
const h = harness();
h.follower.start();
const at = WALL - 600_000;
h.clock.seek(at);
await flush();
await h.answer();
const before = loads(h.calls).length;
for (const listener of h.coverageListeners) listener();
await flush();
assert.equal(loads(h.calls).length, before + 1);
assert.equal(loads(h.calls).at(-1).atMs, at);
await h.answer(h.pending.length - 1);
h.clock.play();
const playing = loads(h.calls).length;
for (const listener of h.coverageListeners) listener();
await flush();
assert.ok(
loads(h.calls)
.slice(playing)
.every((call) => call.atMs !== at),
'playing, the time shown is not loaded again',
);
h.clock.goLive();
await flush();
const live = loads(h.calls).length;
for (const listener of h.coverageListeners) listener();
await flush();
assert.equal(loads(h.calls).length, live, 'live, nothing is loaded');
h.follower.stop();
});
+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');
});