@inventure71/paddockjs 3.0.0 → 4.0.0

package/src/simulation/timing/lapTelemetry.js

@@ -12,7 +12,7 @@ function getSectorLength(track) {
   return track.length / TELEMETRY_SECTOR_COUNT;
 }
 
-function getLapTelemetryPosition(track, raceDistance, totalLaps = Infinity) {
+function writeLapTelemetryPosition(target, track, raceDistance, totalLaps = Infinity) {
   const positiveDistance = Math.max(0, raceDistance ?? 0);
   const lapIndex = Math.min(
     Math.floor(positiveDistance / track.length),
@@ -25,42 +25,40 @@ function getLapTelemetryPosition(track, raceDistance, totalLaps = Infinity) {
   const sectorIndex = Math.min(TELEMETRY_SECTOR_COUNT - 1, Math.floor(lapProgress / sectorLength));
   const sectorStart = sectorIndex * sectorLength;
 
-  return {
-    completedLaps: Math.floor(positiveDistance / track.length),
-    currentLap: Math.max(1, lapIndex + 1),
-    currentSector: sectorIndex + 1,
-    currentSectorProgress: clamp((lapProgress - sectorStart) / sectorLength, 0, 1),
-  };
+  target.completedLaps = Math.floor(positiveDistance / track.length);
+  target.currentLap = Math.max(1, lapIndex + 1);
+  target.currentSector = sectorIndex + 1;
+  target.currentSectorProgress = clamp((lapProgress - sectorStart) / sectorLength, 0, 1);
+  return target;
 }
 
 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;
-  });
+  const progress = createEmptySectorTimes();
+  writeSectorProgress(progress, position, currentSectors, { preserveCompletedSectors, activeIndex });
+  return progress;
 }
 
 export function createLapTelemetry(track, currentTime = 0, raceDistance = 0, totalLaps = Infinity) {
-  const position = getLapTelemetryPosition(track, raceDistance, totalLaps);
-  return {
-    ...position,
+  const telemetry = {
     currentLapStartedAt: currentTime,
     currentSectorStartedAt: currentTime,
     lastUpdatedAt: currentTime,
     currentLapTime: 0,
     currentSectorElapsed: 0,
     currentSectors: createEmptySectorTimes(),
-    sectorProgress: createSectorProgress(position),
+    sectorProgress: createEmptySectorTimes(),
     liveSectors: createEmptySectorTimes(),
     lastLapTime: null,
     bestLapTime: null,
     lastSectors: createEmptySectorTimes(),
     bestSectors: createEmptySectorTimes(),
     sectorPerformance: createEmptySectorPerformance(),
+    sectorPerformanceRevision: 0,
   };
+  writeLapTelemetryPosition(telemetry, track, raceDistance, totalLaps);
+  telemetry.sectorProgress = createSectorProgress(telemetry);
+  return telemetry;
 }
 
 export function resetLapTelemetry(car, currentTime, track, totalLaps) {
@@ -106,7 +104,7 @@ export function updateLapTelemetry(car, previousRaceDistance, currentTime, track
     Math.abs(travelled) > track.length / 2
   ) {
     resetLapTelemetry(car, currentTime, track, totalLaps);
-    return;
+    return true;
   }
 
   if (travelled < -1e-3) {
@@ -114,10 +112,11 @@ export function updateLapTelemetry(car, previousRaceDistance, currentTime, track
       preserveCompletedSectors: true,
     });
     telemetry.lastUpdatedAt = currentTime;
-    return;
+    return false;
   }
 
   const sectorLength = getSectorLength(track);
+  let crossedBoundary = false;
   if (travelled > 1e-6) {
     const firstBoundary = Math.floor(previousDistance / sectorLength) + 1;
     const lastBoundary = Math.floor(currentDistance / sectorLength);
@@ -125,6 +124,7 @@ export function updateLapTelemetry(car, previousRaceDistance, currentTime, track
     for (let boundary = firstBoundary; boundary <= lastBoundary; boundary += 1) {
       const boundaryDistance = boundary * sectorLength;
       if (boundaryDistance <= previousDistance + 1e-3 || boundaryDistance > currentDistance + 1e-3) continue;
+      crossedBoundary = true;
 
       const boundaryRatio = clamp((boundaryDistance - previousDistance) / travelled, 0, 1);
       const crossingTime = previousUpdateTime + boundaryRatio * elapsedTime;
@@ -140,8 +140,8 @@ export function updateLapTelemetry(car, previousRaceDistance, currentTime, track
         telemetry.bestLapTime = Number.isFinite(telemetry.bestLapTime)
           ? Math.min(telemetry.bestLapTime, lapTime)
           : lapTime;
-        telemetry.lastSectors = serializeSectorTimes(telemetry.currentSectors);
-        telemetry.currentSectors = createEmptySectorTimes();
+        telemetry.lastSectors = copySectorTimes(telemetry.lastSectors, telemetry.currentSectors);
+        clearSectorTimes(telemetry.currentSectors);
         telemetry.currentLapStartedAt = crossingTime;
         telemetry.completedLaps = Math.max(telemetry.completedLaps + 1, Math.min(Math.floor(boundaryDistance / track.length), totalLaps));
       }
@@ -150,8 +150,18 @@ export function updateLapTelemetry(car, previousRaceDistance, currentTime, track
     }
   }
 
+  if (!crossedBoundary) {
+    syncInProgressLapTelemetry(telemetry, currentTime, currentRaceDistance, track, totalLaps);
+    telemetry.lastUpdatedAt = currentTime;
+    return false;
+  }
+
   syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps);
   telemetry.lastUpdatedAt = currentTime;
+  if (crossedBoundary) {
+    telemetry.sectorPerformanceRevision = (telemetry.sectorPerformanceRevision ?? 0) + 1;
+  }
+  return crossedBoundary;
 }
 
 function updateBestSector(telemetry, sectorIndex, sectorTime) {
@@ -170,32 +180,101 @@ function clearFutureSectorTelemetry(telemetry) {
 
 function syncLiveSectorTelemetry(telemetry, { preserveCompletedSectors = false } = {}) {
   const activeIndex = clamp((telemetry.currentSector ?? 1) - 1, 0, TELEMETRY_SECTOR_COUNT - 1);
+  const liveSectors = ensureSectorTimesArray(telemetry.liveSectors);
+  clearSectorTimes(liveSectors);
+  for (let index = 0; index < TELEMETRY_SECTOR_COUNT; index += 1) {
+    const time = telemetry.currentSectors[index];
+    if (!preserveCompletedSectors && index >= activeIndex) continue;
+    if (!Number.isFinite(time)) continue;
+    liveSectors[index] = time;
+  }
+  if (!Number.isFinite(liveSectors[activeIndex])) {
+    liveSectors[activeIndex] = telemetry.currentSectorElapsed;
+  }
+  telemetry.liveSectors = liveSectors;
+}
 
-  telemetry.liveSectors = createEmptySectorTimes();
-  telemetry.currentSectors.forEach((time, index) => {
-    if (!preserveCompletedSectors && index >= activeIndex) return;
-    if (!Number.isFinite(time)) return;
-    telemetry.liveSectors[index] = time;
-  });
-  if (!Number.isFinite(telemetry.liveSectors[activeIndex])) {
-    telemetry.liveSectors[activeIndex] = telemetry.currentSectorElapsed;
+function syncInProgressLapTelemetry(telemetry, currentTime, currentRaceDistance, track, totalLaps) {
+  const positiveDistance = Math.max(0, currentRaceDistance ?? 0);
+  const maxLapIndex = Math.max(0, totalLaps - 1);
+  const lapIndex = Math.min(Math.floor(positiveDistance / track.length), maxLapIndex);
+  const lapProgress = positiveDistance >= track.length * totalLaps
+    ? track.length
+    : positiveDistance - lapIndex * track.length;
+  const sectorLength = getSectorLength(track);
+  const activeIndex = Math.min(TELEMETRY_SECTOR_COUNT - 1, Math.floor(lapProgress / sectorLength));
+  const sectorStart = activeIndex * sectorLength;
+  const sectorProgress = ensureSectorTimesArray(telemetry.sectorProgress);
+  const liveSectors = ensureSectorTimesArray(telemetry.liveSectors);
+
+  telemetry.completedLaps = Math.floor(positiveDistance / track.length);
+  telemetry.currentLap = Math.max(1, lapIndex + 1);
+  telemetry.currentSector = activeIndex + 1;
+  telemetry.currentSectorProgress = clamp((lapProgress - sectorStart) / sectorLength, 0, 1);
+  telemetry.currentLapTime = Math.max(0, currentTime - telemetry.currentLapStartedAt);
+  telemetry.currentSectorElapsed = Math.max(0, currentTime - telemetry.currentSectorStartedAt);
+  for (let index = activeIndex; index < TELEMETRY_SECTOR_COUNT; index += 1) {
+    telemetry.currentSectors[index] = null;
+    liveSectors[index] = null;
+    sectorProgress[index] = 0;
   }
+  sectorProgress[activeIndex] = telemetry.currentSectorProgress;
+  liveSectors[activeIndex] = telemetry.currentSectorElapsed;
+  telemetry.sectorProgress = sectorProgress;
+  telemetry.liveSectors = liveSectors;
 }
 
 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;
+  writeLapTelemetryPosition(telemetry, track, currentRaceDistance, totalLaps);
   if (!preserveCompletedSectors) clearFutureSectorTelemetry(telemetry);
-  telemetry.sectorProgress = createSectorProgress(position, telemetry.currentSectors, {
+  const sectorProgress = ensureSectorTimesArray(telemetry.sectorProgress);
+  writeSectorProgress(sectorProgress, telemetry, telemetry.currentSectors, {
     preserveCompletedSectors,
   });
-  telemetry.completedLaps = Math.max(telemetry.completedLaps, Math.min(position.completedLaps, totalLaps));
+  telemetry.sectorProgress = sectorProgress;
+  telemetry.completedLaps = Math.max(telemetry.completedLaps, Math.min(telemetry.completedLaps, totalLaps));
   telemetry.currentLapTime = Math.max(0, currentTime - telemetry.currentLapStartedAt);
   telemetry.currentSectorElapsed = Math.max(0, currentTime - telemetry.currentSectorStartedAt);
   syncLiveSectorTelemetry(telemetry, { preserveCompletedSectors });
 }
+
+function ensureSectorTimesArray(values) {
+  return Array.isArray(values) && values.length === TELEMETRY_SECTOR_COUNT
+    ? values
+    : createEmptySectorTimes();
+}
+
+function clearSectorTimes(values) {
+  for (let index = 0; index < TELEMETRY_SECTOR_COUNT; index += 1) {
+    values[index] = null;
+  }
+}
+
+function copySectorTimes(target, source) {
+  const nextTarget = ensureSectorTimesArray(target);
+  for (let index = 0; index < TELEMETRY_SECTOR_COUNT; index += 1) {
+    nextTarget[index] = finiteOrNull(source?.[index]);
+  }
+  return nextTarget;
+}
+
+function writeSectorProgress(target, position, currentSectors = null, { preserveCompletedSectors = false, activeIndex = null } = {}) {
+  const resolvedActiveIndex = activeIndex == null
+    ? clamp((position.currentSector ?? 1) - 1, 0, TELEMETRY_SECTOR_COUNT - 1)
+    : activeIndex;
+  for (let index = 0; index < TELEMETRY_SECTOR_COUNT; index += 1) {
+    if (preserveCompletedSectors && Number.isFinite(currentSectors?.[index])) {
+      target[index] = 1;
+      continue;
+    }
+    if (index < resolvedActiveIndex && Number.isFinite(currentSectors?.[index])) {
+      target[index] = 1;
+      continue;
+    }
+    target[index] = index === resolvedActiveIndex
+      ? clamp(position.currentSectorProgress ?? 0, 0, 1)
+      : 0;
+  }
+}

package/src/simulation/timing/raceTiming.js

@@ -5,7 +5,11 @@ export {
   updateLapTelemetry,
 } from './lapTelemetry.js';
 export { estimateGapAheadSeconds, estimateTimingLineGapSeconds, wholeLapGap } from './gapEstimation.js';
-export { createEmptySectorPerformance, createEmptySectorTimes, updateSectorPerformance } from './sectorPerformance.js';
+export {
+  createEmptySectorPerformance,
+  createEmptySectorTimes,
+  updateSectorPerformance,
+} from './sectorPerformance.js';
 export { recordTimingSample, resetTimingHistory, trimTimingHistory } from './timingHistory.js';
 export {
   createTimingLines,

package/src/simulation/timing/sectorPerformance.js

@@ -1,5 +1,9 @@
 import { TELEMETRY_SECTOR_COUNT } from './timingConstants.js';
 
+const OVERALL_BEST_0 = '_sectorPerformanceOverallBest0';
+const OVERALL_BEST_1 = '_sectorPerformanceOverallBest1';
+const OVERALL_BEST_2 = '_sectorPerformanceOverallBest2';
+
 export function createEmptySectorTimes() {
   return Array.from({ length: TELEMETRY_SECTOR_COUNT }, () => null);
 }
@@ -20,32 +24,80 @@ export function serializeSectorPerformance(values) {
   return createEmptySectorTimes().map((_, index) => values?.[index] ?? null);
 }
 
-export function updateSectorPerformance(cars) {
-  const overallBestSectors = createEmptySectorTimes();
-  cars.forEach((car) => {
-    car.lapTelemetry?.bestSectors?.forEach((value, index) => {
-      if (!Number.isFinite(value)) return;
-      const previousBest = overallBestSectors[index];
-      if (!Number.isFinite(previousBest) || value < previousBest) overallBestSectors[index] = value;
-    });
-  });
-  cars.forEach((car) => {
-    const telemetry = car.lapTelemetry;
-    if (!telemetry) return;
-    telemetry.sectorPerformance = {
-      current: telemetry.currentSectors.map((value, index) => classifySectorPerformance(
-        value,
-        telemetry.bestSectors[index],
-        overallBestSectors[index],
-      )),
-      last: telemetry.lastSectors.map((value, index) => classifySectorPerformance(
-        value,
-        telemetry.bestSectors[index],
-        overallBestSectors[index],
-      )),
-      best: telemetry.bestSectors.map((value, index) => classifySectorPerformance(value, value, overallBestSectors[index])),
-    };
-  });
+export function updateSectorPerformance(cars, stats = null) {
+  let overallBest0 = null;
+  let overallBest1 = null;
+  let overallBest2 = null;
+  let changedCars = 0;
+
+  for (let index = 0; index < cars.length; index += 1) {
+    const telemetry = cars[index]?.lapTelemetry;
+    if (!telemetry) continue;
+    const best0 = finiteOrNull(telemetry.bestSectors?.[0]);
+    const best1 = finiteOrNull(telemetry.bestSectors?.[1]);
+    const best2 = finiteOrNull(telemetry.bestSectors?.[2]);
+    const revision = telemetry.sectorPerformanceRevision ?? 0;
+    if (telemetry._sectorPerfAppliedRevision !== revision) changedCars += 1;
+    if (Number.isFinite(best0) && (!Number.isFinite(overallBest0) || best0 < overallBest0)) overallBest0 = best0;
+    if (Number.isFinite(best1) && (!Number.isFinite(overallBest1) || best1 < overallBest1)) overallBest1 = best1;
+    if (Number.isFinite(best2) && (!Number.isFinite(overallBest2) || best2 < overallBest2)) overallBest2 = best2;
+  }
+
+  const overallBestChanged =
+    overallBest0 !== cars[OVERALL_BEST_0] ||
+    overallBest1 !== cars[OVERALL_BEST_1] ||
+    overallBest2 !== cars[OVERALL_BEST_2];
+
+  if (stats) {
+    stats.sectorPerformanceChangedCars = (stats.sectorPerformanceChangedCars ?? 0) + changedCars;
+  }
+
+  if (!overallBestChanged && changedCars === 0) {
+    if (stats) stats.sectorPerformanceSkippedRebuilds = (stats.sectorPerformanceSkippedRebuilds ?? 0) + 1;
+    return false;
+  }
+
+  cars[OVERALL_BEST_0] = overallBest0;
+  cars[OVERALL_BEST_1] = overallBest1;
+  cars[OVERALL_BEST_2] = overallBest2;
+
+  let updatedCars = 0;
+  const overallBestSectors = [overallBest0, overallBest1, overallBest2];
+  for (let index = 0; index < cars.length; index += 1) {
+    const telemetry = cars[index]?.lapTelemetry;
+    if (!telemetry) continue;
+    const revision = telemetry.sectorPerformanceRevision ?? 0;
+    if (!overallBestChanged && telemetry._sectorPerfAppliedRevision === revision) continue;
+    const sectorPerformance = ensureSectorPerformanceShape(telemetry.sectorPerformance);
+    writeSectorPerformance(
+      sectorPerformance.current,
+      telemetry.currentSectors,
+      telemetry.bestSectors,
+      overallBestSectors,
+    );
+    writeSectorPerformance(
+      sectorPerformance.last,
+      telemetry.lastSectors,
+      telemetry.bestSectors,
+      overallBestSectors,
+    );
+    writeSectorPerformance(
+      sectorPerformance.best,
+      telemetry.bestSectors,
+      telemetry.bestSectors,
+      overallBestSectors,
+    );
+    telemetry.sectorPerformance = sectorPerformance;
+    telemetry._sectorPerfAppliedRevision = revision;
+    updatedCars += 1;
+  }
+
+  if (stats) {
+    stats.sectorPerformanceRebuilds = (stats.sectorPerformanceRebuilds ?? 0) + 1;
+    stats.sectorPerformanceUpdatedCars = (stats.sectorPerformanceUpdatedCars ?? 0) + updatedCars;
+    if (overallBestChanged) stats.sectorPerformanceOverallBestChanges = (stats.sectorPerformanceOverallBestChanges ?? 0) + 1;
+  }
+  return true;
 }
 
 export function finiteOrNull(value) {
@@ -58,3 +110,29 @@ function classifySectorPerformance(value, personalBest, overallBest) {
   if (Number.isFinite(personalBest) && Math.abs(value - personalBest) <= 1e-6) return 'personal-best';
   return 'slower';
 }
+
+function ensureSectorPerformanceShape(sectorPerformance) {
+  if (!sectorPerformance || typeof sectorPerformance !== 'object') {
+    return createEmptySectorPerformance();
+  }
+  sectorPerformance.current = ensureSectorArray(sectorPerformance.current);
+  sectorPerformance.last = ensureSectorArray(sectorPerformance.last);
+  sectorPerformance.best = ensureSectorArray(sectorPerformance.best);
+  return sectorPerformance;
+}
+
+function ensureSectorArray(values) {
+  return Array.isArray(values) && values.length === TELEMETRY_SECTOR_COUNT
+    ? values
+    : createEmptySectorTimes();
+}
+
+function writeSectorPerformance(target, sectorValues, bestSectors, overallBestSectors) {
+  for (let index = 0; index < TELEMETRY_SECTOR_COUNT; index += 1) {
+    target[index] = classifySectorPerformance(
+      sectorValues?.[index],
+      bestSectors?.[index],
+      overallBestSectors[index],
+    );
+  }
+}

package/src/simulation/timing/timingHistory.js

@@ -1,39 +1,218 @@
 import { TIMING_HISTORY_MAX_SAMPLES, TIMING_HISTORY_WINDOW_SECONDS } from './timingConstants.js';
 
+const TIMING_HISTORY_START_INDEX = '_startIndex';
+const TIMING_HISTORY_COUNT = '_count';
+const TIMING_HISTORY_INTERPOLATION_OFFSET = '_interpolationOffset';
+const TIMING_HISTORY_INTERPOLATION_LOWER_DISTANCE = '_interpolationLowerDistance';
+const TIMING_HISTORY_INTERPOLATION_UPPER_DISTANCE = '_interpolationUpperDistance';
+const TIMING_HISTORY_INTERPOLATION_LOWER_TIME = '_interpolationLowerTime';
+const TIMING_HISTORY_INTERPOLATION_UPPER_TIME = '_interpolationUpperTime';
+const TIMING_HISTORY_INTERPOLATION_STATS = '_interpolationStats';
+
+function isStructuredTimingHistory(history) {
+  return Boolean(
+    history &&
+    history.times instanceof Float64Array &&
+    history.distances instanceof Float64Array,
+  );
+}
+
+function createStructuredTimingHistory(currentTime, raceDistance) {
+  const history = {
+    times: new Float64Array(TIMING_HISTORY_MAX_SAMPLES),
+    distances: new Float64Array(TIMING_HISTORY_MAX_SAMPLES),
+  };
+  history.times[0] = currentTime;
+  history.distances[0] = raceDistance;
+  history[TIMING_HISTORY_START_INDEX] = 0;
+  history[TIMING_HISTORY_COUNT] = 1;
+  return history;
+}
+
+function getTimingHistoryStartIndex(history) {
+  if (isStructuredTimingHistory(history)) {
+    const value = history[TIMING_HISTORY_START_INDEX];
+    return Number.isInteger(value) && value >= 0 ? value : 0;
+  }
+  const value = history?.[TIMING_HISTORY_START_INDEX];
+  return Number.isInteger(value) && value >= 0 ? value : 0;
+}
+
+function setTimingHistoryStartIndex(history, startIndex) {
+  if (isStructuredTimingHistory(history)) {
+    history[TIMING_HISTORY_START_INDEX] = startIndex;
+    return;
+  }
+  Object.defineProperty(history, TIMING_HISTORY_START_INDEX, {
+    value: startIndex,
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+}
+
+function clearTimingHistoryStartIndex(history) {
+  if (isStructuredTimingHistory(history)) {
+    history[TIMING_HISTORY_START_INDEX] = 0;
+    return;
+  }
+  delete history[TIMING_HISTORY_START_INDEX];
+}
+
+function activeTimingHistoryLength(history, startIndex = getTimingHistoryStartIndex(history)) {
+  if (isStructuredTimingHistory(history)) {
+    const count = history[TIMING_HISTORY_COUNT];
+    return Number.isInteger(count) && count >= 0 ? count : 0;
+  }
+  return Math.max(0, history.length - startIndex);
+}
+
+function compactTimingHistory(history, startIndex) {
+  if (isStructuredTimingHistory(history)) {
+    history[TIMING_HISTORY_START_INDEX] = startIndex;
+    return;
+  }
+  if (startIndex <= 0) {
+    clearTimingHistoryStartIndex(history);
+    return;
+  }
+  history.splice(0, startIndex);
+  clearTimingHistoryStartIndex(history);
+}
+
+function trimStructuredTimingHistory(history, currentTime) {
+  let startIndex = getTimingHistoryStartIndex(history);
+  let count = activeTimingHistoryLength(history, startIndex);
+  const cutoff = currentTime - TIMING_HISTORY_WINDOW_SECONDS;
+  while (
+    count > 2 &&
+    history.times[startIndex] < cutoff
+  ) {
+    startIndex = (startIndex + 1) % TIMING_HISTORY_MAX_SAMPLES;
+    count -= 1;
+  }
+  history[TIMING_HISTORY_START_INDEX] = startIndex;
+  history[TIMING_HISTORY_COUNT] = count;
+}
+
 export function trimTimingHistory(history, currentTime) {
+  if (isStructuredTimingHistory(history)) {
+    trimStructuredTimingHistory(history, currentTime);
+    return;
+  }
+  if (!Array.isArray(history)) return;
   const cutoff = currentTime - TIMING_HISTORY_WINDOW_SECONDS;
-  while (history.length > 2 && (history[0].time < cutoff || history.length > TIMING_HISTORY_MAX_SAMPLES)) {
-    history.shift();
+  let startIndex = getTimingHistoryStartIndex(history);
+  if (
+    startIndex === 0 &&
+    history.length <= TIMING_HISTORY_MAX_SAMPLES &&
+    history.length <= 2
+  ) return;
+  if (
+    startIndex === 0 &&
+    history.length <= TIMING_HISTORY_MAX_SAMPLES &&
+    history[0]?.time >= cutoff
+  ) return;
+  while (
+    activeTimingHistoryLength(history, startIndex) > 2 &&
+    (
+      history[startIndex]?.time < cutoff ||
+      activeTimingHistoryLength(history, startIndex) > TIMING_HISTORY_MAX_SAMPLES
+    )
+  ) {
+    startIndex += 1;
   }
+  if (startIndex > 0 && (startIndex >= 64 || startIndex * 2 >= history.length)) {
+    compactTimingHistory(history, startIndex);
+    return;
+  }
+  if (startIndex > 0) setTimingHistoryStartIndex(history, startIndex);
+  else clearTimingHistoryStartIndex(history);
 }
 
 export function resetTimingHistory(car, currentTime) {
-  car.timingHistory = [{ time: currentTime, raceDistance: car.raceDistance }];
+  car.timingHistory = createStructuredTimingHistory(currentTime, car.raceDistance);
 }
 
 export function recordTimingSample(car, currentTime) {
   if (!Number.isFinite(car.raceDistance)) return;
-  if (!Array.isArray(car.timingHistory)) {
+  if (!isStructuredTimingHistory(car.timingHistory)) {
     resetTimingHistory(car, currentTime);
-    return;
   }
-
-  const previous = car.timingHistory[car.timingHistory.length - 1];
+  const history = car.timingHistory;
+  const startIndex = getTimingHistoryStartIndex(history);
+  const count = activeTimingHistoryLength(history, startIndex);
+  const previousIndex = count > 0
+    ? (startIndex + count - 1) % TIMING_HISTORY_MAX_SAMPLES
+    : 0;
+  const previousTime = count > 0 ? history.times[previousIndex] : null;
+  const previousRaceDistance = count > 0 ? history.distances[previousIndex] : null;
   if (
-    previous &&
-    Math.abs(previous.time - currentTime) <= 1e-6 &&
-    Math.abs(previous.raceDistance - car.raceDistance) <= 1e-3
+    count > 0 &&
+    Math.abs(previousTime - currentTime) <= 1e-6 &&
+    Math.abs(previousRaceDistance - car.raceDistance) <= 1e-3
   ) {
     return;
   }
 
-  car.timingHistory.push({ time: currentTime, raceDistance: car.raceDistance });
-  trimTimingHistory(car.timingHistory, currentTime);
+  let nextStartIndex = startIndex;
+  let nextCount = count;
+  let writeIndex = 0;
+  if (nextCount < TIMING_HISTORY_MAX_SAMPLES) {
+    writeIndex = (nextStartIndex + nextCount) % TIMING_HISTORY_MAX_SAMPLES;
+    nextCount += 1;
+  } else {
+    writeIndex = nextStartIndex;
+    nextStartIndex = (nextStartIndex + 1) % TIMING_HISTORY_MAX_SAMPLES;
+  }
+  history.times[writeIndex] = currentTime;
+  history.distances[writeIndex] = car.raceDistance;
+  history[TIMING_HISTORY_START_INDEX] = nextStartIndex;
+  history[TIMING_HISTORY_COUNT] = nextCount;
+  trimStructuredTimingHistory(history, currentTime);
 }
 
 export function interpolateTimeAtDistance(history, targetDistance) {
-  if (!Array.isArray(history) || history.length < 2) return null;
-  for (let index = history.length - 1; index > 0; index -= 1) {
+  if (isStructuredTimingHistory(history)) {
+    const directCachedTime = interpolateDirectCachedSegment(history, targetDistance);
+    if (Number.isFinite(directCachedTime)) return directCachedTime;
+    const startIndex = getTimingHistoryStartIndex(history);
+    const count = activeTimingHistoryLength(history, startIndex);
+    if (count < 2) return null;
+    const cachedOffset = history[TIMING_HISTORY_INTERPOLATION_OFFSET];
+    if (Number.isInteger(cachedOffset) && cachedOffset >= 0 && cachedOffset < count - 1) {
+      const cachedTime = interpolateStructuredTimingHistoryAtOffset(history, startIndex, count, targetDistance, cachedOffset);
+      if (Number.isFinite(cachedTime)) return cachedTime;
+      const resolvedOffset = history[TIMING_HISTORY_INTERPOLATION_OFFSET];
+      if (Number.isInteger(resolvedOffset) && resolvedOffset >= 0 && resolvedOffset < count - 1) {
+        const currentPosition = count - 1 - resolvedOffset;
+        const currentIndex = (startIndex + currentPosition) % TIMING_HISTORY_MAX_SAMPLES;
+        const previousIndex = (startIndex + currentPosition - 1) % TIMING_HISTORY_MAX_SAMPLES;
+        const currentDistance = history.distances[currentIndex];
+        const previousDistance = history.distances[previousIndex];
+        if (targetDistance > currentDistance) {
+          for (let offset = resolvedOffset - 1; offset >= 0; offset -= 1) {
+            const value = interpolateStructuredTimingHistoryAtOffset(history, startIndex, count, targetDistance, offset);
+            if (Number.isFinite(value)) return value;
+          }
+        } else if (targetDistance < previousDistance) {
+          for (let offset = resolvedOffset + 1; offset < count - 1; offset += 1) {
+            const value = interpolateStructuredTimingHistoryAtOffset(history, startIndex, count, targetDistance, offset);
+            if (Number.isFinite(value)) return value;
+          }
+        }
+      }
+    }
+    for (let offset = 0; offset < count - 1; offset += 1) {
+      const value = interpolateStructuredTimingHistoryAtOffset(history, startIndex, count, targetDistance, offset);
+      if (Number.isFinite(value)) return value;
+    }
+    return null;
+  }
+  if (!Array.isArray(history)) return null;
+  const startIndex = getTimingHistoryStartIndex(history);
+  if (activeTimingHistoryLength(history, startIndex) < 2) return null;
+  for (let index = history.length - 1; index > startIndex; index -= 1) {
     const current = history[index];
     const previous = history[index - 1];
     if (targetDistance < previous.raceDistance || targetDistance > current.raceDistance) continue;
@@ -44,3 +223,39 @@ export function interpolateTimeAtDistance(history, targetDistance) {
   }
   return null;
 }
+
+function interpolateStructuredTimingHistoryAtOffset(history, startIndex, count, targetDistance, offsetFromTail) {
+  const currentPosition = count - 1 - offsetFromTail;
+  const currentIndex = (startIndex + currentPosition) % TIMING_HISTORY_MAX_SAMPLES;
+  const previousIndex = (startIndex + currentPosition - 1) % TIMING_HISTORY_MAX_SAMPLES;
+  const currentDistance = history.distances[currentIndex];
+  const previousDistance = history.distances[previousIndex];
+  if (targetDistance < previousDistance || targetDistance > currentDistance) return null;
+  history[TIMING_HISTORY_INTERPOLATION_OFFSET] = offsetFromTail;
+  history[TIMING_HISTORY_INTERPOLATION_LOWER_DISTANCE] = previousDistance;
+  history[TIMING_HISTORY_INTERPOLATION_UPPER_DISTANCE] = currentDistance;
+  history[TIMING_HISTORY_INTERPOLATION_LOWER_TIME] = history.times[previousIndex];
+  history[TIMING_HISTORY_INTERPOLATION_UPPER_TIME] = history.times[currentIndex];
+  const coveredDistance = currentDistance - previousDistance;
+  if (coveredDistance <= 1e-6) return history.times[currentIndex];
+  const ratio = (targetDistance - previousDistance) / coveredDistance;
+  return history.times[previousIndex] + (history.times[currentIndex] - history.times[previousIndex]) * ratio;
+}
+
+function interpolateDirectCachedSegment(history, targetDistance) {
+  const lowerDistance = history[TIMING_HISTORY_INTERPOLATION_LOWER_DISTANCE];
+  const upperDistance = history[TIMING_HISTORY_INTERPOLATION_UPPER_DISTANCE];
+  if (!Number.isFinite(lowerDistance) || !Number.isFinite(upperDistance)) return null;
+  if (targetDistance < lowerDistance || targetDistance > upperDistance) return null;
+
+  const lowerTime = history[TIMING_HISTORY_INTERPOLATION_LOWER_TIME];
+  const upperTime = history[TIMING_HISTORY_INTERPOLATION_UPPER_TIME];
+  const stats = history[TIMING_HISTORY_INTERPOLATION_STATS];
+  if (stats) {
+    stats.directSegmentCacheHits = (stats.directSegmentCacheHits ?? 0) + 1;
+  }
+  const coveredDistance = upperDistance - lowerDistance;
+  if (coveredDistance <= 1e-6) return upperTime;
+  const ratio = (targetDistance - lowerDistance) / coveredDistance;
+  return lowerTime + (upperTime - lowerTime) * ratio;
+}