Types

type Station = {
    /** Station id; equals the owning track group's id. */
    id: string;
    /** Competitive multiplayer company id inherited from the track group. */
    companyId?: string;
    /** Display name: `'Turnaround'` for a pocket station. */
    name: string;
    /** [lng, lat] midpoint of the track group's centerline. */
    coords: [number, number];
    /** Ids of the track group's tracks. */
    trackIds: string[];
    /** Owning track group id; same value as `id`. */
    trackGroupId: string;
    /** Ids of the group's station track nodes (platform lines), yard berths excluded. */
    stNodeIds: string[];
    /** `'constructed'` | `'blueprint'` | `'preview'`. */
    buildType: BuildType;
    /** Ids of routes whose stNodes include one of this station's. */
    routeIds: string[];
    /** Declared TrainTypeId; the station builder sets no value for it. */
    trainType?: TrainTypeId;
    /** StationTypeId; kept from the previous derivation, else `'standard'`. */
    stationType?: StationTypeId;
    /** Stations reachable on foot with `walkingTime` in seconds … */
    nearbyStations?: { stationId: string; walkingTime: number }[];
    /** Unix time in ms (`Date.now()`) of the first derivation, kept across rebuilds. */
    createdAt?: number;
    /** Cars the platform fits, rounded down to whole car sets … */
    maxCars?: number;
    /** True for a pocket (zero-platform) station where routes reverse and nobody boards. */
    noBoarding?: boolean;
};

type Route = {
    /** UUID assigned at creation. */
    id: string;
    /** Competitive multiplayer company id; absent otherwise. */
    companyId?: string;
    /** Null on player routes; the parent route id on a temporary route created for one train … */
    tempParentId: string | null;
    /** On yard temp routes: `'pull-out'` (berth to route) or `'put-in'` (route to berth). */
    yardDeadhead?: 'pull-out' | 'put-in';
    /** Put-in temp routes: berth slot the train parks on, 0 = deepest. */
    parkSlot?: number;
    /** Short label shown in the route bullet. */
    bullet: string;
    /** Optional long name. */
    fullName?: string;
    /** Station track nodes in stop order; empty from route creation (a duplicate copies its source's). */
    stNodes: StationTrackNode[];
    /** Consecutive stNode pairs with the track path between them. */
    stCombos: RouteStCombo[];
    /** Player-placed via points the path must run through. */
    waypoints?: RouteWaypoint[];
    /** Route color; CSS color string. */
    color: string;
    /** Bullet text color; CSS color string. */
    textColor: string;
    /** True for a two-tone bullet; undefined when off. */
    bordered?: boolean;
    /** Per stNode visit: `arrivalTime` and `departureTime` in seconds from route start. */
    stComboTimings: RouteStComboTiming[];
    /** A flat train count; 0 at creation. */
    idealTrainCount: number;
    /** Trains per demand period (`highDemand`, `mediumDemand`, `lowDemand`, ...). */
    trainSchedule?: RouteTrainSchedule;
    /** Timetable scheduling: `mode` (`'frequency'` | `'timetable'`) and `periods`. */
    timetableSchedule?: RouteTimetableSchedule;
    /** Bullet shape: `'circle'` | `'diamond'` | `'square'` | `'rounded-square'` | `'triangle'`. */
    shape?: RouteShape;
    /** Bullet font style: `'mono'` | `'bolder'` | `'lighter'` | `'italic'`. */
    font?: RouteBulletFont;
    /** Bullet label size: `'small'` shrinks the glyphs within the badge. */
    textSize?: RouteBulletTextSize;
    /** Diagram label style: `'bullet'` | `'text'`. */
    catStyle?: RouteCatStyle;
    /** Alternate-platform terminus entries: `arrivalStComboIndex`, `departureStComboIndex`, `stationId`, `platforms`. */
    terminusPlatformAlternates?: TerminusPlatformAlternates[];
    /** Player allowlist of platform stNode ids per terminus station id. */
    allowedTerminusPlatforms?: { [stationId: string]: string[] } | null;
    /** Cars per train; the train type's `defaultCars` (falling back to `minCars`) at creation. */
    carsPerTrain?: number;
    /** TrainTypeId the route runs; DEFAULT_TRAIN_TYPE_ID when none was chosen. */
    trainType?: TrainTypeId;
    /** Single yard id from route creation … */
    yardId?: string;
    /** Supplying yards, each `{ yardId, share }` with `share` the fraction (0..1] of that yard's berths. */
    yardAssignments?: RouteYardAssignment[];
    /** Unix time in ms (`Date.now()`) at creation or duplication. */
    createdAt?: number;
    /** Set while a track edit, or a save load with missing tracks, left the route without a path. */
    disruption?: RouteDisruption | null;
};

type RouteTrainSchedule = {
    /** Number of trains for high demand periods */
    highDemand: number;
    /** Number of trains for medium demand periods */
    mediumDemand: number;
    /** Number of trains for low demand periods */
    lowDemand: number;
    /** Number of trains for very low demand periods. */
    veryLowDemand?: number;
};

type RouteTimetableSchedule = {
    /** `'frequency'` (train counts per demand tier from `trainSchedule`) or `'timetable'` (headways per period). */
    mode: SchedulingMode;
    /** Time periods with their target headways. */
    periods: ScheduleTimePeriod[];
};

type ScheduleTimePeriod = {
    /** Period id. */
    id: string;
    /** Display name. */
    name: string;
    /** First hour of the period, inclusive. */
    startHour: number;
    /** Hour the period ends, exclusive. */
    endHour: number;
    /** Target headway in seconds. */
    headwaySeconds: number;
};

type RouteScheduleSnapshot = {
    /** Number of trains the route is set to run. */
    idealTrainCount: number;
    /** Copy of the demand-tier train counts (`highDemand`, `mediumDemand`, `lowDemand`, `veryLowDemand`). */
    trainSchedule?: RouteTrainSchedule;
    /** Copy of the timetable `mode` and `periods` (each period copied). */
    timetableSchedule?: RouteTimetableSchedule;
};

type StationTrackNode = {
    /** Station track node id; routes list these as stops (`Route.stNodes`). */
    id: string;
    /** [lng, lat] of the node. */
    center: [number, number];
    /** The track IDs that connect to this node */
    trackIds: [string, string];
    /** Build state of the node. */
    buildType: BuildType;
    /** True when this node joins two yard tracks, or two station tracks the player designated as a yard berth … */
    isYard?: boolean;
};

type RouteStCombo = {
    /** The ID of the starting station track node */
    startStNodeId: string;
    /** The ID of the ending station track node */
    endStNodeId: string;
    /** The path of the route between the two station track nodes */
    path: TrackRoutePath[];
    /** Summed `length` of the path; m. */
    distance: number;
};

type TrackRoutePath = {
    /** Track id. */
    trackId: string;
    /** If trains on this route travel in the opposite direction of the track */
    reversed: boolean;
    /** Track length; m. */
    length: number;
    /** The IDs of the signals on part or all of this path */
    signals: TrackRoutePathSignal[];
};

type TrackRoutePathSignal = {
    /** Signal id. */
    signalId: string;
    /** Part of the track the signal covers: `{ start, end }` progress in m, or `'all'`. */
    areaCovered: SignalTrackCoverage;
};

type RouteStComboTiming = {
    /** Station track node of this stop. */
    stNodeId: string;
    /** The order the station track node is in the route so if a train visits an stNode more than once they don't … */
    stNodeIndex: number;
    /** Seconds from route start to arrival at this stop. */
    arrivalTime: number;
    /** Seconds from route start to departure from this stop. */
    departureTime: number;
};

type RouteWaypoint = {
    /** Waypoint id. */
    id: string;
    /** Snapped position on the track, where the waypoint marker renders. */
    coords: [number, number];
    /** Track the leg must run over. */
    trackId: string;
    /** Stop the leg starts at. */
    fromStNodeId: string;
    /** Stop the leg ends at. */
    toStNodeId: string;
};

type TerminusPlatformAlternates = {
    /** Index in route.stCombos of the stCombo arriving at the terminus */
    arrivalStComboIndex: number;
    /** Index in route.stCombos of the stCombo departing from the terminus */
    departureStComboIndex: number;
    /** ID of the terminus station */
    stationId: string;
    /** Each entry is one platform the train can use at this terminus. */
    platforms: Array<{…}>;
};

type RouteYardAssignment = {
    /** Supplying yard id. */
    yardId: string;
    /** Fraction (0..1] of the yard's berths this route may claim. */
    share: number;
};

type RouteDisruption = {
    /** Human-readable cause, e.g. */
    reason: string;
    /** Game time (elapsedSeconds) when the disruption began */
    sinceSeconds: number;
};

type FareGroup = {
    /** Fare group id. */
    id: string;
    /** Player-editable display name; empty string shows the localized default. */
    name: string;
    /** `'flat'` | `'route'` | `'distance'` | `'zone'`. */
    fareSystem: FareSystem;
    /** Fare when `fareSystem` is `'flat'`: charged once per journey in the group … */
    flatFare: number;
    /** Per-route price keyed by route id when `fareSystem` is `'route'`. */
    routeFares: Record<string, number>;
    /** Ordered route ids in the group. */
    routeIds: string[];
    /** `'all-paid'` | `'count-within-group'` | `'count-all-groups'` | `'free-within-group'` (legacy … */
    transferPolicy: FareTransferPolicy;
    /** Distance system: flag-fall charge, paid once per trip in the group … */
    boardingCharge: number;
    /** Distance system: price per km ridden; $/km. */
    perKmRate: number;
    /** Distance system: `'straight-line'` or `'track'`. */
    distanceMode: FareDistanceMode;
    /** Distance and zone systems: maximum fare per trip. */
    fareCap: number;
    /** Zone system: ordered fare zones; index + 1 is the displayed zone number and the ring order. */
    zones: FareZone[];
    /** Zone system: `'count'` (pay per distinct zone) or `'combination'` (pay the contiguous span … */
    zonePricingMode: FareZonePricingMode;
    /** Zone system: fare for the first charged zone. */
    zoneBaseFare: number;
    /** Zone system: amount added per additional charged zone. */
    zonePerZoneFare: number;
    /** Deprecated early-save flag superseded by `transferPolicy`. */
    chargeOnInterGroupTransfer?: boolean;
    /** Off-peak discount. */
    offPeakFareMultiplier?: number;
};

type FareZone = {
    /** Zone id. */
    id: string;
    /** MultiPolygon coordinates ([lng, lat]): polygons … */
    polygons: [number, number][][][];
};

type Track = {
    /** Track id. A drag preview uses `'preview-centerline'` plus `'preview-track-<n>'` lanes. */
    id: string | 'preview-centerline' | 'preview-track-1' | 'preview-track-2';
    /** [lng, lat] polyline in travel order. */
    coords: [number, number][];
    /** Elevation at `coords[0]`; m; negative below grade. */
    startElevation: number;
    /** Elevation at the last coordinate; m; same scale as `startElevation`. */
    endElevation: number;
    /** `'constructed'` | `'blueprint'` | `'preview'`. */
    buildType: BuildType;
    /** Render state: `'constructed'` | `'blueprint'` | `'preview'` | `'preview-center'` | `'preview-connected'`. */
    displayType: 'constructed' | 'blueprint' | 'preview' | 'preview-center' | 'preview-connected';
    /** `'station'` | `'scissors-crossover'` | `'express-station'` | `'yard'` | null. */
    type: 'station' | 'scissors-crossover' | 'express-station' | 'yard' | null;
    /** True on both half-tracks of a station platform line the player converted to a yard berth. */
    yardBerth?: boolean;
    /** True on a `'station'`-type track whose platform has screen doors. */
    platformScreenDoors?: boolean;
    /** True where trains may reverse. */
    reversable: boolean;
    /** False on scissors-crossover diagonals, true on tracks from regular construction. */
    interactable: boolean;
    /** Polyline length of `coords`; m. */
    length: number;
    /** TrackTypeId: decides which train types may run it, and its train type's stats set the track's speed limits … */
    trackType?: TrackTypeId;
    /** Share of `length` over water, 0 to 100 … */
    waterIntersectionPercentage?: number;
    /** Unix time in ms (`Date.now()`) when the generator created the track. */
    createdAt?: number;
    /** CurveType the generator used; `'straight'` unless a curve was fitted. */
    curveType?: CurveType;
    /** Analytic centerline curvature: `startCurvature`, `endCurvature` (1/m), `length` (m) … */
    curveGeometry?: {
        /** Curvature at the start; 1/m, signed. */
        startCurvature: number;
        /** Curvature at the end; 1/m, signed. */
        endCurvature: number;
        /** Centerline arc length (m) the curvatures are parameterized over. */
        length: number;
        /** Optional piecewise-linear curvature profile. */
        profile?: { position: number; curvature: number }[];
    };
    /** True on tracks from track construction, yard generation and `api.build`. */
    cantEnabled?: boolean;
    /** Meters at each end (`start`, `end`) covered by a lane-spacing transition … */
    offsetTransitionZones?: {
        /** Transition length at the start of the track. */
        start?: number;
        /** Transition length at the end of the track. */
        end?: number;
    };
    /** Street-running data: `roadSegmentIds`, `speedLimitMps` (m/s), optional `roadName`. */
    streetRunning?: {
        /** Ids of the road segments the track runs along. */
        roadSegmentIds: string[];
        /** Speed limit of the road; m/s. */
        speedLimitMps: number;
        /** Name of the road, when it has one. */
        roadName?: string;
        /** Declared on the type; the game writes and reads no value. */
        isExclusiveROW?: boolean;
    };
};

type Train = {
    /** UUID assigned when the train is generated, unless the generator was given an id. */
    id: string;
    /** Competitive multiplayer company id; absent otherwise. */
    companyId?: string;
    /** Id of the route the train runs, temp routes included. */
    routeId: string;
    /** `cars` times the train type's `carLength`. */
    length: number;
    /** Car count: the route's `carsPerTrain`, else the train type's `carsPerCarSet`. */
    cars?: number;
    /** TrainTypeId of the generated train. */
    trainType?: TrainTypeId;
    /** Progress through the route: `index` of the current stCombo, `gapFromHeadToEndOfRoute` (m) … */
    currentStComboInfo: {
        /** The index of the current station track route combo */
        index: number;
        /** The train should stop when the head of the train is this distance from the end of the current station … */
        gapFromHeadToEndOfRoute: number;
        /** The game time when the train arrived the first station track node of the current station track route combo */
        timeAtStop: number | null;
        /** The game time when the train departed the first station track node of the current station track route combo */
        timeAtStopEnd: number | null;
        /** The ID of the station track node that this train is headed to */
        endStNodeId: string | null;
        /** True when the train has to change direction to depart the stop it's currently dwelling at … */
        reversesAtStop?: boolean;
        /** The dynamic dwell computed for the in-progress stop (see DynamicDwellSnapshot). */
        dynamicDwell?: DynamicDwellSnapshot;
    };
    /** `speed` in m/s and `acceleration` in m/s^2. */
    motion: {
        /** Current speed; m/s. */
        speed: number;
        /** Current acceleration; m/s^2. */
        acceleration: number;
    };
    /** Per window type: occupied tracks, head and tail progress along the stCombo, coords and signal ids. */
    windows: AllTrainWindowCollections;
    /** Per stNode visit: actual and expected arrival and departure times in game seconds, null until known. */
    timings: TrainStNodeTiming[];
    /** `maxCapacity` in passengers: `cars` times the train type's `capacityPerCar`. */
    specs: {
        /** Passenger capacity: `cars` times the train type's `capacityPerCar`. */
        maxCapacity: number;
    };
    /** `totalSeconds` in service and `lastChargedAt` (game seconds) for operating-cost billing. */
    operationalTime: {
        /** Total seconds this train has been in service */
        totalSeconds: number;
        /** Last time the operational cost was charged */
        lastChargedAt: number;
    };
    /** Per-train substitute stCombos keyed by stCombo index, applied over the route for alternate-platform termini. */
    stComboOverrides?: { [index: number]: RouteStCombo } | null;
    /** Which demand periods the train runs: `highDemand`, `mediumDemand`, `lowDemand`, `veryLowDemand` booleans. */
    operatingSchedule?: {
        /** Runs in high-demand hours. */
        highDemand: boolean;
        /** Runs in medium-demand hours. */
        mediumDemand: boolean;
        /** Runs in low-demand hours. */
        lowDemand: boolean;
        /** Runs in very-low-demand hours. */
        veryLowDemand: boolean;
    };
    /** Declared on the type; the game writes no value, so it is always absent. */
    assignedSlot?: number;
    /** `lastMovementTime` (game seconds) and `lastStComboIndex` of the last detected movement. */
    stuckDetection?: {
        /** Last time this train moved (changed stComboIndex or had speed > 0) */
        lastMovementTime: number;
        /** Last stComboIndex when movement was detected */
        lastStComboIndex: number;
    };
    /** Set while stabled at a yard: `yardId`, `berthStNodeId`, optional `slot` (0 = deepest). */
    parked?: { yardId: string; berthStNodeId: string; slot?: number; } | null;
};

type TrainStNodeTiming = {
    /** Station track node this timing is for. */
    stNodeId: string;
    /** The order the station track node is in the route so if a train visits an stNode more than once they don't … */
    stNodeIndex: number;
    /** Game seconds (`elapsedSeconds`) the train arrived. */
    arrivalTime: number | null;
    /** Game seconds the train departed; null until it has. */
    departureTime: number | null;
    /** Next scheduled arrival in game seconds, from the route's timings. */
    expectedArrivalTime: number | null;
    /** Next scheduled departure in game seconds. */
    expectedDepartureTime: number | null;
    /** Adjusted expected arrival time accounting for delays from previous stations */
    adjustedExpectedArrivalTime: number | null;
    /** Adjusted expected departure time accounting for delays from previous stations */
    adjustedExpectedDepartureTime: number | null;
    /** Expected arrival times for future cycles of the route */
    futureCycleArrivalTimes?: number[];
    /** Expected departure times for future cycles of the route */
    futureCycleDepartureTimes?: number[];
};

type DynamicDwellSnapshot = {
    /** Total passenger-exchange dwell in seconds (function time + flow terms) … */
    seconds: number;
    /** True when the raw model output exceeded MAX_DWELL_SECONDS (running far outside the calibrated envelope). */
    clampedAtMax: boolean;
    /** Head-count that alighted here. */
    alighting: number;
    /** Head-count boarding here (after capacity limiting). */
    boarding: number;
    /** Standing through-riders (through load beyond the train's seats). */
    standees: number;
    /** Fixed mechanical door-cycle + dispatch seconds. */
    functionTime: number;
    /** Alighting-flow seconds. */
    alightTime: number;
    /** Boarding-flow seconds. */
    boardTime: number;
    /** Opposing-stream friction seconds (0 on both-side platforms, where the streams split). */
    frictionTime: number;
    /** Standee-crowding seconds. */
    crowdTime: number;
    /** 2 when the platform track had slabs on both sides (Spanish solution), else 1. */
    platformSides: 1 | 2;
};

type AllTrainWindowCollections = { [key in TrainWindowType]: TrainWindowCollection; }

type TrainWindowCollection = {
    /** Tracks the window covers, each with head and tail progress along it and the signals it triggered. */
    tracks: TrainWindowTrack[];
    /** The progress of the train's head along the current station track route combo */
    headStComboProgress: number;
    /** The progress of the train's tail along the current station track route combo */
    tailStComboProgress: number;
    /** [lng, lat] line of the window for the map layers. */
    coords: [number, number][] | null;
    /** Ids of the signals inside the window. */
    signalIds: string[];
};

type TrainWindowTrack = {
    /** Track id. */
    trackId: string;
    /** Progress of the window's head along the track. */
    headProgress: number;
    /** Progress of the window's tail along the track. */
    tailProgress: number;
    /** Signals on this track the window has triggered. */
    triggeredSignalIds: string[];
};

type Bond = {
    /** UUID assigned at issue. */
    id: string;
    /** `id` of the BOND_TYPES entry: `'small'`, `'medium'`, `'large'`, or `'custom'` for a slider-issued bond. */
    bondTypeId: string;
    /** Amount borrowed; $. */
    principal: number;
    /** Principal still owed; $; reduced by `monthlyPayment` each game hour and by manual payments. */
    remainingPrincipal: number;
    /** Daily interest fraction on `remainingPrincipal` (SMALL default 0.06 = 6% per game day). */
    interestRate: number;
    /** Principal repaid every game hour; $; `principal` times the type's `principalPaymentRate`. */
    monthlyPayment: number;
    /** Game time at issue; game seconds (`elapsedSeconds`). */
    issuedAt: number;
    /** Game time of the last hourly charge, the issue time before the first. */
    lastPaymentAt: number;
};

type StationGroup = {
    /** Group id; kept from the matching previous group, else a fresh UUID. */
    id: string;
    /** `customName` when set; else a name two or more members share … */
    name: string;
    /** Member station ids. */
    stationIds: string[];
    /** [lng, lat]: `manualCenter` when set; else the mean of member centers, or … */
    center: [number, number];
    /** Bounding box of member centers: `minLng`, `maxLng`, `minLat`, `maxLat`. */
    bounds: {
        /** Westmost member center longitude; degrees. */
        minLng: number;
        /** Eastmost member center longitude; degrees. */
        maxLng: number;
        /** Southmost member center latitude; degrees. */
        minLat: number;
        /** Northmost member center latitude; degrees. */
        maxLat: number;
    };
    /** Station ids the player added by hand; carried over from the matched previous group. */
    manualAdditions?: string[];
    /** Station ids the player removed by hand … */
    manualRemovals?: string[];
    /** Player-picked marker position [lng, lat]. */
    manualCenter?: [number, number];
    /** Player-given name; cleared on a one-station group. */
    customName?: string;
};

type DemandData = {
    /** Map of point id to demand point: `location` [lng, lat], `jobs`, `residents`, `popIds` … */
    points: ExtendedDemandPointMap;
    /** Map of pop id to pop: `size` people, `residenceId`, `jobId`, driving data … */
    popsMap: ExtendedPopMap;
};

type ExtendedDemandPointMap = Map<string, ExtendedDemandPoint>;

type ExtendedDemandPoint = {
    /** Demand point id; pops name it as `residenceId` or `jobId`. */
    id: string;
    /** [lng, lat] of the point. */
    location: [number, number];
    /** People who work here. */
    jobs: number;
    /** People who live here. */
    residents: number;
    /** Ids of the pops that live or work here. */
    popIds: string[];
    /** Mode split of the people living here (home-to-work leg). */
    residentModeShare?: ModeChoice;
    /** Mode split of the people working here (home-to-work leg). */
    workerModeShare?: ModeChoice;
    /** Nearest walk-graph node id. */
    walkNode?: number;
    /** Distance from the point to `walkNode`; m. */
    walkSnapM?: number;
};

type ExtendedPopMap = Map<string, ExtendedPop>;

type ExtendedPop = {
    /** Pop id. */
    id: string;
    /** People this pop stands for; a pop commutes as one group. */
    size: number;
    /** Demand point id of the home end. */
    residenceId: string;
    /** Demand point id of the work end; `AIR_` and `UNI_` prefixes mark airport and university jobs … */
    jobId: string;
    /** Driving time between home and work; s. */
    drivingSeconds: number;
    /** Driving distance between home and work; m. */
    drivingDistance: number;
    /** Optional: GeoJSON LineString coordinates for driving route [lng, lat] pairs */
    drivingPath?: [number, number][];
    /** Time in seconds from midnight when the pop leaves for work */
    homeDepartureTime: number;
    /** Time in seconds from midnight when the pop leaves for home */
    workDepartureTime: number;
    /** The most recent commute the pop made or is on currently */
    lastCommute?: {
        /** Candidate transit journeys fed to mode choice (same order as `modeChoice.transitByPath`). */
        transitPaths: RaptorPath[];
        /** The walk-only option: `distance` m, `time` s. */
        walking: { distance: number; time: number; };
        /** Mode split of this commute; people. */
        modeChoice: ModeChoice;
    };
    /** Both directions' mode splits, each overwritten only by its own direction. */
    commutes?: {
        homeToWork?: CommuteSummary;
        workToHome?: CommuteSummary;
    };
    /** Sim-host slim mirror only (see helpers/popMovements/slimPops.ts). */
    legacyCommute?: CommuteSummary;
};

type CommuteSummary = {
    /** Mode split of this leg; people. */
    modeChoice: ModeChoice;
    /** Perceived transit time fed to getModeChoice. */
    transitTime?: number;
    /** Fare charged for the chosen journey. */
    transitCost?: number;
    /** The candidate journeys fed to getModeChoice with how many commuters chose each … */
    transitOptions?: Array<{ riders: number; perceivedTime: number; fareCost: number }>;
    /** Traffic multiplier for this direction's departure hour. */
    drivingTimeMultiplier: number;
};

type ModeChoice = {
    /** People who walk. */
    walking: number;
    /** People who drive. */
    driving: number;
    /** People who ride transit. */
    transit: number;
    /** People with no mode decided. */
    unknown: number;
    /** How `transit` splits across the candidate journeys fed to getModeChoice … */
    transitByPath?: number[];
};

type RaptorPath = {
    /** Legs in travel order: train rides, walks and driving access legs. */
    segments: RaptorPathSegment[];
    /** Journey span in seconds: first segment departure to final arrival. */
    totalTime: number;
    /** Transfers between trains. */
    transfers: number;
    /** Generalized ("perceived") time in seconds. */
    perceivedTime?: number;
    /** Walk weight applied to this path's perceivedTime when it differs from the baseline WALK_MULTIPLIER. */
    perceivedWalkMultiplier?: number;
    /** Unweighted real-time components behind perceivedTime, for UI display */
    timeBreakdown?: RaptorTimeBreakdown;
    /** Fare in dollars for this journey, computed AFTER pathfinding from the fare groups of the routes it boards … */
    fareCost?: number;
};

type RaptorPathSegment = {
    /** Route ridden on this leg; `'walking'` for a walk leg. */
    routeId: string | 'walking';
    /** Station id where the leg starts, or `'origin'` for the first walk. */
    fromStopId: RaptorStationId;
    /** Station id where the leg ends, or `'destination'` for the last walk. */
    toStopId: RaptorStationId;
    /** [lng, lat] where the leg starts. */
    fromStopCoords: [number, number];
    /** [lng, lat] where the leg ends. */
    toStopCoords: [number, number];
    /** In game-time seconds */
    departureTime: number;
    /** In game-time seconds */
    arrivalTime: number;
    /** Whether this segment is walking (not a train) */
    isWalking?: boolean;
    /** Whether this segment is driving (access leg) */
    isDriving?: boolean;
    /** Walk leg priced as a straight line: the place had no walk-graph node (off-network, or an airport terminal … */
    directWalk?: boolean;
};

type RaptorTimeBreakdown = {
    /** Time on board trains */
    inVehicle: number;
    /** Access/egress/transfer walking */
    walk: number;
    /** Park-and-ride driving access */
    drive: number;
    /** Platform waits between segments (includes the ARRIVAL_GAP buffer) */
    wait: number;
    /** How much later the journey departs than the pop requested */
    departureShift: number;
};

type RidershipStats = {
    /** `totalRiders` divided by 0.25; people per game hour. */
    totalRidersPerHour: number;
    /** People (summed commute `size`) who finished a transit journey in the last 900 game seconds. */
    totalRiders: number;
    /** Window length; game hours; always 0.25. */
    timeWindowHours: number;
};

type LineMetric = {
    /** Route id. */
    routeId: string;
    /** Route bullet text. */
    routeBullet: string;
    /** Route color; CSS color string. */
    routeColor: string;
    /** Trains whose `routeId` is the route. */
    trainCount: number;
    /** 3600 / (last `stComboTimings` departureTime / `trainCount`). */
    trainsPerHour: number | null;
    /** People per game hour who finished a commute on the route in the last 900 game seconds. */
    ridersPerHour: number;
    /** `ridersPerHour` times the global ticket price times RULES.FARE_MULTIPLIER (365). */
    revenuePerHour: number;
};

type RouteFinancials = {
    /** Route id. */
    routeId: string;
    /** Route bullet text. */
    routeBullet: string;
    /** Route color; CSS color string. */
    routeColor: string;
    /** Completed game hours, oldest first, at most 336 (14 game days). */
    hourly: Array<{ timestamp: number; revenue: number; expenses: number }>;
    /** Amounts of the hour in progress; they move to `hourly` when the hour completes. */
    currentHour: { revenue: number; expenses: number };
    /** Sums of the last 24 entries of `hourly` plus `currentHour` (when nonzero). */
    last24Hours: { revenue: number; expenses: number; profit: number };
};

type ModeChoiceStats = {
    /** People whose displayed commute walks; summed over pops. */
    walking: number;
    /** People whose displayed commute drives; summed over pops. */
    driving: number;
    /** People whose displayed commute rides transit. */
    transit: number;
    /** People with no displayed commute (whole pop `size`) plus the unknown share of simulated pops. */
    unknown: number;
};

type StationRidership = {
    /** People (summed `size`) in snapshot commutes touching the station. */
    total: number;
    /** People in those commutes for which the station appears in more than one leg … */
    transfers: number;
    /** Per route: `popCount` people (each route once per commute … */
    byRoute: Array<{ routeId: string; popCount: number; percent: number }>;
};

type RouteRidership = {
    /** People (summed `size`) in snapshot commutes with a leg on the route. */
    total: number;
    /** Per station: `popCount` people (boarded or alighted there on the route, once per commute) … */
    byStation: Array<{ stationId: string; popCount: number; percent: number }>;
};

type BlueprintCost = {
    /** Full construction cost; $; includes cost lines the breakdown omits. */
    totalCost: number;
    /** Partial cost lines; $: `trackCost` (track plus yard trackage), `stationCost`, `buildingDemolitionCost`. */
    breakdown: { trackCost: number; stationCost: number; buildingDemolitionCost: number; };
};

/** Build state of a track, station or route part. */
type BuildType = 'constructed' | 'blueprint' | 'preview';

/** Track geometry. */
type CurveType = 'hobby' | 'straight' | 'quadratic-start' | 'quadratic-end' | 'cubic' | 'euler-quadratic-start' | 'euler-quadratic-end' | 'euler-cubic';

/** A key of the train type registry (`TRAIN_TYPES`), so any string a mod registers with `trains.registerTrainType`. */
type TrainTypeId = string; // built in: 'heavy-metro', 'light-metro', 'light-rail', 'commuter-rail', 'commuter-rail-diesel'

/** A track type named in some train type's `compatibleTrackTypes`. */
type TrackTypeId = string;

/** A key of the station type registry (`STATION_TYPES`), so any string a mod registers with `stations.registerStationType`. */
type StationTypeId = string; // built in: 'standard'

/** Route bullet shape; absent draws a circle. */
type RouteShape = 'circle' | 'diamond' | 'square' | 'rounded-square' | 'triangle';

/** Bullet text styling. */
type RouteBulletFont = 'default' | 'mono' | 'bolder' | 'lighter' | 'italic';

/** How the schematic diagram labels a route along its ribbon. */
type RouteCatStyle = 'bullet' | 'text';

/** How fares are priced within a fare group. */
type FareSystem = 'flat' | 'route' | 'distance' | 'zone';

/** How transfers are priced for a fare group (the policy of the group being boarded). */
type FareTransferPolicy = 'all-paid' | 'count-within-group' | 'count-all-groups' | 'free-within-group';

/** How a distance-based fare group measures the distance a journey leg is charged for. */
type FareDistanceMode = 'straight-line' | 'track';

/** How a zone-based fare group counts zones for pricing. */
type FareZonePricingMode = 'count' | 'combination';

/** Keys of `AllTrainWindowCollections`: the occupied-track windows each train holds. */
type TrainWindowType = 'warningExtra' | 'warning' | 'train';

/** Mode of a route's timetable schedule: `frequency` runs the demand-tier counts in `trainSchedule`, `timetable` the headways per period. */
type SchedulingMode = 'frequency' | 'timetable';

/** Part of a track a signal covers: progress `start` to `end` in m, or the whole track. */
type SignalTrackCoverage = { start: number; end: number; } | 'all';

/** Station id of a journey leg end, or `origin` and `destination` for the walks at either end. */
type RaptorStationId = string | 'origin' | 'destination';

/** How challenging a city is to build a successful network in, shown as a badge on the city-select screen. */
type CityDifficulty = 'very-easy' | 'easy' | 'medium' | 'hard' | 'very-hard';

/** Country code of a city; the city picker filters and shows flags by it. */
type Country = 'US' | 'UK' | 'CA' | 'IE' | 'FR' | 'JP' | 'NZ' | 'CH' | 'AU';