Files
gods-eye-view/src/layers/transit/policy.js
T
Aditya 812cdf6be7 fix(transit): show a reported 359.6° bearing as hdg 0°, not hdg 360°
The selected-vehicle card rounded the operator's reported bearing without
wrapping, so a GTFS-Realtime vehicle heading 359.5° or more read
"reported hdg 360°". The card now wraps after rounding: 359.6° reads
"reported hdg 0°", 359.4° still reads "reported hdg 359°".
2026-10-28 15:09:27 +05:30

670 lines
26 KiB
JavaScript

/**
* @module layers/transit/policy
* @description Constants and pure decisions for the Transit layer. No Cesium
* scene state, no network: everything here is exercised by node:test.
*/
import {
TRANSIT_MODE_ICON,
transitRouteLabel,
} from '../../data/transitFeeds.js';
import { displayMotion, playbackPosition } from './movement.js';
export const TRANSIT_SELECTED_OVERLAY_SOURCE_ID = 'transit-selected';
export const TRANSIT_SELECTED_OVERLAY_SOURCE_OPTIONS = Object.freeze({
cohortLimit: 1,
collisionCapacity: 0,
moving: true,
});
// --- Polling / activation ---
/** Poll interval (ms). */
export const TRANSIT_POLL_MS = 15_000;
/**
* How a vehicle moves between fixes is delayed playback, not a glide: the
* display clock runs a feed-derived lag behind real time and interpolates
* between the two fixes bracketing it (`src/layers/transit/movement.js`).
* A glide that started from the drawn position at receipt time and spanned the
* report gap ran every second segment at 1.5x when MBTA vehicles reported
* every ten seconds against this fifteen-second poll — buses plainly too fast.
*/
/** Camera altitude (m) above which the layer idles: a national fleet still reads at 3,000 km. */
export const ACTIVATION_ALTITUDE_M = 3_000_000;
export const ACTIVATION_ENTER_ALTITUDE_M = ACTIVATION_ALTITUDE_M - 150_000;
export const ACTIVATION_EXIT_ALTITUDE_M = ACTIVATION_ALTITUDE_M + 150_000;
/** Debounce (ms) for camera-change proximity checks. */
export const CAMERA_DEBOUNCE_MS = 340;
/** Camera sensitivity this layer asks for while it is enabled. */
export const CAMERA_PERCENTAGE_CHANGED = 0.05;
/** Extra coverage radius (km) granted to a feed that is already active, so it does not flap at the edge. */
export const RANGE_SLACK_KM = 40;
/** Hard cap on rendered vehicles across all active feeds. */
export const MAX_VEHICLES_TOTAL = 15_000;
/** A vehicle absent from this many consecutive polls is removed. */
export const MISSED_POLLS_TO_DROP = 2;
// --- Age policy ---
/**
* Oldest fix still drawn, in ms. Past this a vehicle is REMOVED, not merely
* skipped on arrival: a feed that stops answering must not leave the last
* snapshot frozen on the globe pretending to be live traffic.
*/
export const VEHICLE_MAX_FIX_AGE_MS = 10 * 60_000;
/** A feed with no successful poll for this long reads as stale in the panel. */
export const FEED_STALE_AFTER_MS = 90_000;
/**
* A feed with no successful poll for this long has its vehicles dropped. It is
* deliberately shorter than VEHICLE_MAX_FIX_AGE_MS so a dead feed empties even
* when its last snapshot carried optimistic timestamps.
*/
export const FEED_EVICT_AFTER_MS = 5 * 60_000;
// --- Ground anchoring ---
/**
* Above this camera altitude (m) a few metres of terrain are invisible, so the
* fleet renders on the ellipsoid and no floor cells are warmed. A national view
* must not queue a country's worth of ground lookups.
*/
export const HEIGHT_SAMPLE_MAX_ALTITUDE_M = 60_000;
/**
* Floor cells warmed per poll. The shared resolver batches and chunks, but the
* bound belongs here: a metropolitan fleet is hundreds of vehicles and only the
* ones in view are worth a lookup at all.
*/
export const FLOOR_WARM_PER_POLL = 300;
/** How soon after a warm the layer looks again to see which cells landed. */
export const FLOOR_REREAD_MS = 900;
/** Re-reads before a poll's cycle gives up and waits for the next poll. */
export const FLOOR_REREAD_ATTEMPTS = 6;
// --- Rendering ---
/** On-screen glyph size in CSS px at the near end of the distance ramp. */
export const MARKER_PIXEL_SIZE = 20;
export const SELECTED_PIXEL_SIZE = 30;
/**
* How often the fleet's screen-space rotations may be recomputed. Projecting a
* course into screen space depends on the camera, so a moving camera would
* otherwise re-solve every glyph every frame; a fifth of a second of rotation
* lag on a bus icon is invisible, and the saving is not.
*/
export const ROTATION_REFRESH_MS = 200;
/**
* How often the shown/hidden sweep may run. `billboard.show` is a dirty flag,
* so doing this on every camera event during a drag would re-upload the whole
* fleet once a frame — which is the cost it exists to avoid.
*/
export const VISIBILITY_REFRESH_MS = 250;
/**
* How much wider than the camera's own view rectangle a vehicle still counts as
* on screen. Generous on purpose: a vehicle that crosses the edge mid-glide
* should already have been moving, not pop into motion at the border.
*/
const VIEW_MARGIN_RATIO = 0.6;
/**
* Whether a vehicle is close enough to the camera's look-at area to be worth
* animating frame by frame.
*
* At street level the layer holds an entire metropolitan fleet — five hundred
* and more vehicles — while the camera can see about fifteen of them. Gliding
* the other five hundred means writing five hundred billboard positions every
* frame, which makes Cesium re-upload the whole buffer, for motion nobody can
* observe. Off-screen vehicles take their newest fix directly instead; they are
* in exactly the right place, and the frame that would have drawn them moving
* is spent on the ones a person is actually looking at.
*
* @param {{south:number,north:number,west:number,east:number}|null} bounds Inflated view bounds, degrees.
* @param {{lat:number, lon:number}} at Vehicle position.
* @returns {boolean} True when there are no bounds to apply, or it is inside them.
*/
export function withinViewBounds(bounds, at) {
if (!bounds || !at) return true;
if (at.lat < bounds.south || at.lat > bounds.north) return false;
if (bounds.west <= bounds.east) {
return at.lon >= bounds.west && at.lon <= bounds.east;
}
// The rectangle straddles the antimeridian, so "inside" is the union of the
// two halves rather than the span between them.
return at.lon >= bounds.west || at.lon <= bounds.east;
}
/**
* Whether a gliding vehicle is near enough the view to be worth animating and
* showing — judged on where it is NOW as well as where it is going.
*
* Testing only the destination hid a bus that was plainly on screen: a fix
* arrives placing it just past the padded edge, and it disappeared from inside
* the view instead of driving out of it, its glide thrown away in the same
* frame. A vehicle counts as near the view while either end of its current
* glide is inside the bounds, so it leaves the way a person expects — by
* travelling out — and arrives the same way.
*
* @param {{south:number,north:number,west:number,east:number}|null} bounds
* @param {{to:{lat:number,lon:number}, from:{lat:number,lon:number}|null}} entry
* @returns {boolean}
*/
export function vehicleNearView(bounds, entry) {
if (!bounds || !entry) return true;
if (withinViewBounds(bounds, entry.to)) return true;
return entry.from ? withinViewBounds(bounds, entry.from) : false;
}
/**
* Inflate a camera view rectangle (degrees) into the bounds above.
*
* Longitude is a circle, so padding it has a ceiling: once the padded span
* reaches 360° the rectangle is every longitude there is, and wrapping each
* endpoint on its own would turn that into a narrow band pointing the wrong
* way. A high oblique view over Europe spans about 166°, pads to well past a
* full turn, and used to come back as -177.8°..-172.2° — five degrees of the
* Pacific — which hid an entire national fleet that was plainly on screen. So
* a padded span that closes the circle is reported as the whole circle, and
* only a span that stays under it is wrapped.
*
* @param {{south:number,north:number,west:number,east:number}|null} rect
* @param {number} [ratio=VIEW_MARGIN_RATIO]
* @returns {{south:number,north:number,west:number,east:number}|null}
*/
export function inflateViewBounds(rect, ratio = VIEW_MARGIN_RATIO) {
if (!rect) return null;
const { south, north, west, east } = rect;
if (![south, north, west, east].every(Number.isFinite)) return null;
const padLat = Math.max(0, (north - south) * ratio);
const spanLon = west <= east ? east - west : 360 - west + east;
const padLon = Math.max(0, spanLon * ratio);
const bounds = {
south: Math.max(-90, south - padLat),
north: Math.min(90, north + padLat),
west: -180,
east: 180,
};
if (spanLon + padLon * 2 >= 360) return bounds;
bounds.west = west - padLon < -180 ? west - padLon + 360 : west - padLon;
bounds.east = east + padLon > 180 ? east + padLon - 360 : east + padLon;
return bounds;
}
/** Throttle (ms) for re-anchoring the selected vehicle's card while it glides. */
export const SELECTED_CARD_REFRESH_MS = 250;
/** Mode palette: distinct at a glance, none reused by flights (white/cyan), military (amber), or vessels. */
export const TRANSIT_MODE_COLORS = Object.freeze({
bus: '#5EF08A',
tram: '#FFC24A',
subway: '#FF4538',
rail: '#D9A6FF',
ferry: '#5FD6FF',
unknown: '#D8DDE5',
});
/**
* Stable key for a vehicle across polls.
* @param {string} feedId
* @param {string} vehicleId
* @returns {string}
*/
export function transitVehicleKey(feedId, vehicleId) {
return `${feedId}:${vehicleId}`;
}
/**
* Where the vehicle is drawn: the display clock's position along its fix
* history. `now` is accepted for the older callers and ignored — the clock is
* advanced by the frame pass, and reading it here must not move it.
* @param {{fixes?:Array, to?:{lat:number,lon:number}}} entry
* @param {number} [now] Unused.
* @returns {{lat:number, lon:number, settled:boolean}}
*/
export function interpolatedVehiclePosition(entry, now) {
void now;
const played = entry?.track ? playbackPosition(entry) : null;
if (played) return played;
const to = entry?.to || { lat: NaN, lon: NaN };
return { lat: to.lat, lon: to.lon, settled: true };
}
/**
* When a fix was REPORTED, in ms, from the best timestamp available.
*
* The ordering questions — is this fix newer than the one we drew, how much
* time passed between them — need an absolute time, not an age. Same ladder as
* the age helper: the vehicle's own stamp, else the snapshot's fetch time.
*
* @param {object} record Normalized vehicle record.
* @param {number|null} [fetchedAtMs] Snapshot fetch time.
* @returns {number} Report time in ms.
*/
export function vehicleReportTimeMs(record, fetchedAtMs = null) {
const seconds = Number(record?.timestamp);
if (Number.isFinite(seconds) && seconds > 0) return seconds * 1000;
if (Number.isFinite(fetchedAtMs)) return fetchedAtMs;
return Date.now();
}
/**
* Age of a vehicle's reported fix in ms, from the best timestamp available.
*
* The proxy already resolves the ladder (the vehicle's own timestamp, else the
* feed header's, else fetch time) and says which it used. A record that somehow
* arrives with no usable timestamp at all is aged from the snapshot's fetch
* time, never from "now" — treating an unstamped fix as fresh is exactly how a
* ten-minute-old bus gets drawn as live.
*
* @param {object} record Normalized vehicle record.
* @param {number} nowMs
* @param {number|null} [fetchedAtMs] Snapshot fetch time.
* @returns {number} Age in ms (never negative).
*/
export function vehicleFixAgeMs(record, nowMs, fetchedAtMs = null) {
const seconds = Number(record?.timestamp);
if (Number.isFinite(seconds) && seconds > 0) {
return Math.max(0, nowMs - seconds * 1000);
}
if (Number.isFinite(fetchedAtMs)) return Math.max(0, nowMs - fetchedAtMs);
return 0;
}
/**
* Whether a feed fix is too old to draw.
* @param {object} record Normalized vehicle record.
* @param {number} nowMs
* @param {number|null} [fetchedAtMs] Snapshot fetch time.
* @returns {boolean}
*/
export function isStaleVehicleFix(record, nowMs, fetchedAtMs = null) {
return vehicleFixAgeMs(record, nowMs, fetchedAtMs) > VEHICLE_MAX_FIX_AGE_MS;
}
/**
* Roll per-feed poll health into the one honest row state the layer panel reads.
*
* `every(stale)` was the bug this replaces: with Boston fresh and Helsinki an
* hour old, "not every feed is stale" read as nominal and the row claimed
* everything was fine. One stale feed beside a fresh one is DEGRADED — the
* view is part live and part not, and the row has to say so.
*
* @param {Array<{stale:boolean, error:string|null, retryInSec?:number|null,
* upstreamAt:number|null, loading:boolean}>} statuses
* @param {number} nowMs
* @returns {{stale:boolean, degraded:boolean, error:string|null, retryInSec:number|null,
* loading:boolean, staleFeeds:number}}
*/
export function aggregateTransitFeedHealth(statuses, nowMs) {
const list = Array.isArray(statuses) ? statuses : [];
if (list.length === 0) {
return {
stale: false,
degraded: false,
error: null,
retryInSec: null,
loading: false,
staleFeeds: 0,
};
}
// Age is measured from when the OPERATOR last answered, never from when this
// browser last received bytes — the proxy replays its cached copy on a fixed
// cadence during an outage, and that cadence is not freshness.
const isStale = (status) =>
status.stale === true ||
(Number.isFinite(status.upstreamAt) &&
nowMs - status.upstreamAt > FEED_STALE_AFTER_MS);
const staleFeeds = list.filter(isStale).length;
const failing = list.find((status) => status.error) || null;
const error = failing?.error || null;
return {
stale: staleFeeds === list.length,
degraded: (staleFeeds > 0 && staleFeeds < list.length) || Boolean(error),
error,
retryInSec: Number.isFinite(failing?.retryInSec)
? failing.retryInSec
: null,
loading: list.some((status) => status.loading),
staleFeeds,
};
}
// AI tools (src/tools/queries/mobility.js) import this module, so no i18n here:
// the card copy takes `t` from the caller (selection.js); without it, English.
const msg = (text) => text;
/** English {placeholder} interpolation, the default `t` of the card copy. */
function englishText(text, values) {
if (!values) return text;
return text.replace(/\{([A-Za-z0-9_]+)\}/g, (literal, name) =>
Object.hasOwn(values, name) ? String(values[name]) : literal,
);
}
/** GTFS-realtime OccupancyStatus in words. */
function occupancyText(occupancy, t) {
switch (occupancy) {
case 'EMPTY':
return t('empty', { context: 'occupancy' });
case 'MANY_SEATS_AVAILABLE':
return t('many seats available', { context: 'occupancy' });
case 'FEW_SEATS_AVAILABLE':
return t('few seats available', { context: 'occupancy' });
case 'STANDING_ROOM_ONLY':
return t('standing room only', { context: 'occupancy' });
case 'CRUSHED_STANDING_ROOM_ONLY':
return t('crushed standing room only', { context: 'occupancy' });
case 'FULL':
return t('full', { context: 'occupancy' });
case 'NOT_ACCEPTING_PASSENGERS':
return t('not accepting passengers', { context: 'occupancy' });
case 'NOT_BOARDABLE':
return t('not boardable', { context: 'occupancy' });
default:
return occupancy.toLowerCase().replaceAll('_', ' ');
}
}
/**
* Build the human lines of the selection card from a vehicle record.
* @param {object} feed Registry entry.
* @param {object} record Normalized vehicle record.
* @param {string} mode Resolved transit mode.
* @param {number} nowMs
* @param {number|null} [fetchedAtMs] Snapshot fetch time.
* @param {object|null} [entry] Playback entry of the vehicle.
* @param {(text: string, values?: object) => string} [t] Translates the
* card's English text; English when omitted.
* @returns {{title:string, details:string[]}}
*/
export function buildTransitSelectionCopy(
feed,
record,
mode,
nowMs,
fetchedAtMs = null,
entry = null,
t = englishText,
) {
const icon = TRANSIT_MODE_ICON[mode] || TRANSIT_MODE_ICON.unknown;
const routeLabel = record.routeId
? t('Route {route}', { route: transitRouteLabel(feed, record.routeId) })
: t('Vehicle {vehicle}', { vehicle: record.label || record.id });
const title = `${icon} ${routeLabel}`;
// The mode is said in words on its own line. A glyph and a route id do not
// tell a reader that the dot on Tremont Street is a subway train, and a
// subway drawn on a street reads as a bug until the card says what it is.
// An operator's own mode word (feed.modeWords) is a name and stays as is.
const kindWord =
feed?.modeWords?.[mode]?.word ||
t(TRANSIT_MODE_WORD[mode] || TRANSIT_MODE_WORD.unknown);
const details = [`${kindWord} · ${feed.name} · ${feed.region}`];
const motion = [];
// What the SCREEN is doing leads, because that is what the reader can check.
const shown = entry ? displayMotion(entry, nowMs) : null;
if (shown?.word === 'STOPPED')
motion.push(t('Stopped', { context: 'vehicle motion' }));
else if (shown?.word === 'NO FIX') motion.push(t('No recent fix'));
else if (shown?.word === 'WAITING') motion.push(t('Waiting for update'));
else if (shown) motion.push(t('Moving'));
if (motion.length) details.push(motion.join(' · '));
const reportedMotion = [];
if (Number.isFinite(record.speedMps))
reportedMotion.push(
t('reported {speed} km/h', { speed: Math.round(record.speedMps * 3.6) }),
);
// 359.5° and above rounds to north; modulo keeps it from printing 360°.
if (Number.isFinite(record.bearing))
reportedMotion.push(
t('reported hdg {heading}°', {
heading: Math.round(record.bearing) % 360,
}),
);
// The operator's own claim, kept as a REPORT rather than as the live state.
// It describes the moment of the report, which the display may not have
// reached yet; presenting it as "now" is what put STOPPED on a moving metro.
const state = [];
if (record.status === 'STOPPED_AT' && record.stopId)
state.push(
t('Last report: stopped at stop {stop}', { stop: record.stopId }),
);
else if (record.status === 'INCOMING_AT' && record.stopId)
state.push(
t('Last report: arriving at stop {stop}', { stop: record.stopId }),
);
else if (record.status === 'IN_TRANSIT_TO' && record.stopId)
state.push(t('Last report: next stop {stop}', { stop: record.stopId }));
if (record.occupancy && record.occupancy !== 'NO_DATA_AVAILABLE') {
state.push(occupancyText(record.occupancy, t));
}
if (reportedMotion.length) details.push(reportedMotion.join(' · '));
if (state.length) details.push(state.join(' · '));
// Underground services are drawn on the surface directly above themselves.
// That is a deliberate choice — a train nobody can see is not worth drawing —
// but it has to be stated, or a metro sitting on a road looks like an error.
if (UNDERGROUND_MODES.has(mode)) {
details.push(t('Shown at street level · depth not in the feed'));
}
details.push(
`${t('Vehicle {vehicle}', { vehicle: record.id })}${record.label && record.label !== record.id ? ` · ${record.label}` : ''}`,
);
const ageS = Math.round(
(Number.isFinite(entry?.sample?.latestReportAgeMs)
? entry.sample.latestReportAgeMs
: vehicleFixAgeMs(record, nowMs, fetchedAtMs)) / 1000,
);
// Seconds through 89s, then whole minutes. Rounding 90s up would skip
// "1 min" and call a minute-and-a-half-old report two minutes old.
const reported =
ageS < 90
? t('Reported {seconds} s ago', { seconds: ageS })
: t('Reported {minutes} min ago', { minutes: Math.floor(ageS / 60) });
// A time the feed did not give for THIS vehicle is labelled, so the card
// never presents a borrowed or inferred time as the vehicle's own report.
const ownTime =
Number.isFinite(record.timestamp) &&
record.timestamp > 0 &&
(!record.timestampSource || record.timestampSource === 'vehicle');
// How far behind real time the display is running, said separately from
// how old the newest report is: the two are different facts.
const lagS = Number.isFinite(entry?.sample?.actualDelayMs)
? Math.max(0, Math.round(entry.sample.actualDelayMs / 1000))
: null;
const behind =
lagS === null
? ''
: ` · ${t('shown {seconds} s behind', { seconds: lagS })}`;
details.splice(
motion.length ? 2 : 1,
0,
(ownTime ? reported : t('{reported} (feed time)', { reported })) + behind,
);
if (entry?.track?.count) {
const duration = Math.max(
0,
Math.min(entry.playT, entry.fixes.at(-1).t) - entry.fixes[0].t,
);
const minutes = Math.round(duration / 60000);
details.push(
entry.track.truncated || entry.trailTruncated
? t('Available trail: {minutes} min (limited)', { minutes })
: t('Available trail: {minutes} min', { minutes }),
);
}
return { title, details };
}
/**
* Shared-host card for the selected vehicle.
* @param {string} key
* @param {object|(() => object|null)} position Cartesian position, or a
* getter the host calls on every paint so the anchor follows the marker.
* @param {{title:string, details:string[]}} copy
* @param {string} mode
* @returns {object|null}
*/
export function createTransitSelectedOverlayEntry(key, position, copy, mode) {
if (!key || !position) return null;
return {
id: String(key),
position,
variant: 'selected',
selected: true,
protected: true,
paintLane: 'selected',
collisionGroup: 'ambient-card',
priority: Number.MAX_SAFE_INTEGER,
title: copy.title,
details: copy.details,
accent: TRANSIT_MODE_COLORS[mode] || TRANSIT_MODE_COLORS.unknown,
interactive: false,
anchorRadiusPx: 9,
minAnchorGapPx: 11,
verticalOnly: true,
placement: 'above',
edgeFade: 'keyhole',
horizonCull: true,
terrainOcclusion: false,
};
}
/** Modes that ordinarily run below the street, drawn on the surface above themselves. */
const UNDERGROUND_MODES = new Set(['subway']);
/** The mode in plain words, for a card a person reads rather than scans. */
const TRANSIT_MODE_WORD = Object.freeze({
bus: msg('Bus'),
tram: msg('Tram'),
subway: msg('Subway'),
rail: msg('Train'),
ferry: msg('Ferry'),
unknown: msg('Transit vehicle'),
});
/** Short, fixed-width mode word for the detection card's class field. */
const TRANSIT_MODE_ABBR = Object.freeze({
bus: 'BUS',
tram: 'TRAM',
subway: 'METRO',
rail: 'RAIL',
ferry: 'FERRY',
unknown: 'TRANSIT',
});
/**
* The mode in the operator's own vocabulary. A Toronto 501 and a Helsinki 1010
* are both the `tram` mode, but only one of them is called a tram by the people
* who ride it. A feed may name the modes it runs; everything else falls through
* to the shared table, so an override renames one word and nothing else.
* @param {string} mode Resolved transit mode.
* @param {object|null} [feed] Registry entry.
* @returns {string}
*/
export function transitModeWord(mode, feed = null) {
return (
feed?.modeWords?.[mode]?.word ||
TRANSIT_MODE_WORD[mode] ||
TRANSIT_MODE_WORD.unknown
);
}
/**
* The operator's short mode word for the fixed-width detection fields.
* @param {string} mode Resolved transit mode.
* @param {object|null} [feed] Registry entry.
* @returns {string}
*/
export function transitModeAbbr(mode, feed = null) {
return (
feed?.modeWords?.[mode]?.abbr ||
TRANSIT_MODE_ABBR[mode] ||
TRANSIT_MODE_ABBR.unknown
);
}
/**
* The bright first line of a vehicle's detection label: its route when the feed
* names one, else the fleet number, else the raw id. What a person standing at
* the stop would call it.
* @param {object} record Normalized vehicle record.
* @param {object|null} [feed] Registry entry, for feeds whose route ids are
* internal keys rather than the number on the vehicle.
* @returns {string}
*/
export function transitDetectionId(record, feed = null) {
const route =
typeof record?.routeId === 'string' ? record.routeId.trim() : '';
if (route) return elideRouteText(transitRouteLabel(feed, route));
const label = typeof record?.label === 'string' ? record.label.trim() : '';
if (label) return elideRouteText(label);
return elideRouteText(String(record?.id || 'TRANSIT'));
}
/** Longest route text the single-line detection label can carry. */
const DETECTION_ID_MAX_CHARS = 14;
/**
* Cut long route text with an ellipsis, so a reader can see it was cut.
*
* `Shuttle-Generic` used to reach the screen as `SHUTTLE-GENERI`, which does
* not read as an abbreviation — it reads as a typo, or as a route that exists.
* A trailing ellipsis costs one character and says plainly that there is more.
*
* @param {string} text
* @returns {string} Uppercase, at most DETECTION_ID_MAX_CHARS characters.
*/
function elideRouteText(text) {
const value = String(text || '').toUpperCase();
if (value.length <= DETECTION_ID_MAX_CHARS) return value;
return `${value.slice(0, DETECTION_ID_MAX_CHARS - 1)}\u2026`;
}
/**
* The dim second line: what kind of vehicle it is and who runs it.
* @param {string} mode Resolved transit mode.
* @param {object} feed Registry entry.
* @returns {string}
*/
export function transitDetectionClass(mode, feed) {
const kind = transitModeAbbr(mode, feed);
const operator =
typeof feed?.name === 'string' ? feed.name.toUpperCase() : '';
return operator ? `${kind} ${operator}`.slice(0, 20) : kind;
}
/**
* The micro field the detection host actually paints beside the route.
*
* The host draws a single-line track label — the bright id and one dim
* micro-field — so mode and status have to share that field or go unseen. Mode
* leads because it tells you what you are looking at (and matches the glyph
* shape), then what the vehicle is doing: a stopped bus reporting 0 km/h is
* worth saying out loud, it is the most common state in a city at rush hour.
*
* @param {object} record Normalized vehicle record.
* @param {string} mode Resolved transit mode.
* @param {number} [nowMs]
* @param {object|null} [feed] Registry entry, for its own mode vocabulary.
* @returns {string}
*/
export function transitDetectionMetric(
entry,
mode,
nowMs = Date.now(),
feed = null,
) {
const kind = transitModeAbbr(mode, feed);
const state = transitVehicleState(entry, nowMs);
return state ? `${kind} ${state}` : kind;
}
/**
* What the vehicle is doing right now, in as few characters as it takes —
* judged on what the screen is showing, not on what the feed claims.
*
* This used to read `current_status` straight out of the newest record, which
* is how a metro came to glide across the owner's screen with STOPPED printed
* beside it: the status describes the moment of the report, and the display is
* still animating the segment before it. The feed is not lying; it is early.
* Its claim is kept, verbatim and dated, on the selected card.
*
* @param {object} entry Vehicle runtime entry.
* @param {number} [nowMs]
* @returns {string}
*/
function transitVehicleState(entry, nowMs = Date.now()) {
return displayMotion(entry, nowMs).word;
}