@inventure71/paddockjs 4.1.0 → 4.3.0

package/src/simulation/track/spatialQueries.js

@@ -2,31 +2,63 @@ import { clamp, normalizeAngle, wrapDistance } from '../simMath.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 { queryNearestTrackProjectionInto } from './trackQueryIndex.js';
 import { recordStat } from './trackQueryStats.js';
 
 export function pointAt(track, distanceAlong) {
+  return pointAtInto(track, distanceAlong, {});
+}
+
+export function pointAtInto(track, distanceAlong, target) {
   const wrapped = wrapDistance(distanceAlong, track.length);
-  const low = sampleIndexAtDistance(track, wrapped);
+  const low = sampleIndexAtDistanceUnwrapped(track, wrapped);
 
   const next = track.samples[low] ?? track.samples[0];
   const previous = track.samples[Math.max(0, low - 1)] ?? next;
   const span = Math.max(1, next.distance - previous.distance);
   const amount = clamp((wrapped - previous.distance) / span, 0, 1);
 
-  return {
-    x: previous.x + (next.x - previous.x) * amount,
-    y: previous.y + (next.y - previous.y) * amount,
-    heading: previous.heading + normalizeAngle(next.heading - previous.heading) * amount,
-    normalX: previous.normalX + (next.normalX - previous.normalX) * amount,
-    normalY: previous.normalY + (next.normalY - previous.normalY) * amount,
-    curvature: previous.curvature + (next.curvature - previous.curvature) * amount,
-    distance: wrapped,
-  };
+  target.x = previous.x + (next.x - previous.x) * amount;
+  target.y = previous.y + (next.y - previous.y) * amount;
+  target.heading = previous.heading + normalizeAngle(next.heading - previous.heading) * amount;
+  target.normalX = previous.normalX + (next.normalX - previous.normalX) * amount;
+  target.normalY = previous.normalY + (next.normalY - previous.normalY) * amount;
+  target.curvature = previous.curvature + (next.curvature - previous.curvature) * amount;
+  target.distance = wrapped;
+  return target;
 }
 
-export function sampleIndexAtDistance(track, distanceAlong) {
+export function sampleHeadingCurvatureAtInto(track, distanceAlong, target) {
   const wrapped = wrapDistance(distanceAlong, track.length);
+  const low = sampleIndexAtDistanceUnwrapped(track, wrapped);
+
+  const next = track.samples[low] ?? track.samples[0];
+  const previous = track.samples[Math.max(0, low - 1)] ?? next;
+  const span = Math.max(1, next.distance - previous.distance);
+  const amount = clamp((wrapped - previous.distance) / span, 0, 1);
+
+  target.heading = previous.heading + normalizeAngle(next.heading - previous.heading) * amount;
+  target.curvature = previous.curvature + (next.curvature - previous.curvature) * amount;
+  return target;
+}
+
+export function sampleHeadingAt(track, distanceAlong) {
+  const wrapped = wrapDistance(distanceAlong, track.length);
+  const low = sampleIndexAtDistanceUnwrapped(track, wrapped);
+
+  const next = track.samples[low] ?? track.samples[0];
+  const previous = track.samples[Math.max(0, low - 1)] ?? next;
+  const span = Math.max(1, next.distance - previous.distance);
+  const amount = clamp((wrapped - previous.distance) / span, 0, 1);
+
+  return previous.heading + normalizeAngle(next.heading - previous.heading) * amount;
+}
+
+export function sampleIndexAtDistance(track, distanceAlong) {
+  return binarySampleIndexAtDistance(track, wrapDistance(distanceAlong, track.length));
+}
+
+function binarySampleIndexAtDistance(track, wrapped) {
   let low = 0;
   let high = track.samples.length - 1;
 
@@ -39,28 +71,41 @@ export function sampleIndexAtDistance(track, distanceAlong) {
   return low;
 }
 
-export function nearestSampleInRange(track, position, startIndex, endIndex) {
-  const sampleCount = track.samples.length - 1;
-  let best = null;
-  let bestDistance = Infinity;
-
-  for (let index = startIndex; index <= endIndex; index += 1) {
-    const wrappedIndex = ((index % sampleCount) + sampleCount) % sampleCount;
-    const sample = track.samples[wrappedIndex];
-    const dx = position.x - sample.x;
-    const dy = position.y - sample.y;
-    const squared = dx * dx + dy * dy;
-    if (squared < bestDistance) {
-      bestDistance = squared;
-      best = sample;
-    }
+// Uniform-bin index over sample distances: table[bin] holds the smallest
+// sample index whose distance reaches the bin start, so a lookup plus a short
+// forward walk returns exactly what the binary search would, in O(1). Built
+// eagerly when the track query index is attached; lookups on sample arrays
+// without a prepared table fall back to the binary search.
+const SAMPLE_INDEX_LUTS = new WeakMap();
+
+export function prepareSampleIndexLut(track) {
+  const samples = track?.samples;
+  if (!Array.isArray(samples) || samples.length < 2 || !Number.isFinite(track.length) || track.length <= 0) return;
+  if (SAMPLE_INDEX_LUTS.has(samples)) return;
+  const lastIndex = samples.length - 1;
+  const bins = Math.max(1, lastIndex * 2);
+  const table = new Int32Array(bins);
+  const binSize = track.length / bins;
+  let index = 0;
+  for (let bin = 0; bin < bins; bin += 1) {
+    const start = bin * binSize;
+    while (index < lastIndex && samples[index].distance < start) index += 1;
+    table[bin] = index;
   }
-
-  return { best, bestDistance };
+  SAMPLE_INDEX_LUTS.set(samples, { bins, binSize, table });
 }
 
-export function nearestSampleGlobal(track, position) {
-  return nearestSampleInRange(track, position, 0, track.samples.length - 2);
+function sampleIndexAtDistanceUnwrapped(track, wrapped) {
+  const samples = track.samples;
+  const lut = Number.isFinite(wrapped) ? SAMPLE_INDEX_LUTS.get(samples) : null;
+  if (!lut) return binarySampleIndexAtDistance(track, wrapped);
+  const lastIndex = samples.length - 1;
+  let bin = Math.floor(wrapped / lut.binSize);
+  if (bin < 0) bin = 0;
+  else if (bin >= lut.bins) bin = lut.bins - 1;
+  let index = lut.table[bin];
+  while (index < lastIndex && samples[index].distance < wrapped) index += 1;
+  return index;
 }
 
 export function createTrackState(track, position, best) {

package/src/simulation/track/trackBuilder.js

@@ -0,0 +1,54 @@
+import { CENTERLINE_CONTROLS, TRACK } from './trackConstants.js';
+import { distance } from './trackMath.js';
+import { rawCenterPoint } from './centerlineSpline.js';
+import { recalculateSampleGeometry } from './sampleGeometry.js';
+import { rotateSamplesToStandingStart, straightenStandingStartSamples } from './startStraight.js';
+import { prepareSampleIndexLut } from './spatialQueries.js';
+import { createTrackSectors } from './trackSectors.js';
+import { deriveDrsZones, normalizeDrsZone } from './drsZones.js';
+import { createPitLaneModel } from './pitLaneLayout.js';
+import { attachTrackQueryIndex, createTrackQueryIndex } from './trackQueryConstruction.js';
+import { attachTrackSnapshotJsonSerializer } from './trackSnapshotJson.js';
+import { cacheTrackModel, getCachedTrackModel } from './trackModelCache.js';
+
+export function buildTrackModel(track = TRACK) {
+  const cached = getCachedTrackModel(track);
+  if (cached) return cached;
+
+  const controls = track.centerlineControls ?? CENTERLINE_CONTROLS;
+  const base = [];
+  for (let index = 0; index <= track.sampleCount; index += 1) {
+    base.push(rawCenterPoint(index / track.sampleCount, controls, track.curveInterpolation));
+  }
+
+  let totalLength = 0;
+  const samples = base.map((point, index) => {
+    if (index > 0) totalLength += distance(base[index - 1], point);
+    return { ...point, distance: totalLength, heading: 0, normalX: 0, normalY: 0, curvature: 0 };
+  });
+  recalculateSampleGeometry(samples);
+
+  const startStraightOptions = track.generationOptions?.startStraight;
+  const rotatedSamples = rotateSamplesToStandingStart(samples, totalLength, startStraightOptions);
+  const straightenedTrack = straightenStandingStartSamples(rotatedSamples, totalLength, startStraightOptions);
+  const normalizedSamples = straightenedTrack.samples;
+  totalLength = straightenedTrack.totalLength;
+
+  const model = {
+    ...track,
+    centerlineControls: controls,
+    length: totalLength,
+    samples: normalizedSamples,
+    sectors: createTrackSectors(totalLength),
+    drsZones: (track.drsZones ?? deriveDrsZones(normalizedSamples, totalLength))
+      .map((zone) => normalizeDrsZone(zone, totalLength)),
+  };
+  model.pitLane = track.pitLane?.enabled === false || track.generationOptions?.pitLane?.enabled === false
+    ? null
+    : createPitLaneModel(model);
+  attachTrackQueryIndex(model, createTrackQueryIndex(model));
+  prepareSampleIndexLut(model);
+  attachTrackSnapshotJsonSerializer(model);
+  cacheTrackModel(track, model);
+  return model;
+}

package/src/simulation/track/trackConstants.js

@@ -34,7 +34,6 @@ export const START_STRAIGHT_GRID_LENGTH = metersToSimUnits(496);
 export const START_STRAIGHT_EXIT_LENGTH = metersToSimUnits(500);
 export const START_STRAIGHT_LOCK_EXTRA = metersToSimUnits(43);
 export const START_STRAIGHT_BLEND_LENGTH = metersToSimUnits(320);
-export const NEAREST_HINT_WINDOW_SAMPLES = 240;
 export const PIT_LANE_WIDTH = metersToSimUnits(12);
 export const PIT_LANE_EDGE_GAP = metersToSimUnits(16);
 export const PIT_ACCESS_MIN_LENGTH = metersToSimUnits(70);
@@ -66,27 +65,6 @@ export const PIT_LANE_FINISH_RATIO = 0.64;
 export const PIT_WORLD_PADDING = metersToSimUnits(24);
 export const PIT_TRACK_CLEARANCE_MARGIN = metersToSimUnits(5);
 export const PIT_LANE_OFFSET_SEARCH_STEP = metersToSimUnits(12);
-export const PROCEDURAL_TRACK_TEMPLATES = [
-  [
-    [0.08, 0.55], [0.10, 0.80], [0.22, 0.89], [0.42, 0.84], [0.52, 0.93],
-    [0.60, 0.75], [0.74, 0.88], [0.91, 0.76], [0.94, 0.54], [0.82, 0.46],
-    [0.94, 0.28], [0.78, 0.18], [0.62, 0.31], [0.54, 0.13], [0.43, 0.30],
-    [0.33, 0.17], [0.20, 0.24], [0.12, 0.38], [0.22, 0.48], [0.13, 0.50],
-  ],
-  [
-    [0.07, 0.46], [0.14, 0.72], [0.25, 0.83], [0.39, 0.73], [0.47, 0.88],
-    [0.56, 0.70], [0.67, 0.82], [0.88, 0.84], [0.95, 0.63], [0.83, 0.56],
-    [0.92, 0.43], [0.79, 0.35], [0.88, 0.20], [0.68, 0.15], [0.58, 0.29],
-    [0.47, 0.18], [0.34, 0.30], [0.21, 0.19], [0.10, 0.28], [0.17, 0.39],
-  ],
-  [
-    [0.06, 0.61], [0.13, 0.86], [0.31, 0.91], [0.43, 0.79], [0.57, 0.87],
-    [0.71, 0.70], [0.92, 0.72], [0.95, 0.50], [0.84, 0.43], [0.91, 0.32],
-    [0.74, 0.24], [0.69, 0.11], [0.54, 0.18], [0.45, 0.08], [0.35, 0.22],
-    [0.23, 0.17], [0.11, 0.31], [0.24, 0.43], [0.15, 0.52], [0.28, 0.60],
-  ],
-];
-
 export const CENTERLINE_CONTROLS = [
   { x: WORLD.width * 0.05, y: WORLD.height * 0.56 },
   { x: WORLD.width * 0.10, y: WORLD.height * 0.81 },

package/src/simulation/track/trackMath.js

@@ -161,35 +161,6 @@ export function pointInsideBounds(point, bounds) {
   );
 }
 
-export function projectPointToSegment(position, start, end) {
-  const dx = end.x - start.x;
-  const dy = end.y - start.y;
-  const lengthSquared = dx * dx + dy * dy;
-  const amount = lengthSquared > 0
-    ? clamp(((position.x - start.x) * dx + (position.y - start.y) * dy) / lengthSquared, 0, 1)
-    : 0;
-  const projected = {
-    x: start.x + dx * amount,
-    y: start.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 - projected.x) * normalX + (position.y - projected.y) * normalY;
-
-  return {
-    point: projected,
-    amount,
-    length,
-    heading,
-    normalX,
-    normalY,
-    signedOffset,
-    crossTrackError: Math.abs(signedOffset),
-  };
-}
-
 export function nearestPointOnPolyline(points, position, segmentIndices = null) {
   return nearestPointOnPolylineInto({}, points, position, { segmentIndices });
 }
@@ -306,3 +277,7 @@ export function pointIsInsidePolygon(point, polygon) {
 
   return inside;
 }
+
+export function finitePoint(point) {
+  return Number.isFinite(point?.x) && Number.isFinite(point?.y);
+}

package/src/simulation/track/trackModel.js

@@ -1,242 +1,14 @@
-import { normalizeAngle } from '../simMath.js';
-import { CENTERLINE_CONTROLS, TRACK } from './trackConstants.js';
-import { distance } from './trackMath.js';
-import { rawCenterPoint } from './centerlineSpline.js';
-import { generateCenterlineControls, generateFallbackCenterlineControls, generateSafeFallbackCenterlineControls, normalizeSeed } from './proceduralCenterline.js';
-import { isValidProceduralTrackModel } from './trackValidation.js';
-import { recalculateSampleGeometry } from './sampleGeometry.js';
-import { rotateSamplesToStandingStart, straightenStandingStartSamples } from './startStraight.js';
-import { createTrackSectors } from './trackSectors.js';
-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 { normalizeAngle } from '../simMath.js';
 export { isInDrsZone } from './drsZones.js';
-export { nearestTrackState, offsetTrackPoint, pointAt } from './spatialQueries.js';
-
-const PROCEDURAL_TRACK_CACHE = new Map();
-const TRACK_MODEL_CACHE = new WeakMap();
-
-export function buildTrackModel(track = TRACK) {
-  const canReuseCachedModel = track === TRACK || Object.isFrozen(track);
-  const cached = canReuseCachedModel ? TRACK_MODEL_CACHE.get(track) : null;
-  if (cached) return cached;
-
-  const controls = track.centerlineControls ?? CENTERLINE_CONTROLS;
-  const base = [];
-  for (let index = 0; index <= track.sampleCount; index += 1) {
-    base.push(rawCenterPoint(index / track.sampleCount, controls, track.curveInterpolation));
-  }
-
-  let totalLength = 0;
-  const samples = base.map((point, index) => {
-    if (index > 0) totalLength += distance(base[index - 1], point);
-    return { ...point, distance: totalLength, heading: 0, normalX: 0, normalY: 0, curvature: 0 };
-  });
-  recalculateSampleGeometry(samples);
-
-  const startStraightOptions = track.generationOptions?.startStraight;
-  const rotatedSamples = rotateSamplesToStandingStart(samples, totalLength, startStraightOptions);
-  const straightenedTrack = straightenStandingStartSamples(rotatedSamples, totalLength, startStraightOptions);
-  const normalizedSamples = straightenedTrack.samples;
-  totalLength = straightenedTrack.totalLength;
-
-  const model = {
-    ...track,
-    centerlineControls: controls,
-    length: totalLength,
-    samples: normalizedSamples,
-    sectors: createTrackSectors(totalLength),
-    drsZones: (track.drsZones ?? deriveDrsZones(normalizedSamples, totalLength))
-      .map((zone) => normalizeDrsZone(zone, totalLength)),
-  };
-  model.pitLane = track.pitLane?.enabled === false || track.generationOptions?.pitLane?.enabled === false
-    ? null
-    : createPitLaneModel(model);
-  attachTrackQueryIndex(model, createTrackQueryIndex(model));
-  attachTrackSnapshotJsonSerializer(model);
-  if (canReuseCachedModel) {
-    TRACK_MODEL_CACHE.set(track, freezeTrackModel(model));
-  }
-  return model;
-}
-
-export function createProceduralTrack(seed = Date.now(), options = {}) {
-  const normalizedSeed = normalizeSeed(seed);
-  const generationOptions = resolveProceduralTrackOptions(options);
-  const cacheKey = `${normalizedSeed}:${generationOptions.cacheKey}`;
-  const cached = PROCEDURAL_TRACK_CACHE.get(cacheKey);
-  if (cached) return cached;
-
-  for (let attempt = 0; attempt < generationOptions.attempts.primary; attempt += 1) {
-    const candidateSeed = (normalizedSeed + Math.imul(attempt, 2654435761)) >>> 0;
-    const candidate = {
-      ...TRACK,
-      name: `Generated GP ${candidateSeed.toString(36).toUpperCase().padStart(6, '0').slice(-6)}`,
-      seed: candidateSeed,
-      curveInterpolation: 'centripetal',
-      centerlineControls: generateCenterlineControls(candidateSeed, generationOptions.shape),
-      drsZones: null,
-      generationOptions,
-      ...(generationOptions.pitLane.enabled === false ? { pitLane: { enabled: false } } : {}),
-    };
-    const model = buildTrackModel(candidate);
-    if (isValidProceduralTrackModel(model, generationOptions)) {
-      const trackDefinition = {
-        ...candidate,
-        drsZones: model.drsZones.map(({ id, startRatio, endRatio }) => ({ id, startRatio, endRatio })),
-      };
-      return cacheProceduralTrackDefinition(cacheKey, trackDefinition);
-    }
-  }
-
-  let fallback = null;
-  let fallbackModel = null;
-  for (let attempt = 0; attempt < generationOptions.attempts.fallback; attempt += 1) {
-    const candidateSeed = (normalizedSeed ^ Math.imul(attempt + 1, 2246822519)) >>> 0;
-    const candidate = {
-      ...TRACK,
-      name: `Generated GP ${normalizedSeed.toString(36).toUpperCase().padStart(6, '0').slice(-6)}`,
-      seed: candidateSeed,
-      curveInterpolation: 'centripetal',
-      centerlineControls: generateFallbackCenterlineControls(candidateSeed, generationOptions.shape),
-      drsZones: null,
-      generationOptions,
-      ...(generationOptions.pitLane.enabled === false ? { pitLane: { enabled: false } } : {}),
-    };
-    const model = buildTrackModel(candidate);
-    if (isValidProceduralTrackModel(model, generationOptions)) {
-      fallback = candidate;
-      fallbackModel = model;
-      break;
-    }
-  }
-
-  if (!fallback || !fallbackModel) {
-    fallback = {
-      ...TRACK,
-      name: `Generated GP ${normalizedSeed.toString(36).toUpperCase().padStart(6, '0').slice(-6)}`,
-      seed: normalizedSeed,
-      curveInterpolation: 'centripetal',
-      centerlineControls: generateSafeFallbackCenterlineControls(normalizedSeed, generationOptions.shape),
-      drsZones: null,
-      generationOptions,
-      ...(generationOptions.pitLane.enabled === false ? { pitLane: { enabled: false } } : {}),
-    };
-    fallbackModel = buildTrackModel(fallback);
-  }
-  const fallbackDefinition = {
-    ...fallback,
-    drsZones: fallbackModel.drsZones.map(({ id, startRatio, endRatio }) => ({ id, startRatio, endRatio })),
-  };
-  return cacheProceduralTrackDefinition(cacheKey, fallbackDefinition);
-}
-
-export { normalizeAngle };
-
-function cacheProceduralTrackDefinition(cacheKey, trackDefinition) {
-  const frozen = deepFreeze(trackDefinition);
-  PROCEDURAL_TRACK_CACHE.set(cacheKey, frozen);
-  return frozen;
-}
-
-function freezeTrackModel(model) {
-  freezeArrayItems(model.samples);
-  freezeArrayItems(model.centerlineControls);
-  freezeArrayItems(model.sectors);
-  freezeArrayItems(model.drsZones);
-  deepFreeze(model.pitLane);
-  freezeTrackQueryIndex(model.queryIndex);
-  return Object.freeze(model);
-}
-
-function freezeArrayItems(items) {
-  if (!Array.isArray(items)) return;
-  items.forEach((item) => deepFreeze(item));
-  Object.freeze(items);
-}
-
-function deepFreeze(value) {
-  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
-  Object.freeze(value);
-  Object.values(value).forEach((child) => {
-    deepFreeze(child);
-  });
-  return value;
-}
-
-function freezeTrackQueryIndex(index) {
-  if (!index || typeof index !== 'object') return index;
-  deepFreeze(index.bands);
-  freezeCenterlineSegments(index.centerline);
-  freezeSpatialGrid(index.grid);
-  freezeSpatialGrid(index.segmentGrid);
-  freezeArcBuckets(index.arcBuckets);
-  freezePitQueryIndex(index.pit);
-  return Object.freeze(index);
-}
-
-function freezeCenterlineSegments(centerline) {
-  if (!centerline || typeof centerline !== 'object') return centerline;
-  Object.entries(centerline).forEach(([key, value]) => {
-    if (ArrayBuffer.isView(value)) {
-      centerline[key] = Object.freeze(Array.from(value));
-    }
-  });
-  return Object.freeze(centerline);
-}
-
-function freezeSpatialGrid(grid) {
-  if (!grid || typeof grid !== 'object') return grid;
-  deepFreeze(grid.bounds);
-  if (grid.cells instanceof Map) {
-    for (const cell of grid.cells.values()) Object.freeze(cell);
-    grid.cells = readonlyMap(grid.cells);
-  }
-  return Object.freeze(grid);
-}
-
-function freezeArcBuckets(arcBuckets) {
-  if (!arcBuckets || typeof arcBuckets !== 'object') return arcBuckets;
-  if (Array.isArray(arcBuckets.buckets)) {
-    arcBuckets.buckets.forEach((bucket) => Object.freeze(bucket));
-    Object.freeze(arcBuckets.buckets);
-  }
-  return Object.freeze(arcBuckets);
-}
-
-function freezePitQueryIndex(pit) {
-  if (!pit || typeof pit !== 'object') return pit;
-  freezeSpatialGrid(pit.roadGrid);
-  freezeSpatialGrid(pit.boxGrid);
-  deepFreeze(pit.routes);
-  freezeArrayItems(pit.roadSegments);
-  freezeArrayItems(pit.boxCandidates);
-  return Object.freeze(pit);
-}
-
-function readonlyMap(map) {
-  return new Proxy(map, {
-    get(target, property) {
-      if (property === 'set' || property === 'delete' || property === 'clear') {
-        return () => {
-          throw new TypeError('Cannot mutate a cached track query index');
-        };
-      }
-      const value = Reflect.get(target, property, target);
-      return typeof value === 'function' ? value.bind(target) : value;
-    },
-    set() {
-      throw new TypeError('Cannot mutate a cached track query index');
-    },
-    deleteProperty() {
-      throw new TypeError('Cannot mutate a cached track query index');
-    },
-    defineProperty() {
-      throw new TypeError('Cannot mutate a cached track query index');
-    },
-  });
-}
+export { buildTrackModel } from './trackBuilder.js';
+export { createProceduralTrack } from './proceduralTrack.js';
+export { PROCEDURAL_TRACK_CACHE_MAX_ENTRIES } from './trackModelCache.js';
+export {
+  nearestTrackState,
+  offsetTrackPoint,
+  pointAt,
+  pointAtInto,
+  sampleHeadingAt,
+  sampleHeadingCurvatureAtInto,
+} from './spatialQueries.js';

package/src/simulation/track/trackModelCache.js

@@ -0,0 +1,105 @@
+import { TRACK } from './trackConstants.js';
+
+const PROCEDURAL_TRACK_CACHE = new Map();
+const TRACK_MODEL_CACHE = new WeakMap();
+export const PROCEDURAL_TRACK_CACHE_MAX_ENTRIES = 8;
+
+export function getCachedTrackModel(track) {
+  return track === TRACK || Object.isFrozen(track) ? TRACK_MODEL_CACHE.get(track) : null;
+}
+
+export function cacheTrackModel(track, model) {
+  if (track === TRACK || Object.isFrozen(track)) TRACK_MODEL_CACHE.set(track, freezeTrackModel(model));
+}
+
+export function getCachedProceduralTrack(cacheKey) {
+  const cached = PROCEDURAL_TRACK_CACHE.get(cacheKey);
+  if (!cached) return null;
+  PROCEDURAL_TRACK_CACHE.delete(cacheKey);
+  PROCEDURAL_TRACK_CACHE.set(cacheKey, cached);
+  return cached;
+}
+
+export function cacheProceduralTrackDefinition(cacheKey, trackDefinition, model) {
+  const frozen = deepFreeze(trackDefinition);
+  if (model) TRACK_MODEL_CACHE.set(frozen, freezeTrackModel(model));
+  while (PROCEDURAL_TRACK_CACHE.size >= PROCEDURAL_TRACK_CACHE_MAX_ENTRIES) {
+    const oldestKey = PROCEDURAL_TRACK_CACHE.keys().next().value;
+    if (oldestKey == null) break;
+    PROCEDURAL_TRACK_CACHE.delete(oldestKey);
+  }
+  PROCEDURAL_TRACK_CACHE.set(cacheKey, frozen);
+  return frozen;
+}
+
+function freezeTrackModel(model) {
+  freezeArrayItems(model.samples);
+  freezeArrayItems(model.centerlineControls);
+  freezeArrayItems(model.sectors);
+  freezeArrayItems(model.drsZones);
+  deepFreeze(model.pitLane);
+  freezeTrackQueryIndex(model.queryIndex);
+  return Object.freeze(model);
+}
+
+function freezeArrayItems(items) {
+  if (!Array.isArray(items)) return;
+  items.forEach((item) => deepFreeze(item));
+  Object.freeze(items);
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  Object.values(value).forEach((child) => {
+    deepFreeze(child);
+  });
+  return value;
+}
+
+function freezeTrackQueryIndex(index) {
+  if (!index || typeof index !== 'object') return index;
+  deepFreeze(index.bands);
+  freezeCenterlineSegments(index.centerline);
+  freezeSpatialGrid(index.grid);
+  freezeSpatialGrid(index.segmentGrid);
+  freezeArcBuckets(index.arcBuckets);
+  freezePitQueryIndex(index.pit);
+  return Object.freeze(index);
+}
+
+function freezeCenterlineSegments(centerline) {
+  if (!centerline || typeof centerline !== 'object') return centerline;
+  Object.entries(centerline).forEach(([key, value]) => {
+    if (ArrayBuffer.isView(value)) {
+      centerline[key] = Object.freeze(Array.from(value));
+    }
+  });
+  return Object.freeze(centerline);
+}
+
+function freezeSpatialGrid(grid) {
+  if (!grid || typeof grid !== 'object') return grid;
+  deepFreeze(grid.bounds);
+  freezeArrayItems(grid.cells);
+  return Object.freeze(grid);
+}
+
+function freezeArcBuckets(arcBuckets) {
+  if (!arcBuckets || typeof arcBuckets !== 'object') return arcBuckets;
+  if (Array.isArray(arcBuckets.buckets)) {
+    arcBuckets.buckets.forEach((bucket) => Object.freeze(bucket));
+    Object.freeze(arcBuckets.buckets);
+  }
+  return Object.freeze(arcBuckets);
+}
+
+function freezePitQueryIndex(pit) {
+  if (!pit || typeof pit !== 'object') return pit;
+  freezeSpatialGrid(pit.roadGrid);
+  freezeSpatialGrid(pit.boxGrid);
+  deepFreeze(pit.routes);
+  freezeArrayItems(pit.roadSegments);
+  freezeArrayItems(pit.boxCandidates);
+  return Object.freeze(pit);
+}