@inventure71/paddockjs 4.1.0 → 4.3.0

package/src/simulation/timing/lapTelemetry.js

@@ -25,7 +25,7 @@ function writeLapTelemetryPosition(target, track, raceDistance, totalLaps = Infi
   const sectorIndex = Math.min(TELEMETRY_SECTOR_COUNT - 1, Math.floor(lapProgress / sectorLength));
   const sectorStart = sectorIndex * sectorLength;
 
-  target.completedLaps = Math.floor(positiveDistance / track.length);
+  target.completedLaps = Math.min(Math.floor(positiveDistance / track.length), totalLaps);
   target.currentLap = Math.max(1, lapIndex + 1);
   target.currentSector = sectorIndex + 1;
   target.currentSectorProgress = clamp((lapProgress - sectorStart) / sectorLength, 0, 1);
@@ -143,7 +143,10 @@ export function updateLapTelemetry(car, previousRaceDistance, currentTime, track
         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));
+        telemetry.completedLaps = Math.min(
+          totalLaps,
+          Math.max(telemetry.completedLaps + 1, Math.floor(boundaryDistance / track.length)),
+        );
       }
 
       telemetry.currentSectorStartedAt = crossingTime;
@@ -207,7 +210,7 @@ function syncInProgressLapTelemetry(telemetry, currentTime, currentRaceDistance,
   const sectorProgress = ensureSectorTimesArray(telemetry.sectorProgress);
   const liveSectors = ensureSectorTimesArray(telemetry.liveSectors);
 
-  telemetry.completedLaps = Math.floor(positiveDistance / track.length);
+  telemetry.completedLaps = Math.min(Math.floor(positiveDistance / track.length), totalLaps);
   telemetry.currentLap = Math.max(1, lapIndex + 1);
   telemetry.currentSector = activeIndex + 1;
   telemetry.currentSectorProgress = clamp((lapProgress - sectorStart) / sectorLength, 0, 1);
@@ -234,7 +237,7 @@ function syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, t
     preserveCompletedSectors,
   });
   telemetry.sectorProgress = sectorProgress;
-  telemetry.completedLaps = Math.max(telemetry.completedLaps, Math.min(telemetry.completedLaps, totalLaps));
+  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 });

package/src/simulation/timing/sectorPerformance.js

@@ -1,3 +1,6 @@
+import { finiteOrNull } from '../simMath.js';
+export { finiteOrNull } from '../simMath.js';
+
 import { TELEMETRY_SECTOR_COUNT } from './timingConstants.js';
 
 const OVERALL_BEST_0 = '_sectorPerformanceOverallBest0';
@@ -5,7 +8,7 @@ const OVERALL_BEST_1 = '_sectorPerformanceOverallBest1';
 const OVERALL_BEST_2 = '_sectorPerformanceOverallBest2';
 
 export function createEmptySectorTimes() {
-  return Array.from({ length: TELEMETRY_SECTOR_COUNT }, () => null);
+  return new Array(TELEMETRY_SECTOR_COUNT).fill(null);
 }
 
 export function createEmptySectorPerformance() {
@@ -17,11 +20,19 @@ export function createEmptySectorPerformance() {
 }
 
 export function serializeSectorTimes(values) {
-  return createEmptySectorTimes().map((_, index) => finiteOrNull(values?.[index]));
+  const result = new Array(TELEMETRY_SECTOR_COUNT);
+  for (let index = 0; index < TELEMETRY_SECTOR_COUNT; index += 1) {
+    result[index] = finiteOrNull(values?.[index]);
+  }
+  return result;
 }
 
 export function serializeSectorPerformance(values) {
-  return createEmptySectorTimes().map((_, index) => values?.[index] ?? null);
+  const result = new Array(TELEMETRY_SECTOR_COUNT);
+  for (let index = 0; index < TELEMETRY_SECTOR_COUNT; index += 1) {
+    result[index] = values?.[index] ?? null;
+  }
+  return result;
 }
 
 export function updateSectorPerformance(cars, stats = null) {
@@ -100,9 +111,6 @@ export function updateSectorPerformance(cars, stats = null) {
   return true;
 }
 
-export function finiteOrNull(value) {
-  return Number.isFinite(value) ? value : null;
-}
 
 function classifySectorPerformance(value, personalBest, overallBest) {
   if (!Number.isFinite(value)) return null;

package/src/simulation/timing/timingLines.js

@@ -76,7 +76,13 @@ export function createTimingLines(track) {
 export function getTimingLineNumber(track, raceDistance) {
   const spacing = track.timingLines?.spacing;
   if (!Number.isFinite(spacing) || spacing <= 0 || !Number.isFinite(raceDistance)) return null;
-  return Math.floor(Math.max(0, raceDistance) / spacing);
+  const distance = Math.max(0, raceDistance);
+  let lineNumber = Math.floor(distance / spacing);
+  // Division can round onto a line whose stored product is still ahead of
+  // the car. Use the same representable boundary for lookup and recording.
+  if (lineNumber > 0 && lineNumber * spacing > distance) lineNumber -= 1;
+  else if ((lineNumber + 1) * spacing <= distance) lineNumber += 1;
+  return lineNumber;
 }
 
 export function resetTimingLineCrossings(car, currentTime) {
@@ -105,7 +111,7 @@ export function recordTimingLineCrossings(car, previousRaceDistance, currentTime
     ? latestLine - (track.timingLines.count * TIMING_LINE_HISTORY_LAPS)
     : null;
 
-  if (Math.abs(travelled) <= 1e-6) {
+  if (travelled === 0) {
     car.timingLineLastUpdatedAt = currentTime;
     if (!Number.isFinite(cutoff) || cutoff <= 0 || cutoff === car.timingLinePruneCutoff) return;
     pruneTimingLineCrossings(car, cutoff);
@@ -113,12 +119,12 @@ export function recordTimingLineCrossings(car, previousRaceDistance, currentTime
     return;
   }
 
-  if (travelled > 1e-6 && travelled < track.length / 2) {
-    const firstLine = Math.floor(Math.max(0, previousDistance) / spacing) + 1;
-    const lastLine = Math.floor(Math.max(0, currentDistance) / spacing);
+  if (travelled > 0 && travelled < track.length / 2) {
+    const firstLine = getTimingLineNumber(track, previousDistance) + 1;
+    const lastLine = getTimingLineNumber(track, currentDistance);
     for (let lineNumber = firstLine; lineNumber <= lastLine; lineNumber += 1) {
       const lineDistance = lineNumber * spacing;
-      if (lineDistance <= previousDistance + 1e-6 || lineDistance > currentDistance + 1e-6) continue;
+      if (lineDistance <= previousDistance || lineDistance > currentDistance) continue;
       const ratio = clamp((lineDistance - previousDistance) / travelled, 0, 1);
       setTimingLineCrossing(car, lineNumber, previousTime + ratio * elapsed);
     }

package/src/simulation/track/pitLaneAccess.js

@@ -1,5 +1,5 @@
-import { clamp, wrapDistance } from '../simMath.js';
-import { PIT_ACCESS_MAX_LENGTH, PIT_ACCESS_SAMPLE_STEPS, PIT_ACCESS_SEARCH_STEP, PIT_ACCESS_TRACK_OVERLAP, PIT_LANE_WIDTH } from './trackConstants.js';
+import { wrapDistance } from '../simMath.js';
+import { PIT_ACCESS_SAMPLE_STEPS, PIT_ACCESS_SEARCH_STEP, PIT_ACCESS_TRACK_OVERLAP } from './trackConstants.js';
 import { angleBetweenVectors, headingVector, normalizeVector, sampleCubicBezier, signedLateralOffsetToPoint } from './trackMath.js';
 import { offsetTrackPoint, pointAt } from './spatialQueries.js';
 

package/src/simulation/track/pitLaneLayout.js

@@ -1,9 +1,12 @@
 import { clamp } from '../simMath.js';
 import { metersToSimUnits } from '../units.js';
-import { WORLD, PIT_BOX_COUNT, PIT_BOX_DEPTH, PIT_BOX_LENGTH, PIT_BOX_PAIR_GAP, PIT_BOX_TO_LANE_GAP, PIT_ENTRY_SEARCH_AFTER, PIT_ENTRY_SEARCH_BEFORE, PIT_EXIT_SEARCH_AFTER, PIT_EXIT_SEARCH_BEFORE, PIT_LANE_EDGE_GAP, PIT_LANE_ENTRY_BUFFER, PIT_LANE_EXIT_BUFFER, PIT_LANE_FINISH_RATIO, PIT_LANE_OFFSET_SEARCH_STEP, PIT_LANE_WIDTH, PIT_SERVICE_AREA_DEPTH, PIT_SERVICE_AREA_LENGTH, PIT_SERVICE_QUEUE_GAP, PIT_TEAM_COUNT, PIT_TEAM_GAP, PIT_BOXES_PER_TEAM, PIT_WORKING_LANE_GAP, PIT_WORKING_LANE_WIDTH, PIT_ACCESS_MAX_LENGTH, PIT_ACCESS_MIN_LENGTH, PIT_ACCESS_TANGENT_RATIO, PIT_TRACK_CLEARANCE_MARGIN } from './trackConstants.js';
+import { WORLD, PIT_BOX_COUNT, PIT_BOX_DEPTH, PIT_BOX_TO_LANE_GAP, PIT_ENTRY_SEARCH_AFTER, PIT_ENTRY_SEARCH_BEFORE, PIT_EXIT_SEARCH_AFTER, PIT_EXIT_SEARCH_BEFORE, PIT_LANE_EDGE_GAP, PIT_LANE_ENTRY_BUFFER, PIT_LANE_EXIT_BUFFER, PIT_LANE_FINISH_RATIO, PIT_LANE_OFFSET_SEARCH_STEP, PIT_LANE_WIDTH, PIT_SERVICE_AREA_DEPTH, PIT_TEAM_COUNT, PIT_BOXES_PER_TEAM, PIT_WORKING_LANE_GAP, PIT_WORKING_LANE_WIDTH, PIT_ACCESS_MAX_LENGTH, PIT_ACCESS_MIN_LENGTH, PIT_ACCESS_TANGENT_RATIO, PIT_TRACK_CLEARANCE_MARGIN } from './trackConstants.js';
 import { clonePoint, distance, headingVector, interpolatePitPoint, nearestPointOnPolyline, normalizeVector, pointWorldClearance, projectPitPoint, createPointBounds } from './trackMath.js';
 import { findPitAccessConnection, createPitAccessRoadCenterline } from './pitLaneAccess.js';
 import { pointAt } from './spatialQueries.js';
+import { createPitBoxes, getPitBoxRunLength } from './pitServiceLayout.js';
+
+export { getPitBoxRunLength, createPitBoxCorners, createPitRectangleCorners, createPitBoxes } from './pitServiceLayout.js';
 
 export function createStartStraightBasis(track) {
   const finish = pointAt(track, 0);
@@ -20,20 +23,6 @@ export function createStartStraightBasis(track) {
   };
 }
 
-export function getPitBoxRunLength({
-  teamCount = PIT_TEAM_COUNT,
-  boxesPerTeam = PIT_BOXES_PER_TEAM,
-  boxLength = PIT_BOX_LENGTH,
-  pairGap = PIT_BOX_PAIR_GAP,
-  teamGap = PIT_TEAM_GAP,
-} = {}) {
-  const boxCount = teamCount * boxesPerTeam;
-  return (
-    boxCount * boxLength +
-    teamCount * Math.max(0, boxesPerTeam - 1) * pairGap +
-    Math.max(0, teamCount - 1) * teamGap
-  );
-}
 
 export function createPitLaneLayout() {
   const runLength = getPitBoxRunLength();
@@ -130,128 +119,8 @@ export function choosePitLanePlacement(track, baseLaneOffset, layout) {
   return candidates.sort((left, right) => right.score - left.score)[0];
 }
 
-export function createPitBoxCorners(center, forward, serviceNormal) {
-  const halfLength = PIT_BOX_LENGTH / 2;
-  const halfDepth = PIT_BOX_DEPTH / 2;
-  return [
-    {
-      x: center.x + forward.x * halfLength + serviceNormal.x * halfDepth,
-      y: center.y + forward.y * halfLength + serviceNormal.y * halfDepth,
-    },
-    {
-      x: center.x - forward.x * halfLength + serviceNormal.x * halfDepth,
-      y: center.y - forward.y * halfLength + serviceNormal.y * halfDepth,
-    },
-    {
-      x: center.x - forward.x * halfLength - serviceNormal.x * halfDepth,
-      y: center.y - forward.y * halfLength - serviceNormal.y * halfDepth,
-    },
-    {
-      x: center.x + forward.x * halfLength - serviceNormal.x * halfDepth,
-      y: center.y + forward.y * halfLength - serviceNormal.y * halfDepth,
-    },
-  ];
-}
 
-export function createPitRectangleCorners(center, forward, serviceNormal, length, depth) {
-  const halfLength = length / 2;
-  const halfDepth = depth / 2;
-  return [
-    {
-      x: center.x + forward.x * halfLength + serviceNormal.x * halfDepth,
-      y: center.y + forward.y * halfLength + serviceNormal.y * halfDepth,
-    },
-    {
-      x: center.x - forward.x * halfLength + serviceNormal.x * halfDepth,
-      y: center.y - forward.y * halfLength + serviceNormal.y * halfDepth,
-    },
-    {
-      x: center.x - forward.x * halfLength - serviceNormal.x * halfDepth,
-      y: center.y - forward.y * halfLength - serviceNormal.y * halfDepth,
-    },
-    {
-      x: center.x + forward.x * halfLength - serviceNormal.x * halfDepth,
-      y: center.y + forward.y * halfLength - serviceNormal.y * halfDepth,
-    },
-  ];
-}
-
-export function createPitBoxes({ laneStart, laneForward, laneLength, serviceNormal }) {
-  const runLength = getPitBoxRunLength();
-  let cursor = Math.max(PIT_SERVICE_QUEUE_GAP + PIT_BOX_LENGTH / 2, (laneLength - runLength) / 2);
-  const workingLaneOffset = PIT_LANE_WIDTH / 2 + PIT_WORKING_LANE_GAP + PIT_WORKING_LANE_WIDTH / 2;
-  const boxLateral = workingLaneOffset + PIT_WORKING_LANE_WIDTH / 2 + PIT_BOX_TO_LANE_GAP + PIT_BOX_DEPTH / 2;
-  const boxes = [];
-  const serviceAreas = [];
-
-  for (let index = 0; index < PIT_BOX_COUNT; index += 1) {
-    const distanceAlongLane = cursor + PIT_BOX_LENGTH / 2;
-    const laneTarget = interpolatePitPoint(laneStart, laneForward, distanceAlongLane);
-    const center = {
-      x: laneTarget.x + serviceNormal.x * boxLateral,
-      y: laneTarget.y + serviceNormal.y * boxLateral,
-    };
-    const teamIndex = Math.floor(index / PIT_BOXES_PER_TEAM);
-    const teamBoxIndex = index % PIT_BOXES_PER_TEAM;
 
-    boxes.push({
-      id: `team-${teamIndex + 1}-box-${teamBoxIndex + 1}`,
-      index,
-      teamIndex,
-      teamBoxIndex,
-      distanceAlongLane,
-      laneTarget,
-      center,
-      length: PIT_BOX_LENGTH,
-      depth: PIT_BOX_DEPTH,
-      corners: createPitBoxCorners(center, laneForward, serviceNormal),
-    });
-
-    if (teamBoxIndex === PIT_BOXES_PER_TEAM - 1) {
-      const firstTeamBox = boxes[index - (PIT_BOXES_PER_TEAM - 1)];
-      const serviceDistance = (firstTeamBox.distanceAlongLane + distanceAlongLane) / 2;
-      const queueDistance = Math.max(PIT_SERVICE_QUEUE_GAP / 2, serviceDistance - PIT_SERVICE_QUEUE_GAP);
-      const serviceCenter = projectPitPoint(
-        laneStart,
-        laneForward,
-        serviceNormal,
-        serviceDistance,
-        workingLaneOffset,
-      );
-      const queuePoint = projectPitPoint(
-        laneStart,
-        laneForward,
-        serviceNormal,
-        queueDistance,
-        workingLaneOffset,
-      );
-
-      serviceAreas.push({
-        id: `team-${teamIndex + 1}-service`,
-        index: teamIndex,
-        teamIndex,
-        distanceAlongLane: serviceDistance,
-        queueDistanceAlongLane: queueDistance,
-        laneTarget: serviceCenter,
-        center: serviceCenter,
-        queuePoint,
-        length: PIT_SERVICE_AREA_LENGTH,
-        depth: PIT_SERVICE_AREA_DEPTH,
-        corners: createPitRectangleCorners(serviceCenter, laneForward, serviceNormal, PIT_SERVICE_AREA_LENGTH, PIT_SERVICE_AREA_DEPTH),
-        queueCorners: createPitRectangleCorners(queuePoint, laneForward, serviceNormal, PIT_SERVICE_AREA_LENGTH * 0.72, PIT_SERVICE_AREA_DEPTH),
-        garageBoxIds: boxes
-          .slice(index - (PIT_BOXES_PER_TEAM - 1), index + 1)
-          .map((box) => box.id),
-      });
-    }
-
-    cursor += PIT_BOX_LENGTH;
-    if (teamBoxIndex === 0) cursor += PIT_BOX_PAIR_GAP;
-    else if (teamIndex < PIT_TEAM_COUNT - 1) cursor += PIT_TEAM_GAP;
-  }
-
-  return { boxes, serviceAreas, workingLaneOffset };
-}
 
 export function createPitLaneBounds(pitLane) {
   const points = [

package/src/simulation/track/pitLaneModel.js

@@ -0,0 +1,70 @@
+function clonePointLike(point) {
+  if (!point) return point;
+  return { ...point };
+}
+
+function clonePointArray(points) {
+  return Array.isArray(points) ? points.map(clonePointLike) : points;
+}
+
+export function clonePitLaneModel(pitLane) {
+  if (!pitLane) return pitLane;
+  return {
+    ...pitLane,
+    entry: pitLane.entry ? {
+      ...pitLane.entry,
+      trackPoint: clonePointLike(pitLane.entry.trackPoint),
+      edgePoint: clonePointLike(pitLane.entry.edgePoint),
+      trackConnectPoint: clonePointLike(pitLane.entry.trackConnectPoint),
+      lanePoint: clonePointLike(pitLane.entry.lanePoint),
+      roadCenterline: clonePointArray(pitLane.entry.roadCenterline),
+      connector: clonePointArray(pitLane.entry.connector),
+    } : pitLane.entry,
+    exit: pitLane.exit ? {
+      ...pitLane.exit,
+      trackPoint: clonePointLike(pitLane.exit.trackPoint),
+      edgePoint: clonePointLike(pitLane.exit.edgePoint),
+      trackConnectPoint: clonePointLike(pitLane.exit.trackConnectPoint),
+      lanePoint: clonePointLike(pitLane.exit.lanePoint),
+      roadCenterline: clonePointArray(pitLane.exit.roadCenterline),
+      connector: clonePointArray(pitLane.exit.connector),
+    } : pitLane.exit,
+    mainLane: pitLane.mainLane ? {
+      ...pitLane.mainLane,
+      start: clonePointLike(pitLane.mainLane.start),
+      end: clonePointLike(pitLane.mainLane.end),
+      points: clonePointArray(pitLane.mainLane.points),
+    } : pitLane.mainLane,
+    workingLane: pitLane.workingLane ? {
+      ...pitLane.workingLane,
+      start: clonePointLike(pitLane.workingLane.start),
+      end: clonePointLike(pitLane.workingLane.end),
+      points: clonePointArray(pitLane.workingLane.points),
+    } : pitLane.workingLane,
+    fastLane: pitLane.fastLane ? { ...pitLane.fastLane } : pitLane.fastLane,
+    serviceNormal: clonePointLike(pitLane.serviceNormal),
+    boxes: Array.isArray(pitLane.boxes)
+      ? pitLane.boxes.map((box) => ({
+        ...box,
+        laneTarget: clonePointLike(box.laneTarget),
+        center: clonePointLike(box.center),
+        corners: clonePointArray(box.corners),
+      }))
+      : pitLane.boxes,
+    serviceAreas: Array.isArray(pitLane.serviceAreas)
+      ? pitLane.serviceAreas.map((area) => ({
+        ...area,
+        laneTarget: clonePointLike(area.laneTarget),
+        center: clonePointLike(area.center),
+        queuePoint: clonePointLike(area.queuePoint),
+        corners: clonePointArray(area.corners),
+        queueCorners: clonePointArray(area.queueCorners),
+        garageBoxIds: [...(area.garageBoxIds ?? [])],
+        pitCrew: area.pitCrew ? { ...area.pitCrew } : area.pitCrew,
+      }))
+      : pitLane.serviceAreas,
+    teams: Array.isArray(pitLane.teams)
+      ? pitLane.teams.map((team) => ({ ...team, boxIds: [...(team.boxIds ?? [])], pitCrew: team.pitCrew ? { ...team.pitCrew } : team.pitCrew }))
+      : pitLane.teams,
+  };
+}

package/src/simulation/track/pitLaneState.js

@@ -1,5 +1,4 @@
 import { clamp, wrapDistance } from '../simMath.js';
-import { PIT_LANE_WIDTH } from './trackConstants.js';
 import { nearestPointOnPolyline, nearestPointOnPolylineInto, pointInsideBounds, pointIsInsidePolygon } from './trackMath.js';
 import { queryPitBoxCandidates, queryPitRoadSegmentCandidatesByRoute } from './trackQueryIndex.js';
 import { ensureQueryScratch } from './trackQueryScratch.js';

package/src/simulation/track/pitServiceLayout.js

@@ -0,0 +1,121 @@
+import { PIT_BOX_COUNT, PIT_BOX_DEPTH, PIT_BOX_LENGTH, PIT_BOX_PAIR_GAP, PIT_BOX_TO_LANE_GAP, PIT_LANE_WIDTH, PIT_SERVICE_AREA_DEPTH, PIT_SERVICE_AREA_LENGTH, PIT_SERVICE_QUEUE_GAP, PIT_TEAM_COUNT, PIT_TEAM_GAP, PIT_BOXES_PER_TEAM, PIT_WORKING_LANE_GAP, PIT_WORKING_LANE_WIDTH } from './trackConstants.js';
+import { interpolatePitPoint, projectPitPoint } from './trackMath.js';
+
+export function getPitBoxRunLength({
+  teamCount = PIT_TEAM_COUNT,
+  boxesPerTeam = PIT_BOXES_PER_TEAM,
+  boxLength = PIT_BOX_LENGTH,
+  pairGap = PIT_BOX_PAIR_GAP,
+  teamGap = PIT_TEAM_GAP,
+} = {}) {
+  const boxCount = teamCount * boxesPerTeam;
+  return (
+    boxCount * boxLength +
+    teamCount * Math.max(0, boxesPerTeam - 1) * pairGap +
+    Math.max(0, teamCount - 1) * teamGap
+  );
+}
+
+export function createPitBoxCorners(center, forward, serviceNormal) {
+  return createPitRectangleCorners(center, forward, serviceNormal, PIT_BOX_LENGTH, PIT_BOX_DEPTH);
+}
+
+export function createPitRectangleCorners(center, forward, serviceNormal, length, depth) {
+  const halfLength = length / 2;
+  const halfDepth = depth / 2;
+  return [
+    {
+      x: center.x + forward.x * halfLength + serviceNormal.x * halfDepth,
+      y: center.y + forward.y * halfLength + serviceNormal.y * halfDepth,
+    },
+    {
+      x: center.x - forward.x * halfLength + serviceNormal.x * halfDepth,
+      y: center.y - forward.y * halfLength + serviceNormal.y * halfDepth,
+    },
+    {
+      x: center.x - forward.x * halfLength - serviceNormal.x * halfDepth,
+      y: center.y - forward.y * halfLength - serviceNormal.y * halfDepth,
+    },
+    {
+      x: center.x + forward.x * halfLength - serviceNormal.x * halfDepth,
+      y: center.y + forward.y * halfLength - serviceNormal.y * halfDepth,
+    },
+  ];
+}
+
+export function createPitBoxes({ laneStart, laneForward, laneLength, serviceNormal }) {
+  const runLength = getPitBoxRunLength();
+  let cursor = Math.max(PIT_SERVICE_QUEUE_GAP + PIT_BOX_LENGTH / 2, (laneLength - runLength) / 2);
+  const workingLaneOffset = PIT_LANE_WIDTH / 2 + PIT_WORKING_LANE_GAP + PIT_WORKING_LANE_WIDTH / 2;
+  const boxLateral = workingLaneOffset + PIT_WORKING_LANE_WIDTH / 2 + PIT_BOX_TO_LANE_GAP + PIT_BOX_DEPTH / 2;
+  const boxes = [];
+  const serviceAreas = [];
+
+  for (let index = 0; index < PIT_BOX_COUNT; index += 1) {
+    const distanceAlongLane = cursor + PIT_BOX_LENGTH / 2;
+    const laneTarget = interpolatePitPoint(laneStart, laneForward, distanceAlongLane);
+    const center = {
+      x: laneTarget.x + serviceNormal.x * boxLateral,
+      y: laneTarget.y + serviceNormal.y * boxLateral,
+    };
+    const teamIndex = Math.floor(index / PIT_BOXES_PER_TEAM);
+    const teamBoxIndex = index % PIT_BOXES_PER_TEAM;
+
+    boxes.push({
+      id: `team-${teamIndex + 1}-box-${teamBoxIndex + 1}`,
+      index,
+      teamIndex,
+      teamBoxIndex,
+      distanceAlongLane,
+      laneTarget,
+      center,
+      length: PIT_BOX_LENGTH,
+      depth: PIT_BOX_DEPTH,
+      corners: createPitBoxCorners(center, laneForward, serviceNormal),
+    });
+
+    if (teamBoxIndex === PIT_BOXES_PER_TEAM - 1) {
+      const firstTeamBox = boxes[index - (PIT_BOXES_PER_TEAM - 1)];
+      const serviceDistance = (firstTeamBox.distanceAlongLane + distanceAlongLane) / 2;
+      const queueDistance = Math.max(PIT_SERVICE_QUEUE_GAP / 2, serviceDistance - PIT_SERVICE_QUEUE_GAP);
+      const serviceCenter = projectPitPoint(
+        laneStart,
+        laneForward,
+        serviceNormal,
+        serviceDistance,
+        workingLaneOffset,
+      );
+      const queuePoint = projectPitPoint(
+        laneStart,
+        laneForward,
+        serviceNormal,
+        queueDistance,
+        workingLaneOffset,
+      );
+
+      serviceAreas.push({
+        id: `team-${teamIndex + 1}-service`,
+        index: teamIndex,
+        teamIndex,
+        distanceAlongLane: serviceDistance,
+        queueDistanceAlongLane: queueDistance,
+        laneTarget: serviceCenter,
+        center: serviceCenter,
+        queuePoint,
+        length: PIT_SERVICE_AREA_LENGTH,
+        depth: PIT_SERVICE_AREA_DEPTH,
+        corners: createPitRectangleCorners(serviceCenter, laneForward, serviceNormal, PIT_SERVICE_AREA_LENGTH, PIT_SERVICE_AREA_DEPTH),
+        queueCorners: createPitRectangleCorners(queuePoint, laneForward, serviceNormal, PIT_SERVICE_AREA_LENGTH * 0.72, PIT_SERVICE_AREA_DEPTH),
+        garageBoxIds: boxes
+          .slice(index - (PIT_BOXES_PER_TEAM - 1), index + 1)
+          .map((box) => box.id),
+      });
+    }
+
+    cursor += PIT_BOX_LENGTH;
+    if (teamBoxIndex === 0) cursor += PIT_BOX_PAIR_GAP;
+    else if (teamIndex < PIT_TEAM_COUNT - 1) cursor += PIT_TEAM_GAP;
+  }
+
+  return { boxes, serviceAreas, workingLaneOffset };
+}

package/src/simulation/track/proceduralTrack.js

@@ -0,0 +1,77 @@
+import { TRACK } from './trackConstants.js';
+import { buildTrackModel } from './trackBuilder.js';
+import { generateCenterlineControls, generateFallbackCenterlineControls, generateSafeFallbackCenterlineControls, normalizeSeed } from './proceduralCenterline.js';
+import { isValidProceduralTrackModel } from './trackValidation.js';
+import { resolveProceduralTrackOptions } from './trackGenerationOptions.js';
+import { cacheProceduralTrackDefinition, getCachedProceduralTrack } from './trackModelCache.js';
+
+export function createProceduralTrack(seed = Date.now(), options = {}) {
+  const normalizedSeed = normalizeSeed(seed);
+  const generationOptions = resolveProceduralTrackOptions(options);
+  const cacheKey = `${normalizedSeed}:${generationOptions.cacheKey}`;
+  const cached = getCachedProceduralTrack(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, model);
+    }
+  }
+
+  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, fallbackModel);
+}