@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/environment/sensors/nearbyCars.js

@@ -0,0 +1,52 @@
+import { metersToSimUnits, simUnitsToMeters } from '../../simulation/units.js';
+import { normalizeRelativeHeading } from './rayGeometry.js';
+import { nearbyDetectableTargets } from './sensorTargets.js';
+
+export function buildNearbyCars(car, snapshot, { maxCars = 6, radiusMeters = 150 } = {}) {
+  const limit = Math.max(0, Math.floor(maxCars));
+  if (limit === 0) return [];
+  const radius = metersToSimUnits(radiusMeters);
+  const radiusSquared = radius * radius;
+  const forwardX = Math.cos(car.heading);
+  const forwardY = Math.sin(car.heading);
+  const rightX = -Math.sin(car.heading);
+  const rightY = Math.cos(car.heading);
+  const nearest = [];
+
+  nearbyDetectableTargets(car, snapshot).forEach((other) => {
+    const dx = other.x - car.x;
+    const dy = other.y - car.y;
+    const distanceSquared = dx * dx + dy * dy;
+    if (distanceSquared > radiusSquared) return;
+
+    const forward = forwardX * dx + forwardY * dy;
+    const right = rightX * dx + rightY * dy;
+    const entry = {
+      id: other.id,
+      relativeForwardMeters: simUnitsToMeters(forward),
+      relativeRightMeters: simUnitsToMeters(right),
+      relativeDistanceMeters: simUnitsToMeters(Math.sqrt(distanceSquared)),
+      relativeSpeedKph: other.speedKph - car.speedKph,
+      relativeHeadingRadians: normalizeRelativeHeading(other.heading - car.heading),
+      ahead: forward > 0,
+      sameLap: other.lap != null && other.lap === car.lap,
+      entityType: other.entityType,
+      distanceSquared,
+      order: other.order,
+    };
+    insertNearestCar(nearest, entry, limit);
+  });
+
+  return nearest.map(({ distanceSquared, order, ...entry }) => entry);
+}
+
+function insertNearestCar(nearest, entry, limit) {
+  let insertAt = nearest.findIndex((candidate) => (
+    entry.distanceSquared < candidate.distanceSquared ||
+    (entry.distanceSquared === candidate.distanceSquared && entry.order < candidate.order)
+  ));
+  if (insertAt < 0) insertAt = nearest.length;
+  if (insertAt >= limit) return;
+  nearest.splice(insertAt, 0, entry);
+  if (nearest.length > limit) nearest.pop();
+}

package/src/environment/sensors/opponentRadar.js

@@ -0,0 +1,65 @@
+import { kphToSimSpeed, simSpeedToMetersPerSecond, simUnitsToMeters } from '../../simulation/units.js';
+import { VEHICLE_GEOMETRY } from '../../simulation/vehicle/vehicleGeometry.js';
+
+export function enrichOpponentRadar(car, nearbyCars, snapshot) {
+  const targetsById = new Map([
+    ...(snapshot.cars ?? []).map((entry) => [entry.id, entry]),
+    ...(snapshot.replayGhosts ?? []).map((entry) => [entry.id, entry]),
+  ]);
+
+  return nearbyCars.map((nearby) => {
+    const target = targetsById.get(nearby.id);
+    const derived = target ? deriveRadarFields(car, target, nearby) : fallbackRadarFields(nearby);
+    return {
+      ...nearby,
+      ...derived,
+    };
+  });
+}
+
+function deriveRadarFields(car, target, nearby) {
+  const dx = (target.x ?? 0) - (car.x ?? 0);
+  const dy = (target.y ?? 0) - (car.y ?? 0);
+  const distance = Math.max(1e-9, Math.hypot(dx, dy));
+  const selfVelocity = velocity(car);
+  const targetVelocity = velocity(target);
+  const relativeVelocity = {
+    x: targetVelocity.x - selfVelocity.x,
+    y: targetVelocity.y - selfVelocity.y,
+  };
+  const closingRate = -((relativeVelocity.x * dx + relativeVelocity.y * dy) / distance);
+  const closingRateMetersPerSecond = simSpeedToMetersPerSecond(closingRate);
+  const distanceMeters = nearby.relativeDistanceMeters ?? simUnitsToMeters(distance);
+  const longitudinalOverlap = Math.abs(nearby.relativeForwardMeters ?? 0) <= simUnitsToMeters(VEHICLE_GEOMETRY.bodyLength);
+  const lateralOverlap = Math.abs(nearby.relativeRightMeters ?? 0) <= simUnitsToMeters(VEHICLE_GEOMETRY.bodyWidth);
+  const sideOverlap = longitudinalOverlap && lateralOverlap;
+
+  return {
+    behind: !nearby.ahead,
+    closingRateMetersPerSecond,
+    timeToContactSeconds: closingRateMetersPerSecond > 0
+      ? distanceMeters / closingRateMetersPerSecond
+      : null,
+    leftOverlap: sideOverlap && (nearby.relativeRightMeters ?? 0) < 0,
+    rightOverlap: sideOverlap && (nearby.relativeRightMeters ?? 0) > 0,
+  };
+}
+
+function fallbackRadarFields(nearby) {
+  return {
+    behind: !nearby.ahead,
+    closingRateMetersPerSecond: 0,
+    timeToContactSeconds: null,
+    leftOverlap: false,
+    rightOverlap: false,
+  };
+}
+
+function velocity(car) {
+  const speed = Number.isFinite(car.speed) ? car.speed : kphToSimSpeed(car.speedKph ?? 0);
+  const heading = car.heading ?? car.headingRadians ?? 0;
+  return {
+    x: Math.cos(heading) * speed,
+    y: Math.sin(heading) * speed,
+  };
+}

package/src/environment/sensors/rayConfig.js

@@ -0,0 +1,110 @@
+import { DEFAULT_RAY_ANGLES_DEGREES } from './rayDefaults.js';
+
+export const DEFAULT_RAY_LENGTH_METERS = 120;
+
+export const RAY_CHANNELS = Object.freeze([
+  'roadEdge',
+  'kerb',
+  'illegalSurface',
+  'car',
+]);
+
+export const RAY_PRECISION_MODES = Object.freeze(['driver', 'debug']);
+
+export const RAY_LAYOUT_PRESETS = Object.freeze({
+  compact: DEFAULT_RAY_ANGLES_DEGREES.map((angleDegrees) => ({ angleDegrees })),
+  'driver-front-heavy': [
+    -140, -100, -70, -50, -35, -20, -10, 0, 10, 20, 35, 50, 70, 100, 140, 180,
+  ].map((angleDegrees) => ({
+    angleDegrees,
+    lengthMeters: Math.abs(angleDegrees) <= 70 ? 240 : Math.abs(angleDegrees) <= 100 ? 90 : 60,
+  })),
+  'lidar-lite': Array.from({ length: 25 }, (_, index) => ({
+    angleDegrees: -120 + index * 10,
+    lengthMeters: Math.abs(-120 + index * 10) <= 70 ? 260 : 100,
+  })),
+});
+
+export function normalizeRayOptions(rayOptions = {}) {
+  const defaultLengthMeters = positiveNumber(
+    rayOptions.defaultLengthMeters ?? rayOptions.lengthMeters,
+    DEFAULT_RAY_LENGTH_METERS,
+  );
+  const rays = normalizeRays(rayOptions, defaultLengthMeters);
+  const channels = normalizeRayChannels(rayOptions);
+  const precision = RAY_PRECISION_MODES.includes(rayOptions.precision) ? rayOptions.precision : 'driver';
+  const anglesDegrees = rays.map((ray) => ray.angleDegrees);
+  const lengthMeters = rays.length ? Math.max(...rays.map((ray) => ray.lengthMeters)) : defaultLengthMeters;
+
+  return {
+    ...rayOptions,
+    enabled: rayOptions.enabled !== false,
+    anglesDegrees,
+    lengthMeters,
+    defaultLengthMeters,
+    rays,
+    channels,
+    precision,
+    detectTrack: channels.includes('roadEdge'),
+    detectCars: channels.includes('car'),
+  };
+}
+
+function normalizeRays(rayOptions, defaultLengthMeters) {
+  const configuredRays = Array.isArray(rayOptions.rays)
+    ? rayOptions.rays
+    : resolvePresetRays(rayOptions.layout);
+  const source = configuredRays.length
+    ? configuredRays
+    : normalizeAngles(rayOptions.anglesDegrees).map((angleDegrees) => ({ angleDegrees }));
+
+  return source.map((ray, index) => {
+    const angleDegrees = finiteNumber(
+      typeof ray === 'number' ? ray : ray?.angleDegrees,
+      DEFAULT_RAY_ANGLES_DEGREES[index % DEFAULT_RAY_ANGLES_DEGREES.length],
+    );
+    const lengthMeters = positiveNumber(
+      typeof ray === 'object' ? ray.lengthMeters : null,
+      defaultLengthMeters,
+    );
+    return {
+      id: typeof ray === 'object' && ray.id ? String(ray.id) : `ray-${index}`,
+      angleDegrees,
+      lengthMeters,
+    };
+  });
+}
+
+function resolvePresetRays(layout) {
+  if (typeof layout !== 'string') return [];
+  return RAY_LAYOUT_PRESETS[layout] ?? [];
+}
+
+function normalizeAngles(value) {
+  if (!Array.isArray(value) || value.length === 0) return [...DEFAULT_RAY_ANGLES_DEGREES];
+  const angles = value.map((angle) => Number(angle)).filter((angle) => Number.isFinite(angle));
+  return angles.length ? angles : [...DEFAULT_RAY_ANGLES_DEGREES];
+}
+
+function normalizeRayChannels(rayOptions) {
+  if (Array.isArray(rayOptions.channels) && rayOptions.channels.length) {
+    const channelSet = new Set(RAY_CHANNELS);
+    const channels = rayOptions.channels.filter((channel) => channelSet.has(channel));
+    if (channels.length) return [...new Set(channels)];
+  }
+
+  const channels = [];
+  if (rayOptions.detectTrack !== false) channels.push('roadEdge');
+  if (rayOptions.detectCars !== false) channels.push('car');
+  return channels;
+}
+
+function positiveNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}
+
+function finiteNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}

package/src/environment/sensors/rayDefaults.js

@@ -0,0 +1,6 @@
+export const TRACK_RAY_STEP_METERS = 1;
+export const TRACK_RAY_REFINE_STEPS = 12;
+export const DRIVER_RAY_REFINE_STEPS = 0;
+export const ANALYTIC_TRACK_RAY_MAX_CURVATURE = 0.00005;
+export const PIT_CONNECTOR_RAY_FALLBACK_METERS = 55;
+export const DEFAULT_RAY_ANGLES_DEGREES = [-135, -60, -20, 0, 20, 60, 135, 180];

package/src/environment/sensors/rayGeometry.js

@@ -0,0 +1,60 @@
+export function getCarRayOrigin(car) {
+  return {
+    x: car.x,
+    y: car.y,
+  };
+}
+
+export function getCarRayVector(car, angleDegrees) {
+  const angle = car.heading + degreesToRadians(angleDegrees);
+  return {
+    x: Math.cos(angle),
+    y: Math.sin(angle),
+  };
+}
+
+export function pointOnRay(origin, ray, distance) {
+  return {
+    x: origin.x + ray.x * distance,
+    y: origin.y + ray.y * distance,
+  };
+}
+
+export function intersectAxisAlignedBoxRay(origin, ray, halfLength, halfWidth) {
+  let tMin = -Infinity;
+  let tMax = Infinity;
+  const xRange = intersectSlab(origin.x, ray.x, -halfLength, halfLength);
+  const yRange = intersectSlab(origin.y, ray.y, -halfWidth, halfWidth);
+  if (!xRange || !yRange) return null;
+  tMin = Math.max(tMin, xRange.min, yRange.min);
+  tMax = Math.min(tMax, xRange.max, yRange.max);
+  if (tMax < 0 || tMin > tMax) return null;
+  return Math.max(0, tMin);
+}
+
+export function dot(a, b) {
+  return a.x * b.x + a.y * b.y;
+}
+
+export function degreesToRadians(degrees) {
+  return (degrees * Math.PI) / 180;
+}
+
+export function normalizeRelativeHeading(angle) {
+  let value = angle;
+  while (value > Math.PI) value -= Math.PI * 2;
+  while (value < -Math.PI) value += Math.PI * 2;
+  return value;
+}
+
+function intersectSlab(origin, direction, min, max) {
+  if (Math.abs(direction) < 1e-9) {
+    return origin >= min && origin <= max ? { min: -Infinity, max: Infinity } : null;
+  }
+  const first = (min - origin) / direction;
+  const second = (max - origin) / direction;
+  return {
+    min: Math.min(first, second),
+    max: Math.max(first, second),
+  };
+}

package/src/environment/sensors/rayGuards.js

@@ -0,0 +1,19 @@
+import { metersToSimUnits } from '../../simulation/units.js';
+
+export function canUseLocalStripRayApproximation(track, state) {
+  if (!track || !state || state.inPitLane) return false;
+  const kerbOuter = track.width / 2 + (track.kerbWidth ?? 0);
+  return Number.isFinite(state.crossTrackError) && state.crossTrackError <= kerbOuter;
+}
+
+export function canUseIndexedRecoveryRayApproximation(track, state) {
+  if (!track || !state || state.inPitLane) return false;
+  const recoveryBand = track.width / 2 +
+    (track.kerbWidth ?? 0) +
+    (track.gravelWidth ?? 0) +
+    (track.runoffWidth ?? 0) +
+    metersToSimUnits(64);
+  return Number.isFinite(state.crossTrackError) && state.crossTrackError <= recoveryBand;
+}
+
+export const canUseBatchTrainingRayApproximation = canUseIndexedRecoveryRayApproximation;

package/src/environment/sensors/sensorTargets.js

@@ -0,0 +1,60 @@
+import {
+  isNearbyDetectable,
+  isRayDetectable,
+} from '../../simulation/participants/participantInteractions.js';
+
+export const SENSOR_TARGET_CAR = 'car';
+export const SENSOR_TARGET_REPLAY_GHOST = 'replayGhost';
+
+export function rayDetectableTargets(self, snapshot) {
+  return rayDetectableTargetsForSnapshot(snapshot).filter((target) => target.id !== self.id);
+}
+
+export function nearbyDetectableTargets(self, snapshot) {
+  return nearbyDetectableTargetsForSnapshot(snapshot).filter((target) => target.id !== self.id);
+}
+
+export function rayDetectableTargetsForSnapshot(snapshot) {
+  return [
+    ...detectableCars(snapshot, isRayDetectable),
+    ...detectableReplayGhosts(snapshot, 'detectableByRays'),
+  ];
+}
+
+export function nearbyDetectableTargetsForSnapshot(snapshot) {
+  return [
+    ...detectableCars(snapshot, isNearbyDetectable),
+    ...detectableReplayGhosts(snapshot, 'detectableAsNearby'),
+  ];
+}
+
+function detectableCars(snapshot, predicate) {
+  return (snapshot.cars ?? [])
+    .filter((car) => predicate(car))
+    .map((car, order) => ({
+      entityType: SENSOR_TARGET_CAR,
+      id: car.id,
+      x: car.x,
+      y: car.y,
+      heading: car.heading,
+      speedKph: car.speedKph ?? 0,
+      lap: car.lap,
+      order,
+    }));
+}
+
+function detectableReplayGhosts(snapshot, sensorFlag) {
+  const carCount = snapshot.cars?.length ?? 0;
+  return (snapshot.replayGhosts ?? [])
+    .filter((ghost) => ghost.sensors?.[sensorFlag] === true)
+    .map((ghost, index) => ({
+      entityType: SENSOR_TARGET_REPLAY_GHOST,
+      id: ghost.id,
+      x: ghost.x,
+      y: ghost.y,
+      heading: ghost.heading,
+      speedKph: ghost.speedKph ?? 0,
+      lap: null,
+      order: carCount + index,
+    }));
+}

package/src/environment/sensors/surfaceRays.js

@@ -0,0 +1,296 @@
+import { nearestTrackState } from '../../simulation/track/trackModel.js';
+import { pitOverrideAllowedForCar } from '../../simulation/track/trackStatePolicy.js';
+import { metersToSimUnits, simUnitsToMeters } from '../../simulation/units.js';
+import {
+  ANALYTIC_TRACK_RAY_MAX_CURVATURE,
+  DRIVER_RAY_REFINE_STEPS,
+  PIT_CONNECTOR_RAY_FALLBACK_METERS,
+  TRACK_RAY_REFINE_STEPS,
+  TRACK_RAY_STEP_METERS,
+} from './rayDefaults.js';
+import { canUseIndexedRecoveryRayApproximation } from './rayGuards.js';
+import { pointOnRay } from './rayGeometry.js';
+import { findIndexedTrackBandBoundaries } from './indexedRayBands.js';
+
+const LEGAL_SURFACES = new Set(['track', 'kerb', 'pit-entry', 'pit-lane', 'pit-exit', 'pit-box']);
+const SURFACE_CHANNELS = new Set(['kerb', 'illegalSurface']);
+
+export function requestedSurfaceChannels(channels = []) {
+  return channels.filter((channel) => SURFACE_CHANNELS.has(channel));
+}
+
+export function createSurfaceMiss(lengthMeters) {
+  return {
+    hit: false,
+    distanceMeters: lengthMeters,
+    surface: null,
+  };
+}
+
+export function estimateSurfaceHits(
+  car,
+  snapshot,
+  ray,
+  origin,
+  vector,
+  channels,
+  context = null,
+  { precision = 'driver', sharedRayQuery = null } = {},
+) {
+  const requested = requestedSurfaceChannels(channels);
+  const misses = Object.fromEntries(requested.map((channel) => [channel, createSurfaceMiss(ray.lengthMeters)]));
+  if (!requested.length || !Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
+    return misses;
+  }
+
+  const originState = context?.originState ?? nearestRayTrackState(snapshot.track, car, origin, car.progress);
+  const indexedHits = estimateIndexedSurfaceHits({
+    car,
+    track: snapshot.track,
+    ray,
+    origin,
+    vector,
+    requested,
+    originState,
+    sharedRayQuery,
+  });
+  if (indexedHits) return { ...misses, ...indexedHits };
+  const analyticHits = estimateAnalyticSurfaceHits({
+    car,
+    track: snapshot.track,
+    ray,
+    vector,
+    requested,
+    originState,
+  });
+  if (analyticHits) return { ...misses, ...analyticHits };
+
+  const pending = new Set(requested);
+  const maxDistance = metersToSimUnits(ray.lengthMeters);
+  const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
+  let previousDistance = 0;
+  let previousState = null;
+
+  for (let distance = 0; distance <= maxDistance; distance += step) {
+    const state = nearestRayTrackState(snapshot.track, car, pointOnRay(origin, vector, distance), car.progress);
+    for (const channel of [...pending]) {
+      if (!matchesSurfaceChannel(channel, state)) continue;
+      const hitDistance = previousState
+        ? refineSurfaceTransition(snapshot.track, car, origin, vector, car.progress, previousDistance, distance, channel, refineStepsForPrecision(precision))
+        : distance;
+      misses[channel] = {
+        hit: true,
+        distanceMeters: simUnitsToMeters(hitDistance),
+        surface: state.surface ?? null,
+      };
+      pending.delete(channel);
+    }
+    if (pending.size === 0) break;
+    previousDistance = distance;
+    previousState = state;
+  }
+
+  return misses;
+}
+
+function estimateAnalyticSurfaceHits({ car, track, ray, vector, requested, originState }) {
+  if (!originState || car.inPitLane || originState.inPitLane) return null;
+  if (!usesMainTrackOnlyRays(car) && isNearPitConnector(track, originState)) return null;
+  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return null;
+  if (Math.abs(originState.curvature ?? 0) > ANALYTIC_TRACK_RAY_MAX_CURVATURE) return null;
+
+  const lateral = vector.x * originState.normalX + vector.y * originState.normalY;
+  if (Math.abs(lateral) < 0.08) return Object.fromEntries(requested.map((channel) => [
+    channel,
+    createSurfaceMiss(ray.lengthMeters),
+  ]));
+
+  const trackHalfWidth = track.width / 2;
+  const kerbOuter = trackHalfWidth + (track.kerbWidth ?? 0);
+  const maxDistance = metersToSimUnits(ray.lengthMeters);
+  const offset = originState.signedOffset ?? car.signedOffset ?? 0;
+  const hits = {};
+
+  requested.forEach((channel) => {
+    if (channel === 'kerb') {
+      hits[channel] = hitAbsOffsetBand({
+        offset,
+        lateral,
+        minAbsOffset: trackHalfWidth,
+        maxAbsOffset: kerbOuter,
+        maxDistance,
+        lengthMeters: ray.lengthMeters,
+        surface: 'kerb',
+      });
+    } else if (channel === 'illegalSurface') {
+      hits[channel] = hitAbsOffsetBand({
+        offset,
+        lateral,
+        minAbsOffset: kerbOuter,
+        maxAbsOffset: Infinity,
+        maxDistance,
+        lengthMeters: ray.lengthMeters,
+        surface: surfaceBeyondKerb(track, offset, lateral, maxDistance),
+      });
+    }
+  });
+
+  return hits;
+}
+
+function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested, originState, sharedRayQuery }) {
+  if (!originState || car.inPitLane || originState.inPitLane) return null;
+  if (!usesMainTrackOnlyRays(car) && isNearPitConnector(track, originState)) return null;
+  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return null;
+
+  const trackHalfWidth = track.width / 2;
+  const kerbOuter = trackHalfWidth + (track.kerbWidth ?? 0);
+  const lateral = vector.x * originState.normalX + vector.y * originState.normalY;
+  const boundaries = findIndexedTrackBandBoundaries(
+    track,
+    origin,
+    vector,
+    ray.lengthMeters,
+    trackHalfWidth,
+    kerbOuter,
+    sharedRayQuery,
+  );
+  if (!boundaries.available) return null;
+  const hits = {};
+
+  for (const channel of requested) {
+    if (matchesSurfaceChannel(channel, originState)) {
+      hits[channel] = { hit: true, distanceMeters: 0, surface: originState.surface ?? null };
+      continue;
+    }
+
+    const boundaryDistance = channel === 'kerb'
+      ? minFinite(boundaries.trackEdgeDistance, boundaries.kerbOuterDistance)
+      : boundaries.kerbOuterDistance;
+    if (boundaryDistance == null) return null;
+    hits[channel] = {
+      hit: true,
+      distanceMeters: simUnitsToMeters(boundaryDistance),
+      surface: channel === 'kerb'
+        ? 'kerb'
+        : surfaceBeyondKerb(track, originState.signedOffset ?? 0, lateral, metersToSimUnits(ray.lengthMeters)),
+    };
+  }
+
+  return hits;
+}
+
+function usesMainTrackOnlyRays(car) {
+  return car?.interaction?.profile === 'batch-training';
+}
+
+function hitAbsOffsetBand({ offset, lateral, minAbsOffset, maxAbsOffset, maxDistance, lengthMeters, surface }) {
+  const currentAbs = Math.abs(offset);
+  if (currentAbs >= minAbsOffset && currentAbs <= maxAbsOffset) {
+    return { hit: true, distanceMeters: 0, surface };
+  }
+
+  const candidates = [
+    distanceToOffset(minAbsOffset, offset, lateral),
+    distanceToOffset(-minAbsOffset, offset, lateral),
+  ].filter((distance) => Number.isFinite(distance) && distance >= 0 && distance <= maxDistance);
+
+  if (Number.isFinite(maxAbsOffset)) {
+    candidates.push(
+      ...[
+        distanceToOffset(maxAbsOffset, offset, lateral),
+        distanceToOffset(-maxAbsOffset, offset, lateral),
+      ].filter((distance) => Number.isFinite(distance) && distance >= 0 && distance <= maxDistance),
+    );
+  }
+
+  const distance = candidates
+    .filter((candidate) => {
+      const nextAbs = Math.abs(offset + lateral * candidate);
+      return nextAbs >= minAbsOffset - 1e-6 && nextAbs <= maxAbsOffset + 1e-6;
+    })
+    .sort((a, b) => a - b)[0];
+
+  if (!Number.isFinite(distance)) return createSurfaceMiss(lengthMeters);
+  return { hit: true, distanceMeters: simUnitsToMeters(distance), surface };
+}
+
+function distanceToOffset(targetOffset, offset, lateral) {
+  return (targetOffset - offset) / lateral;
+}
+
+function surfaceBeyondKerb(track, offset, lateral, maxDistance) {
+  const gravelOuter = track.width / 2 + (track.kerbWidth ?? 0) + (track.gravelWidth ?? 0);
+  const hitDistance = Math.min(
+    ...[
+      distanceToOffset(track.width / 2 + (track.kerbWidth ?? 0), offset, lateral),
+      distanceToOffset(-track.width / 2 - (track.kerbWidth ?? 0), offset, lateral),
+    ].filter((distance) => Number.isFinite(distance) && distance >= 0 && distance <= maxDistance),
+  );
+  const hitAbs = Math.abs(offset + lateral * hitDistance);
+  return hitAbs <= gravelOuter ? 'gravel' : 'grass';
+}
+
+function isNearPitConnector(track, state) {
+  const pitLane = track.pitLane;
+  if (!pitLane?.enabled || !Number.isFinite(state?.distance)) return false;
+  const window = metersToSimUnits(PIT_CONNECTOR_RAY_FALLBACK_METERS);
+  const entryDistance = pitLane.entry?.trackDistance ?? pitLane.entry?.distanceFromStart;
+  const exitDistance = pitLane.exit?.trackDistance ?? pitLane.exit?.distanceFromStart;
+  return wrappedTrackDistance(state.distance, entryDistance, track.length) <= window ||
+    wrappedTrackDistance(state.distance, exitDistance, track.length) <= window;
+}
+
+function wrappedTrackDistance(first, second, totalLength) {
+  if (!Number.isFinite(first) || !Number.isFinite(second) || !Number.isFinite(totalLength) || totalLength <= 0) {
+    return Infinity;
+  }
+  const delta = Math.abs(first - second);
+  return Math.min(delta, totalLength - delta);
+}
+
+function refineSurfaceTransition(
+  track,
+  car,
+  origin,
+  ray,
+  progressHint,
+  lowDistance,
+  highDistance,
+  channel,
+  refineSteps = TRACK_RAY_REFINE_STEPS,
+) {
+  let low = lowDistance;
+  let high = highDistance;
+  for (let index = 0; index < refineSteps; index += 1) {
+    const middle = (low + high) / 2;
+    const state = nearestRayTrackState(track, car, pointOnRay(origin, ray, middle), progressHint);
+    if (matchesSurfaceChannel(channel, state)) high = middle;
+    else low = middle;
+  }
+  return high;
+}
+
+function refineStepsForPrecision(precision) {
+  return precision === 'debug' ? TRACK_RAY_REFINE_STEPS : DRIVER_RAY_REFINE_STEPS;
+}
+
+function matchesSurfaceChannel(channel, state) {
+  if (channel === 'kerb') return state.surface === 'kerb';
+  if (channel === 'illegalSurface') return !LEGAL_SURFACES.has(state.surface) && state.surface !== 'barrier';
+  return false;
+}
+
+function nearestRayTrackState(track, car, point, progressHint) {
+  const useBatchTrainingIndexMode = usesMainTrackOnlyRays(car);
+  return nearestTrackState(track, point, progressHint, {
+    allowPitOverride: pitOverrideAllowedForCar(car),
+    indexMode: useBatchTrainingIndexMode ? 'sample' : undefined,
+    hintMaxDistance: useBatchTrainingIndexMode ? Infinity : undefined,
+  });
+}
+
+function minFinite(...values) {
+  const minimum = Math.min(...values.filter((value) => Number.isFinite(value)));
+  return Number.isFinite(minimum) ? minimum : null;
+}