@inventure71/paddockjs 2.0.1 → 3.0.0

package/src/index.d.ts

@@ -2,6 +2,7 @@ import type {
   PaddockActionSpec,
   PaddockDriverControllerLoop,
   PaddockDriverControllerLoopOptions,
+  PaddockEnvironmentOptions,
   PaddockObservationSpec,
   PaddockParticipantInteraction as EnvPaddockParticipantInteraction,
   PaddockParticipantInteractionsOptions as EnvPaddockParticipantInteractionsOptions,
@@ -23,7 +24,7 @@ export type {
 } from './environment/index.js';
 
 export type TireCompound = 'S' | 'M' | 'H';
-export type PaddockPhysicsMode = 'arcade' | 'simulator';
+export type PaddockPhysicsMode = 'arcade' | 'advanced';
 export type PaddockWarmupPolicy = 'config-change' | 'always' | 'never';
 export type PaddockProceduralTrackProfile = 'race' | 'training-short' | 'training-medium' | 'training-technical';
 
@@ -81,11 +82,12 @@ export type PaddockPitIntentRequest = PaddockPitIntent | {
   pitTargetCompound?: TireCompound | string;
   targetTire?: TireCompound | string;
 };
-export type CameraMode = 'overview' | 'leader' | 'selected' | 'show-all' | 'pit';
+export type CameraMode = 'overview' | 'leader' | 'selected' | 'driver' | 'show-all' | 'pit';
 export type RaceBannerMode = 'project' | 'radio' | 'hidden';
 export type RaceBannerEnabledMode = 'project' | 'radio';
 export type RaceDataBannerSize = 'auto' | 'custom';
 export type TimingTowerVerticalFit = 'expand-race-view' | 'scroll';
+export type TimingGapMode = 'interval' | 'leader';
 export type LayoutPreset = 'standard' | 'left-tower-overlay';
 export type CameraControlsMode = 'embedded' | 'external' | false;
 export type PaddockPresetName = 'dashboard' | 'timing-overlay' | 'compact-race' | 'full-dashboard';
@@ -111,6 +113,7 @@ export interface TeamData {
   name?: string;
   color?: string;
   icon?: string;
+  theme?: PaddockThemeSelector;
   pitCrew?: PaddockPitCrewStats;
   pitCrewStats?: PaddockPitCrewStats;
 }
@@ -254,12 +257,84 @@ export interface NormalizedSimulatorDriver extends SimulatorDriver {
   };
 }
 
-export interface F1SimulatorTheme {
-  accentColor?: string;
-  greenColor?: string;
-  yellowColor?: string;
-  timingTowerMaxWidth?: string;
-  raceViewMinHeight?: string;
+export type PaddockThemeMode = 'dark' | 'light' | 'system';
+export type PaddockThemeSelector = 'default' | 'active' | 'selectedTeam' | 'team' | `team:${string}` | string;
+export type PaddockThemeTokenValue = string | { light?: string; dark?: string };
+export type PaddockThemeTokenName =
+  | 'primary'
+  | 'primaryText'
+  | 'secondary'
+  | 'secondaryText'
+  | 'surface'
+  | 'surfaceRaised'
+  | 'surfacePanel'
+  | 'text'
+  | 'mutedText'
+  | 'border'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'info'
+  | 'yellowFlag'
+  | 'greenFlag'
+  | 'redFlag'
+  | 'safetyCar'
+  | 'drsActive'
+  | 'pitLane'
+  | 'track'
+  | 'trackEdge'
+  | 'timingTowerMaxWidth'
+  | 'raceViewMinHeight';
+
+export interface F1SimulatorThemeTokens extends Partial<Record<PaddockThemeTokenName, PaddockThemeTokenValue>> {
+  /** Compatibility alias for `primary`. Prefer `tokens.primary` in new 3.0.0 code. */
+  accentColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `greenFlag`. Prefer `tokens.greenFlag` or `tokens.success`. */
+  greenColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `yellowFlag`. Prefer `tokens.yellowFlag` or `tokens.warning`. */
+  yellowColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `info`. */
+  blueColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `redFlag`. Prefer `tokens.redFlag` or `tokens.danger`. */
+  raceControlRedColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `surface`. */
+  surfaceColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `surfaceRaised`. */
+  surfaceRaisedColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `surfacePanel`. */
+  surfacePanelColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `border`. */
+  lineColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `border`. */
+  lineStrongColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `text`. */
+  textColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `mutedText`. */
+  mutedTextColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `track`. */
+  trackColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `trackEdge`. */
+  trackEdgeColor?: PaddockThemeTokenValue;
+}
+
+export interface F1SimulatorThemePackage extends F1SimulatorThemeTokens {
+  extends?: string;
+  tokens?: F1SimulatorThemeTokens;
+  components?: Record<string, Partial<Record<string, PaddockThemeTokenName>>>;
+  light?: F1SimulatorThemeTokens;
+  dark?: F1SimulatorThemeTokens;
+}
+
+export interface F1SimulatorTheme extends Omit<F1SimulatorThemePackage, 'components'> {
+  mode?: PaddockThemeMode;
+  use?: string;
+  themes?: Record<string, F1SimulatorThemePackage>;
+  componentThemes?: Record<string, PaddockThemeSelector | { theme: PaddockThemeSelector }>;
+  teamThemes?: Record<string, PaddockThemeSelector | { theme: PaddockThemeSelector }>;
+  components?: Record<
+    string,
+    PaddockThemeSelector | { theme: PaddockThemeSelector } | Partial<Record<string, PaddockThemeTokenName>>
+  >;
 }
 
 export interface F1SimulatorUiOptions {
@@ -277,10 +352,15 @@ export interface F1SimulatorUiOptions {
   };
   raceDataBannerSize?: RaceDataBannerSize;
   raceDataTelemetryDetail?: boolean;
+  driverCamera?: boolean;
   penaltyBanners?: boolean;
   timingPenaltyBadges?: boolean;
   simulationSpeedControl?: boolean;
   timingTowerVerticalFit?: TimingTowerVerticalFit;
+  timingGapMode?: TimingGapMode;
+  timingGapModeToggle?: boolean;
+  timingEntryVerticalPadding?: number;
+  responsiveNarrowLayout?: boolean;
 }
 
 export interface F1SimulatorDebugOptions {
@@ -638,6 +718,18 @@ export interface WheelSurfaceSnapshot {
   fullyOutsideWhiteLine: boolean;
 }
 
+export interface CarTrackStateSnapshot {
+  distance: number;
+  signedOffset: number;
+  crossTrackError: number;
+  surface: string;
+  inPitLane: boolean;
+  pitLanePart: 'entry' | 'fast-lane' | 'working-lane' | 'exit' | 'service-box' | 'garage-box' | null;
+  pitBoxId: string | null;
+  curvature: number;
+  heading: number;
+}
+
 export interface CarSnapshot {
   id: string;
   rank: number | null;
@@ -683,6 +775,7 @@ export interface CarSnapshot {
   stabilityState?: PaddockStabilityState;
   signedOffset?: number;
   crossTrackError?: number;
+  trackState?: CarTrackStateSnapshot | null;
   inPitLane?: boolean;
   wheels?: WheelSurfaceSnapshot[];
   pitLanePart?: 'entry' | 'fast-lane' | 'working-lane' | 'exit' | 'service-box' | 'garage-box' | null;
@@ -791,6 +884,7 @@ export interface F1SimulatorExpertOptions {
   enabled: boolean;
   controlledDrivers: string[];
   frameSkip?: number;
+  episode?: PaddockEnvironmentOptions['episode'];
   visualizeSensors?: boolean | {
     rays?: boolean;
     drivers?: 'selected' | 'all' | string[];
@@ -862,7 +956,6 @@ export interface F1SimulatorOptions extends F1SimulatorCallbacks {
   seed?: number;
   trackSeed?: number;
   trackGeneration?: PaddockProceduralTrackOptions;
-  trackQueryIndex?: boolean;
   warmup?: PaddockWarmupOptions | boolean;
   totalLaps?: number;
   physicsMode?: PaddockPhysicsMode;
@@ -889,6 +982,7 @@ export interface MountRaceCanvasOptions {
   includeTimingTower?: boolean;
   includeTelemetrySectorBanner?: boolean;
   timingTowerVerticalFit?: TimingTowerVerticalFit;
+  responsiveNarrowLayout?: boolean;
 }
 
 export interface MountTelemetryPanelOptions {
@@ -899,6 +993,7 @@ export interface MountRaceTelemetryDrawerOptions {
   timingTowerVerticalFit?: TimingTowerVerticalFit;
   drawerInitiallyOpen?: boolean;
   raceDataTelemetryDetail?: boolean;
+  responsiveNarrowLayout?: boolean;
 }
 
 export interface F1MountedSimulator {
@@ -916,6 +1011,9 @@ export interface F1MountedSimulator {
   getPitIntent(driverId: string): PaddockPitIntent;
   getPitTargetCompound(driverId: string): TireCompound | string | null;
   getSimulationSpeed(): number;
+  setTimingGapMode(mode: TimingGapMode): TimingGapMode;
+  getTimingGapMode(): TimingGapMode;
+  toggleTimingGapMode(): TimingGapMode;
   servePenalty(penaltyId: string): PaddockPenaltyEntry | null;
   cancelPenalty(penaltyId: string): PaddockPenaltyEntry | null;
   getSnapshot(): RaceSnapshot | null;
@@ -953,6 +1051,9 @@ export interface PaddockSimulatorController {
   getPitIntent(driverId: string): PaddockPitIntent;
   getPitTargetCompound(driverId: string): TireCompound | string | null;
   getSimulationSpeed(): number;
+  setTimingGapMode(mode: TimingGapMode): TimingGapMode;
+  getTimingGapMode(): TimingGapMode;
+  toggleTimingGapMode(): TimingGapMode;
   servePenalty(penaltyId: string): PaddockPenaltyEntry | null;
   cancelPenalty(penaltyId: string): PaddockPenaltyEntry | null;
   getSnapshot(): RaceSnapshot | null;

package/src/index.js

@@ -61,6 +61,21 @@ export async function mountF1Simulator(root, options = {}) {
   const app = new F1SimulatorApp(shell, resolvedOptions);
   await app.init();
 
+  const syncResolvedTimingGapMode = (timingGapMode) => {
+    resolvedOptions = {
+      ...resolvedOptions,
+      ui: {
+        ...resolvedOptions.ui,
+        timingGapMode,
+      },
+    };
+    return timingGapMode;
+  };
+  const syncResolvedRuntimeOptions = () => {
+    syncResolvedTimingGapMode(app.getTimingGapMode());
+    return resolvedOptions;
+  };
+
   return {
     get expert() {
       return app.expert ?? null;
@@ -70,7 +85,7 @@ export async function mountF1Simulator(root, options = {}) {
       root.innerHTML = '';
     },
     restart(nextOptions = {}) {
-      const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(resolvedOptions, nextOptions));
+      const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(syncResolvedRuntimeOptions(), nextOptions));
       app.restart(nextResolvedOptions);
       resolvedOptions = nextResolvedOptions;
     },
@@ -108,6 +123,15 @@ export async function mountF1Simulator(root, options = {}) {
     getSimulationSpeed() {
       return app.simulationSpeed;
     },
+    setTimingGapMode(mode) {
+      return syncResolvedTimingGapMode(app.setTimingGapMode(mode));
+    },
+    getTimingGapMode() {
+      return app.getTimingGapMode();
+    },
+    toggleTimingGapMode() {
+      return syncResolvedTimingGapMode(app.toggleTimingGapMode());
+    },
     servePenalty(penaltyId) {
       return app.servePenalty(penaltyId);
     },

package/src/simulation/driver/driverController.js

@@ -37,7 +37,7 @@ export function decideDriverControls({ car, orderIndex, race }) {
 }
 
 function shouldStabilizeSimulatorCar(car, race) {
-  if (race.physicsMode !== 'simulator') return false;
+  if (race.physicsMode !== 'advanced') return false;
   const gripUsage = car.gripUsage ?? 0;
   const slipAngle = Math.abs(car.slipAngleRadians ?? 0);
   const edgeDistance = race.track.width / 2 - VEHICLE_LIMITS.carWidth * 2.25;

package/src/simulation/driver/edgeRecovery.js

@@ -5,7 +5,7 @@ import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
 import { REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_MAX } from './driverControlConstants.js';
 
 export function calculateTrackEdgeGuard(car, race) {
-  const simulatorMode = race.physicsMode === 'simulator';
+  const simulatorMode = race.physicsMode === 'advanced';
   const trackLimit = race.track.width / 2;
   const halfCarWidth = VEHICLE_LIMITS.carWidth / 2;
   const wholeCarOutsideLimit = trackLimit + halfCarWidth;

package/src/simulation/driver/racingControls.js

@@ -10,7 +10,7 @@ import { calculateActualOverlapPenalty, calculatePlannedTrafficPenalty, planRaci
 import { analyzeTrackEdgeMotion } from './recoveryDynamics.js';
 
 export function decideRacingControls(car, orderIndex, race) {
-  if (race.physicsMode === 'simulator') {
+  if (race.physicsMode === 'advanced') {
     return decideSimulatorRacingControls(car, orderIndex, race);
   }
   return decideArcadeRacingControls(car, orderIndex, race);
@@ -389,7 +389,7 @@ export function calculateRacingLineOffset(car, race, lookahead, curvature, edgeG
   if (turnDirection === 0) return 0;
 
   const aggression = car.aggression ?? car.personality?.baseAggression ?? 0.5;
-  const simulatorMode = race.physicsMode === 'simulator';
+  const simulatorMode = race.physicsMode === 'advanced';
   const safeEdge = race.track.width / 2 - VEHICLE_LIMITS.carWidth *
     (simulatorMode ? 2.05 - aggression * 0.08 : 1.15 - aggression * 0.12);
   const apexOffset = turnDirection * safeEdge *

package/src/simulation/driver/rejoinControls.js

@@ -8,7 +8,7 @@ import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
 import { analyzeTrackEdgeMotion } from './recoveryDynamics.js';
 
 export function decideRejoinControls(car, race) {
-  if (race.physicsMode === 'simulator') {
+  if (race.physicsMode === 'advanced') {
     return decideSimulatorRejoinControls(car, race);
   }
   return decideArcadeRejoinControls(car, race);
@@ -103,7 +103,7 @@ export function decideSimulatorRejoinControls(car, race) {
 }
 
 function decideRejoinControlsForMode(car, race, profile) {
-  const simulatorMode = race.physicsMode === 'simulator';
+  const simulatorMode = race.physicsMode === 'advanced';
   const lookahead = clamp(car.speed * (profile.simulatorMode ? 0.58 : 0.72) + REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_MAX);
   const edgeMotion = analyzeTrackEdgeMotion(car, race);
   const lowSpeedOffTrack = !car.trackState.onTrack && car.speed < kphToSimSpeed(24);

package/src/simulation/pit/pitKinematics.js

@@ -1,7 +1,7 @@
-export function syncPitCarKinematics(car, { physicsMode = 'simulator' } = {}) {
+export function syncPitCarKinematics(car, { physicsMode = 'arcade' } = {}) {
   const speed = Number.isFinite(car.speed) ? car.speed : 0;
   const heading = Number.isFinite(car.heading) ? car.heading : 0;
-  if (physicsMode === 'simulator') {
+  if (physicsMode === 'advanced') {
     car.velocityX = Math.cos(heading) * speed;
     car.velocityY = Math.sin(heading) * speed;
   } else {

package/src/simulation/pit/pitRouting.js

@@ -285,11 +285,9 @@ export function nearestDistanceOnRoute(route, position, previousDistance = 0) {
 export function createPitApproachPoints(track, car, pitLane, entryRaceDistance) {
   const currentDistance = car.raceDistance ?? entryRaceDistance - PIT_ENTRY_APPROACH_DISTANCE;
   const remaining = Math.max(0, entryRaceDistance - currentDistance);
-  const currentState = nearestTrackState(track, car, car.progress, { indexMode: 'legacy' });
+  const currentState = nearestTrackState(track, car, car.progress);
   const startOffset = currentState.inPitLane ? 0 : currentState.signedOffset ?? 0;
-  const entryConnectState = nearestTrackState(track, pitLane.entry.trackConnectPoint, pitLane.entry.trackDistance, {
-    indexMode: 'legacy',
-  });
+  const entryConnectState = nearestTrackState(track, pitLane.entry.trackConnectPoint, pitLane.entry.trackDistance);
   const targetOffset = entryConnectState.signedOffset ?? 0;
   const points = [routePoint(car, car.heading)];
   const straightDistance = remaining > metersToSimUnits(14)

package/src/simulation/race/raceSetup.js

@@ -29,7 +29,6 @@ export function initializeRaceSimulation(simulation, {
   track = null,
   trackSeed = null,
   trackGeneration = {},
-  trackQueryIndex = true,
   physicsMode = 'arcade',
   participantInteractions = {},
   replayGhosts = [],
@@ -43,11 +42,8 @@ export function initializeRaceSimulation(simulation, {
     ...builtTrack,
     pitLane: clonePitLaneModel(builtTrack.pitLane),
   };
-  const useTrackQueryIndex = trackQueryIndex !== false;
-  if (useTrackQueryIndex) {
-    const forkedCachedIndex = forkTrackQueryIndex(builtTrack.queryIndex);
-    attachTrackQueryIndex(simulation.track, forkedCachedIndex ?? createTrackQueryIndex(simulation.track));
-  }
+  const forkedCachedIndex = forkTrackQueryIndex(builtTrack.queryIndex, simulation.track);
+  attachTrackQueryIndex(simulation.track, forkedCachedIndex ?? createTrackQueryIndex(simulation.track));
   simulation.track.timingLines = createTimingLines(simulation.track);
   simulation.trackSeed = simulation.track.seed ?? trackSeed;
   simulation.rules = normalizeRaceRules(rules);

package/src/simulation/race/raceStep.js

@@ -59,7 +59,7 @@ export function runRaceStep(simulation, dt) {
       throttle: controls.throttle ?? 0,
       brake: controls.brake ?? 0,
     };
-    if (simulation.physicsMode === 'simulator') {
+    if (simulation.physicsMode === 'advanced') {
       applyWheelSurfaceState(car, simulation.track);
     }
     integrateVehiclePhysics(car, controls, delta, {

package/src/simulation/race/safetyCar.js

@@ -82,7 +82,7 @@ export function setRedFlagState(sim, deployed) {
         });
       } else if (!car.finished) {
         car.speed = Math.max(car.speed, kphToSimSpeed(60));
-        if (sim.physicsMode === 'simulator') syncVehicleVelocityToHeading(car);
+        if (sim.physicsMode === 'advanced') syncVehicleVelocityToHeading(car);
         car.brake = 0;
         car.throttle = Math.max(car.throttle ?? 0, 0.35);
       }

package/src/simulation/race/stalledDnf.js

@@ -59,7 +59,7 @@ function retireStalledCar(sim, car) {
   });
 }
 
-export function freezeRetiredCar(car, { physicsMode = 'simulator' } = {}) {
+export function freezeRetiredCar(car, { physicsMode = 'arcade' } = {}) {
   freezeVehicleMotion(car, {
     clearManualControls: true,
     physicsMode,

package/src/simulation/timing/lapTelemetry.js

@@ -33,9 +33,10 @@ function getLapTelemetryPosition(track, raceDistance, totalLaps = Infinity) {
   };
 }
 
-function createSectorProgress(position, currentSectors = null) {
+function createSectorProgress(position, currentSectors = null, { preserveCompletedSectors = false } = {}) {
   const activeIndex = clamp((position.currentSector ?? 1) - 1, 0, TELEMETRY_SECTOR_COUNT - 1);
   return createEmptySectorTimes().map((_, index) => {
+    if (preserveCompletedSectors && Number.isFinite(currentSectors?.[index])) return 1;
     if (index < activeIndex && Number.isFinite(currentSectors?.[index])) return 1;
     if (index === activeIndex) return clamp(position.currentSectorProgress ?? 0, 0, 1);
     return 0;
@@ -99,11 +100,23 @@ export function updateLapTelemetry(car, previousRaceDistance, currentTime, track
   const previousUpdateTime = Number.isFinite(telemetry.lastUpdatedAt) ? telemetry.lastUpdatedAt : currentTime;
   const elapsedTime = Math.max(0, currentTime - previousUpdateTime);
 
-  if (!Number.isFinite(previousDistance) || !Number.isFinite(currentDistance) || travelled < -1e-3 || travelled > track.length / 2) {
+  if (
+    !Number.isFinite(previousDistance) ||
+    !Number.isFinite(currentDistance) ||
+    Math.abs(travelled) > track.length / 2
+  ) {
     resetLapTelemetry(car, currentTime, track, totalLaps);
     return;
   }
 
+  if (travelled < -1e-3) {
+    syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps, {
+      preserveCompletedSectors: true,
+    });
+    telemetry.lastUpdatedAt = currentTime;
+    return;
+  }
+
   const sectorLength = getSectorLength(track);
   if (travelled > 1e-6) {
     const firstBoundary = Math.floor(previousDistance / sectorLength) + 1;
@@ -155,28 +168,34 @@ function clearFutureSectorTelemetry(telemetry) {
   }
 }
 
-function syncLiveSectorTelemetry(telemetry) {
+function syncLiveSectorTelemetry(telemetry, { preserveCompletedSectors = false } = {}) {
   const activeIndex = clamp((telemetry.currentSector ?? 1) - 1, 0, TELEMETRY_SECTOR_COUNT - 1);
 
   telemetry.liveSectors = createEmptySectorTimes();
   telemetry.currentSectors.forEach((time, index) => {
-    if (index >= activeIndex) return;
+    if (!preserveCompletedSectors && index >= activeIndex) return;
     if (!Number.isFinite(time)) return;
     telemetry.liveSectors[index] = time;
   });
-  telemetry.liveSectors[activeIndex] = telemetry.currentSectorElapsed;
+  if (!Number.isFinite(telemetry.liveSectors[activeIndex])) {
+    telemetry.liveSectors[activeIndex] = telemetry.currentSectorElapsed;
+  }
 }
 
-function syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps) {
+function syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps, {
+  preserveCompletedSectors = false,
+} = {}) {
   const position = getLapTelemetryPosition(track, currentRaceDistance, totalLaps);
   telemetry.completedLaps = position.completedLaps;
   telemetry.currentLap = position.currentLap;
   telemetry.currentSector = position.currentSector;
   telemetry.currentSectorProgress = position.currentSectorProgress;
-  clearFutureSectorTelemetry(telemetry);
-  telemetry.sectorProgress = createSectorProgress(position, telemetry.currentSectors);
+  if (!preserveCompletedSectors) clearFutureSectorTelemetry(telemetry);
+  telemetry.sectorProgress = createSectorProgress(position, telemetry.currentSectors, {
+    preserveCompletedSectors,
+  });
   telemetry.completedLaps = Math.max(telemetry.completedLaps, Math.min(position.completedLaps, totalLaps));
   telemetry.currentLapTime = Math.max(0, currentTime - telemetry.currentLapStartedAt);
   telemetry.currentSectorElapsed = Math.max(0, currentTime - telemetry.currentSectorStartedAt);
-  syncLiveSectorTelemetry(telemetry);
+  syncLiveSectorTelemetry(telemetry, { preserveCompletedSectors });
 }

package/src/simulation/track/pitLaneLayout.js

@@ -1,9 +1,9 @@
 import { clamp } from '../simMath.js';
 import { metersToSimUnits } from '../units.js';
 import { WORLD, PIT_BOX_COUNT, PIT_BOX_DEPTH, PIT_BOX_LENGTH, PIT_BOX_PAIR_GAP, PIT_BOX_TO_LANE_GAP, PIT_ENTRY_SEARCH_AFTER, PIT_ENTRY_SEARCH_BEFORE, PIT_EXIT_SEARCH_AFTER, PIT_EXIT_SEARCH_BEFORE, PIT_LANE_EDGE_GAP, PIT_LANE_ENTRY_BUFFER, PIT_LANE_EXIT_BUFFER, PIT_LANE_FINISH_RATIO, PIT_LANE_OFFSET_SEARCH_STEP, PIT_LANE_WIDTH, PIT_SERVICE_AREA_DEPTH, PIT_SERVICE_AREA_LENGTH, PIT_SERVICE_QUEUE_GAP, PIT_TEAM_COUNT, PIT_TEAM_GAP, PIT_BOXES_PER_TEAM, PIT_WORKING_LANE_GAP, PIT_WORKING_LANE_WIDTH, PIT_ACCESS_MAX_LENGTH, PIT_ACCESS_MIN_LENGTH, PIT_ACCESS_TANGENT_RATIO, PIT_TRACK_CLEARANCE_MARGIN } from './trackConstants.js';
-import { clonePoint, distance, headingVector, interpolatePitPoint, normalizeVector, pointWorldClearance, projectPitPoint, createPointBounds } from './trackMath.js';
+import { clonePoint, distance, headingVector, interpolatePitPoint, nearestPointOnPolyline, normalizeVector, pointWorldClearance, projectPitPoint, createPointBounds } from './trackMath.js';
 import { findPitAccessConnection, createPitAccessRoadCenterline } from './pitLaneAccess.js';
-import { nearestTrackState, pointAt } from './spatialQueries.js';
+import { pointAt } from './spatialQueries.js';
 
 export function createStartStraightBasis(track) {
   const finish = pointAt(track, 0);
@@ -90,7 +90,7 @@ export function scorePitLanePlacement(track, side, laneOffset, layout) {
     minimumClearance = Math.min(minimumClearance, pointWorldClearance(lanePoint), pointWorldClearance(boxPoint));
     minimumTrackClearance = Math.min(
       minimumTrackClearance,
-      nearestTrackState(track, lanePoint).crossTrackError -
+      nearestMainTrackProjection(track, lanePoint).crossTrackError -
         (track.width / 2 + (track.kerbWidth ?? 0) + PIT_TRACK_CLEARANCE_MARGIN),
     );
   }
@@ -105,6 +105,10 @@ export function scorePitLanePlacement(track, side, laneOffset, layout) {
   };
 }
 
+function nearestMainTrackProjection(track, position) {
+  return nearestPointOnPolyline(track.samples, position) ?? { crossTrackError: Infinity };
+}
+
 export function choosePitLanePlacement(track, baseLaneOffset, layout) {
   const candidates = [];
   for (let offsetStep = 0; offsetStep <= 9; offsetStep += 1) {

package/src/simulation/track/spatialQueries.js

@@ -1,5 +1,5 @@
 import { clamp, normalizeAngle, wrapDistance } from '../simMath.js';
-import { NEAREST_HINT_WINDOW_SAMPLES, PIT_LANE_WIDTH } from './trackConstants.js';
+import { PIT_LANE_WIDTH } from './trackConstants.js';
 import { nearestPitLaneState } from './pitLaneState.js';
 import { queryNearestTrackProjection } from './trackQueryIndex.js';
 
@@ -91,13 +91,10 @@ export function createTrackState(track, position, best) {
 
 export function nearestTrackState(track, position, progressHint = null, options = {}) {
   const allowPitOverride = options.allowPitOverride !== false;
-  const best = options.indexMode === 'legacy'
-    ? nearestTrackSampleLegacy(track, position, progressHint)
-    : queryNearestTrackProjection(track, position, progressHint, {
-      indexMode: options.indexMode,
-      hintMaxDistance: options.hintMaxDistance,
-    }) ??
-    nearestTrackSampleLegacy(track, position, progressHint);
+  const best = queryNearestTrackProjection(track, position, progressHint);
+  if (!best) {
+    throw new Error('nearestTrackState requires a finite position and an indexed track model. Build tracks with buildTrackModel() or createRaceSimulation().');
+  }
   const trackState = createTrackState(track, position, best);
   if (!allowPitOverride) return trackState;
   const pitState = nearestPitLaneState(track, position);
@@ -125,26 +122,6 @@ export function nearestTrackState(track, position, progressHint = null, options
   };
 }
 
-function nearestTrackSampleLegacy(track, position, progressHint = null) {
-  let nearest = null;
-
-  if (Number.isFinite(progressHint)) {
-    const centerIndex = sampleIndexAtDistance(track, progressHint);
-    nearest = nearestSampleInRange(
-      track,
-      position,
-      centerIndex - NEAREST_HINT_WINDOW_SAMPLES,
-      centerIndex + NEAREST_HINT_WINDOW_SAMPLES,
-    );
-    const fallbackDistance = track.width / 2 + (track.kerbWidth ?? 0) + track.gravelWidth + track.runoffWidth + 180;
-    if (!nearest.best || nearest.bestDistance > fallbackDistance * fallbackDistance) {
-      nearest = null;
-    }
-  }
-
-  return nearest?.best ?? nearestSampleGlobal(track, position).best;
-}
-
 export function offsetTrackPoint(point, offset) {
   return {
     x: point.x + point.normalX * offset,