Keep tracked-entity state in app records instead of on Cesium entities

Flights, military, satellites, installations, local ADS-B and ALPR hung
gevTrackedId, gevDisplayPosition, gevVisualPosition, gevSelectionOrigin and
gevLabelModel on the Cesium entities they draw, and the tracked readout,
follow camera, cockpit, share links and awareness read them back. They now
live in src/data/entityRecords.js, an app-owned record per entity: layers
write entityRecord(entity), readers use readEntityRecord(entity). Nothing
changes on screen. This is the first slice of the renderer plan's state
mirror (P1).

The module is exported as ./data/entity-records so callers can read the
same records, and window.__godsEyeView.entityRecords gives the QA scripts
the same access from the page.
This commit is contained in:
Sameh Khamis committed 2026-11-03 08:09:00 -08:00
1 parent ea69bb4ce2
commit 65587f6c08
53 files changed
+408 -291

No files matched your search

+9 -8
View File
@@ -23,6 +23,7 @@ import {
alprLabelDetails,
validAlprGroundHeight,
} from './visuals.js';
import { entityRecord, readEntityRecord } from '../../data/entityRecords.js';
export function createAlprPresentation({ state, services, source }) {
const { governorRequestRender } = services.render;
@@ -236,11 +237,10 @@ export function createAlprPresentation({ state, services, source }) {
entity.billboard.width = entity.billboard.height = selected
? SELECTED_MARKER_ICON_SIZE
: MARKER_ICON_SIZE;
if (entity.gevLabelModel) {
entity.gevLabelModel.accent = color.toCssColorString();
entity.gevLabelModel.leaderAnimationStartedAt = selected
? selectionStartedAt
: 0;
const labelModel = readEntityRecord(entity)?.labelModel;
if (labelModel) {
labelModel.accent = color.toCssColorString();
labelModel.leaderAnimationStartedAt = selected ? selectionStartedAt : 0;
}
}
@@ -425,13 +425,14 @@ export function createAlprPresentation({ state, services, source }) {
}
}
entity.gevAlprRecord = record;
entity.gevTrackedId = record.id;
entityRecord(entity).trackedId = record.id;
// The mapped camera datum has no elevation; it is not the clamped marker's
// visual anchor. Only the selected marker samples the rendered surface,
// at most once per second, through Cesium's public height APIs.
entity.gevAlprDisplayPosition ??= null;
entity.gevDisplayPosition = () => entity.gevAlprDisplayPosition;
entity.gevLabelModel = {
entityRecord(entity).displayPosition = () =>
entity.gevAlprDisplayPosition;
entityRecord(entity).labelModel = {
title: alprDisplayId(record),
details: alprLabelDetails(record, source),
accent: color.toCssColorString(),
+9 -5
View File
@@ -10,6 +10,7 @@ import {
SUBJECT_PRESENCE,
AWARENESS_PAGE_SIZE,
} from './policy.js';
import { readEntityRecord } from '../../data/entityRecords.js';
// coverageLabel is machine-composed English from installations/controls.js
// (pinned by src/data/militaryInstallations.test.mjs); translate the known
@@ -192,7 +193,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
function currentTrackedFlightSubject() {
const trackedKey = normalizeContextId(
layerState.viewer?.trackedEntity?.gevTrackedId,
readEntityRecord(layerState.viewer?.trackedEntity)?.trackedId,
);
if (!trackedKey) return null;
const subjects = [
@@ -260,16 +261,19 @@ export function createSubject({ state: layerState, services, parts, source }) {
) {
if (!subject?.position) return null;
if (subject.layerId === 'flights' || subject.layerId === 'military') {
const trackedPosition =
layerState.viewer?.trackedEntity?.gevDisplayPosition?.();
const trackedPosition = readEntityRecord(
layerState.viewer?.trackedEntity,
)?.displayPosition?.();
if (trackedPosition) {
return {
position: Cesium.Cartesian3.clone(trackedPosition),
// Only the follow camera's own contact proves presence this way; a
// different tracked entity says nothing about this subject.
presence:
String(layerState.viewer?.trackedEntity?.gevTrackedId || '') ===
subjectKey(subject)
String(
readEntityRecord(layerState.viewer?.trackedEntity)?.trackedId ||
'',
) === subjectKey(subject)
? SUBJECT_PRESENCE.LIVE
: SUBJECT_PRESENCE.UNCHECKED,
};
+1 -1
View File
@@ -515,7 +515,7 @@ export function createMotion({
*
* It reads `modelMatrix`, which `_updateTrackedModel` already wrote this frame — no
* sampling, no `_modelDisplayPosition` call from postRender, and no new dead reckoning,
* so the follow-camera anti-jitter contract on `gevDisplayPosition` is untouched.
* so the follow-camera anti-jitter contract on the entity record's `displayPosition` is untouched.
*/
function _trackedVisualCached() {
+14 -17
View File
@@ -25,6 +25,7 @@ import {
CYAN_TRANSPARENT,
} from './policy.js';
import { roundHeadingDegrees } from '../../data/headingDegrees.js';
import { entityRecord, readEntityRecord } from '../../data/entityRecords.js';
export function createTracking({
flightState,
@@ -66,7 +67,7 @@ export function createTracking({
const info = flightState.records.data.get(icao24);
if (!bb?.position || !info) return false;
if (flightState._trackedEntity)
flightState._trackedEntity.gevSelectionOrigin = origin;
entityRecord(flightState._trackedEntity).selectionOrigin = origin;
_emitAwarenessEvent('gev:awareness-subject-selected', {
layerId: 'flights',
id: icao24,
@@ -788,10 +789,8 @@ export function createTracking({
function _updateTrackedLabelModel(icao24) {
if (!flightState._trackedEntity || icao24 !== flightState._trackedIcao)
return;
flightState._trackedEntity.gevLabelModel = trackedLabelModelFromText(
_trackedLabelText(icao24),
'#39d0ff',
);
entityRecord(flightState._trackedEntity).labelModel =
trackedLabelModelFromText(_trackedLabelText(icao24), '#39d0ff');
refreshTrackedReadout(flightState._trackedEntity);
// The readout and the context slot describe the same contact — refresh them
// together so voice never narrates a fix the card has already replaced.
@@ -1007,12 +1006,10 @@ export function createTracking({
}, false),
},
});
flightState._trackedEntity.gevSelectionOrigin = origin;
flightState._trackedEntity.gevTrackedId = `flights:${icao24}`;
flightState._trackedEntity.gevLabelModel = trackedLabelModelFromText(
_trackedLabelText(icao24),
'#39d0ff',
);
entityRecord(flightState._trackedEntity).selectionOrigin = origin;
entityRecord(flightState._trackedEntity).trackedId = `flights:${icao24}`;
entityRecord(flightState._trackedEntity).labelModel =
trackedLabelModelFromText(_trackedLabelText(icao24), '#39d0ff');
// A billboard has a ~zero bounding sphere, so Cesium's default follow distance is
// far too tight (the user had to scroll out to read the plane). Give the entity a
@@ -1035,12 +1032,12 @@ export function createTracking({
// Expose the camera's already-settled position to cross-module HUD consumers (the tracked-target
// readout) so they draw at the SAME spot the camera framed, without recomputing the dead-reckon in
// postRender (which would jitter the label against the now-stable plane).
flightState._trackedEntity.gevDisplayPosition =
entityRecord(flightState._trackedEntity).displayPosition =
parts.motion._trackedDisplayCached;
// Separate accessor on purpose: `gevDisplayPosition` carries the follow-camera
// Separate accessor on purpose: the entity record's `displayPosition` carries the follow-camera
// anti-jitter contract and must keep returning the cached DR position. Presentation
// that should weld to the AIRCRAFT YOU SEE reads `gevVisualPosition` instead.
flightState._trackedEntity.gevVisualPosition =
// that should weld to the AIRCRAFT YOU SEE reads the entity record's `visualPosition` instead.
entityRecord(flightState._trackedEntity).visualPosition =
parts.motion._trackedVisualCached;
refreshTrackedReadout(flightState._trackedEntity);
flightState._viewer.camera.cancelFlight();
@@ -1155,8 +1152,8 @@ export function createTracking({
) {
_clearTracking(true, {
origin:
flightState._viewer.trackedEntity?.gevSelectionOrigin ||
'programmatic',
readEntityRecord(flightState._viewer.trackedEntity)
?.selectionOrigin || 'programmatic',
});
}
});
+5 -4
View File
@@ -2,6 +2,7 @@ import { installationClassLabel, installationTitle } from './classLabel.js';
import * as Cesium from 'cesium';
import { t } from '../../i18n/index.js';
import { LAYER_ID, MAX_RENDERED, COLOR_BY_CLASS } from './policy.js';
import { entityRecord } from '../../data/entityRecords.js';
export function createRendering({
state: layerState,
@@ -221,7 +222,7 @@ export function createRendering({
if (retained.gevInstallationHeightM !== surfaceHeightM) {
retained.gevInstallationHeightM = surfaceHeightM;
retained.position = displayPosition;
retained.gevDisplayPosition = () => displayPosition;
entityRecord(retained).displayPosition = () => displayPosition;
}
if (retained.gevInstallationSelected !== selectedRecord) {
retained.gevInstallationSelected = selectedRecord;
@@ -269,9 +270,9 @@ export function createRendering({
}
entity.gevInstallationHeightM = surfaceHeightM;
entity.gevInstallationSelected = selectedRecord;
entity.gevTrackedId = `installations:${record.id}`;
entity.gevDisplayPosition = () => displayPosition;
entity.gevLabelModel = {
entityRecord(entity).trackedId = `installations:${record.id}`;
entityRecord(entity).displayPosition = () => displayPosition;
entityRecord(entity).labelModel = {
title: installationTitle(record.name) || t('MAPPED INSTALLATION'),
details: [
installationClassLabel(record.class),
+6 -5
View File
@@ -35,6 +35,7 @@ import {
LOCAL_ADSB_UAT_RING_COLOR,
} from './policy.js';
import { localAdsbStatus } from './status.js';
import { entityRecord } from '../../data/entityRecords.js';
export { HEARD_BY_RECEIVER } from './policy.js';
export { localAdsbCardModel, localAdsbReceiverLine } from './card.js';
@@ -458,14 +459,14 @@ export function createLocalAdsbLayer({
),
},
});
marker.entity.gevTrackedId = id;
marker.entity.gevDisplayPosition = () => marker.position;
entityRecord(marker.entity).trackedId = id;
entityRecord(marker.entity).displayPosition = () => marker.position;
}
refreshClass(marker);
const uat = localAdsbIsUat(record);
if (uat !== Boolean(marker.entity.point))
marker.entity.point = uat ? uatRing(marker) : undefined;
marker.entity.gevLabelModel = cardModel(marker, at);
entityRecord(marker.entity).labelModel = cardModel(marker, at);
registerEntityContext(marker.entity, contextMetadata(id, marker));
if (newFix && id === selectedId) refreshTrail();
return id;
@@ -481,7 +482,7 @@ export function createLocalAdsbLayer({
function refreshSelectedCard() {
const marker = selectedId ? markers.get(selectedId) : null;
if (!marker) return;
marker.entity.gevLabelModel = cardModel(marker, now());
entityRecord(marker.entity).labelModel = cardModel(marker, now());
services.overlays?.refreshReadout?.(marker.entity);
}
@@ -567,7 +568,7 @@ export function createLocalAdsbLayer({
const reselect = id === selectedId && selectedTrail?.id === id;
selectedId = id;
enrichment.request(marker.record, { selected: true });
marker.entity.gevLabelModel = cardModel(marker, now());
entityRecord(marker.entity).labelModel = cardModel(marker, now());
selectEntityContext(marker.entity);
if (!reselect) startTrail(marker);
governorRequestRender('local-adsb-selection');
+11 -7
View File
@@ -12,6 +12,7 @@ import {
localAdsbReceiverLine,
localAdsbStatus,
} from './index.js';
import { readEntityRecord } from '../../data/entityRecords.js';
function fakeReceiver(initial = {}) {
const state = {
@@ -252,8 +253,8 @@ test('local aircraft use their class silhouette and scale in magenta', async (t)
),
);
assert.equal(entity.billboard.rotation.getValue(), 0);
assert.equal(entity.gevLabelModel.title, 'LOCAL1');
assert.equal(typeof entity.gevDisplayPosition, 'function');
assert.equal(readEntityRecord(entity)?.labelModel.title, 'LOCAL1');
assert.equal(typeof readEntityRecord(entity)?.displayPosition, 'function');
const heli = sources[0].entities.getById('local-adsb:a0b702');
assert.equal(heli.billboard.image.getValue(), aircraftIcon('helicopter'));
@@ -265,7 +266,10 @@ test('local aircraft use their class silhouette and scale in magenta', async (t)
),
'the helicopter keeps the local magenta',
);
assert.equal(heli.gevLabelModel.details[1], 'Helicopter · A7');
assert.equal(
readEntityRecord(heli)?.labelModel.details[1],
'Helicopter · A7',
);
// On the ground the silhouette shrinks like a grounded public flight.
receiver.set({
@@ -479,14 +483,14 @@ test('adsbdb type, operator and route reach the card for the selected aircraft o
await new Promise((resolve) => setTimeout(resolve, 400));
assert.deepEqual([...queries].sort(), ['route:EVC145', 'type:a0b702']);
const entity = sources[0].entities.getById('local-adsb:a0b702');
assert.deepEqual(entity.gevLabelModel.details.slice(0, 4), [
assert.deepEqual(readEntityRecord(entity)?.labelModel.details.slice(0, 4), [
'ICAO A0B702 · EVC145',
'Helicopter · A7',
'Air Evac · Bell 407',
'AUS → SAT',
]);
assert.equal(
entity.gevLabelModel.details.at(-1),
readEntityRecord(entity)?.labelModel.details.at(-1),
'Heard by your receiver · 1090 MHz · browser SDR',
);
layer.selectAircraft('a0b702');
@@ -760,7 +764,7 @@ test('feed records merge with browser SDR records by ICAO and UAT-only aircraft
);
assert.equal(shared.point, undefined, 'heard on 1090 too: no UAT ring');
assert.equal(
shared.gevLabelModel.details.at(-1),
readEntityRecord(shared)?.labelModel.details.at(-1),
'Heard by your receiver · 1090 MHz + 978 MHz UAT · browser SDR + decoder feed',
);
assert.ok(uat.point, 'a UAT-only aircraft carries the ring');
@@ -776,7 +780,7 @@ test('feed records merge with browser SDR records by ICAO and UAT-only aircraft
'same magenta marker family',
);
assert.equal(
uat.gevLabelModel.details.at(-1),
readEntityRecord(uat)?.labelModel.details.at(-1),
'Heard by your receiver · 978 MHz UAT · decoder feed',
);
const stats = layer.getStats();
+1 -1
View File
@@ -370,7 +370,7 @@ export function createMotion({
* model is actually rendering with when the model owns the visual, otherwise the cached
* dead-reckoned position. Mirror of flights.js; see that copy for the full rationale.
* Reads the modelMatrix the tracked-model update already wrote this frame: no sampling,
* no `_modelDisplayPosition` from postRender, and `gevDisplayPosition` keeps its
* no `_modelDisplayPosition` from postRender, and the entity record's `displayPosition` keeps its
* follow-camera anti-jitter contract untouched.
*/
+17 -17
View File
@@ -26,6 +26,7 @@ import {
TRACKED_ICON_COLOR,
} from './policy.js';
import { roundHeadingDegrees } from '../../data/headingDegrees.js';
import { entityRecord, readEntityRecord } from '../../data/entityRecords.js';
export function createTracking({
flightState,
@@ -65,7 +66,7 @@ export function createTracking({
const info = flightState.records.data.get(icao24);
if (!bb?.position || !info) return false;
if (flightState._trackedEntity)
flightState._trackedEntity.gevSelectionOrigin = origin;
entityRecord(flightState._trackedEntity).selectionOrigin = origin;
_emitAwarenessEvent('gev:awareness-subject-selected', {
layerId: 'military',
id: icao24,
@@ -252,10 +253,11 @@ export function createTracking({
function _updateTrackedLabelModel(icao24) {
if (!flightState._trackedEntity || icao24 !== flightState._trackedIcao)
return;
flightState._trackedEntity.gevLabelModel = trackedLabelModelFromText(
_buildTrackedLabel(flightState.records.data.get(icao24), icao24),
'#ffd166',
);
entityRecord(flightState._trackedEntity).labelModel =
trackedLabelModelFromText(
_buildTrackedLabel(flightState.records.data.get(icao24), icao24),
'#ffd166',
);
refreshTrackedReadout(flightState._trackedEntity);
// The readout and the context slot describe the same contact — refresh them
// together so voice never narrates a fix the card has already replaced.
@@ -966,12 +968,10 @@ export function createTracking({
}, false),
},
});
flightState._trackedEntity.gevSelectionOrigin = origin;
flightState._trackedEntity.gevTrackedId = `military:${icao24}`;
flightState._trackedEntity.gevLabelModel = trackedLabelModelFromText(
_buildTrackedLabel(info, icao24),
'#ffd166',
);
entityRecord(flightState._trackedEntity).selectionOrigin = origin;
entityRecord(flightState._trackedEntity).trackedId = `military:${icao24}`;
entityRecord(flightState._trackedEntity).labelModel =
trackedLabelModelFromText(_buildTrackedLabel(info, icao24), '#ffd166');
// A billboard has a ~zero bounding sphere, so Cesium's default follow distance is
// far too tight (the user had to scroll out to read the plane). Give the entity a
@@ -990,12 +990,12 @@ export function createTracking({
// mid-fly_to_location) would follow the plane WITHOUT centering it like a click does.
// Cross-module HUD consumers (tracked-target readout) read the camera's settled position, not a
// postRender recompute, so the label doesn't jitter against the now-stable plane (mirror of flights).
flightState._trackedEntity.gevDisplayPosition =
entityRecord(flightState._trackedEntity).displayPosition =
parts.motion._trackedDisplayCached;
// Separate accessor on purpose (mirror of flights.js): `gevDisplayPosition` keeps the
// Separate accessor on purpose (mirror of flights.js): the entity record's `displayPosition` keeps the
// follow-camera anti-jitter contract; presentation that must weld to the aircraft you
// can see reads `gevVisualPosition`.
flightState._trackedEntity.gevVisualPosition =
// can see reads the entity record's `visualPosition`.
entityRecord(flightState._trackedEntity).visualPosition =
parts.motion._trackedVisualCached;
refreshTrackedReadout(flightState._trackedEntity);
flightState._viewer.camera.cancelFlight();
@@ -1060,8 +1060,8 @@ export function createTracking({
) {
_clearTracking(true, {
origin:
flightState._viewer.trackedEntity?.gevSelectionOrigin ||
'programmatic',
readEntityRecord(flightState._viewer.trackedEntity)
?.selectionOrigin || 'programmatic',
});
}
});
+3 -2
View File
@@ -1,5 +1,6 @@
import * as Cesium from 'cesium';
import { isPointerFree } from '../../data/inputOwnership.js';
import { readEntityRecord } from '../../data/entityRecords.js';
export function createInteraction({
state: layerState,
@@ -36,8 +37,8 @@ export function createInteraction({
) {
parts.tracking._clearTracking(true, {
origin:
layerState._viewer.trackedEntity?.gevSelectionOrigin ||
'programmatic',
readEntityRecord(layerState._viewer.trackedEntity)
?.selectionOrigin || 'programmatic',
});
}
});
+7 -5
View File
@@ -9,6 +9,7 @@ import {
TRACK_VIEW_FROM_HIGH_SCALE,
TRACK_VIEW_FROM_LEO,
} from './policy.js';
import { entityRecord, readEntityRecord } from '../../data/entityRecords.js';
export function createTracking({ state: layerState, services, parts, source }) {
const { clearFocusTarget, publishFocusTargetFromCachedPosition } =
@@ -384,7 +385,7 @@ export function createTracking({ state: layerState, services, parts, source }) {
: t('DOCKED · {name}', { name: companions[0] }),
);
}
const current = layerState._trackedEntity.gevLabelModel;
const current = readEntityRecord(layerState._trackedEntity)?.labelModel;
// Compare the WHOLE detail array: comparing only `details[0]` swallowed any
// change confined to the companions line, so the card would never republish.
const unchanged =
@@ -392,7 +393,7 @@ export function createTracking({ state: layerState, services, parts, source }) {
current?.details?.length === details.length &&
details.every((line, index) => current.details[index] === line);
if (unchanged) return;
layerState._trackedEntity.gevLabelModel = {
entityRecord(layerState._trackedEntity).labelModel = {
title,
details,
accent: '#ffd84d',
@@ -456,9 +457,10 @@ export function createTracking({ state: layerState, services, parts, source }) {
disableDepthTestDistance: Number.POSITIVE_INFINITY,
},
});
layerState._trackedEntity.gevSelectionOrigin = origin;
layerState._trackedEntity.gevTrackedId = `satellites:${noradId}`;
layerState._trackedEntity.gevDisplayPosition = _trackedDisplayCached;
entityRecord(layerState._trackedEntity).selectionOrigin = origin;
entityRecord(layerState._trackedEntity).trackedId = `satellites:${noradId}`;
entityRecord(layerState._trackedEntity).displayPosition =
_trackedDisplayCached;
_updateTrackedSatelliteLabelModel(initialPos?.altitude ?? null);
_emitAwarenessEvent('gev:awareness-subject-selected', {