import { cameraOf, findCamera, findFrame } from '../../render/rendererOf.js'; import { entityFollowTarget, onFollowChanged, stopFollowing, } from '../../data/followed.js'; import { formatNumber, t } from '../../i18n/index.js'; import { unitLabel } from '../../ui/unitLabels.js'; import { nextCockpitNearContacts } from '../../data/cockpitAirLod.js'; import { trackedModelZoomActive } from '../../data/trackedModelRegime.js'; import { courseScreenRotation, stabilizeScreenRotation, } from '../../data/screenRotation.js'; import { createTrackedAircraftIcon, isOtherTrackedIconSet, trackedContactHolder, } from '../../data/trackedAircraftIcon.js'; import { fromDegrees, toLonLatH } from '../../geo/ellipsoid.js'; import { addSeconds, julianLessThanOrEquals, julianNow, julianToEpochMs, } from '../../geo/julian.js'; import { clone, distanceSquared, vec } from '../../geo/vector.js'; import { trailHeadStart } from '../../data/modelVisualAnchor.js'; import { aircraftIcon, TRACKED_ICON_PX } from '../../data/aircraftIcons.js'; import { routePlausible } from '../../data/routePlausible.js'; import { CLASS_SCALE_2D } from '../../data/aircraftClass.js'; import { isTrackingSelectionGesture, isTrackingClickGesture, } from '../../data/trackingClickGesture.js'; import { inputFor } from '../../input/dispatcher.js'; import { TRAIL_MAX_POINTS, RENDER_DELAY_SEC, TRAIL_COLOR, CYAN_TRANSPARENT, TRACKED_CYAN, TRACKED_BILLBOARD_SCALE_BY_DISTANCE, } from './policy.js'; import { roundHeadingDegrees } from '../../data/headingDegrees.js'; import { entityRecord } from '../../data/entityRecords.js'; /** * The icao a click's hit carries (`event.hit`, the contract's `Hit`): a * draw-set item's id (the icon and model sets' rows), or the id of * something drawn outside the draw port (a hit with no set). */ function aircraftPickId(hit) { if (!hit || hit.surface) return undefined; if (!hit.set) return hit.id || undefined; return isOtherTrackedIconSet(hit.set, 'flights') ? undefined : hit.id; } export function createTracking({ flightState, services, parts, layer, resolveAsset, }) { const { selectTrackedSubjectContext, clearTrackedSubjectContext, refreshTrackedSubjectContext, } = services.context; const { isTr3b, tr3bTypeLabel, tr3bConvertedIds } = services.aircraftPresentation; const { createTrail } = services.trails; const { ensureGeoidReady, geoidHeight } = services.geoid; const { resolveGroundFloorCellsBounded, floorAltitudeM, cachedGroundFloor } = services.groundFloor; const { clearFocusTarget } = services.focus; const { isMilitaryLayerActive, isMilitaryIcao } = services.militaryRegistry; const { trackedLabelModelFromText, refreshTrackedReadout } = services.readout; const { FOLLOW_MIN_RANGE_M } = services.camera; const { resolvePickId, isOwnedByOtherLayer } = services.picking; const flightsLayer = layer; /** The tracked contact's billboard (an icon set on the draw port). */ const trackedIcon = createTrackedAircraftIcon({ viewer: () => flightState._viewer, setPrefix: 'flights', }); /** The camera's pose, or null without a camera to ask. */ function _pose() { const viewer = flightState._viewer; try { return (viewer && findCamera(viewer)?.pose()) ?? null; } catch { return null; } } function _emitAwarenessEvent(type, detail) { if ( typeof window === 'undefined' || !window.dispatchEvent || typeof CustomEvent === 'undefined' ) return; window.dispatchEvent(new CustomEvent(type, { detail })); } function _publishTrackedSelection(icao24, origin = 'programmatic') { const position = parts.icons._iconPosition(icao24, vec()); const info = flightState.records.data.get(icao24); if (!position || !info) return false; if (flightState._trackedEntity) entityRecord(flightState._trackedEntity).selectionOrigin = origin; _emitAwarenessEvent('gev:awareness-subject-selected', { layerId: 'flights', id: icao24, // Canonical display chain (callsign → registration → hex). Publishing a // bare `callsign || icao24` here resurrected the pre-enrichment behavior: // a callsign-less contact reached Context as its raw hex even once adsbdb // had supplied a registration. Identity below stays `icao24`. label: parts.queries._contactLabel(icao24, info), position, origin, }); selectTrackedSubjectContext(_contextSubjectMetadata(icao24)); return true; } /** * Describe the selected contact for the shared context slot the voice tools * and Cockpit read. Values are the LIVE descriptor, not a selection-time * snapshot, so a long follow never narrates a position the plane has left. * @param {string} icao24 Contact identity. * @returns {object|null} Context metadata, or null when the contact is gone. */ function _contextSubjectMetadata(icao24) { const described = parts.queries._describeFlight(icao24); if (!described) return null; const altFt = Math.round((described.altitudeM || 0) * 3.28084); const route = described.route && _routeIsPlausible(icao24, described.route) ? `${described.route.origin.code} → ${described.route.destination.code}` : null; return { id: icao24, layerId: 'flights', layerName: 'Live Flights', source: flightState.feed._lastSource, label: parts.queries._contactLabel( icao24, flightState.records.data.get(icao24), ), latitude: described.latitude, longitude: described.longitude, // Flat text only: the voice payload compacts properties through a // string cleaner that drops nested objects. properties: { name: parts.queries._contactLabel( icao24, flightState.records.data.get(icao24), ), operator: described.airline || '', callsign: described.callsign || '', registration: described.registration || '', type: described.typeName || described.typeCode || '', altitude: described.onGround ? 'on ground' : `${altFt.toLocaleString('en-US')} ft`, speed: Number.isFinite(described.velocityMps) ? `${Math.round(described.velocityMps * 1.944)} kt` : '', heading: Number.isFinite(described.track) ? `${roundHeadingDegrees(described.track)}°` : '', route: route || '', icao24, // Honesty cue: the contact is coasting on dead reckoning, so the // narrated position/velocity are last-known rather than live. // i18n-ignore: voice-context data, English for the model status: described.stale ? 'stale (missed polls)' : 'live', }, }; } function _isExplicitTrackingOrigin(origin) { return origin === 'user' || origin === 'voice' || origin === 'tool'; } /** * Refresh the Cockpit AIR near/far band without consulting model state. * Near contacts keep their 2D aircraft silhouette when 3D is off, loading, or * capped; only a ready admitted model may take that silhouette over later. */ function _refreshCockpitNearContacts() { const eye = flightState._cockpitContactMode ? _pose()?.position : null; if (!eye) { if (flightState._cockpitNearContacts.size) flightState._cockpitNearContacts = new Set(); return; } const previous = flightState._cockpitNearContacts; const distancesSquared = []; const icons = flightState._icons; const t = parts.icons._displayMs(); for (const icao24 of icons?.ids() ?? []) { if (icao24 === flightState._trackedIcao) continue; const position = icons.position( icao24, t, flightState._scratchCockpitPos, ); distancesSquared.push([icao24, distanceSquared(eye, position)]); } const next = nextCockpitNearContacts( previous, distancesSquared, parts.rendering._modelAddDistM(), parts.rendering._modelKeepDistM(), ); flightState._cockpitNearContacts = next; for (const icao24 of previous) if (!next.has(icao24)) parts.icons._applyIconPresentation(icao24); for (const icao24 of next) if (!previous.has(icao24)) parts.icons._applyIconPresentation(icao24); } /** Switch all current and future ambient contacts between silhouettes and cockpit pips. */ function _setCockpitContactMode(active) { const next = active === true; if (flightState._cockpitContactMode === next) return; flightState._cockpitContactMode = next; if (next) _refreshCockpitNearContacts(); else flightState._cockpitNearContacts = new Set(); // The collection stays visible in cockpit. Near AIR contacts retain their // aircraft silhouette until a ready model takes over; far contacts are pips. // Never destroy on entry: tearing down hundreds of live glTF instances // synchronously blocked Chrome's renderer into Page Unresponsive. parts.rendering._setModelsShown(true); flightState._trail?.setVisible(!next); for (const icao24 of flightState._icons?.ids() ?? []) parts.icons._applyIconPresentation(icao24); flightState._lastFleetTickMs = 0; } function _applyCockpitState(detail = {}) { const active = detail?.active === true; flightState._cockpitSubjectId = active ? String(detail?.subjectId || '') .trim() .toLowerCase() || null : null; _setCockpitContactMode(active); } /** Clear the per-SELECTION tracked-model latches: the zoom hysteresis band * and the load-failure budget. * Called from each path that changes which contact is * selected — deselect, re-track, cross-layer handoff, init, destroy. * * This must live in the production lifecycle, not only in the predicate's * icao-change guard: a deselect followed by a same-turn re-track of the SAME * icao (Contacts re-entry, a cross-layer round trip back to the original * layer) never makes `_trackedIcao` *observably* change, so the guard never * fires. Without the reset, a contact dropped inside the hysteresis band comes * back as a MODEL above the ENTER ceiling. */ function _resetTrackedSelectionState() { flightState._trackedZoomLatched = false; flightState._trackedZoomLatchIcao = null; flightState._trackedModelFailIcao = null; flightState._trackedModelFailCount = 0; flightState._trackedModelRetryAtMs = 0; } /** * The TRACKED aircraft's own model regime — DEFAULT-ON, camera-distance driven * (owner directive 2026-08-19). Unlike the fleet, this does NOT consult the * DISPLAY-rail `models3d` toggle: the selected contact is a single model, it is * what the camera is pointed at, and zooming in on a target should resolve it * into an aircraft without the operator arming anything. The toggle keeps * owning the FLEET (`_modelRegimeActive`), which is the draw-call budget. * * Thresholds + hysteresis live in trackedModelRegime.js: enter at * TRACKED_MODEL_ENTER_ALT_M (150_000 m — the owner's playtested swap distance, * deliberately NEARER than the fleet's 800 km ceiling this used to inherit), * hand back only above TRACKED_MODEL_EXIT_ALT_M, so orbiting AT the boundary * cannot flap billboard↔model. See that module's header for why the tracked * contact now goes 3D closer in than the fleet does. * * In cockpit you are sitting 7 m behind and 2.6 m above your own aircraft's * origin, so its ~26 m airframe would fill the visor. First-person means your * own airframe is not drawn. */ function _trackedModelRegimeActive() { if (flightState._trackedZoomLatchIcao !== flightState._trackedIcao) { flightState._trackedZoomLatchIcao = flightState._trackedIcao; flightState._trackedZoomLatched = false; } // A converted TR-3B has no 3D asset — suppressing the regime keeps its // tracked billboard fully opaque (the colour callback reads this too), so // the triangle stays the visual all the way in. if ( !flightState._trackedIcao || flightState._cockpitContactMode || isTr3b(flightState._trackedIcao) ) { flightState._trackedZoomLatched = false; return false; } flightState._trackedZoomLatched = trackedModelZoomActive( _pose()?.height, flightState._trackedZoomLatched, ); return flightState._trackedZoomLatched; } /** Seed the tracked billboard's 2D orientation before a 3D→2D handoff. */ function _syncTracked2dRotation() { if (!flightState._trackedIcao || !flightState._viewer) return; const pos = parts.motion._trackedDisplayCached() || parts.icons._iconPosition(flightState._trackedIcao, vec()); if (!pos) return; const projected = courseScreenRotation( _pose(), pos, parts.motion._trackedDisplayCourse(), flightState._lastTrackedRotation, ); const rotation = stabilizeScreenRotation( flightState._lastTrackedRotation, projected, 0, ); if (rotation !== null) flightState._lastTrackedRotation = rotation; } /** * Append one fix to the tracked aircraft's trail accumulation and refresh * the rendered trail. Caller passes an owned (cloned) Cartesian3. * @param {{x: number, y: number, z: number}} position - New ECEF fix, appended at the head. */ function _appendTrailFix(position) { flightState._trailPositions.push(position); if (flightState._trailPositions.length > TRAIL_MAX_POINTS) flightState._trailPositions.shift(); _refreshTrailDisplay(); } /** * Renders the trail with its head clamped to the render-behind display * position. Raw newest fixes run up to RENDER_DELAY_SEC ahead of the * displayed aircraft (PRD C2 delayed clock) — drawing them verbatim makes * the trail extend in FRONT of the icon. The head is refreshed ~1Hz from * the fleet tick so it stays glued to the moving aircraft. */ function _refreshTrailDisplay() { // The trail BODY is the accumulated fixes EXCLUDING the newest raw one — that newest // fix is at ~now, ~one poll interval AHEAD of the delayed icon (rendered at // now − RENDER_DELAY_SEC), so drawing it would push the trail in front of the plane. // The cheap per-frame trail head segment bridges the last body point to the // delayed dead-reckoned head, so the body primitive only rebuilds on a real fix // (poll cadence), never at motion cadence. if (!flightState._trail) return; flightState._trail.setPositions( flightState._trailPositions.length > 1 ? flightState._trailPositions.slice(0, -1) : flightState._trailPositions, ); } /** * The live head: the last DISPLAYED body point to the delayed head, or no * positions while there is none. * @returns {Array<{x: number, y: number, z: number}>} */ function _trailHeadPositions() { // Need ≥2 accumulated points: the body draws all-but-newest, so the head must // start at the last DISPLAYED body point (index n−2). With a single fix that // point would be the sole raw fix — which is ~now, AHEAD of the delayed icon — // so the segment would draw IN FRONT of the plane. Likewise during warm-up the // icon predates all real history, so there is no valid body point behind it. if ( !flightState._trackedIcao || flightState._trailPositions.length < 2 || parts.motion._isTrackWarmingUp() ) return []; const head = parts.motion._trackedTrailCached() || parts.motion._trackedDisplayPosition(flightState._trackedIcao); if (!head) return []; // body[n−2] (last displayed body point) → delayed head: runs FORWARD, never a // backward/reversing segment. const start = flightState._trailPositions[flightState._trailPositions.length - 2]; // On a contact that has not moved this segment runs from inside the // model out to its own anchor — a line through the fuselage. The END // never gives, so a moving trail still terminates on the tail; the // START is what slides, from nothing on a parked contact out to the // whole segment once it has cleared its own envelope. // See trailHeadStart. Read `head` in place and clone only on the draw // path — a suppressed parked contact runs this every frame. const from = trailHeadStart( start, head, parts.motion._trackedModelCenterWorld(), parts.motion._trackedModelEnvelopeM(), flightState._scratchTrailHead, ); if (!from) return []; return [from, clone(head)]; } /** Each drawn frame, before it draws: the live head where the aircraft is now. */ function _drawTrailHead() { flightState._trail?.setHead(_trailHeadPositions()); } /** * Start the trail for a newly tracked aircraft: seed it with the short * dead-reckoning history (chronological), render immediately, then * fire-and-forget an OpenSky track backfill. * @param {string} icao24 - ICAO 24-bit transponder address being tracked. */ function _startTrail(icao24) { flightState._trailBackfillToken += 1; flightState._trailPositions = []; const history = flightState._positionHistory.get(icao24) || []; // Seed only fixes at/behind the DELAYED display time (now − RENDER_DELAY_SEC). The // newest ~RENDER_DELAY_SEC of fixes are AHEAD of the displayed icon; including them // would draw the trail in front of the plane. They join the trail via _appendTrailFix // as they age past the delay. const seedRenderTime = addSeconds( julianNow(), -RENDER_DELAY_SEC, flightState._scratchWarmupTime, ); for (const fix of history) { if (julianLessThanOrEquals(fix.time, seedRenderTime)) { flightState._trailPositions.push(clone(fix.position)); } } if (!flightState._trail && flightState._viewer) { flightState._trail = createTrail(flightState._viewer, { color: TRAIL_COLOR, width: 2.5, }); } flightState._trail?.setVisible(!flightState._cockpitContactMode); // Live head segment: last displayed body point → current dead-reckoned icon, drawn // again each frame before it draws, so it stays glued to the 12 Hz icon instead of // lagging ~1 s behind it. Only the head line is rebuilt; the body rebuilds on a real // fix (poll cadence). Dimmed where occluded (round 4), geodesic as the body (round 8). if (!flightState._trailHeadOff && flightState._viewer) { flightState._trailHeadOff = findFrame(flightState._viewer)?.on('preRender', _drawTrailHead) ?? null; } _refreshTrailDisplay(); const oldestFixEpochSec = history.length ? julianToEpochMs(history[0].time) / 1000 : Infinity; _backfillTrail(icao24, flightState._trailBackfillToken, oldestFixEpochSec); } /** * Fire-and-forget OpenSky /tracks backfill (PRD F1). On success, splices * waypoints strictly older than the oldest seeded fix AHEAD of the locally * accumulated fine segment, capped at TRAIL_MAX_POINTS (newest kept). Any * failure (404/429/timeout/malformed) silently keeps the local-only trail. * @param {string} icao24 - ICAO 24-bit transponder address being tracked. * @param {number} token - Backfill token captured at request time. * @param {number} oldestFixEpochSec - Epoch seconds of the oldest seeded fix. * @returns {Promise} */ async function _backfillTrail(icao24, token, oldestFixEpochSec) { let path = null; try { const track = await flightState.feed._source.getTrack?.( flightState.records.data.get(icao24)?.sourceReference ?? icao24, { signal: AbortSignal.any([ flightState.lifetime.signal, AbortSignal.timeout(8000), ]), }, ); path = track?.records ?? null; } catch { return; // silent fallback to the accumulated trail } if ( !path || token !== flightState._trailBackfillToken || icao24 !== flightState._trackedIcao ) return; // OpenSky track waypoints: [time, latitude, longitude, baro_altitude, true_track, on_ground] // Height-datum fix (Task 6): /tracks only ever reports barometric/MSL altitude // (no per-waypoint geo_altitude in this endpoint), so waypoint render height is // the documented visual FALLBACK baroM + geoidHeight(waypointLat, waypointLon) // — geometrically approximate, not exact, same honesty caveat as the live // baro-fallback branch of pickRenderAltitudeM. await ensureGeoidReady(); const parsed = []; for (const waypoint of path) { const { observedAtMs, latitude: lat, longitude: lon, baroAltitudeM: baroAlt, } = waypoint; const time = observedAtMs / 1000; if (!Number.isFinite(lat) || !Number.isFinite(lon)) continue; if (!Number.isFinite(time) || time >= oldestFixEpochSec) continue; parsed.push({ lat, lon, baroAlt }); } if (!parsed.length) return; // Field-test fix (WAKE01 trail-underground, 2026-07-06 — mirror of // militaryFlights.js): resolve the coarse ellipsoidal ground along the track // and floor every waypoint at it so low baro segments never dive below the // mesh; a no-baro waypoint (predominantly taxi/ground segments in /tracks) // sits ON the surface when the floor is known. // Round-2 fix (owner: "trails suddenly much shorter / not loading"): the // resolve is BOUNDED (≤1.2 s), not a blocking await — a cold Re:Earth // lookup across a long path could stall the paint for seconds-to-timeout. // Paint with whatever cells are warm; the resolve keeps filling the cache // in the background for the next paint/select. await resolveGroundFloorCellsBounded(parsed); // Re-check the backfill token after the await (same guard as post-fetch): // tracking may have moved on while the terrain race was in flight. if ( token !== flightState._trailBackfillToken || icao24 !== flightState._trackedIcao ) return; const older = []; let lastAltM = null; // carry-forward for no-baro points whose cell isn't warm yet for (const { lat, lon, baroAlt } of parsed) { const baroM = Number.isFinite(baroAlt) ? baroAlt + geoidHeight(lat, lon) : null; let altM = floorAltitudeM(baroM, cachedGroundFloor(lat, lon)); // No baro + unresolved floor: hold the previous waypoint's altitude // (continuity — never a dive/spike to a made-up height). Leading points // with nothing to carry keep the old 10 km airborne default. if (altM == null) altM = lastAltM != null ? lastAltM : 10000; lastAltM = altM; older.push(fromDegrees(lon, lat, altM)); } flightState._trailPositions = older.concat(flightState._trailPositions); if (flightState._trailPositions.length > TRAIL_MAX_POINTS) { flightState._trailPositions = flightState._trailPositions.slice( flightState._trailPositions.length - TRAIL_MAX_POINTS, ); } _refreshTrailDisplay(); } /** * Clear the rendered trail and accumulation; invalidate pending backfills. */ function _clearTrail() { flightState._trailBackfillToken += 1; flightState._trailPositions = []; if (flightState._trail) flightState._trail.clear(); flightState._trailHeadOff?.(); flightState._trailHeadOff = null; } /** * Destroy the trail primitive entirely (layer disable/teardown). */ function _destroyTrail() { _clearTrail(); if (flightState._trail) { flightState._trail.destroy(); flightState._trail = null; } } /** * Stop tracking the currently followed aircraft. * * Restores the hidden billboard, removes the tracked Entity, resets lerp * state, and RELEASES the camera IN PLACE — no flyTo. Deselect used to fly * an ~80 km pulled-back overview; the owner field-ruled that wrong * (2026-07-02: "it randomly zooms way up and loses my context"). The camera * now simply stays at its current position/orientation, immediately free to * orbit/zoom. Applies to every deselect path: click-empty-space, Escape, * aged-out plane, layer disable, and voice stopTracking. * * @param {boolean} [skipViewerUntrack=false] - ANOTHER layer just grabbed the * follow-camera: tear down our own state but leave the camera's follow * alone (the new owner controls it). * @param {object} [options] - Clear origin. * @param {boolean} [options.evicted=false] - The contact aged out of the feed * rather than being deselected. Consumers that keep a readout on screen * (the Cockpit Contact panel) hold last-known values for an eviction and * only tear down on a deliberate clear. */ function _clearTracking( skipViewerUntrack = false, { evicted = false, origin = 'programmatic' } = {}, ) { flightState._followTarget = null; if (!flightState._trackedIcao) { clearFocusTarget('flights'); return; } const clearedIcao = flightState._trackedIcao; clearFocusTarget('flights', clearedIcao); // The nose the icon continues from (the shared _displayCourse entry), so // release never flips it. const trackedCourseDeg = flightState._displayCourse.get(clearedIcao); // Stop tracking and hide the tracked billboard. skipViewerUntrack: when ANOTHER layer just // grabbed the follow-camera, we tear down our own state but must NOT clear the camera's follow // (the new owner controls it now — clearing it would yank the camera off their plane). // Releasing the follow does NOT move the camera: the view stays where the follow left it and // the user can immediately orbit/zoom. if (flightState._viewer && !skipViewerUntrack) { stopFollowing(flightState._viewer); } trackedIcon.hide(); flightState._trackedEntity = null; parts.rendering._releaseTrackedModel(); _resetTrackedSelectionState(); // the zoom band + load-failure budget belong to the selection we just dropped flightState._trackedIcao = null; // Hand the contact back to its icon only now: settling floors a grounded // contact, and while it still read as tracked its tracked model owned the // visual, so the floor would have stepped aside. if (flightState._icons?.has(clearedIcao)) { flightState._icons.setShown(clearedIcao, true); parts.icons._settleIcon(clearedIcao, { fromCourseDeg: trackedCourseDeg }); } parts.icons._applyIconPresentation(clearedIcao); clearTrackedSubjectContext('flights'); _emitAwarenessEvent('gev:awareness-subject-cleared', { layerId: 'flights', id: clearedIcao, origin, reason: evicted ? 'evicted' : 'deliberate', }); // Invalidate the per-frame DR cache + reconciliation state so a same-frame re-track // cannot read the previous aircraft's cached/smoothed position. parts.motion._resetTrackedDisplay(); _clearTrail(); } /** * Whether the Military layer suppresses this civil duplicate right now. * * The dedicated Military layer owns icon/track/click for known-military * contacts, so the OpenSky duplicate is dropped while that layer is on. Two * contacts are exempt, both for the same reason — this layer still owns them: * * - the CURRENTLY tracked one, which hands off on untrack; and * - a target this layer is holding on its deferred-restore latch. * * The second exemption is what makes a shared/local Follow of a mil-registry * hex restorable at all. The accepted-snapshot id set is built BEFORE this * suppression runs, so without it the target is provably present in a healthy * feed yet has no billboard, `trackById` fails, and the restore reports * "feed unavailable" about a feed that was perfectly fine. * * @param {string} icao24 - Normalized ICAO 24-bit address. * @returns {boolean} True when the civil duplicate must be dropped. */ function _militaryLayerSuppresses(icao24) { if (!isMilitaryLayerActive()) return false; if (icao24 === flightState._trackedIcao) return false; if (icao24 === flightState._pendingTrackingRestore?.id) return false; return true; } function _applyPendingTrackingRestore() { const pending = flightState._pendingTrackingRestore; if ( !pending || pending.generation !== flightState._trackingIntentGeneration ) return false; if (!flightState._icons?.show || !flightState._icons.has(pending.id)) return false; flightState._pendingTrackingRestore = null; _trackFlight(pending.id, { origin: pending.origin }); return true; } function _cancelPendingTrackingRestore() { flightState._trackingIntentGeneration += 1; flightState._pendingTrackingRestore = null; } /** Multi-line tracked presentation text: "CS · FL · kts" + "Airline · Type" + * "ORIG → DEST". The route line is gated by * routePlausible so a wrong-leg adsbdb route is hidden, not displayed. * While the plane is in its missed-poll grace (coasting on dead reckoning * with sticky metadata), the first line carries a "· STALE" cue — the fleet's * 45%-alpha billboard fade doesn't apply to the tracked plane (its entity * owns the visual), so without this the readout would present last-known * velocity/altitude as live. */ function _trackedLabelText(icao24) { const info = flightState.records.data.get(icao24); if (!info) return icao24; // A whitespace-only callsign (" ") is truthy, so `(info.callsign || icao24)` // kept it, then .trim() emptied it → the callsign slot dropped out of the // readout. `_contactLabel` trims FIRST, then falls through registration to // the ICAO hex, so a callsign-less enriched contact heads its readout with // the tail number rather than raw hex. const cs = parts.queries._contactLabel(icao24, info); const altFt = Math.round((info.altitude || 0) * 3.28084); // Flight levels are an aviation code; feet and knots read in the active // language ("0 фт · 1 уз"). const quantity = (value, unit) => `${formatNumber(value, { useGrouping: false })} ${unitLabel(unit)}`; const fl = altFt >= 18000 ? `FL${Math.round(altFt / 100)}` : quantity(altFt, 'ft'); const spd = info.velocity ? quantity(Math.round(info.velocity * 1.944), 'kts') : ''; const stale = flightState.records.missingPolls.get(icao24) || flightState.feed._backoff ? t('STALE') : ''; const lines = [[cs, fl, spd, stale].filter(Boolean).join(' · ')]; // Converted contacts report their class as TR-3B and nothing else — the // operator/type identity is exactly what the Easter egg is replacing. const ident = isTr3b(icao24) ? tr3bTypeLabel(icao24) : [info.airline, info.typeName || info.typeCode] .filter(Boolean) .join(' · '); if (ident) lines.push(ident); if (info.route && _routeIsPlausible(icao24, info.route)) { lines.push(`${info.route.origin.code} → ${info.route.destination.code}`); } return lines.join('\n'); } /** Write the explicit tracked presentation model and refresh its host entry. */ function _updateTrackedLabelModel(icao24) { if (!flightState._trackedEntity || icao24 !== flightState._trackedIcao) return; 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. refreshTrackedSubjectContext(_contextSubjectMetadata(icao24)); } /** The tracked billboard's image, from the current class/conversion. */ function _trackedBillboardImage() { return aircraftIcon( parts.rendering._iconKind( flightState._trackedIcao, flightState.records.data.get(flightState._trackedIcao)?.klass, ), TRACKED_ICON_PX, ); } /** Re-image the tracked billboard from the current class/conversion. */ function _syncTrackedBillboardImage() { if (!flightState._trackedIcao || !flightState._trackedEntity) return; trackedIcon.setImage(_trackedBillboardImage()); } /** * Re-render one contact after its TR-3B conversion (or the active IR style) * changed. Converting drops any 3D model so the triangle owns the visual; the * billboard image, tracked entity, and tracked card are all re-derived here. * @param {string} icao24 - ICAO 24-bit address. * @returns {boolean} True when the layer owns this contact. */ function _refreshTr3bContact(icao24) { const id = String(icao24 || '') .trim() .toLowerCase(); if (!id) return false; if (isTr3b(id)) { // Drop the 3D handoff for this contact — the fleet tick now skips it, so // an already-loaded model would otherwise linger with the billboard hidden. if (flightState._models.has(id)) parts.rendering._releaseModel(id); if (flightState._icons?.has(id) && id !== flightState._trackedIcao) flightState._icons.setShown(id, true); if (id === flightState._trackedIcao) { parts.rendering._releaseTrackedModel(); _syncTracked2dRotation(); } } parts.icons._applyIconPresentation(id); if (id === flightState._trackedIcao) { _syncTrackedBillboardImage(); _updateTrackedLabelModel(id); } if (flightState._viewer) findFrame(flightState._viewer)?.requestRender('flights: TR-3B restyle'); return flightState._icons?.has(id) || id === flightState._trackedIcao; } /** Re-image every converted contact this layer owns (IR style flip). */ function _refreshTr3bForStyle() { for (const id of tr3bConvertedIds()) { if (flightState._icons?.has(id) || id === flightState._trackedIcao) _refreshTr3bContact(id); } } /** Plausibility check anchored to the plane's icon position (coarse is * fine here — this gates a LABEL, and it must not touch the tracked frame * cache). Missing data → true (never hide what we can't judge). */ function _routeIsPlausible(icao24, route) { const info = flightState.records.data.get(icao24); const position = parts.icons._iconPosition(icao24, vec()); if (!info || !position) return true; const carto = toLonLatH(position); if (!carto) return true; return routePlausible({ latDeg: carto.lat, lonDeg: carto.lon, altitudeM: info.altitude ?? null, verticalRateMps: info.verticalRate ?? null, origin: route.origin, destination: route.destination, }); } /** * Begin tracking a specific aircraft by ICAO24 address. * * Clears any existing tracked flight, hides its fleet icon, and shows the * tracked billboard (`createTrackedAircraftIcon`), drawn each frame at the * dead-reckoned display position, screen-rotated along the displayed * course. The tracked record carries the host presentation model * (callsign, flight level, speed, identity, plausible route text), and the * camera follows a target that reads it. * * @param {string} icao24 - ICAO 24-bit transponder address to track. */ function _trackFlight(icao24, { origin = 'programmatic' } = {}) { _clearTracking(false, { origin }); // switching planes — the new follow-camera takes over const icons = flightState._icons; const info = flightState.records.data.get(icao24); if (!icons?.has(icao24) || !info) return; // The tracked limiter continues from the nose the icon was drawn with, and // the entity starts with the rotation the icon had on screen. const t = parts.icons._displayMs(); const iconPosition = icons.position(icao24, t, vec()); const iconCourse = icons.course(icao24, t); flightState._displayCourse.set(icao24, iconCourse); flightState._trackedIcao = icao24; _resetTrackedSelectionState(); // fresh selection: enter at the ENTER ceiling, full load-retry budget flightState._cachedDRFrame = -1; flightState._lastTrackedRotation = courseScreenRotation(_pose(), iconPosition, iconCourse, 0) ?? 0; // Drop any fleet 3D model for this aircraft — the tracked entity now owns its visual (its // own billboard + model graphic), and the fleet tick skips the tracked icao, so a leftover // fleet model would be orphaned + double-rendered. parts.rendering._releaseModel(icao24); // Hide the icon — the tracked entity replaces it visually icons.setShown(icao24, false); // Helper: smoothed, per-frame-cached tracked position (see _trackedDisplayPosition — // one computation shared by the position/alignedAxis/rotation/trail-head callbacks, // with discontinuity reconciliation). Falls back to the icon's position when // the aircraft has no fix. const getTrackedPosition = () => parts.motion._trackedDisplayPosition(icao24) || parts.icons._iconPosition(icao24, vec()) || iconPosition; // The tracked billboard: a 2D icon when zoomed out, handing over to the 3D model when zoomed // in past the TRACKED altitude ceiling. That handoff is DEFAULT behaviour — it does NOT wait on // the DISPLAY-rail 3D toggle, which arms the FLEET. The plane the user zooms into always // resolves into an aircraft. // // The billboard stays SHOWN at all times and is hidden by going TRANSPARENT (alpha 0), not by // show=false: it drops its alpha only once the tracked model is drawing, so there's neither a // billboard+model double-image nor a gap. The camera follows its own target through the camera // port, so nothing here frames the camera. The 3D model for the tracked plane is a draw-set // item driven by _updateTrackedModel() (see _trackedModel). // What the tracked billboard is drawn at, kept in its record so the // camera guard and screen annotations size it from the app. const sprite = { width: 28, height: 28, scale: CLASS_SCALE_2D[ flightState.records.data.get(flightState._trackedIcao)?.klass ] || 1, scaleByDistance: TRACKED_BILLBOARD_SCALE_BY_DISTANCE, }; // The tracked contact as its readers see it (the tracked card, Cockpit, share links): a // plain holder of its entity record, drawn while it is the one tracked. const holder = trackedContactHolder( `flights:${icao24}`, trackedIcon, parts.motion._trackedDisplayCached, ); flightState._trackedEntity = holder; entityRecord(holder).drawn = () => flightState._trackedEntity === holder; // The draw sets a height sample under the contact sees through (its // icons and models), for Cockpit's ground probe. entityRecord(holder).groundSets = () => { const sets = [...parts.rendering._groundSampleExclusions().sets]; if (trackedIcon.setId) sets.push(trackedIcon.setId); return sets; }; trackedIcon.show({ id: icao24, image: _trackedBillboardImage(), sprite, position: getTrackedPosition, // Solid cyan when the billboard is the visual (zoomed out, 3D off, or model still loading); // transparent once the tracked model is actually up (ready + shown). color: () => parts.rendering._modelOwnsVisual(flightState._trackedIcao) ? CYAN_TRANSPARENT : TRACKED_CYAN, // Screen-projected rotation, evaluated per frame on the camera's own // axes, so it stays exact through a tracked orbit. The tracked target // must never vanish into tile geometry — tracking a taxiing plane at // street level would otherwise bury the cyan icon inside the runway // skin, so it draws over depth like the fleet icon set; its // shared-host tracked card is top-composited separately. rotation: () => { const tracked = flightState.records.data.get(flightState._trackedIcao); const pos = getTrackedPosition(); if (!tracked || !pos || !flightState._viewer) return flightState._lastTrackedRotation; const projected = courseScreenRotation( _pose(), pos, parts.motion._trackedDisplayCourse(), flightState._lastTrackedRotation, ); const rot = stabilizeScreenRotation( flightState._lastTrackedRotation, projected, ); if (rot !== null) flightState._lastTrackedRotation = rot; return flightState._lastTrackedRotation; }, }); entityRecord(flightState._trackedEntity).selectionOrigin = origin; entityRecord(flightState._trackedEntity).trackedId = `flights:${icao24}`; entityRecord(flightState._trackedEntity).sprite = sprite; entityRecord(flightState._trackedEntity).labelModel = trackedLabelModelFromText(_trackedLabelText(icao24), '#39d0ff'); // A billboard has a ~zero bounding sphere, so the renderer's default follow distance is // far too tight (the user had to scroll out to read the plane). Give the target a // calibrated viewFrom — behind + above, distance scaled to altitude — for a readable // initial frame with surrounding context. (ENU: east=+X, north=+Y, up=+Z.) const followRange = Math.min( Math.max((info.altitude || 1500) * 1.1 + 2500, 3000), 30000, ); const viewFrom = vec(0, -followRange * 0.8, followRange * 0.55); // Cancel any in-progress camera flight first — otherwise the camera won't apply the // follow target's viewFrom on the first frame, so voice-initiated tracking (which // often fires mid-fly_to_location) would follow the plane WITHOUT centering/framing it // the way a click (idle camera) does. // 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). entityRecord(flightState._trackedEntity).displayPosition = parts.motion._trackedDisplayCached; // 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 the entity record's `visualPosition` instead. entityRecord(flightState._trackedEntity).visualPosition = parts.motion._trackedVisualCached; refreshTrackedReadout(flightState._trackedEntity); // The camera follows through its port: a target framed from viewFrom in // ENU, never closer than the readable minimum, whose presentation (key, // label, sprite, display position) reads the tracked entity's record. const camera = cameraOf(flightState._viewer); camera.cancelFlight(); flightState._followTarget = entityFollowTarget(flightState._trackedEntity, { position: getTrackedPosition, frame: 'enu', viewFrom, minRange: FOLLOW_MIN_RANGE_M, }); camera.follow(flightState._followTarget); // Track-history trail (PRD F1): seed from local history + async backfill. // Ground traffic draws NO trail (a taxi path is noise, not a track) — if the // plane takes off while tracked, the on_ground→false transition in update() // starts one. parts.enrichment._requestTypeEnrichment(icao24, true); // tracked plane — front of the enrichment queue parts.enrichment._requestRouteEnrichment(icao24); // Round 2 (owner): grounded contacts get trails too — a landed-but-taxiing // aircraft's history is retrievable on select. Grounded flights positions // are already surface-clamped (the surfaceM chain), so seeds/appends drape. _startTrail(icao24); _publishTrackedSelection(icao24, origin); console.log( `[Data:Flights] Tracking ${parts.queries._contactLabel(icao24, info)} (${icao24})`, ); } /** * Immediate military-suppression handoff sweep (pre-ship audit M2). * * The poll-time suppression branch in update() only reconciles every 30 s, so * toggling the Military layer showed duplicate icons (military ON: both layers * render the same aircraft ~3-4 km apart) or holes (military OFF: suppressed * aircraft absent) for up to a full poll. Fired synchronously by the registry * on the active-state TRANSITION: * * - activated → suppress known-military billboards NOW (mirror of the * poll-time branch, tracked aircraft excluded — it hands off on untrack); * - deactivated → the suppressed aircraft's state was deleted, so bring the * next OpenSky poll forward instead of waiting out the interval (update() * itself still honors _retryAt backoff). * * @param {boolean} active - New military-layer active state. * @returns {void} */ function _onMilitaryActiveChange(active) { const icons = flightState._icons; if (!flightState._viewer || !icons) return; if (active) { const suppressed = []; for (const icao24 of icons.ids()) { if (isMilitaryIcao(icao24) && icao24 !== flightState._trackedIcao) suppressed.push(icao24); } // Military-suppression: drop each duplicate with any 3D model too. for (const icao24 of suppressed) parts.icons._forgetContact(icao24); flightState.feed._count = icons.count; } else if (icons.show) { // Fire-and-forget refresh; only while the layer is actually enabled. void flightsLayer.update(flightState._viewer); } } /** * Global keydown handler — Escape deselects the tracked flight. * @param {KeyboardEvent} e */ function _onKeyDown(e) { if (e.key === 'Escape' && flightState._trackedIcao) { _cancelPendingTrackingRestore(); _clearTracking(false, { origin: 'user' }); } } /** * Install a click handler for flight selection: a pick names a draw-set * item by the contact's icao (see `aircraftPickId`). Also registers a * global keydown listener for the Escape key. * * Idempotent — returns immediately if a handler is already installed. * * @param {object} viewer */ function _installClickHandler(viewer) { if (flightState._clickSubscription) return; // already installed // Cross-layer untrack: if ANOTHER layer (military, vessels, …) grabs the follow-camera, drop our // tracking so its model/entity/update-loop don't orphan — without touching the camera's follow // (the new owner controls it). Guarded so the intermediate untrack→retrack of OUR OWN switch // (the follow briefly ended) doesn't self-clear. if (!flightState._trackedEntityChangedRemove) { flightState._trackedEntityChangedRemove = onFollowChanged( viewer, (followed) => { if ( flightState._trackedIcao && flightState._viewer && followed && followed !== flightState._followTarget ) { _clearTracking(true, { origin: followed.selectionOrigin || 'programmatic', }); } }, ); } flightState._clickSubscription = inputFor(viewer).onClick((event) => { const gesture = event.gesture; // Camera drags never select or deselect, even if they finish over a plane. // Duration alone is allowed through so a stationary long press can still // select/switch contacts; the destructive empty-space branch below applies // the full travel + duration click classifier. if (!isTrackingSelectionGesture(gesture)) return; // Cockpit mode owns the camera and keeps the current aircraft as its // first-person reference. A globe click must not fall through to the // normal empty-space deselection path; cockpit has explicit exit controls. if (document.body.classList.contains('cockpit-mode')) return; const picked = event.hit; if (picked) { // Clicking the plane we're ALREADY tracking (its tracked billboard, its // 3D model, or any pick carrying its icao) — ignore, don't deselect. // H1: the model used to have no pick id, so this fell through to // "empty space" and deselected the very plane being tracked. // Its billboard and models are draw-set items keyed by icao, like its icons. const pickedIcao = aircraftPickId(picked); if (flightState._trackedIcao && pickedIcao === flightState._trackedIcao) return; if (pickedIcao && flightState._icons?.has(pickedIcao)) { _cancelPendingTrackingRestore(); _trackFlight(pickedIcao, { origin: 'user' }); return; } } // A pick that belongs to a sibling layer (military aircraft, satellite, // vessel, station, CCTV camera…) is not "empty space" — leave tracking // alone and let that layer handle it. resolvePickId String()-coerces the // heterogeneous pick ids (numeric NORAD ids, AIS record objects) so the // registry predicates can recognize them (H2). if (picked) { const pickedId = resolvePickId(picked); if (pickedId && isOwnedByOtherLayer('flights', pickedId)) return; } // Clicked empty space — deselect only for a clean, short click. A slow // stationary press may select above, but cannot release existing tracking. if (!isTrackingClickGesture(gesture)) return; if (flightState._trackedIcao) { _cancelPendingTrackingRestore(); _clearTracking(false, { origin: 'user' }); } }); document.addEventListener('keydown', _onKeyDown); } return { _emitAwarenessEvent, _publishTrackedSelection, _contextSubjectMetadata, _isExplicitTrackingOrigin, _refreshCockpitNearContacts, _setCockpitContactMode, _applyCockpitState, _resetTrackedSelectionState, _trackedModelRegimeActive, _syncTracked2dRotation, _appendTrailFix, _refreshTrailDisplay, _startTrail, _backfillTrail, _clearTrail, _destroyTrail, /** Let the tracked billboard's set go (layer teardown). */ _disposeTrackedIcon: () => trackedIcon.dispose(), /** The tracked billboard's set id, or null before one is made. */ _clearTracking, _militaryLayerSuppresses, _applyPendingTrackingRestore, _cancelPendingTrackingRestore, _trackedLabelText, _updateTrackedLabelModel, _syncTrackedBillboardImage, _refreshTr3bContact, _refreshTr3bForStyle, _routeIsPlausible, _trackFlight, _onMilitaryActiveChange, _onKeyDown, _installClickHandler, }; }