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

+43
View File
@@ -8,6 +8,20 @@
* 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.
* Every record has a stable `id` (a non-empty string) that keys it across
* snapshots. A vessel record's `id` is whatever its source gives, such as a
* provider id; its `mmsi` is an optional attribute ('' or absent when
* unknown), never its key, since vessels can share an MMSI. A source that
* only has MMSIs uses the MMSI as the id.
*
* 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 +154,32 @@ 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, or of a
* better answer for a time already answered (a paused layer then loads the
* time shown again), 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,
};
}
+174
View File
@@ -8,6 +8,8 @@ import {
normalizeVesselObservation,
openSkySnapshot,
readsbSnapshot,
readSnapshotTimeline,
vesselSnapshot,
} from './index.js';
const now = 1800000000000;
@@ -195,6 +197,7 @@ test('vessel identity, opaque reference and heading/course remain distinct, unkn
'opaque-reference',
);
assert.equal(row.id, '123456789');
assert.equal(row.mmsi, '123456789');
assert.equal(row.reference, 'opaque-reference');
assert.equal(row.headingDeg, 45);
assert.equal(row.courseDeg, 60);
@@ -412,3 +415,174 @@ test('squawks are validated and omitted OpenSky status differs from an explicit
assert.equal(quiet.squawk, null);
assert.equal(quiet.emergency, null);
});
test('a photo enrichment asks Planespotters directly and returns the checked photo', async () => {
const requests = [];
const source = createFlightSource({
fetchImpl: async (url, init) => {
requests.push({ url, init });
return response({
photos: [
{
thumbnail_large: {
src: 'https://t.plnspttrs.net/33043/1745410_822dfe330c_280.jpg',
size: { width: 420, height: 280 },
},
link: 'https://www.planespotters.net/photo/1745410/x?utm_source=api',
photographer: 'Jan Seler',
},
],
});
},
});
const signal = new AbortController().signal;
const photo = await source.getEnrichment(
{ kind: 'photo', id: 'a0f1bb' },
{ signal },
);
assert.equal(
requests[0].url,
'https://api.planespotters.net/pub/photos/hex/a0f1bb',
);
assert.ok(requests[0].init.signal, 'the request is cancellable');
assert.equal(requests[0].init.credentials, 'omit');
assert.deepEqual(photo, {
found: true,
src: 'https://t.plnspttrs.net/33043/1745410_822dfe330c_280.jpg',
width: 420,
height: 280,
photographer: 'Jan Seler',
link: 'https://www.planespotters.net/photo/1745410/x?utm_source=api',
});
});
test('a photo enrichment reads an empty answer as no photo and refuses a bad hex', async () => {
let calls = 0;
const source = createFlightSource({
fetchImpl: async (_url, _init) => {
calls++;
return response({ photos: [] });
},
});
assert.deepEqual(
await source.getEnrichment({ kind: 'photo', id: 'a0f1bb' }),
{ found: false },
);
await assert.rejects(source.getEnrichment({ kind: 'photo', id: '../x' }), {
code: 'unsupported',
});
assert.equal(calls, 1);
});
test('a photo enrichment outage rejects without echoing the body', async () => {
for (const status of [403, 429, 502]) {
const source = createFlightSource({
fetchImpl: async () => response({ error: 'sensitive' }, {}, status),
});
await assert.rejects(
source.getEnrichment({ kind: 'photo', id: 'a0f1bb' }),
(error) => {
assert.equal(error.status, status);
assert.equal(error.message.includes('sensitive'), false);
return true;
},
);
}
});
test('a source declares a timeline only with a coverage reader and a positive step', () => {
assert.equal(readSnapshotTimeline(null), null);
assert.equal(readSnapshotTimeline({ getSnapshot() {} }), null);
assert.equal(readSnapshotTimeline({ timeline: { stepMs: 10_000 } }), null);
assert.equal(
readSnapshotTimeline({ timeline: { coverage: () => null, stepMs: 0 } }),
null,
);
assert.equal(
readSnapshotTimeline({
timeline: { coverage: () => null, stepMs: 10_000, subscribe: 'no' },
}),
null,
);
const span = { start: 1000, end: 5000 };
const plain = readSnapshotTimeline({
timeline: { coverage: () => span, stepMs: 10_000 },
});
assert.equal(plain.stepMs, 10_000);
assert.deepEqual(plain.coverage(), span);
assert.equal(plain.subscribe, null);
const listeners = [];
const told = readSnapshotTimeline({
timeline: {
coverage: () => null,
stepMs: 5_000,
subscribe(listener) {
listeners.push(listener);
return () => listeners.splice(listeners.indexOf(listener), 1);
},
},
});
const stop = told.subscribe(() => {});
assert.equal(listeners.length, 1);
stop();
assert.equal(listeners.length, 0);
});
test('vessel snapshots key rows by the id idFor gives; the MMSI is an attribute', () => {
const at = { lat: 30, lon: -97 };
const rows = [
{ uuid: 'hull-a', mmsi: '123456789', ...at },
{ uuid: 'hull-b', mmsi: '123456789', ...at },
{ uuid: 'hull-c', mmsi: 'not-an-mmsi', ...at },
{ uuid: 'hull-a', mmsi: '123456789', ...at },
];
const keyed = vesselSnapshot(
{ rows },
{ idFor: (row) => row.uuid || row.mmsi },
);
assert.deepEqual(
keyed.records.map(({ id, mmsi, reference }) => [id, mmsi, reference]),
[
['hull-a', '123456789', 'hull-a'],
['hull-b', '123456789', 'hull-b'],
['hull-c', '', 'hull-c'],
],
);
assert.equal(keyed.rejectedCount, 1, 'a repeated id is one vessel');
// AISStream rows have only MMSIs: one MMSI is one vessel, as before.
const ais = vesselSnapshot({ rows });
assert.deepEqual(
ais.records.map(({ id, mmsi, reference }) => [id, mmsi, reference]),
[
['123456789', '123456789', '123456789'],
['not-an-mmsi', '', 'not-an-mmsi'],
],
);
const referenced = vesselSnapshot(
{ rows: rows.slice(0, 1) },
{ idFor: (row) => row.uuid, referenceFor: (row) => `track:${row.uuid}` },
);
assert.equal(referenced.records[0].reference, 'track:hull-a');
});
test('a vessel with no name is not named by its id; a ten-digit MMSI is an MMSI', () => {
const at = { lat: 30, lon: -97 };
const [unnamed, longMmsi, named] = vesselSnapshot(
{
rows: [
{ uuid: 'f00dcafe-0000-0000-0000-000000000001', ...at },
{ uuid: 'hull-x', mmsi: '1234567890', ...at },
{ uuid: 'hull-y', mmsi: '244123456', name: 'EVER GIVEN', ...at },
],
},
{ idFor: (row) => row.uuid },
).records;
assert.equal(unnamed.name, '');
assert.equal(unnamed.mmsi, '');
assert.deepEqual(
[longMmsi.mmsi, longMmsi.name],
['1234567890', '1234567890'],
);
assert.equal(named.name, 'EVER GIVEN');
});
+1 -1
View File
@@ -1,4 +1,4 @@
export { LiveSourceError } from './contract.js';
export { LiveSourceError, readSnapshotTimeline } from './contract.js';
export {
normalizeOpenSkyAircraft,
normalizeReadsbAircraft,
+29
View File
@@ -11,10 +11,37 @@ import {
readsbIdentities,
} from './aircraft.js';
import { normalizeVesselTrack, vesselSnapshot } from './vessels.js';
import { parsePlanespottersPhoto } from '../../data/planespottersPhoto.js';
const defaultFetch = (...args) => globalThis.fetch(...args);
const header = (response, name) => response.headers?.get?.(name);
/** Planespotters' public photo lookup, called straight from the browser (it
* answers with `access-control-allow-origin: *`). */
const PLANESPOTTERS_PHOTOS = 'https://api.planespotters.net/pub/photos/hex/';
/** A photo is decoration: a slow answer gives up rather than hold an
* enrichment slot. */
const PHOTO_TIMEOUT_MS = 8000;
/** The tracked plane's Planespotters photo, read and host-checked. */
async function planespottersPhoto(fetchImpl, hex, signal) {
const id = String(hex || '').toLowerCase();
if (!/^[0-9a-f]{6}$/.test(id))
throw new LiveSourceError('unsupported', 'Enrichment unavailable');
const timeout = AbortSignal.timeout(PHOTO_TIMEOUT_MS);
const { response, payload } = await readResponse(
fetchImpl,
PLANESPOTTERS_PHOTOS + id,
{
signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
credentials: 'omit',
},
'Planespotters',
);
if (!response.ok) throw httpError(response, 'Planespotters');
return parsePlanespottersPhoto(payload);
}
function openSkyError(response) {
const error = httpError(response, 'Flights');
const mode = String(
@@ -106,6 +133,8 @@ export function createFlightSource({
};
},
async getEnrichment(query, { signal } = {}) {
if (query.kind === 'photo')
return planespottersPhoto(fetchImpl, query.id, signal);
if (!['type', 'route'].includes(query.kind))
throw new LiveSourceError('unsupported', 'Enrichment unavailable');
const { response, payload } = await readResponse(
+47 -10
View File
@@ -1,18 +1,41 @@
import { coordinates, epoch, finite, LiveSourceError } from './contract.js';
/** AIS positions are sea-surface observations; heading and course are distinct. */
export function normalizeVesselObservation(row, reference = null) {
const id = String(row?.mmsi || row?.input_identifier || '').trim();
/** An MMSI is up to ten digits (AIS carries it in 30 bits); anything else a
* row names it is not one. */
const MMSI_PATTERN = /^\d{1,10}$/;
/** The row's MMSI when it carries one that looks like an MMSI, else ''. */
function vesselMmsi(row) {
const text = String(row?.mmsi ?? '').trim();
return MMSI_PATTERN.test(text) ? text : '';
}
/** A row's stable id when its source names none: its MMSI or identifier. */
function defaultVesselId(row) {
return String(row?.mmsi || row?.input_identifier || '');
}
/**
* AIS positions are sea-surface observations; heading and course are distinct.
* `id` is the vessel's key; an MMSI is not one (vessels share numbers and a
* number can move to another hull), so `mmsi` is an attribute, '' when the
* row has none. A row with no id of its own is keyed by its MMSI.
*/
export function normalizeVesselObservation(row, reference = null, id = null) {
const key = String(id ?? defaultVesselId(row)).trim();
const latitude = finite(row?.lat),
longitude = finite(row?.lon);
if (!id || !coordinates(latitude, longitude)) return null;
if (!key || !coordinates(latitude, longitude)) return null;
const mmsi = vesselMmsi(row);
const speedKts = finite(row.speed);
return {
id,
reference: reference ?? id,
id: key,
mmsi,
reference: reference ?? key,
latitude,
longitude,
name: String(row.name || row.input_name || id),
// A source's own id is not a name: a vessel with none is unnamed.
name: String(row.name || row.input_name || mmsi || defaultVesselId(row)),
imo: String(row.imo || ''),
type: String(row.type_specific || row.type || ''),
destination: String(row.destination || ''),
@@ -26,12 +49,21 @@ export function normalizeVesselObservation(row, reference = null) {
};
}
/**
* A vessel snapshot from a `{ rows }` payload. `idFor(row)` gives a row's
* stable id (its MMSI or identifier by default); rows are deduped by that id,
* so two vessels sharing an MMSI stay two vessels. A source whose rows carry
* an id of their own passes it, such as `idFor: (row) => row.uuid || row.mmsi`.
* `referenceFor(row)` gives the reference its track is asked for by; the id
* by default.
*/
export function vesselSnapshot(
payload,
{
source = 'AISStream',
coverage = 'received AIS positions',
referenceFor = (row) => String(row.mmsi || row.input_identifier || ''),
idFor = defaultVesselId,
referenceFor = null,
} = {},
) {
if (!Array.isArray(payload?.rows))
@@ -40,8 +72,13 @@ export function vesselSnapshot(
const records = [],
ids = new Set();
for (const row of rows) {
const record = normalizeVesselObservation(row);
if (record) record.reference = referenceFor(row);
const record = normalizeVesselObservation(
row,
null,
row && typeof row === 'object' ? idFor(row) : null,
);
// A row's track is asked for by its id unless the source says otherwise.
if (record && referenceFor) record.reference = referenceFor(row);
if (record && !ids.has(record.id)) {
records.push(record);
ids.add(record.id);