@inventure71/paddockjs 2.0.1 → 4.0.0

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 { NEAREST_HINT_WINDOW_SAMPLES, PIT_LANE_WIDTH } from './trackConstants.js';
-import { nearestPitLaneState } from './pitLaneState.js';
-import { queryNearestTrackProjection } from './trackQueryIndex.js';
+import { PIT_LANE_WIDTH } from './trackConstants.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,27 +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 = options.indexMode === 'legacy'
-    ? nearestTrackSampleLegacy(track, position, progressHint)
-    : queryNearestTrackProjection(track, position, progressHint, {
-      indexMode: options.indexMode,
-      hintMaxDistance: options.hintMaxDistance,
-    }) ??
-    nearestTrackSampleLegacy(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);
@@ -125,24 +151,31 @@ export function nearestTrackState(track, position, progressHint = null, options
   };
 }
 
-function nearestTrackSampleLegacy(track, position, progressHint = null) {
-  let nearest = null;
+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);
+  }
 
-  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;
+  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 nearest?.best ?? nearestSampleGlobal(track, position).best;
+  return nearestPitLaneState(track, position, progressHint);
 }
 
 export function offsetTrackPoint(point, offset) {

package/src/simulation/track/trackMath.js

@@ -127,6 +127,16 @@ export function expandBounds(bounds, point) {
   };
 }
 
+export function expandBoundsByPadding(bounds, padding = 0) {
+  const resolvedPadding = Number.isFinite(padding) ? Math.max(0, padding) : 0;
+  return {
+    minX: bounds.minX - resolvedPadding,
+    maxX: bounds.maxX + resolvedPadding,
+    minY: bounds.minY - resolvedPadding,
+    maxY: bounds.maxY + resolvedPadding,
+  };
+}
+
 export function createPointBounds(points, padding = 0) {
   const bounds = points.filter(Boolean).reduce(
     (current, point) => expandBounds(current, point),
@@ -181,43 +191,100 @@ export function projectPointToSegment(position, start, end) {
 }
 
 export function nearestPointOnPolyline(points, position, segmentIndices = null) {
+  return nearestPointOnPolylineInto({}, points, position, { segmentIndices });
+}
+
+export function nearestPointOnPolylineInto(target, points, position, {
+  segmentIndices = null,
+  scratch = null,
+  cumulativeDistances: precomputedCumulativeDistances = null,
+} = {}) {
   if (!Array.isArray(points) || points.length < 2) return null;
-  const restrictedSegments = Array.isArray(segmentIndices) && segmentIndices.length > 0
-    ? [...new Set(segmentIndices)].filter((index) => Number.isInteger(index) && index >= 0 && index < points.length - 1)
+  const output = target ?? {};
+  const outputPoint = output.point ?? {};
+  output.point = outputPoint;
+  const restrictedSegments = Array.isArray(segmentIndices) && segmentIndices.length > 0;
+  const cumulativeDistances = restrictedSegments
+    ? (Array.isArray(precomputedCumulativeDistances) && precomputedCumulativeDistances.length >= points.length
+      ? precomputedCumulativeDistances
+      : writePolylineCumulativeDistances(scratch?.cumulativeDistances ?? new Array(points.length), points))
     : null;
-  const cumulativeDistances = restrictedSegments ? createPolylineCumulativeDistances(points) : null;
-  let best = null;
+  if (scratch && restrictedSegments && cumulativeDistances !== precomputedCumulativeDistances) {
+    scratch.cumulativeDistances = cumulativeDistances;
+  }
+
+  let bestSegmentIndex = -1;
+  let bestAmount = 0;
+  let bestLength = 0;
+  let bestHeading = 0;
+  let bestNormalX = 0;
+  let bestNormalY = 1;
+  let bestSignedOffset = 0;
+  let bestCrossTrackError = Infinity;
+  let bestDistanceAlong = 0;
+  let bestX = 0;
+  let bestY = 0;
   let distanceBefore = 0;
   let totalLength = 0;
 
-  const segmentCount = restrictedSegments?.length ?? (points.length - 1);
+  const segmentCount = restrictedSegments ? segmentIndices.length : (points.length - 1);
   for (let segmentOffset = 0; segmentOffset < segmentCount; segmentOffset += 1) {
-    const index = restrictedSegments ? restrictedSegments[segmentOffset] : segmentOffset;
+    const index = restrictedSegments ? segmentIndices[segmentOffset] : segmentOffset;
+    if (!Number.isInteger(index) || index < 0 || index >= points.length - 1) continue;
     const current = points[index];
     const next = points[index + 1];
-    const projection = projectPointToSegment(position, current, next);
-    if (!best || projection.crossTrackError < best.crossTrackError) {
-      best = {
-        ...projection,
-        segmentIndex: index,
-        distanceAlong: (restrictedSegments ? cumulativeDistances[index] : distanceBefore) + projection.length * projection.amount,
-      };
+    const dx = next.x - current.x;
+    const dy = next.y - current.y;
+    const lengthSquared = dx * dx + dy * dy;
+    const amount = lengthSquared > 0
+      ? clamp(((position.x - current.x) * dx + (position.y - current.y) * dy) / lengthSquared, 0, 1)
+      : 0;
+    const projectedX = current.x + dx * amount;
+    const projectedY = current.y + dy * amount;
+    const length = Math.sqrt(lengthSquared);
+    const heading = Math.atan2(dy, dx);
+    const normalX = length > 0 ? -dy / length : 0;
+    const normalY = length > 0 ? dx / length : 1;
+    const signedOffset = (position.x - projectedX) * normalX + (position.y - projectedY) * normalY;
+    const crossTrackError = Math.abs(signedOffset);
+    if (crossTrackError < bestCrossTrackError) {
+      bestSegmentIndex = index;
+      bestAmount = amount;
+      bestLength = length;
+      bestHeading = heading;
+      bestNormalX = normalX;
+      bestNormalY = normalY;
+      bestSignedOffset = signedOffset;
+      bestCrossTrackError = crossTrackError;
+      bestDistanceAlong = (restrictedSegments ? cumulativeDistances[index] : distanceBefore) + length * amount;
+      bestX = projectedX;
+      bestY = projectedY;
     }
-    if (!restrictedSegments) distanceBefore += projection.length;
-    totalLength += projection.length;
+    if (!restrictedSegments) distanceBefore += length;
+    totalLength += length;
   }
 
-  if (!best) return null;
-  return {
-    ...best,
-    totalLength: restrictedSegments
-      ? cumulativeDistances[cumulativeDistances.length - 1]
-      : totalLength,
-  };
+  if (bestSegmentIndex < 0) return null;
+  outputPoint.x = bestX;
+  outputPoint.y = bestY;
+  output.amount = bestAmount;
+  output.length = bestLength;
+  output.heading = bestHeading;
+  output.normalX = bestNormalX;
+  output.normalY = bestNormalY;
+  output.signedOffset = bestSignedOffset;
+  output.crossTrackError = bestCrossTrackError;
+  output.segmentIndex = bestSegmentIndex;
+  output.distanceAlong = bestDistanceAlong;
+  output.totalLength = restrictedSegments
+    ? cumulativeDistances[cumulativeDistances.length - 1]
+    : totalLength;
+  return output;
 }
 
-function createPolylineCumulativeDistances(points) {
-  const distances = new Array(points.length).fill(0);
+function writePolylineCumulativeDistances(distances, points) {
+  distances.length = points.length;
+  distances[0] = 0;
   for (let index = 1; index < points.length; index += 1) {
     distances[index] = distances[index - 1] + distance(points[index - 1], points[index]);
   }

package/src/simulation/track/trackModel.js

@@ -11,6 +11,7 @@ import { deriveDrsZones, normalizeDrsZone } from './drsZones.js';
 import { createPitLaneModel } from './pitLaneLayout.js';
 import { attachTrackQueryIndex, createTrackQueryIndex } from './trackQueryIndex.js';
 import { resolveProceduralTrackOptions } from './trackGenerationOptions.js';
+import { attachTrackSnapshotJsonSerializer } from './trackSnapshotJson.js';
 
 export { WORLD, TRACK } from './trackConstants.js';
 export { isInDrsZone } from './drsZones.js';
@@ -56,6 +57,7 @@ export function buildTrackModel(track = TRACK) {
     ? null
     : createPitLaneModel(model);
   attachTrackQueryIndex(model, createTrackQueryIndex(model));
+  attachTrackSnapshotJsonSerializer(model);
   if (canReuseCachedModel) {
     TRACK_MODEL_CACHE.set(track, freezeTrackModel(model));
   }