@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/simulation/rules/ruleDefaults.js

@@ -0,0 +1,85 @@
+import { kphToSimSpeed, metersToSimUnits } from '../units.js';
+
+export const DEFAULT_RULES = {
+  drsDetectionSeconds: 1,
+  safetyCarSpeed: kphToSimSpeed(166),
+  safetyCarLeadDistance: metersToSimUnits(55),
+  safetyCarGap: metersToSimUnits(22),
+  collisionRestitution: 0.18,
+  standingStart: true,
+  startLightCount: 5,
+  startLightInterval: 0.72,
+  startLightsOutHold: 0.78,
+};
+
+export const DEFAULT_MODULES = {
+  pitStops: {
+    enabled: false,
+    pitLaneSpeedLimitKph: 80,
+    defaultStopSeconds: 2.8,
+    variability: {
+      enabled: false,
+      perfect: false,
+      speedImpactSeconds: 1.2,
+      consistencyJitterSeconds: 1.4,
+      issueChance: 0.12,
+      issueMaxDelaySeconds: 4,
+    },
+    maxConcurrentPitLaneCars: 3,
+    minimumPitLaneGapMeters: 20,
+    doubleStacking: false,
+    tirePitRequestThresholdPercent: 50,
+    tirePitCommitThresholdPercent: 30,
+  },
+  tireStrategy: {
+    enabled: false,
+    compounds: ['S', 'M', 'H'],
+    mandatoryDistinctDryCompounds: null,
+  },
+  tireDegradation: {
+    enabled: true,
+  },
+  stalledDnf: {
+    enabled: false,
+    maxStoppedSeconds: 12,
+    speedThresholdKph: 5,
+  },
+  penalties: {
+    enabled: false,
+    stewardStrictness: 1,
+    trackLimits: {
+      strictness: 0,
+      warningsBeforePenalty: 3,
+      timePenaltySeconds: 5,
+      relaxedMarginMeters: 3,
+    },
+    collision: {
+      strictness: 0,
+      timePenaltySeconds: 5,
+      minimumSeverity: 2,
+      relaxedSeverityMargin: 6,
+      minimumImpactSpeedKph: 20,
+      relaxedImpactSpeedKph: 20,
+    },
+    tireRequirement: {
+      strictness: 0,
+      timePenaltySeconds: 10,
+    },
+    pitLaneSpeeding: {
+      strictness: 0,
+      speedLimitKph: 80,
+      marginKph: 0.5,
+      relaxedMarginKph: 5,
+      timePenaltySeconds: 5,
+    },
+  },
+  weather: {
+    enabled: false,
+  },
+  reliability: {
+    enabled: false,
+  },
+  fuelLoad: {
+    enabled: false,
+  },
+};

package/src/simulation/rules/rulesReview.js

@@ -0,0 +1,141 @@
+import { calculateCollisionPenalties } from './collisionSteward.js';
+import { calculateTireRequirementPenalty } from './tireRequirementSteward.js';
+import { calculateTrackLimitReview } from './trackLimitsSteward.js';
+import { calculatePitLaneSpeedingReview } from './pitLaneSpeedingSteward.js';
+import { getPenaltyRule } from '../rulesConfig.js';
+import { simSpeedToKph } from '../units.js';
+import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+
+function forwardVector(car) {
+  return { x: Math.cos(car.heading), y: Math.sin(car.heading) };
+}
+
+function velocityVector(car) {
+  const forward = forwardVector(car);
+  return { x: forward.x * car.speed, y: forward.y * car.speed };
+}
+
+function dot(a, b) {
+  return a.x * b.x + a.y * b.y;
+}
+
+function normalizeVector(vector) {
+  const length = Math.hypot(vector.x, vector.y) || 1;
+  return { x: vector.x / length, y: vector.y / length };
+}
+
+function progressDelta(a, b, trackLength) {
+  let delta = a - b;
+  if (delta < -trackLength / 2) delta += trackLength;
+  if (delta > trackLength / 2) delta -= trackLength;
+  return delta;
+}
+
+function createCollisionStewardContext(first, second, collision) {
+  const distanceDelta = collision.trackLength
+    ? progressDelta(second.progress ?? second.raceDistance ?? 0, first.progress ?? first.raceDistance ?? 0, collision.trackLength)
+    : (second.raceDistance ?? 0) - (first.raceDistance ?? 0);
+  const sideBySideTolerance = VEHICLE_LIMITS.carLength * 0.18;
+  if (Math.abs(distanceDelta) <= sideBySideTolerance) {
+    const firstVelocity = velocityVector(first);
+    const secondVelocity = velocityVector(second);
+    const relativeVelocity = {
+      x: firstVelocity.x - secondVelocity.x,
+      y: firstVelocity.y - secondVelocity.y,
+    };
+    return {
+      ...collision,
+      impactSpeed: Math.hypot(relativeVelocity.x, relativeVelocity.y),
+      aheadDriverId: null,
+      atFaultDriverId: null,
+      sharedFault: true,
+      sharedFaultDriverIds: [first.id, second.id],
+    };
+  }
+
+  const firstBehind = distanceDelta > 0;
+  const behind = firstBehind ? first : second;
+  const ahead = firstBehind ? second : first;
+  const directionBehindToAhead = normalizeVector({
+    x: ahead.x - behind.x,
+    y: ahead.y - behind.y,
+  });
+  const behindVelocity = velocityVector(behind);
+  const aheadVelocity = velocityVector(ahead);
+  const relativeVelocity = {
+    x: behindVelocity.x - aheadVelocity.x,
+    y: behindVelocity.y - aheadVelocity.y,
+  };
+
+  return {
+    ...collision,
+    impactSpeed: Math.max(0, dot(relativeVelocity, directionBehindToAhead)),
+    aheadDriverId: ahead.id,
+    atFaultDriverId: behind.id,
+  };
+}
+
+function isLegallyInsidePitLaneForTrackLimits(car) {
+  if (!car.trackState?.inPitLane) return false;
+  const wheels = car.wheelStates ?? [];
+  return wheels.length > 0 && wheels.some((wheel) => wheel.inPitLane);
+}
+
+export function reviewCollisionForSimulation(sim, first, second, collision) {
+  const rule = getPenaltyRule(sim.rules, 'collision');
+  calculateCollisionPenalties({
+    first,
+    second,
+    collision: createCollisionStewardContext(first, second, collision),
+    rule,
+  }).forEach((penalty) => sim.recordPenalty(penalty));
+}
+
+export function reviewTireRequirementForSimulation(sim, car) {
+  const penalty = calculateTireRequirementPenalty({
+    car,
+    tireStrategy: sim.rules.modules?.tireStrategy,
+    rule: getPenaltyRule(sim.rules, 'tireRequirement'),
+  });
+  if (penalty) sim.recordPenalty(penalty);
+}
+
+export function reviewTrackLimitsForSimulation(sim) {
+  const rule = getPenaltyRule(sim.rules, 'trackLimits');
+  sim.cars.forEach((car) => {
+    if (isLegallyInsidePitLaneForTrackLimits(car)) {
+      const current = sim.stewardState.trackLimits[car.id];
+      sim.stewardState.trackLimits[car.id] = { ...(current ?? { violations: 0 }), active: false };
+      return;
+    }
+
+    const currentState = sim.stewardState.trackLimits[car.id];
+    const review = calculateTrackLimitReview({
+      car,
+      rule,
+      track: sim.track,
+      stewardState: currentState,
+    });
+    sim.stewardState.trackLimits[car.id] = review.nextState;
+    if (review.event) sim.events.unshift({ ...review.event, at: sim.time });
+    if (review.penalty) sim.recordPenalty(review.penalty);
+  });
+}
+
+export function reviewPitLaneSpeedingForSimulation(sim) {
+  const rule = getPenaltyRule(sim.rules, 'pitLaneSpeeding');
+  sim.cars.forEach((car) => {
+    const currentState = sim.stewardState.pitLaneSpeeding[car.id];
+    const review = calculatePitLaneSpeedingReview({
+      car: {
+        ...car,
+        speedKph: simSpeedToKph(car.speed),
+      },
+      rule,
+      stewardState: currentState,
+    });
+    sim.stewardState.pitLaneSpeeding[car.id] = review.nextState;
+    if (review.event) sim.events.unshift({ ...review.event, at: sim.time });
+    if (review.penalty) sim.recordPenalty(review.penalty);
+  });
+}

package/src/simulation/rules/rulesetPresets.js

@@ -0,0 +1,47 @@
+import { DEFAULT_MODULES } from './ruleDefaults.js';
+
+export const RULESET_MODULES = {
+  paddock: DEFAULT_MODULES,
+  custom: DEFAULT_MODULES,
+  grandPrix2025: {
+    ...DEFAULT_MODULES,
+    pitStops: {
+      ...DEFAULT_MODULES.pitStops,
+      enabled: true,
+      pitLaneSpeedLimitKph: 80,
+    },
+    tireStrategy: {
+      ...DEFAULT_MODULES.tireStrategy,
+      enabled: true,
+      mandatoryDistinctDryCompounds: 2,
+    },
+    penalties: {
+      ...DEFAULT_MODULES.penalties,
+      enabled: true,
+      stewardStrictness: 0.85,
+      trackLimits: {
+        ...DEFAULT_MODULES.penalties.trackLimits,
+        strictness: 0.85,
+      },
+      collision: {
+        ...DEFAULT_MODULES.penalties.collision,
+        strictness: 0.65,
+      },
+      tireRequirement: {
+        ...DEFAULT_MODULES.penalties.tireRequirement,
+        strictness: 1,
+      },
+      pitLaneSpeeding: {
+        ...DEFAULT_MODULES.penalties.pitLaneSpeeding,
+        strictness: 1,
+        speedLimitKph: 80,
+      },
+    },
+    fuelLoad: {
+      enabled: false,
+      reserved: true,
+    },
+  },
+};
+
+RULESET_MODULES.fia2025 = RULESET_MODULES.grandPrix2025;

package/src/simulation/rules/tireRequirementSteward.js

@@ -0,0 +1,29 @@
+export function calculateTireRequirementPenalty({ car, tireStrategy, rule }) {
+  if (!rule || !tireStrategy?.enabled) return null;
+
+  const requiredDistinctCompounds = tireStrategy.mandatoryDistinctDryCompounds;
+  if (!Number.isFinite(requiredDistinctCompounds) || requiredDistinctCompounds <= 0) return null;
+
+  const usedCompounds = Array.isArray(car.usedTireCompounds) && car.usedTireCompounds.length
+    ? [...new Set(car.usedTireCompounds.filter(Boolean))]
+    : [...new Set([car.tire].filter(Boolean))];
+  const usedDistinctCompounds = usedCompounds.length;
+  const missingCompounds = Math.max(0, requiredDistinctCompounds - usedDistinctCompounds);
+  const toleratedMissingCompounds = Math.floor((1 - rule.strictness) * requiredDistinctCompounds);
+
+  if (missingCompounds <= toleratedMissingCompounds) return null;
+
+  return {
+    type: 'tire-requirement',
+    driverId: car.id,
+    strictness: rule.strictness,
+    penaltySeconds: rule.timePenaltySeconds,
+    consequences: rule.consequences,
+    requiredDistinctCompounds,
+    usedDistinctCompounds,
+    usedCompounds,
+    missingCompounds,
+    toleratedMissingCompounds,
+    reason: 'Mandatory dry compound requirement not met',
+  };
+}

package/src/simulation/rules/trackLimitsSteward.js

@@ -0,0 +1,85 @@
+import { calculateWheelSurfaceState, isWholeCarOutsideTrackLimits } from '../vehicle/wheelSurface.js';
+import { metersToSimUnits } from '../units.js';
+
+const STEWARD_TRACK_LIMIT_EPSILON = metersToSimUnits(0.2);
+
+export function calculateTrackLimitReview({ car, rule, track, stewardState }) {
+  if (!rule) {
+    return {
+      nextState: stewardState ?? { active: false, violations: 0 },
+      event: null,
+      penalty: null,
+    };
+  }
+
+  const current = stewardState ?? { active: false, violations: 0 };
+  const wheelSurfaceState = car.wheelStates?.length
+    ? {
+        wheels: car.wheelStates,
+        trackLimits: isWholeCarOutsideTrackLimits(car.wheelStates, track),
+      }
+    : calculateWheelSurfaceState({ car, track });
+  const wheelStates = wheelSurfaceState.wheels;
+  if (wheelStates.some((wheelState) => wheelState.inPitLane)) {
+    return {
+      nextState: { ...current, active: false },
+      event: null,
+      penalty: null,
+    };
+  }
+  const relaxedMargin = ((rule.relaxedMargin ?? 0) * (1 - rule.strictness)) + STEWARD_TRACK_LIMIT_EPSILON;
+  const trackLimitState = isWholeCarOutsideTrackLimits(wheelStates, track, relaxedMargin);
+  const outsideBy = trackLimitState.outsideBy;
+  const isViolation = trackLimitState.violating;
+
+  if (!isViolation) {
+    return {
+      nextState: { ...current, active: false },
+      event: null,
+      penalty: null,
+    };
+  }
+
+  if (current.active) {
+    return {
+      nextState: current,
+      event: null,
+      penalty: null,
+    };
+  }
+
+  const violationCount = current.violations + 1;
+  const nextState = {
+    active: true,
+    violations: violationCount,
+  };
+  const event = {
+    type: 'track-limits',
+    carId: car.id,
+    violationCount,
+    warningsBeforePenalty: rule.warningsBeforePenalty,
+    decision: violationCount <= rule.warningsBeforePenalty ? 'warning' : 'penalty',
+    strictness: rule.strictness,
+  };
+
+  if (violationCount <= rule.warningsBeforePenalty) {
+    return { nextState, event, penalty: null };
+  }
+
+  return {
+    nextState,
+    event,
+    penalty: {
+      type: 'track-limits',
+      driverId: car.id,
+      strictness: rule.strictness,
+      penaltySeconds: rule.timePenaltySeconds,
+      consequences: rule.consequences,
+      violationCount,
+      margin: relaxedMargin,
+      outsideBy,
+      wheelOffsets: wheelStates.map((wheelState) => wheelState.signedOffset),
+      reason: 'Exceeded track limits',
+    },
+  };
+}

package/src/simulation/rulesConfig.js

@@ -0,0 +1,34 @@
+import { DEFAULT_RULES } from './rules/ruleDefaults.js';
+import { normalizeModules } from './rules/moduleConfig.js';
+import { clamp01, mergeConfig } from './rules/ruleConfigMerge.js';
+import { RULESET_MODULES } from './rules/rulesetPresets.js';
+
+export { DEFAULT_RULES } from './rules/ruleDefaults.js';
+
+export function normalizeRaceRules(rules = {}) {
+  const requestedRuleset = rules?.ruleset ?? rules?.profile ?? 'paddock';
+  const ruleset = Object.hasOwn(RULESET_MODULES, requestedRuleset) ? requestedRuleset : 'custom';
+  const presetModules = RULESET_MODULES[ruleset] ?? RULESET_MODULES.custom;
+  const modules = normalizeModules(mergeConfig(presetModules, rules.modules), rules.modules);
+  const flatOverrides = Object.fromEntries(
+    Object.entries(rules ?? {}).filter(([key]) => key !== 'ruleset' && key !== 'profile' && key !== 'modules'),
+  );
+
+  return {
+    ...DEFAULT_RULES,
+    ...flatOverrides,
+    ruleset,
+    modules,
+  };
+}
+
+export function getPenaltyRule(rules, type) {
+  const penalties = rules?.modules?.penalties;
+  if (!penalties?.enabled) return null;
+  const config = penalties[type];
+  if (!config || config.strictness <= 0) return null;
+  return {
+    ...config,
+    strictness: clamp01(config.strictness * penalties.stewardStrictness, config.strictness),
+  };
+}

package/src/simulation/snapshots/raceSnapshots.js

@@ -0,0 +1,192 @@
+import { WORLD } from '../track/trackModel.js';
+import { simSpeedToKph, simUnitsToMeters } from '../units.js';
+import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+import { serializePenalty } from '../rules/penaltyLedger.js';
+import { normalizePitIntent, PIT_INTENT_NONE } from '../pit/pitIntent.js';
+import {
+  pitLaneStatusSnapshot,
+  serializeObservationPitStop,
+  serializePitStop,
+  serializeRenderPitStop,
+} from '../pit/pitSnapshots.js';
+import {
+  serializeCar,
+  serializeObservationCar,
+  serializeRenderCar,
+  serializeTrainingCar,
+} from '../vehicle/vehicleSnapshots.js';
+import { createLapTelemetry, serializeLapTelemetry } from '../timing/raceTiming.js';
+import { affectsRaceOrder } from '../participants/participantInteractions.js';
+import { serializeReplayGhosts } from '../replay/replayGhosts.js';
+
+function visibleStartState(sim) {
+  return {
+    ...sim.raceControl.start,
+    visible: sim.raceControl.mode === 'pre-start' ||
+      (sim.raceControl.start.releasedAt != null && sim.time - sim.raceControl.start.releasedAt < 1.45),
+  };
+}
+
+function penaltySecondsFor(statsByDriver, driverId) {
+  return statsByDriver.get(driverId)?.seconds ?? 0;
+}
+
+export function createVehicleSnapshotDependencies(sim) {
+  return {
+    createLapTelemetry,
+    normalizePitIntent,
+    PIT_INTENT_NONE,
+    serializeLapTelemetry,
+    serializeObservationPitStop: (pitStop) => serializeObservationPitStop(
+      pitStop,
+      normalizePitIntent,
+      PIT_INTENT_NONE,
+    ),
+    serializePitStop: (pitStop) => serializePitStop(pitStop, normalizePitIntent, PIT_INTENT_NONE),
+    serializeRenderPitStop,
+    simSpeedToKph,
+    simUnitsToMeters,
+    VEHICLE_LIMITS,
+  };
+}
+
+export function snapshotRace(sim) {
+  const ordered = sim.orderedCars();
+  const snapshotCars = carsForSnapshot(sim, ordered);
+  const pitLaneStatus = pitLaneStatusSnapshot(sim.raceControl, sim.track.pitLane, sim.rules.modules?.pitStops);
+  const penaltyStats = sim.getPenaltyStatsByDriver();
+  const vehicleSnapshotDependencies = createVehicleSnapshotDependencies(sim);
+  return {
+    time: sim.time,
+    world: WORLD,
+    physicsMode: sim.physicsMode,
+    track: sim.track,
+    totalLaps: sim.totalLaps,
+    raceControl: {
+      mode: sim.raceControl.mode,
+      redFlag: Boolean(sim.raceControl.redFlag),
+      pitLaneOpen: pitLaneStatus.open,
+      pitLaneStatus,
+      finished: sim.raceControl.finished,
+      finishedAt: sim.raceControl.finishedAt,
+      winner: getRaceWinnerSnapshot(sim),
+      classification: sim.raceControl.classification.map((entry) => ({ ...entry })),
+      start: visibleStartState(sim),
+    },
+    pitLaneStatus,
+    safetyCar: { ...sim.safetyCar },
+    rules: sim.rules,
+    events: [...sim.events],
+    penalties: sim.penalties.map(serializePenalty),
+    cars: snapshotCars.map(({ car, rank }) => serializeCar(
+      car,
+      rank,
+      penaltySecondsFor(penaltyStats, car.id),
+      vehicleSnapshotDependencies,
+    )),
+    replayGhosts: serializeReplayGhosts(sim.replayGhosts),
+  };
+}
+
+export function snapshotRaceRender(sim) {
+  const pitLaneStatus = pitLaneStatusSnapshot(sim.raceControl, sim.track.pitLane, sim.rules.modules?.pitStops);
+  const vehicleSnapshotDependencies = createVehicleSnapshotDependencies(sim);
+  return {
+    time: sim.time,
+    world: WORLD,
+    physicsMode: sim.physicsMode,
+    track: sim.track,
+    totalLaps: sim.totalLaps,
+    raceControl: {
+      mode: sim.raceControl.mode,
+      redFlag: Boolean(sim.raceControl.redFlag),
+      pitLaneOpen: pitLaneStatus.open,
+      pitLaneStatus,
+      finished: sim.raceControl.finished,
+      start: visibleStartState(sim),
+    },
+    pitLaneStatus,
+    safetyCar: { ...sim.safetyCar },
+    cars: carsForSnapshot(sim, sim.orderedCars()).map(({ car }) => serializeRenderCar(car, vehicleSnapshotDependencies)),
+    replayGhosts: serializeReplayGhosts(sim.replayGhosts),
+  };
+}
+
+export function snapshotRaceObservation(sim) {
+  const pitLaneStatus = pitLaneStatusSnapshot(sim.raceControl, sim.track.pitLane, sim.rules.modules?.pitStops);
+  const vehicleSnapshotDependencies = createVehicleSnapshotDependencies(sim);
+  return {
+    time: sim.time,
+    world: WORLD,
+    physicsMode: sim.physicsMode,
+    track: sim.track,
+    totalLaps: sim.totalLaps,
+    raceControl: {
+      mode: sim.raceControl.mode,
+      redFlag: Boolean(sim.raceControl.redFlag),
+      pitLaneOpen: pitLaneStatus.open,
+      pitLaneStatus,
+      finished: sim.raceControl.finished,
+    },
+    pitLaneStatus,
+    safetyCar: { ...sim.safetyCar },
+    events: [...sim.events],
+    cars: carsForSnapshot(sim, sim.orderedCars()).map(({ car, rank }) => serializeObservationCar(
+      car,
+      rank,
+      vehicleSnapshotDependencies,
+    )),
+    replayGhosts: serializeReplayGhosts(sim.replayGhosts),
+  };
+}
+
+export function snapshotRaceTraining(sim) {
+  const pitLaneStatus = pitLaneStatusSnapshot(sim.raceControl, sim.track.pitLane, sim.rules.modules?.pitStops);
+  const vehicleSnapshotDependencies = createVehicleSnapshotDependencies(sim);
+  return {
+    time: sim.time,
+    world: WORLD,
+    physicsMode: sim.physicsMode,
+    track: sim.track,
+    totalLaps: sim.totalLaps,
+    raceControl: {
+      mode: sim.raceControl.mode,
+      redFlag: Boolean(sim.raceControl.redFlag),
+      pitLaneOpen: pitLaneStatus.open,
+      pitLaneStatus,
+      finished: sim.raceControl.finished,
+    },
+    pitLaneStatus,
+    safetyCar: { ...sim.safetyCar },
+    events: [...sim.events],
+    cars: carsForSnapshot(sim, sim.orderedCars()).map(({ car, rank }) => serializeTrainingCar(
+      car,
+      rank,
+      vehicleSnapshotDependencies,
+    )),
+    replayGhosts: serializeReplayGhosts(sim.replayGhosts),
+  };
+}
+
+export function getRaceWinnerSnapshot(sim) {
+  if (!sim.raceControl.winnerId) return null;
+  const car = sim.cars.find((item) => item.id === sim.raceControl.winnerId);
+  if (!car) return null;
+  const rank = car.classifiedRank ?? car.rank ?? 1;
+  return serializeCar(
+    car,
+    rank,
+    penaltySecondsFor(sim.getPenaltyStatsByDriver(), car.id),
+    createVehicleSnapshotDependencies(sim),
+  );
+}
+
+function carsForSnapshot(sim, ordered) {
+  const orderedIds = new Set(ordered.map((car) => car.id));
+  const ranked = ordered.map((car, index) => ({ car, rank: index + 1 }));
+  const unranked = sim.cars
+    .filter((car) => !orderedIds.has(car.id))
+    .sort((a, b) => a.index - b.index)
+    .map((car) => ({ car, rank: affectsRaceOrder(car) ? (car.rank ?? null) : null }));
+  return [...ranked, ...unranked];
+}

package/src/simulation/timing/drsTiming.js

@@ -0,0 +1,87 @@
+import { wrapDistance } from '../simMath.js';
+
+function wrapProgress(value, length) {
+  return wrapDistance(value, length);
+}
+
+function distanceForward(from, to, length) {
+  return wrapProgress(to - from, length);
+}
+
+function crossesDistance(previous, current, target, length) {
+  const travelled = distanceForward(previous, current, length);
+  if (travelled <= 0 || travelled > length / 2) return false;
+  const targetOffset = distanceForward(previous, target, length);
+  return targetOffset > 0 && targetOffset <= travelled + 0.001;
+}
+
+function isProgressInZone(track, progress, zone) {
+  const wrapped = wrapProgress(progress, track.length);
+  const start = wrapProgress(zone.start, track.length);
+  const end = wrapProgress(zone.end, track.length);
+  if (zone.end - zone.start >= track.length) return true;
+  return end >= start
+    ? wrapped >= start && wrapped <= end
+    : wrapped >= start || wrapped <= end;
+}
+
+export function recordDrsDetection(car, zoneId, currentTime) {
+  const previous = car.drsDetection?.[zoneId] ?? { passage: 0, time: -Infinity };
+  const next = { passage: previous.passage + 1, time: currentTime };
+  car.drsDetection = {
+    ...(car.drsDetection ?? {}),
+    [zoneId]: next,
+  };
+  return next;
+}
+
+export function updateDrsLatch(car, ahead, {
+  hasReference = Boolean(ahead),
+  safetyCarDeployed = false,
+  time,
+  track,
+  rules,
+} = {}) {
+  if (safetyCarDeployed || car.finished) {
+    car.drsEligible = false;
+    car.drsActive = false;
+    car.drsZoneId = null;
+    car.drsZoneEnabled = false;
+    return;
+  }
+
+  const previousProgress = car.previousProgress ?? car.progress;
+  const currentZone = car.drsZoneId
+    ? track.drsZones.find((zone) => zone.id === car.drsZoneId)
+    : null;
+
+  if (currentZone && !isProgressInZone(track, car.progress, currentZone)) {
+    car.drsZoneId = null;
+    car.drsZoneEnabled = false;
+  }
+
+  if (!car.drsZoneId) {
+    const crossedZone = track.drsZones.find((zone) => (
+      crossesDistance(previousProgress, car.progress, zone.start, track.length)
+    ));
+    if (crossedZone) {
+      car.drsZoneId = crossedZone.id;
+      const crossing = recordDrsDetection(car, crossedZone.id, time);
+      const aheadCrossing = ahead?.drsDetection?.[crossedZone.id];
+      car.drsZoneEnabled = Boolean(
+        hasReference &&
+        aheadCrossing &&
+        aheadCrossing.passage === crossing.passage &&
+        crossing.time >= aheadCrossing.time &&
+        crossing.time - aheadCrossing.time <= rules.drsDetectionSeconds + 1e-6
+      );
+    }
+  }
+
+  const activeZone = car.drsZoneId
+    ? track.drsZones.find((zone) => zone.id === car.drsZoneId)
+    : null;
+  const inLatchedZone = activeZone ? isProgressInZone(track, car.progress, activeZone) : false;
+  car.drsEligible = Boolean(car.drsZoneEnabled && inLatchedZone);
+  car.drsActive = car.drsEligible;
+}