@inventure71/paddockjs 1.0.0 → 2.0.0

package/src/simulation/vehiclePhysics.js

@@ -1,136 +1 @@
-import { clamp, normalizeAngle } from './simMath.js';
-import {
-  REAL_F1_WHEELBASE_METERS,
-  SIM_UNITS_PER_METER,
-  TOP_SPEED_SIM_UNITS_PER_SECOND,
-  simUnitsToMeters,
-  metersToSimUnits,
-} from './units.js';
-import { VEHICLE_GEOMETRY, getCarCorners } from './vehicleGeometry.js';
-
-const G = 9.80665;
-
-export const VEHICLE_LIMITS = {
-  wheelbase: metersToSimUnits(REAL_F1_WHEELBASE_METERS),
-  maxSteer: 0.56,
-  steerRate: 2.35,
-  maxSpeed: TOP_SPEED_SIM_UNITS_PER_SECOND,
-  carLength: VEHICLE_GEOMETRY.visualLength,
-  carWidth: VEHICLE_GEOMETRY.visualWidth,
-};
-
-const SURFACE_MODEL = {
-  track: { grip: 1, drag: 0, rollingResistance: 0 },
-  'pit-entry': { grip: 0.96, drag: 0.04, rollingResistance: 0.012 },
-  'pit-lane': { grip: 0.96, drag: 0.04, rollingResistance: 0.012 },
-  'pit-exit': { grip: 0.96, drag: 0.04, rollingResistance: 0.012 },
-  'pit-box': { grip: 0.94, drag: 0.08, rollingResistance: 0.025 },
-  kerb: { grip: 0.92, drag: 0.12, rollingResistance: 0.045 },
-  gravel: { grip: 0.43, drag: 4.0, rollingResistance: 0.68 },
-  grass: { grip: 0.34, drag: 1.9, rollingResistance: 0.36 },
-  barrier: { grip: 0.18, drag: 9, rollingResistance: 1.2 },
-};
-const WHEEL_DRAG_YAW_GAIN = 0.08;
-const MAX_WHEEL_DRAG_YAW_RATE = 0.22;
-
-function accelerationLimit(speed, surfaceGrip) {
-  const speedRatio = clamp(speed / VEHICLE_LIMITS.maxSpeed, 0, 1);
-  return SIM_UNITS_PER_METER * surfaceGrip * (17 * (1 - speedRatio ** 2.1) + 1.2);
-}
-
-function brakingLimit(speed, surfaceGrip) {
-  const speedRatio = clamp(speed / VEHICLE_LIMITS.maxSpeed, 0, 1);
-  return SIM_UNITS_PER_METER * surfaceGrip * (20 + speedRatio * 14);
-}
-
-export function tirePerformanceFactor(tireEnergy = 100) {
-  const normalized = clamp((Number(tireEnergy) || 1) / 100, 0.01, 1);
-  return clamp(0.45 + 0.55 * normalized ** 0.72, 0.45, 1);
-}
-
-function surfaceResistance(surfaceName) {
-  const surface = SURFACE_MODEL[surfaceName] ?? SURFACE_MODEL.track;
-  return surface.drag * 0.14 + surface.rollingResistance * 2.4 + (1 - surface.grip) * 0.65;
-}
-
-function sideWheelResistance(wheels, side) {
-  const sideWheels = wheels.filter((wheel) => wheel.id?.endsWith(`-${side}`));
-  if (!sideWheels.length) return 0;
-  return sideWheels.reduce((total, wheel) => total + surfaceResistance(wheel.surface), 0) / sideWheels.length;
-}
-
-function wheelDragYawRate(car) {
-  const wheels = Array.isArray(car.wheelStates) ? car.wheelStates : [];
-  if (!wheels.length) return 0;
-  const leftResistance = sideWheelResistance(wheels, 'left');
-  const rightResistance = sideWheelResistance(wheels, 'right');
-  const speedFactor = clamp(car.speed / VEHICLE_LIMITS.maxSpeed, 0, 1);
-  return clamp(
-    (rightResistance - leftResistance) * speedFactor * WHEEL_DRAG_YAW_GAIN,
-    -MAX_WHEEL_DRAG_YAW_RATE,
-    MAX_WHEEL_DRAG_YAW_RATE,
-  );
-}
-
-export function integrateVehiclePhysics(car, controls, dt) {
-  const steeringTarget = clamp(controls.steering ?? 0, -VEHICLE_LIMITS.maxSteer, VEHICLE_LIMITS.maxSteer);
-  const steerDelta = clamp(
-    steeringTarget - car.steeringAngle,
-    -VEHICLE_LIMITS.steerRate * dt,
-    VEHICLE_LIMITS.steerRate * dt,
-  );
-  car.steeringAngle += steerDelta;
-
-  const throttle = clamp(controls.throttle ?? 0, 0, 1);
-  const brake = clamp(controls.brake ?? 0, 0, 1);
-  const surface = SURFACE_MODEL[car.trackState?.surface] ?? SURFACE_MODEL.track;
-  const tireFactor = tirePerformanceFactor(car.tireEnergy ?? 100);
-  const surfaceGrip = surface.grip * tireFactor;
-  const dragMultiplier = car.drsActive ? 0.42 : 1;
-  const speedRatio = clamp(car.speed / VEHICLE_LIMITS.maxSpeed, 0, 1);
-  const engineForce = throttle *
-    car.powerNewtons *
-    (car.drsActive ? 1.08 : 1) *
-    Math.max(0.12, 1 - speedRatio ** 1.15);
-  const brakeForce = brake * car.brakeNewtons;
-  const speedMetersPerSecondBefore = simUnitsToMeters(car.speed);
-  const dragForce = (car.dragCoefficient * dragMultiplier * 0.12 + surface.drag) *
-    speedMetersPerSecondBefore * speedMetersPerSecondBefore;
-  const rollingForce = surface.rollingResistance * car.mass * G;
-  const driveAcceleration = clamp((engineForce / car.mass) * SIM_UNITS_PER_METER, 0, accelerationLimit(car.speed, surfaceGrip));
-  const drsAcceleration = car.drsActive ? driveAcceleration * 0.06 : 0;
-  const brakeDeceleration = clamp((brakeForce / car.mass) * SIM_UNITS_PER_METER, 0, brakingLimit(car.speed, surfaceGrip));
-  const dragDeceleration = ((dragForce + rollingForce) / car.mass) * SIM_UNITS_PER_METER;
-  const acceleration = driveAcceleration + drsAcceleration - brakeDeceleration - dragDeceleration;
-
-  car.speed = clamp(car.speed + acceleration * dt, 0, VEHICLE_LIMITS.maxSpeed);
-
-  const speedMetersPerSecond = simUnitsToMeters(car.speed);
-  const rawYawRate = (speedMetersPerSecond / REAL_F1_WHEELBASE_METERS) *
-    Math.tan(car.steeringAngle) *
-    tireFactor;
-  const downforceGrip = car.downforceCoefficient * speedMetersPerSecond * speedMetersPerSecond / car.mass;
-  const tyreConditionGrip = tireFactor;
-  const maxYawRate = ((car.tireGrip * tyreConditionGrip * G + downforceGrip) * surfaceGrip) /
-    Math.max(speedMetersPerSecond, 1);
-  const steeringYawRate = clamp(rawYawRate, -maxYawRate, maxYawRate);
-  const requestedWheelDragYawRate = wheelDragYawRate(car);
-  car.yawRate = clamp(steeringYawRate + requestedWheelDragYawRate, -maxYawRate, maxYawRate);
-  car.wheelDragYawRate = car.yawRate - steeringYawRate;
-  car.turnRadius = Math.abs(car.yawRate) < 0.001 ? Infinity : car.speed / Math.abs(car.yawRate);
-  car.heading = normalizeAngle(car.heading + car.yawRate * dt);
-  car.x += Math.cos(car.heading) * car.speed * dt;
-  car.y += Math.sin(car.heading) * car.speed * dt;
-  car.throttle = throttle;
-  car.brake = brake;
-  car.lateralAcceleration = speedMetersPerSecond * car.yawRate;
-  car.steerSaturation = rawYawRate === 0 ? 0 : Math.abs(steeringYawRate / rawYawRate);
-  const tyreLoad = Math.abs(car.lateralAcceleration) / G;
-  const tireCare = clamp(Number(car.tireCare) || 1, 0.45, 1.8);
-  const wearRate = (0.035 + tyreLoad * 0.11 + brake * 0.07 + throttle * 0.025) / tireCare;
-  car.tireEnergy = clamp((car.tireEnergy ?? 100) - wearRate * dt, 1, 100);
-
-  return car;
-}
-
-export { getCarCorners };
+export * from './vehicle/vehiclePhysics.js';

package/src/simulation/warmup/runtimeWarmup.js

@@ -0,0 +1,224 @@
+const DEFAULT_WARMUP_POLICY = 'config-change';
+const DEFAULT_WARMUP_STEPS = Object.freeze({
+  simulation: 20,
+  browser: 20,
+  environment: 20,
+});
+const SUPPORTED_WARMUP_POLICIES = new Set(['config-change', 'always', 'never']);
+const MAX_CACHE_ENTRIES_PER_SURFACE = 256;
+const warmupFingerprintCache = new Map();
+
+export function normalizeWarmupOptions(input, surface = 'simulation') {
+  const fallbackSteps = DEFAULT_WARMUP_STEPS[surface] ?? DEFAULT_WARMUP_STEPS.simulation;
+  if (input === false) {
+    return {
+      enabled: false,
+      policy: 'never',
+      steps: fallbackSteps,
+      surface,
+    };
+  }
+  if (input === true || input == null) {
+    return {
+      enabled: true,
+      policy: DEFAULT_WARMUP_POLICY,
+      steps: fallbackSteps,
+      surface,
+    };
+  }
+  const enabled = input.enabled == null ? true : Boolean(input.enabled);
+  const policy = normalizeWarmupPolicy(input.policy, enabled);
+  return {
+    enabled,
+    policy,
+    steps: normalizeWarmupSteps(input.steps, fallbackSteps),
+    surface: typeof input.surface === 'string' && input.surface.length > 0 ? input.surface : surface,
+  };
+}
+
+export function withWarmupSurfaceOptions(options = {}, surface = 'simulation') {
+  return {
+    ...options,
+    warmup: normalizeWarmupOptions(options.warmup, surface),
+  };
+}
+
+export function disableWarmupOptions(options = {}, surface = 'simulation') {
+  const warmup = normalizeWarmupOptions(options.warmup, surface);
+  return {
+    ...options,
+    warmup: {
+      ...warmup,
+      enabled: false,
+      policy: 'never',
+      surface,
+    },
+  };
+}
+
+export function runWarmupWithGuard({
+  options = {},
+  surface = 'simulation',
+  execute,
+} = {}) {
+  const warmup = normalizeWarmupOptions(options.warmup, surface);
+  const fingerprint = createWarmupFingerprint(options, {
+    surface: warmup.surface,
+    steps: warmup.steps,
+  });
+  if (!shouldRunWarmup(warmup, fingerprint)) {
+    return { ran: false, warmup, fingerprint };
+  }
+  try {
+    execute?.({ warmup, fingerprint });
+    markWarmupComplete(warmup.surface, fingerprint);
+    return { ran: true, warmup, fingerprint };
+  } catch {
+    return { ran: false, warmup, fingerprint };
+  }
+}
+
+export function resetWarmupRuntimeCache() {
+  warmupFingerprintCache.clear();
+}
+
+function shouldRunWarmup(warmup, fingerprint) {
+  if (!warmup.enabled) return false;
+  if (warmup.policy === 'never') return false;
+  if (warmup.policy === 'always') return true;
+  return !hasWarmupFingerprint(warmup.surface, fingerprint);
+}
+
+function hasWarmupFingerprint(surface, fingerprint) {
+  return warmupFingerprintCache.get(surface)?.has(fingerprint) ?? false;
+}
+
+function markWarmupComplete(surface, fingerprint) {
+  let entries = warmupFingerprintCache.get(surface);
+  if (!entries) {
+    entries = new Map();
+    warmupFingerprintCache.set(surface, entries);
+  }
+  entries.set(fingerprint, Date.now());
+  while (entries.size > MAX_CACHE_ENTRIES_PER_SURFACE) {
+    const firstKey = entries.keys().next().value;
+    entries.delete(firstKey);
+  }
+}
+
+function createWarmupFingerprint(options, { surface, steps }) {
+  return stableStringify({
+    surface,
+    steps,
+    seed: finiteOrNull(options.seed),
+    trackSeed: finiteOrNull(options.trackSeed),
+    totalLaps: finiteOrNull(options.totalLaps),
+    trackGeneration: options.trackGeneration ?? null,
+    track: summarizeTrack(options.track),
+    physicsMode: options.physicsMode ?? null,
+    trackQueryIndex: options.trackQueryIndex !== false,
+    rules: options.rules ?? null,
+    participantInteractions: options.participantInteractions ?? null,
+    replayGhosts: summarizeReplayGhosts(options.replayGhosts),
+    drivers: summarizeDrivers(options.drivers),
+    entries: summarizeEntries(options.entries),
+    controlledDrivers: summarizeStringArray(options.controlledDrivers),
+    sensors: options.sensors ?? null,
+    sensorsByDriver: summarizeSensorsByDriver(options.sensorsByDriver),
+    scenario: summarizeScenario(options.scenario),
+    frameSkip: finiteOrNull(options.frameSkip),
+  });
+}
+
+function normalizeWarmupPolicy(value, enabled) {
+  if (!enabled) return 'never';
+  if (typeof value !== 'string') return DEFAULT_WARMUP_POLICY;
+  return SUPPORTED_WARMUP_POLICIES.has(value) ? value : DEFAULT_WARMUP_POLICY;
+}
+
+function normalizeWarmupSteps(value, fallback) {
+  if (value == null) return fallback;
+  const steps = Math.floor(Number(value));
+  if (!Number.isFinite(steps) || steps < 1) return fallback;
+  return steps;
+}
+
+function summarizeTrack(track) {
+  if (!track || typeof track !== 'object') return null;
+  const samples = Array.isArray(track.samples) ? track.samples.length : null;
+  const centerlineControls = Array.isArray(track.centerlineControls) ? track.centerlineControls.length : null;
+  const drsZones = Array.isArray(track.drsZones) ? track.drsZones.length : null;
+  return {
+    name: track.name ?? null,
+    seed: finiteOrNull(track.seed),
+    length: finiteOrNull(track.length),
+    width: finiteOrNull(track.width),
+    sampleCount: finiteOrNull(track.sampleCount) ?? samples,
+    centerlineControls,
+    drsZones,
+    hasPitLane: Boolean(track.pitLane?.enabled),
+  };
+}
+
+function summarizeReplayGhosts(replayGhosts) {
+  if (!Array.isArray(replayGhosts)) return null;
+  return replayGhosts.map((ghost) => ({
+    id: ghost?.id ?? null,
+    visible: ghost?.visible !== false,
+    samples: Array.isArray(ghost?.trajectory) ? ghost.trajectory.length : 0,
+  }));
+}
+
+function summarizeDrivers(drivers) {
+  if (!Array.isArray(drivers)) return null;
+  return {
+    count: drivers.length,
+    ids: drivers.map((driver) => driver?.id ?? null),
+  };
+}
+
+function summarizeEntries(entries) {
+  if (!Array.isArray(entries)) return null;
+  return {
+    count: entries.length,
+    driverIds: entries.map((entry) => entry?.driverId ?? null),
+  };
+}
+
+function summarizeStringArray(values) {
+  if (!Array.isArray(values)) return null;
+  return values.map((value) => String(value));
+}
+
+function summarizeSensorsByDriver(sensorsByDriver) {
+  if (!sensorsByDriver || typeof sensorsByDriver !== 'object') return null;
+  const ids = Object.keys(sensorsByDriver);
+  return {
+    count: ids.length,
+    ids: ids.sort(),
+  };
+}
+
+function summarizeScenario(scenario) {
+  if (!scenario || typeof scenario !== 'object') return null;
+  return {
+    participants: scenario.participants ?? null,
+    preset: scenario.preset ?? null,
+    placements: scenario.placements ?? null,
+    traffic: scenario.traffic ?? null,
+  };
+}
+
+function stableStringify(value) {
+  if (value == null) return 'null';
+  if (typeof value === 'number' || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  if (typeof value !== 'object') return JSON.stringify(String(value));
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+}
+
+function finiteOrNull(value) {
+  return Number.isFinite(Number(value)) ? Number(value) : null;
+}

package/src/simulation/wheelSurface.js

@@ -1,338 +1 @@
-import { nearestTrackState } from './trackModel.js';
-import { metersToSimUnits } from './units.js';
-import { getVehicleGeometryState } from './vehicleGeometry.js';
-
-const SURFACE_PRIORITY = {
-  track: 0,
-  'pit-entry': 1,
-  'pit-exit': 1,
-  'pit-lane': 2,
-  'pit-box': 3,
-  kerb: 4,
-  grass: 5,
-  gravel: 6,
-  barrier: 7,
-};
-const PIT_CONNECTOR_FULL_SAMPLE_WINDOW = metersToSimUnits(35);
-
-function finiteSignatureValue(value) {
-  return Number.isFinite(value) ? Number(value).toFixed(4) : '';
-}
-
-function centerStateSignature(centerState) {
-  if (!centerState) return 'auto';
-  return [
-    finiteSignatureValue(centerState.distance),
-    finiteSignatureValue(centerState.signedOffset),
-    finiteSignatureValue(centerState.crossTrackError),
-    centerState.surface ?? '',
-    centerState.inPitLane ? 1 : 0,
-    centerState.pitLanePart ?? '',
-    centerState.pitBoxId ?? '',
-  ].join(':');
-}
-
-function priority(surface) {
-  return SURFACE_PRIORITY[surface] ?? SURFACE_PRIORITY.barrier;
-}
-
-function worstState(states) {
-  return states.reduce((worst, state) => (
-    priority(state.surface) > priority(worst.surface) ? state : worst
-  ), states[0]);
-}
-
-function patchSamples(patch) {
-  return [patch.center, ...patch.corners];
-}
-
-function wrappedDistanceDelta(first, second, length) {
-  if (!Number.isFinite(first) || !Number.isFinite(second) || !Number.isFinite(length) || length <= 0) return Infinity;
-  const delta = Math.abs(first - second);
-  return Math.min(delta, length - delta);
-}
-
-function isNearPitConnector(track, centerState) {
-  const pitLane = track.pitLane;
-  if (!pitLane?.enabled) return false;
-  const distance = centerState.distance;
-  const entryDistance = pitLane.entry?.trackDistance ?? pitLane.entry?.distanceFromStart;
-  const exitDistance = pitLane.exit?.trackDistance ?? pitLane.exit?.distanceFromStart;
-  return wrappedDistanceDelta(distance, entryDistance, track.length) <= PIT_CONNECTOR_FULL_SAMPLE_WINDOW ||
-    wrappedDistanceDelta(distance, exitDistance, track.length) <= PIT_CONNECTOR_FULL_SAMPLE_WINDOW;
-}
-
-function mainTrackSurface(track, crossTrackError) {
-  const trackEdge = track.width / 2;
-  const kerbEdge = trackEdge + (track.kerbWidth ?? 0);
-  const gravelEdge = kerbEdge + track.gravelWidth;
-  const runoffEdge = gravelEdge + track.runoffWidth;
-  if (crossTrackError <= trackEdge) return 'track';
-  if (crossTrackError <= kerbEdge) return 'kerb';
-  if (crossTrackError <= gravelEdge) return 'gravel';
-  if (crossTrackError <= runoffEdge) return 'grass';
-  return 'barrier';
-}
-
-function localTrackState(track, centerState, point) {
-  const signedOffset =
-    (point.x - centerState.x) * centerState.normalX +
-    (point.y - centerState.y) * centerState.normalY;
-  const crossTrackError = Math.abs(signedOffset);
-  const surface = mainTrackSurface(track, crossTrackError);
-  return {
-    ...centerState,
-    signedOffset,
-    crossTrackError,
-    surface,
-    onTrack: surface === 'track' || surface === 'kerb',
-    inPitLane: false,
-    pitLanePart: null,
-    pitBoxId: null,
-  };
-}
-
-function wheelFullyOutside(samples, trackLimit) {
-  const rightOutside = samples.every((state) => !state.inPitLane && state.signedOffset > trackLimit);
-  const leftOutside = samples.every((state) => !state.inPitLane && state.signedOffset < -trackLimit);
-  return {
-    rightOutside,
-    leftOutside,
-    fullyOutsideWhiteLine: rightOutside || leftOutside,
-    outsideSide: rightOutside ? 1 : leftOutside ? -1 : 0,
-  };
-}
-
-function wheelOutsideFromOffsets(minimumSignedOffset, maximumSignedOffset, trackLimit) {
-  const rightOutside = minimumSignedOffset > trackLimit;
-  const leftOutside = maximumSignedOffset < -trackLimit;
-  return {
-    rightOutside,
-    leftOutside,
-    fullyOutsideWhiteLine: rightOutside || leftOutside,
-    outsideSide: rightOutside ? 1 : leftOutside ? -1 : 0,
-  };
-}
-
-function stateFromSignedOffset(centerState, track, signedOffset) {
-  const crossTrackError = Math.abs(signedOffset);
-  const surface = mainTrackSurface(track, crossTrackError);
-  return {
-    ...centerState,
-    signedOffset,
-    crossTrackError,
-    surface,
-    onTrack: surface === 'track' || surface === 'kerb',
-    inPitLane: false,
-    pitLanePart: null,
-    pitBoxId: null,
-  };
-}
-
-function analyticWheelState(patch, centerState, track, trackLimit) {
-  const wheelCenterOffset =
-    (patch.center.x - centerState.x) * centerState.normalX +
-    (patch.center.y - centerState.y) * centerState.normalY;
-  const projectedHalfWidth =
-    Math.abs(patch.forward.x * centerState.normalX + patch.forward.y * centerState.normalY) * patch.halfLength +
-    Math.abs(patch.right.x * centerState.normalX + patch.right.y * centerState.normalY) * patch.halfWidth;
-  const minimumSignedOffset = wheelCenterOffset - projectedHalfWidth;
-  const maximumSignedOffset = wheelCenterOffset + projectedHalfWidth;
-  const signedOffset = Math.abs(minimumSignedOffset) > Math.abs(maximumSignedOffset)
-    ? minimumSignedOffset
-    : maximumSignedOffset;
-  const state = stateFromSignedOffset(centerState, track, signedOffset);
-  const outside = wheelOutsideFromOffsets(minimumSignedOffset, maximumSignedOffset, trackLimit);
-
-  return {
-    id: patch.id,
-    x: patch.center.x,
-    y: patch.center.y,
-    signedOffset: state.signedOffset,
-    crossTrackError: state.crossTrackError,
-    surface: state.surface,
-    onTrack: Boolean(state.onTrack),
-    inPitLane: false,
-    pitLanePart: null,
-    pitBoxId: null,
-    minimumSignedOffset,
-    maximumSignedOffset,
-    fullyOutsideWhiteLine: outside.fullyOutsideWhiteLine,
-    outsideSide: outside.outsideSide,
-    sampledStates: [state],
-  };
-}
-
-function patchPitOffsetRange(patch, centerState) {
-  const wheelCenterOffset =
-    (patch.center.x - centerState.x) * centerState.normalX +
-    (patch.center.y - centerState.y) * centerState.normalY;
-  const projectedHalfWidth =
-    Math.abs(patch.forward.x * centerState.normalX + patch.forward.y * centerState.normalY) * patch.halfLength +
-    Math.abs(patch.right.x * centerState.normalX + patch.right.y * centerState.normalY) * patch.halfWidth;
-  return {
-    minimum: wheelCenterOffset - projectedHalfWidth,
-    maximum: wheelCenterOffset + projectedHalfWidth,
-  };
-}
-
-function canUseAnalyticPitWheels(geometry, centerState) {
-  const roadWidth = Number(centerState?.pitLaneRoadWidth);
-  if (!centerState?.inPitLane || !Number.isFinite(roadWidth) || roadWidth <= 0) return false;
-  const halfRoadWidth = roadWidth / 2;
-  return geometry.contactPatches.every((patch) => {
-    const range = patchPitOffsetRange(patch, centerState);
-    return range.minimum >= -halfRoadWidth - 0.001 && range.maximum <= halfRoadWidth + 0.001;
-  });
-}
-
-function analyticPitWheelState(patch, centerState) {
-  const range = patchPitOffsetRange(patch, centerState);
-  return {
-    id: patch.id,
-    x: patch.center.x,
-    y: patch.center.y,
-    signedOffset: centerState.mainTrackSignedOffset ?? centerState.signedOffset,
-    crossTrackError: centerState.mainTrackCrossTrackError ?? centerState.crossTrackError,
-    surface: centerState.surface,
-    onTrack: true,
-    inPitLane: true,
-    pitLanePart: centerState.pitLanePart ?? null,
-    pitBoxId: centerState.pitBoxId ?? null,
-    minimumSignedOffset: centerState.mainTrackSignedOffset ?? centerState.signedOffset,
-    maximumSignedOffset: centerState.mainTrackSignedOffset ?? centerState.signedOffset,
-    pitLaneMinimumSignedOffset: range.minimum,
-    pitLaneMaximumSignedOffset: range.maximum,
-    fullyOutsideWhiteLine: false,
-    outsideSide: 0,
-    sampledStates: [centerState],
-  };
-}
-
-export function getEffectiveSurface(wheels = []) {
-  if (!wheels.length) return 'track';
-  return wheels.reduce((surface, wheel) => (
-    priority(wheel.surface) > priority(surface) ? wheel.surface : surface
-  ), 'track');
-}
-
-export function isWholeCarOutsideTrackLimits(wheels = [], track, relaxedMargin = 0) {
-  if (!wheels.length || !track) {
-    return {
-      violating: false,
-      side: 0,
-      outsideBy: 0,
-    };
-  }
-  const trackLimit = track.width / 2 + relaxedMargin;
-  const right = wheels.every((wheel) => wheel.outsideSide === 1);
-  const left = wheels.every((wheel) => wheel.outsideSide === -1);
-  if (!right && !left) {
-    return {
-      violating: false,
-      side: 0,
-      outsideBy: 0,
-    };
-  }
-  const side = right ? 1 : -1;
-  const outsideBy = right
-    ? Math.min(...wheels.map((wheel) => wheel.minimumSignedOffset)) - trackLimit
-    : -trackLimit - Math.max(...wheels.map((wheel) => wheel.maximumSignedOffset));
-
-  return {
-    violating: outsideBy > 0,
-    side,
-    outsideBy: Math.max(0, outsideBy),
-  };
-}
-
-export function calculateWheelSurfaceState({ car, track, centerState: providedCenterState = null }) {
-  const geometry = getVehicleGeometryState(car);
-  const trackLimit = track.width / 2;
-  const centerState = providedCenterState ?? nearestTrackState(track, car, car.progress);
-  const useAnalyticPitSampling = canUseAnalyticPitWheels(geometry, centerState);
-  const useFullSampling = !useAnalyticPitSampling && Boolean(centerState.inPitLane || isNearPitConnector(track, centerState));
-  const wheels = useAnalyticPitSampling
-    ? geometry.contactPatches.map((patch) => analyticPitWheelState(patch, centerState))
-    : useFullSampling
-    ? geometry.contactPatches.map((patch) => {
-        const sampleState = (point) => nearestTrackState(track, point, car.progress);
-        const sampledStates = patchSamples(patch).map(sampleState);
-        const state = worstState(sampledStates);
-        const offsets = sampledStates.map((sample) => sample.signedOffset);
-        const outside = wheelFullyOutside(sampledStates, trackLimit);
-
-        return {
-          id: patch.id,
-          x: patch.center.x,
-          y: patch.center.y,
-          signedOffset: state.signedOffset,
-          crossTrackError: state.crossTrackError,
-          surface: state.surface,
-          onTrack: Boolean(state.onTrack),
-          inPitLane: Boolean(state.inPitLane),
-          pitLanePart: state.pitLanePart ?? null,
-          pitBoxId: state.pitBoxId ?? null,
-          minimumSignedOffset: Math.min(...offsets),
-          maximumSignedOffset: Math.max(...offsets),
-          fullyOutsideWhiteLine: outside.fullyOutsideWhiteLine,
-          outsideSide: outside.outsideSide,
-          sampledStates,
-        };
-      })
-    : geometry.contactPatches.map((patch) => analyticWheelState(patch, centerState, track, trackLimit));
-  const effectiveSurface = getEffectiveSurface(wheels);
-  const representative = wheels.reduce((best, wheel) => (
-    Math.abs(wheel.signedOffset) > Math.abs(best.signedOffset) ? wheel : best
-  ), wheels[0]);
-  const trackLimits = isWholeCarOutsideTrackLimits(wheels, track);
-
-  return {
-    wheels,
-    effectiveSurface,
-    trackLimits,
-    sampleMode: useAnalyticPitSampling ? 'pit-analytic' : useFullSampling ? 'full' : 'analytic',
-    representativeState: representative ? {
-      ...centerState,
-      surface: effectiveSurface,
-      onTrack: wheels.every((wheel) => wheel.onTrack || wheel.inPitLane),
-      inPitLane: wheels.every((wheel) => wheel.inPitLane),
-      signedOffset: representative.signedOffset,
-      crossTrackError: representative.crossTrackError,
-    } : nearestTrackState(track, car, car.progress),
-  };
-}
-
-export function applyWheelSurfaceState(car, track, options = {}) {
-  const geometry = getVehicleGeometryState(car);
-  const cacheKey = {
-    track,
-    geometrySignature: geometry.signature,
-    centerSignature: centerStateSignature(options.centerState),
-  };
-  const cached = car.wheelSurfaceCache;
-  if (
-    cached?.track === cacheKey.track &&
-    cached.geometrySignature === cacheKey.geometrySignature &&
-    cached.centerSignature === cacheKey.centerSignature
-  ) {
-    car.wheelStates = cached.result.wheels;
-    car.trackLimitState = cached.result.trackLimits;
-    car.trackState = cached.trackState;
-    return cached.result;
-  }
-
-  const result = calculateWheelSurfaceState({ car, track, centerState: options.centerState });
-  car.wheelStates = result.wheels;
-  car.trackLimitState = result.trackLimits;
-  car.trackState = {
-    ...result.representativeState,
-    wheelSurface: result.effectiveSurface,
-  };
-  car.wheelSurfaceCache = {
-    ...cacheKey,
-    result,
-    trackState: car.trackState,
-  };
-  return result;
-}
+export * from './vehicle/wheelSurface.js';