@inventure71/paddockjs 3.0.0 → 4.0.0

package/src/simulation/timing/timingLines.js

@@ -3,6 +3,53 @@ import { metersToSimUnits, simUnitsToMeters } from '../units.js';
 import { pointAt } from '../track/trackModel.js';
 import { TIMING_LINE_HISTORY_LAPS, TIMING_LINE_TARGET_SPACING_METERS } from './timingConstants.js';
 
+function setTimingLineCrossingBounds(car, firstLine, lastLine) {
+  car.timingLineFirstStored = Number.isInteger(firstLine) ? firstLine : null;
+  car.timingLineLastStored = Number.isInteger(lastLine) ? lastLine : null;
+}
+
+function ensureTimingLineCrossingBounds(car) {
+  if (Number.isInteger(car.timingLineFirstStored) && Number.isInteger(car.timingLineLastStored)) {
+    return {
+      firstLine: car.timingLineFirstStored,
+      lastLine: car.timingLineLastStored,
+    };
+  }
+  const lineNumbers = Object.keys(car.timingLineCrossings)
+    .map((key) => Number(key))
+    .filter((value) => Number.isFinite(value))
+    .sort((left, right) => left - right);
+  const firstLine = lineNumbers[0];
+  const lastLine = lineNumbers[lineNumbers.length - 1];
+  setTimingLineCrossingBounds(car, firstLine, lastLine);
+  return {
+    firstLine: car.timingLineFirstStored,
+    lastLine: car.timingLineLastStored,
+  };
+}
+
+function setTimingLineCrossing(car, lineNumber, crossingTime) {
+  car.timingLineCrossings[lineNumber] = crossingTime;
+  const firstLine = car.timingLineFirstStored;
+  const lastLine = car.timingLineLastStored;
+  if (!Number.isInteger(firstLine) || lineNumber < firstLine) car.timingLineFirstStored = lineNumber;
+  if (!Number.isInteger(lastLine) || lineNumber > lastLine) car.timingLineLastStored = lineNumber;
+}
+
+function pruneTimingLineCrossings(car, cutoffLine) {
+  const { firstLine, lastLine } = ensureTimingLineCrossingBounds(car);
+  if (!Number.isInteger(firstLine) || !Number.isInteger(lastLine) || cutoffLine <= firstLine) return;
+  const pruneEnd = Math.min(lastLine, cutoffLine - 1);
+  for (let lineNumber = firstLine; lineNumber <= pruneEnd; lineNumber += 1) {
+    delete car.timingLineCrossings[lineNumber];
+  }
+  if (cutoffLine > lastLine) {
+    setTimingLineCrossingBounds(car, null, null);
+    return;
+  }
+  setTimingLineCrossingBounds(car, cutoffLine, lastLine);
+}
+
 export function createTimingLines(track) {
   const targetSpacing = metersToSimUnits(TIMING_LINE_TARGET_SPACING_METERS);
   const count = Math.max(1, Math.round(track.length / targetSpacing));
@@ -36,6 +83,8 @@ export function resetTimingLineCrossings(car, currentTime) {
   car.timingLineCrossings = Object.create(null);
   car.timingLineLastUpdatedAt = currentTime;
   car.previousRaceDistanceForTiming = car.raceDistance;
+  setTimingLineCrossingBounds(car, null, null);
+  car.timingLinePruneCutoff = null;
 }
 
 export function recordTimingLineCrossings(car, previousRaceDistance, currentTime, track) {
@@ -51,6 +100,18 @@ export function recordTimingLineCrossings(car, previousRaceDistance, currentTime
   const travelled = currentDistance - previousDistance;
   const previousTime = Number.isFinite(car.timingLineLastUpdatedAt) ? car.timingLineLastUpdatedAt : currentTime;
   const elapsed = Math.max(0, currentTime - previousTime);
+  const latestLine = getTimingLineNumber(track, currentDistance);
+  const cutoff = latestLine != null
+    ? latestLine - (track.timingLines.count * TIMING_LINE_HISTORY_LAPS)
+    : null;
+
+  if (Math.abs(travelled) <= 1e-6) {
+    car.timingLineLastUpdatedAt = currentTime;
+    if (!Number.isFinite(cutoff) || cutoff <= 0 || cutoff === car.timingLinePruneCutoff) return;
+    pruneTimingLineCrossings(car, cutoff);
+    car.timingLinePruneCutoff = cutoff;
+    return;
+  }
 
   if (travelled > 1e-6 && travelled < track.length / 2) {
     const firstLine = Math.floor(Math.max(0, previousDistance) / spacing) + 1;
@@ -59,17 +120,14 @@ export function recordTimingLineCrossings(car, previousRaceDistance, currentTime
       const lineDistance = lineNumber * spacing;
       if (lineDistance <= previousDistance + 1e-6 || lineDistance > currentDistance + 1e-6) continue;
       const ratio = clamp((lineDistance - previousDistance) / travelled, 0, 1);
-      car.timingLineCrossings[lineNumber] = previousTime + ratio * elapsed;
+      setTimingLineCrossing(car, lineNumber, previousTime + ratio * elapsed);
     }
   }
 
   car.timingLineLastUpdatedAt = currentTime;
-  const latestLine = getTimingLineNumber(track, currentDistance);
-  if (latestLine != null) {
-    const cutoff = latestLine - (track.timingLines.count * TIMING_LINE_HISTORY_LAPS);
-    Object.keys(car.timingLineCrossings).forEach((key) => {
-      if (Number(key) < cutoff) delete car.timingLineCrossings[key];
-    });
+  if (Number.isFinite(cutoff) && cutoff > 0 && cutoff !== car.timingLinePruneCutoff) {
+    pruneTimingLineCrossings(car, cutoff);
+    car.timingLinePruneCutoff = cutoff;
   }
 }
 

package/src/simulation/track/pitLaneLayout.js

@@ -274,6 +274,27 @@ export function createPitLaneBounds(pitLane) {
   return createPointBounds(points, padding);
 }
 
+export function createPitBoxBounds(pitLane) {
+  const points = [
+    ...(pitLane.boxes ?? []).flatMap((box) => box.corners ?? []),
+    ...(pitLane.serviceAreas ?? []).flatMap((area) => [
+      ...(area.corners ?? []),
+      ...(area.queueCorners ?? []),
+    ]),
+  ];
+  if (!points.length) return null;
+  const padding = Math.max(PIT_BOX_DEPTH, PIT_SERVICE_AREA_DEPTH) / 2 + metersToSimUnits(3);
+  return createPointBounds(points, padding);
+}
+
+export function createPitConnectorBounds(pitLane) {
+  const connectorPadding = metersToSimUnits(18);
+  return {
+    entry: createPointBounds(pitLane.entry?.connector ?? [], connectorPadding),
+    exit: createPointBounds(pitLane.exit?.connector ?? [], connectorPadding),
+  };
+}
+
 export function createPitLaneModel(track) {
   const layout = createPitLaneLayout();
   const laneOffset = track.width / 2 + (track.kerbWidth ?? 0) + PIT_LANE_EDGE_GAP + PIT_LANE_WIDTH / 2;
@@ -395,5 +416,7 @@ export function createPitLaneModel(track) {
   return {
     ...pitLane,
     bounds: createPitLaneBounds(pitLane),
+    boxBounds: createPitBoxBounds(pitLane),
+    connectorBounds: createPitConnectorBounds(pitLane),
   };
 }

package/src/simulation/track/pitLaneState.js

@@ -1,7 +1,8 @@
 import { clamp, wrapDistance } from '../simMath.js';
 import { PIT_LANE_WIDTH } from './trackConstants.js';
-import { nearestPointOnPolyline, pointInsideBounds, pointIsInsidePolygon } from './trackMath.js';
+import { nearestPointOnPolyline, nearestPointOnPolylineInto, pointInsideBounds, pointIsInsidePolygon } from './trackMath.js';
 import { queryPitBoxCandidates, queryPitRoadSegmentCandidatesByRoute } from './trackQueryIndex.js';
+import { ensureQueryScratch } from './trackQueryScratch.js';
 
 export function mapPitDistance(track, startDistance, endDistance, amount) {
   return wrapDistance(startDistance + (endDistance - startDistance) * clamp(amount, 0, 1), track.length);
@@ -15,9 +16,37 @@ export function createPitRoadState(track, position, pitLane, {
   startDistance,
   endDistance,
   segmentCandidates = null,
+  projectionTarget = null,
+  projectionScratch = null,
+  cumulativeDistances = null,
+  connectorProjectionStats = false,
+  connectorEndpointWindowProjection = false,
 }) {
+  if (!Array.isArray(points) || points.length < 2) return null;
   if (Array.isArray(segmentCandidates) && segmentCandidates.length === 0) return null;
-  const projected = nearestPointOnPolyline(points, position, segmentCandidates);
+  if (connectorProjectionStats) {
+    const stats = track?.queryIndex?.stats;
+    if (stats) {
+      if (connectorEndpointWindowProjection && Array.isArray(segmentCandidates) && segmentCandidates.length > 0) {
+        stats.pitConnectorEndpointWindowProjectionCalls =
+          (stats.pitConnectorEndpointWindowProjectionCalls ?? 0) + 1;
+      } else if (!Array.isArray(segmentCandidates)) {
+        stats.pitConnectorFullRouteProjectionScans =
+          (stats.pitConnectorFullRouteProjectionScans ?? 0) + 1;
+      }
+    }
+  }
+  if (projectionScratch && Array.isArray(segmentCandidates) && segmentCandidates.length > 0 && !Array.isArray(cumulativeDistances)) {
+    const stats = track?.queryIndex?.stats;
+    if (stats) stats.pitRoadCumulativeDistanceRebuilds = (stats.pitRoadCumulativeDistanceRebuilds ?? 0) + 1;
+  }
+  const projected = projectionTarget
+    ? nearestPointOnPolylineInto(projectionTarget, points, position, {
+      segmentIndices: segmentCandidates,
+      scratch: projectionScratch,
+      cumulativeDistances,
+    })
+    : nearestPointOnPolyline(points, position, segmentCandidates);
   if (!projected || projected.crossTrackError > roadWidth / 2) return null;
   const amount = projected.totalLength > 0 ? projected.distanceAlong / projected.totalLength : 0;
   const distanceAlongTrack = mapPitDistance(track, startDistance, endDistance, amount);
@@ -94,21 +123,27 @@ export function createPitBoxState(track, position, pitLane, candidateBoxes = nul
   };
 }
 
-export function nearestPitLaneState(track, position) {
+export function nearestPitLaneState(track, position, progressHint = null) {
   const pitLane = track.pitLane;
   if (!pitLane?.enabled) return null;
   if (!pointInsideBounds(position, pitLane.bounds)) return null;
+  const scratch = track?.queryIndex ? ensureQueryScratch(track.queryIndex) : null;
 
-  const indexedBoxCandidates = queryPitBoxCandidates(track, position);
-  const boxCandidates = indexedBoxCandidates ?? null;
-  const boxState = createPitBoxState(track, position, pitLane, boxCandidates);
-  if (boxState) return boxState;
+  if (!pitLane.boxBounds || pointInsideBounds(position, pitLane.boxBounds)) {
+    const indexedBoxCandidates = queryPitBoxCandidates(track, position, scratch);
+    const boxCandidates = indexedBoxCandidates ?? null;
+    const boxState = createPitBoxState(track, position, pitLane, boxCandidates);
+    if (boxState) return boxState;
+  }
 
   const laneEntryDistance = pitLane.layout?.entryDistance ?? pitLane.entry.distanceFromStart;
   const laneExitDistance = pitLane.layout?.exitDistance ?? pitLane.exit.distanceFromStart;
-  const roadCandidatesByRoute = queryPitRoadSegmentCandidatesByRoute(track, position);
-  const candidates = [
-    createPitRoadState(track, position, pitLane, {
+  const roadCandidatesByRoute = queryPitRoadSegmentCandidatesByRoute(track, position, progressHint, scratch);
+  const pitRoutes = track?.queryIndex?.pit?.routes ?? {};
+  const projectionTarget = scratch ? (scratch.pitRoadProjection ??= { point: {} }) : null;
+  const projectionScratch = scratch ? (scratch.pitRoadProjectionScratch ??= {}) : null;
+  let bestState = null;
+  bestState = pickPitState(bestState, createPitRoadState(track, position, pitLane, {
       points: pitLane.entry.roadCenterline,
       surface: 'pit-entry',
       part: 'entry',
@@ -116,8 +151,11 @@ export function nearestPitLaneState(track, position) {
       startDistance: pitLane.entry.distanceFromStart,
       endDistance: laneEntryDistance,
       segmentCandidates: roadCandidatesByRoute?.entry ?? null,
-    }),
-    createPitRoadState(track, position, pitLane, {
+      projectionTarget,
+      projectionScratch,
+      cumulativeDistances: pitRoutes.entry?.cumulativeDistances ?? null,
+    }));
+  bestState = pickPitState(bestState, createPitRoadState(track, position, pitLane, {
       points: pitLane.mainLane.points,
       surface: 'pit-lane',
       part: 'fast-lane',
@@ -125,8 +163,11 @@ export function nearestPitLaneState(track, position) {
       startDistance: laneEntryDistance,
       endDistance: laneExitDistance,
       segmentCandidates: roadCandidatesByRoute?.main ?? null,
-    }),
-    createPitRoadState(track, position, pitLane, {
+      projectionTarget,
+      projectionScratch,
+      cumulativeDistances: pitRoutes.main?.cumulativeDistances ?? null,
+    }));
+  bestState = pickPitState(bestState, createPitRoadState(track, position, pitLane, {
       points: pitLane.workingLane?.points,
       surface: 'pit-lane',
       part: 'working-lane',
@@ -134,8 +175,11 @@ export function nearestPitLaneState(track, position) {
       startDistance: laneEntryDistance,
       endDistance: laneExitDistance,
       segmentCandidates: roadCandidatesByRoute?.working ?? null,
-    }),
-    createPitRoadState(track, position, pitLane, {
+      projectionTarget,
+      projectionScratch,
+      cumulativeDistances: pitRoutes.working?.cumulativeDistances ?? null,
+    }));
+  bestState = pickPitState(bestState, createPitRoadState(track, position, pitLane, {
       points: pitLane.exit.roadCenterline,
       surface: 'pit-exit',
       part: 'exit',
@@ -143,10 +187,165 @@ export function nearestPitLaneState(track, position) {
       startDistance: laneExitDistance,
       endDistance: pitLane.exit.distanceFromStart,
       segmentCandidates: roadCandidatesByRoute?.exit ?? null,
-    }),
-  ].filter(Boolean);
+      projectionTarget,
+      projectionScratch,
+      cumulativeDistances: pitRoutes.exit?.cumulativeDistances ?? null,
+    }));
 
-  return candidates.sort((left, right) => left.crossTrackError - right.crossTrackError)[0] ?? null;
+  return bestState;
+}
+
+export function resolveDirectConnectorPitLaneState(track, position, progressHint = null) {
+  const pitLane = track?.pitLane;
+  if (!pitLane?.enabled) return undefined;
+  const inEntryConnector = pointInsideBounds(position, pitLane.connectorBounds?.entry);
+  const inExitConnector = pointInsideBounds(position, pitLane.connectorBounds?.exit);
+  const nearEntryProgress = Number.isFinite(progressHint) && progressHint >= pitLane.entry.trackDistance;
+  const nearExitProgress = Number.isFinite(progressHint) &&
+    progressHint >= 0 &&
+    progressHint <= pitLane.exit.trackDistance;
+  if (!inEntryConnector && !inExitConnector && !nearEntryProgress && !nearExitProgress) return undefined;
+
+  const laneEntryDistance = pitLane.layout?.entryDistance ?? pitLane.entry.distanceFromStart;
+  const laneExitDistance = pitLane.layout?.exitDistance ?? pitLane.exit.distanceFromStart;
+  const scratch = track?.queryIndex ? ensureQueryScratch(track.queryIndex) : null;
+  const pitRoutes = track?.queryIndex?.pit?.routes ?? {};
+  const projectionTarget = scratch ? (scratch.pitRoadProjection ??= { point: {} }) : null;
+  const projectionScratch = scratch ? (scratch.pitRoadProjectionScratch ??= {}) : null;
+  const useEntryEndpoint = inEntryConnector || nearEntryProgress;
+  const useExitEndpoint = inExitConnector || nearExitProgress;
+  const useIndexedConnectorCandidates = inEntryConnector || inExitConnector;
+  const roadCandidatesByRoute = (useIndexedConnectorCandidates || (!nearEntryProgress && !nearExitProgress))
+    ? queryPitRoadSegmentCandidatesByRoute(track, position, null, scratch, {
+      countQuery: false,
+      recordPathStats: !useIndexedConnectorCandidates,
+    })
+    : null;
+  let bestState = null;
+
+  if (useEntryEndpoint) {
+    const entrySegments = connectorRouteSegments(
+      roadCandidatesByRoute,
+      'entry',
+      pitRoutes.entry?.startSegmentWindow ?? null,
+      inEntryConnector,
+    );
+    bestState = pickPitState(bestState, createPitRoadState(track, position, pitLane, {
+      points: pitLane.entry.roadCenterline,
+      surface: 'pit-entry',
+      part: 'entry',
+      roadWidth: pitLane.width,
+      startDistance: pitLane.entry.distanceFromStart,
+      endDistance: laneEntryDistance,
+      projectionTarget,
+      projectionScratch,
+      cumulativeDistances: pitRoutes.entry?.cumulativeDistances ?? null,
+      segmentCandidates: entrySegments.segmentCandidates,
+      connectorProjectionStats: true,
+      connectorEndpointWindowProjection: entrySegments.endpointWindow,
+    }));
+  }
+
+  if (useEntryEndpoint || useExitEndpoint) {
+    const mainSegments = connectorRouteSegments(
+      roadCandidatesByRoute,
+      'main',
+      connectorRouteSegmentWindow(pitRoutes.main, useEntryEndpoint, useExitEndpoint),
+      useIndexedConnectorCandidates,
+    );
+    bestState = pickPitState(bestState, createPitRoadState(track, position, pitLane, {
+      points: pitLane.mainLane.points,
+      surface: 'pit-lane',
+      part: 'fast-lane',
+      roadWidth: pitLane.width,
+      startDistance: laneEntryDistance,
+      endDistance: laneExitDistance,
+      projectionTarget,
+      projectionScratch,
+      cumulativeDistances: pitRoutes.main?.cumulativeDistances ?? null,
+      segmentCandidates: mainSegments.segmentCandidates,
+      connectorProjectionStats: true,
+      connectorEndpointWindowProjection: mainSegments.endpointWindow,
+    }));
+    const workingSegments = connectorRouteSegments(
+      roadCandidatesByRoute,
+      'working',
+      connectorRouteSegmentWindow(pitRoutes.working, useEntryEndpoint, useExitEndpoint),
+      useIndexedConnectorCandidates,
+    );
+    bestState = pickPitState(bestState, createPitRoadState(track, position, pitLane, {
+      points: pitLane.workingLane?.points,
+      surface: 'pit-lane',
+      part: 'working-lane',
+      roadWidth: pitLane.workingLane?.width ?? 0,
+      startDistance: laneEntryDistance,
+      endDistance: laneExitDistance,
+      projectionTarget,
+      projectionScratch,
+      cumulativeDistances: pitRoutes.working?.cumulativeDistances ?? null,
+      segmentCandidates: workingSegments.segmentCandidates,
+      connectorProjectionStats: true,
+      connectorEndpointWindowProjection: workingSegments.endpointWindow,
+    }));
+  }
+
+  if (useExitEndpoint) {
+    const exitSegments = connectorRouteSegments(
+      roadCandidatesByRoute,
+      'exit',
+      pitRoutes.exit?.endSegmentWindow ?? null,
+      inExitConnector,
+    );
+    bestState = pickPitState(bestState, createPitRoadState(track, position, pitLane, {
+      points: pitLane.exit.roadCenterline,
+      surface: 'pit-exit',
+      part: 'exit',
+      roadWidth: pitLane.width,
+      startDistance: laneExitDistance,
+      endDistance: pitLane.exit.distanceFromStart,
+      projectionTarget,
+      projectionScratch,
+      cumulativeDistances: pitRoutes.exit?.cumulativeDistances ?? null,
+      segmentCandidates: exitSegments.segmentCandidates,
+      connectorProjectionStats: true,
+      connectorEndpointWindowProjection: exitSegments.endpointWindow,
+    }));
+  }
+
+  return bestState;
+}
+
+function connectorRouteSegmentWindow(route, useStart, useEnd) {
+  if (!route) return null;
+  if (useStart && useEnd) return route.endpointSegmentWindow ?? null;
+  if (useStart) return route.startSegmentWindow ?? null;
+  if (useEnd) return route.endSegmentWindow ?? null;
+  return null;
+}
+
+function connectorRouteSegments(candidatesByRoute, routeId, endpointWindow, preferIndexedCandidates) {
+  if (preferIndexedCandidates && candidatesByRoute) {
+    return {
+      segmentCandidates: candidatesByRoute[routeId] ?? [],
+      endpointWindow: false,
+    };
+  }
+  if (Array.isArray(endpointWindow)) {
+    return {
+      segmentCandidates: endpointWindow,
+      endpointWindow: endpointWindow.length > 0,
+    };
+  }
+  return {
+    segmentCandidates: candidatesByRoute?.[routeId] ?? null,
+    endpointWindow: false,
+  };
+}
+
+function pickPitState(currentBest, candidate) {
+  if (!candidate) return currentBest;
+  if (!currentBest) return candidate;
+  return candidate.crossTrackError < currentBest.crossTrackError ? candidate : currentBest;
 }
 
 function createLegacyPitBoxCandidates(pitLane) {

package/src/simulation/track/spatialQueries.js

@@ -1,7 +1,9 @@
 import { clamp, normalizeAngle, wrapDistance } from '../simMath.js';
 import { PIT_LANE_WIDTH } from './trackConstants.js';
-import { nearestPitLaneState } from './pitLaneState.js';
-import { queryNearestTrackProjection } from './trackQueryIndex.js';
+import { pointInsideBounds } from './trackMath.js';
+import { nearestPitLaneState, resolveDirectConnectorPitLaneState } from './pitLaneState.js';
+import { queryNearestTrackProjection, queryNearestTrackProjectionInto } from './trackQueryIndex.js';
+import { recordStat } from './trackQueryStats.js';
 
 export function pointAt(track, distanceAlong) {
   const wrapped = wrapDistance(distanceAlong, track.length);
@@ -62,6 +64,10 @@ export function nearestSampleGlobal(track, position) {
 }
 
 export function createTrackState(track, position, best) {
+  return writeTrackState({}, track, position, best);
+}
+
+export function writeTrackState(target, track, position, best) {
   const dx = position.x - best.x;
   const dy = position.y - best.y;
   const signedOffset = dx * best.normalX + dy * best.normalY;
@@ -80,24 +86,47 @@ export function createTrackState(track, position, best) {
           ? 'grass'
           : 'barrier';
 
-  return {
-    ...best,
-    signedOffset,
-    crossTrackError,
-    surface,
-    onTrack: surface === 'track' || surface === 'kerb',
-  };
+  target.segmentId = best.segmentId;
+  target.x = best.x;
+  target.y = best.y;
+  target.distance = best.distance;
+  target.heading = best.heading;
+  target.normalX = best.normalX;
+  target.normalY = best.normalY;
+  target.curvature = best.curvature;
+  target.signedOffset = signedOffset;
+  target.crossTrackError = crossTrackError;
+  target.surface = surface;
+  target.onTrack = surface === 'track' || surface === 'kerb';
+  target.distanceSquared = best.distanceSquared;
+  target.inPitLane = undefined;
+  target.pitLanePart = undefined;
+  target.pitBoxId = undefined;
+  target.mainTrackSignedOffset = undefined;
+  target.mainTrackCrossTrackError = undefined;
+  return target;
 }
 
 export function nearestTrackState(track, position, progressHint = null, options = {}) {
   const allowPitOverride = options.allowPitOverride !== false;
-  const best = queryNearestTrackProjection(track, position, progressHint);
+  const scratch = track?.queryIndex?.queryScratch ?? null;
+  const best = queryNearestTrackProjectionInto(
+    track,
+    position,
+    progressHint,
+    scratch ? (scratch.nearestProjection ??= {}) : null,
+  );
   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);
+  const pitState = queryPitOverrideState(track, position, progressHint, trackState);
+  if (!pitState) return trackState;
+  return resolveTrackStatePitOverride(track, trackState, pitState);
+}
+
+export function resolveTrackStatePitOverride(track, trackState, pitState) {
   if (!pitState) return trackState;
 
   const mainRoadEdge = track.width / 2 + (track.kerbWidth ?? 0);
@@ -122,6 +151,33 @@ export function nearestTrackState(track, position, progressHint = null, options
   };
 }
 
+function queryPitOverrideState(track, position, progressHint, trackState) {
+  const pitLane = track?.pitLane;
+  if (!pitLane?.enabled) return null;
+  if (!pointInsideBounds(position, pitLane.bounds)) return null;
+  if (pitLane.boxBounds && pointInsideBounds(position, pitLane.boxBounds)) {
+    return nearestPitLaneState(track, position, progressHint);
+  }
+
+  const mainRoadEdge = track.width / 2 + (track.kerbWidth ?? 0);
+  if (trackState.crossTrackError <= mainRoadEdge) {
+    recordStat(track?.queryIndex, 'pitPaths', 'main-road-skip');
+    return null;
+  }
+  if ((trackState.signedOffset ?? 0) * pitLane.side > 0) {
+    const directConnectorState = resolveDirectConnectorPitLaneState(track, position, progressHint);
+    if (directConnectorState !== undefined) {
+      if (directConnectorState) {
+        recordStat(track?.queryIndex, 'pitPaths', 'connector-direct-state');
+        return directConnectorState;
+      }
+      recordStat(track?.queryIndex, 'pitPaths', 'connector-direct-skip');
+      return null;
+    }
+  }
+  return nearestPitLaneState(track, position, progressHint);
+}
+
 export function offsetTrackPoint(point, offset) {
   return {
     x: point.x + point.normalX * offset,