@inventure71/paddockjs 3.0.0 → 4.1.0

package/src/environment/sensors/surfaceRays.js

@@ -12,11 +12,21 @@ 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));
+  const requested = [];
+  let hasKerb = false;
+  let hasIllegalSurface = false;
+  for (let index = 0; index < channels.length; index += 1) {
+    const channel = channels[index];
+    if (channel === 'kerb' && !hasKerb) {
+      requested.push(channel);
+      hasKerb = true;
+    } else if (channel === 'illegalSurface' && !hasIllegalSurface) {
+      requested.push(channel);
+      hasIllegalSurface = true;
+    }
+  }
+  return requested;
 }
 
 export function createSurfaceMiss(lengthMeters) {
@@ -38,15 +48,15 @@ export function estimateSurfaceHits(
   { precision = 'driver', sharedRayQuery = null } = {},
 ) {
   const requested = requestedSurfaceChannels(channels);
-  const misses = Object.fromEntries(requested.map((channel) => [channel, createSurfaceMiss(ray.lengthMeters)]));
+  const hits = prepareSurfaceHitContainer(sharedRayQuery, ray.lengthMeters);
   if (!requested.length || !Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
-    return misses;
+    return hits;
   }
 
   const originState = context?.precision === precision
     ? context.originState
     : nearestRayTrackState(snapshot.track, car, origin, car.progress, precision);
-  const originHits = surfaceHitsAtOrigin(requested, originState);
+  writeSurfaceHitsAtOrigin(hits, requested, originState);
   const indexedHits = estimateIndexedSurfaceHits({
     car,
     track: snapshot.track,
@@ -57,8 +67,9 @@ export function estimateSurfaceHits(
     originState,
     precision,
     sharedRayQuery,
+    hits,
   });
-  if (indexedHits) return { ...misses, ...indexedHits, ...originHits };
+  if (indexedHits) return indexedHits;
   const analyticHits = estimateAnalyticSurfaceHits({
     car,
     track: snapshot.track,
@@ -66,15 +77,13 @@ export function estimateSurfaceHits(
     vector,
     requested,
     originState,
+    hits,
   });
-  if (analyticHits) return { ...misses, ...analyticHits, ...originHits };
+  if (analyticHits) return analyticHits;
 
-  const pending = new Set(requested);
-  Object.keys(originHits).forEach((channel) => {
-    misses[channel] = originHits[channel];
-    pending.delete(channel);
-  });
-  if (pending.size === 0) return misses;
+  let pendingKerb = requestedIncludes(requested, 'kerb') && !matchesSurfaceChannel('kerb', originState);
+  let pendingIllegalSurface = requestedIncludes(requested, 'illegalSurface') && !matchesSurfaceChannel('illegalSurface', originState);
+  if (!pendingKerb && !pendingIllegalSurface) return hits;
   const maxDistance = metersToSimUnits(ray.lengthMeters);
   const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
   let previousDistance = 0;
@@ -82,60 +91,78 @@ export function estimateSurfaceHits(
 
   for (let distance = 0; distance <= maxDistance; distance += step) {
     const state = nearestRayTrackState(snapshot.track, car, pointOnRay(origin, vector, distance), car.progress, precision);
-    for (const channel of [...pending]) {
-      if (!matchesSurfaceChannel(channel, state)) continue;
+    if (pendingKerb && matchesSurfaceChannel('kerb', state)) {
       const hitDistance = previousState
-        ? refineSurfaceTransition(snapshot.track, car, origin, vector, car.progress, previousDistance, distance, channel, refineStepsForPrecision(precision))
+        ? refineSurfaceTransition(snapshot.track, car, origin, vector, car.progress, previousDistance, distance, 'kerb', refineStepsForPrecision(precision))
         : distance;
-      misses[channel] = {
-        hit: true,
-        distanceMeters: simUnitsToMeters(hitDistance),
-        surface: state.surface ?? null,
-      };
-      pending.delete(channel);
+      writeSurfaceHit(hits.kerb, simUnitsToMeters(hitDistance), state.surface ?? null);
+      pendingKerb = false;
     }
-    if (pending.size === 0) break;
+    if (pendingIllegalSurface && matchesSurfaceChannel('illegalSurface', state)) {
+      const hitDistance = previousState
+        ? refineSurfaceTransition(snapshot.track, car, origin, vector, car.progress, previousDistance, distance, 'illegalSurface', refineStepsForPrecision(precision))
+        : distance;
+      writeSurfaceHit(hits.illegalSurface, simUnitsToMeters(hitDistance), state.surface ?? null);
+      pendingIllegalSurface = false;
+    }
+    if (!pendingKerb && !pendingIllegalSurface) break;
     previousDistance = distance;
     previousState = state;
   }
 
-  return misses;
+  return hits;
 }
 
-function surfaceHitsAtOrigin(requested, originState) {
-  const hits = {};
-  requested.forEach((channel) => {
-    if (!matchesSurfaceChannel(channel, originState)) return;
-    hits[channel] = {
-      hit: true,
-      distanceMeters: 0,
-      surface: originState.surface ?? null,
-    };
-  });
+function prepareSurfaceHitContainer(cache, lengthMeters) {
+  const hits = cache
+    ? (cache.surfaceHits ?? {})
+    : {};
+  if (cache) cache.surfaceHits = hits;
+  hits.kerb = writeSurfaceMiss(hits.kerb ?? {}, lengthMeters);
+  hits.illegalSurface = writeSurfaceMiss(hits.illegalSurface ?? {}, lengthMeters);
   return hits;
 }
 
-function estimateAnalyticSurfaceHits({ car, track, ray, vector, requested, originState }) {
+function writeSurfaceMiss(target, lengthMeters) {
+  target.hit = false;
+  target.distanceMeters = lengthMeters;
+  target.surface = null;
+  return target;
+}
+
+function writeSurfaceHit(target, distanceMeters, surface) {
+  target.hit = true;
+  target.distanceMeters = distanceMeters;
+  target.surface = surface ?? null;
+  return target;
+}
+
+function writeSurfaceHitsAtOrigin(hits, requested, originState) {
+  for (let index = 0; index < requested.length; index += 1) {
+    const channel = requested[index];
+    if (!matchesSurfaceChannel(channel, originState)) continue;
+    writeSurfaceHit(hits[channel], 0, originState.surface ?? null);
+  }
+}
+
+function estimateAnalyticSurfaceHits({ car, track, ray, vector, requested, originState, hits }) {
   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),
-  ]));
+  if (Math.abs(lateral) < 0.08) return hits;
 
   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) => {
+  for (let index = 0; index < requested.length; index += 1) {
+    const channel = requested[index];
     if (channel === 'kerb') {
-      hits[channel] = hitAbsOffsetBand({
+      hitAbsOffsetBand(hits.kerb, {
         offset,
         lateral,
         minAbsOffset: trackHalfWidth,
@@ -145,7 +172,7 @@ function estimateAnalyticSurfaceHits({ car, track, ray, vector, requested, origi
         surface: 'kerb',
       });
     } else if (channel === 'illegalSurface') {
-      hits[channel] = hitAbsOffsetBand({
+      hitAbsOffsetBand(hits.illegalSurface, {
         offset,
         lateral,
         minAbsOffset: kerbOuter,
@@ -155,12 +182,12 @@ function estimateAnalyticSurfaceHits({ car, track, ray, vector, requested, origi
         surface: surfaceBeyondKerb(track, offset, lateral, maxDistance),
       });
     }
-  });
+  }
 
   return hits;
 }
 
-function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested, originState, precision, sharedRayQuery }) {
+function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested, originState, precision, sharedRayQuery, hits }) {
   if (!originState || car.inPitLane || originState.inPitLane) return null;
   if (!usesMainTrackOnlyRays(car) && isNearPitConnector(track, originState)) return null;
 
@@ -177,24 +204,24 @@ function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested
     sharedRayQuery,
   );
   if (!boundaries.available) return null;
-  const hits = {};
 
-  for (const channel of requested) {
+  for (let index = 0; index < requested.length; index += 1) {
+    const channel = requested[index];
     if (matchesSurfaceChannel(channel, originState)) {
-      hits[channel] = { hit: true, distanceMeters: 0, surface: originState.surface ?? null };
+      writeSurfaceHit(hits[channel], 0, originState.surface ?? null);
       continue;
     }
 
     const boundaryDistance = channel === 'kerb'
-      ? minFinite(boundaries.trackEdgeDistance, boundaries.kerbOuterDistance)
+      ? minFinite2(boundaries.trackEdgeDistance, boundaries.kerbOuterDistance)
       : boundaries.kerbOuterDistance;
     if (boundaryDistance == null) {
       if (usesMainTrackOnlyRays(car) && channel === 'illegalSurface') {
-        hits[channel] = createSurfaceMiss(ray.lengthMeters);
+        writeSurfaceMiss(hits[channel], ray.lengthMeters);
         continue;
       }
       if (canSampleRecoverySurface(track, originState, vector)) return null;
-      hits[channel] = createSurfaceMiss(ray.lengthMeters);
+      writeSurfaceMiss(hits[channel], ray.lengthMeters);
       continue;
     }
     const hitDistance = usesMainTrackOnlyRays(car) || refineStepsForPrecision(precision) <= 0 || precision === 'debug'
@@ -211,13 +238,13 @@ function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested
         precision,
       });
     if (hitDistance == null) return null;
-    hits[channel] = {
-      hit: true,
-      distanceMeters: simUnitsToMeters(hitDistance),
-      surface: channel === 'kerb'
+    writeSurfaceHit(
+      hits[channel],
+      simUnitsToMeters(hitDistance),
+      channel === 'kerb'
         ? 'kerb'
         : surfaceBeyondKerb(track, originState.signedOffset ?? 0, lateral, metersToSimUnits(ray.lengthMeters)),
-    };
+    );
   }
 
   return hits;
@@ -249,35 +276,28 @@ function usesMainTrackOnlyRays(car) {
   return car?.interaction?.profile === 'batch-training';
 }
 
-function hitAbsOffsetBand({ offset, lateral, minAbsOffset, maxAbsOffset, maxDistance, lengthMeters, surface }) {
+function hitAbsOffsetBand(target, { offset, lateral, minAbsOffset, maxAbsOffset, maxDistance, lengthMeters, surface }) {
   const currentAbs = Math.abs(offset);
   if (currentAbs >= minAbsOffset && currentAbs <= maxAbsOffset) {
-    return { hit: true, distanceMeters: 0, surface };
+    return writeSurfaceHit(target, 0, surface);
   }
 
-  const candidates = [
-    distanceToOffset(minAbsOffset, offset, lateral),
-    distanceToOffset(-minAbsOffset, offset, lateral),
-  ].filter((distance) => Number.isFinite(distance) && distance >= 0 && distance <= maxDistance);
-
+  let distance = Infinity;
+  distance = nearestValidBandDistance(distance, distanceToOffset(minAbsOffset, offset, lateral), offset, lateral, minAbsOffset, maxAbsOffset, maxDistance);
+  distance = nearestValidBandDistance(distance, distanceToOffset(-minAbsOffset, offset, lateral), offset, lateral, minAbsOffset, maxAbsOffset, maxDistance);
   if (Number.isFinite(maxAbsOffset)) {
-    candidates.push(
-      ...[
-        distanceToOffset(maxAbsOffset, offset, lateral),
-        distanceToOffset(-maxAbsOffset, offset, lateral),
-      ].filter((distance) => Number.isFinite(distance) && distance >= 0 && distance <= maxDistance),
-    );
+    distance = nearestValidBandDistance(distance, distanceToOffset(maxAbsOffset, offset, lateral), offset, lateral, minAbsOffset, maxAbsOffset, maxDistance);
+    distance = nearestValidBandDistance(distance, distanceToOffset(-maxAbsOffset, offset, lateral), offset, lateral, minAbsOffset, maxAbsOffset, 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 writeSurfaceMiss(target, lengthMeters);
+  return writeSurfaceHit(target, simUnitsToMeters(distance), surface);
+}
 
-  if (!Number.isFinite(distance)) return createSurfaceMiss(lengthMeters);
-  return { hit: true, distanceMeters: simUnitsToMeters(distance), surface };
+function nearestValidBandDistance(current, candidate, offset, lateral, minAbsOffset, maxAbsOffset, maxDistance) {
+  if (!Number.isFinite(candidate) || candidate < 0 || candidate > maxDistance || candidate >= current) return current;
+  const nextAbs = Math.abs(offset + lateral * candidate);
+  return nextAbs >= minAbsOffset - 1e-6 && nextAbs <= maxAbsOffset + 1e-6 ? candidate : current;
 }
 
 function distanceToOffset(targetOffset, offset, lateral) {
@@ -286,12 +306,16 @@ function distanceToOffset(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 kerbOuter = track.width / 2 + (track.kerbWidth ?? 0);
+  const positiveDistance = distanceToOffset(kerbOuter, offset, lateral);
+  const negativeDistance = distanceToOffset(-kerbOuter, offset, lateral);
+  let hitDistance = Infinity;
+  if (Number.isFinite(positiveDistance) && positiveDistance >= 0 && positiveDistance <= maxDistance) {
+    hitDistance = positiveDistance;
+  }
+  if (Number.isFinite(negativeDistance) && negativeDistance >= 0 && negativeDistance <= maxDistance && negativeDistance < hitDistance) {
+    hitDistance = negativeDistance;
+  }
   const hitAbs = Math.abs(offset + lateral * hitDistance);
   return hitAbs <= gravelOuter ? 'gravel' : 'grass';
 }
@@ -342,10 +366,26 @@ function refineStepsForPrecision(precision) {
 
 function matchesSurfaceChannel(channel, state) {
   if (channel === 'kerb') return state.surface === 'kerb';
-  if (channel === 'illegalSurface') return !LEGAL_SURFACES.has(state.surface) && state.surface !== 'barrier';
+  if (channel === 'illegalSurface') return !isLegalSurface(state.surface) && state.surface !== 'barrier';
+  return false;
+}
+
+function requestedIncludes(requested, channel) {
+  for (let index = 0; index < requested.length; index += 1) {
+    if (requested[index] === channel) return true;
+  }
   return false;
 }
 
+function isLegalSurface(surface) {
+  return surface === 'track' ||
+    surface === 'kerb' ||
+    surface === 'pit-entry' ||
+    surface === 'pit-lane' ||
+    surface === 'pit-exit' ||
+    surface === 'pit-box';
+}
+
 function canSampleRecoverySurface(track, originState, vector) {
   if (!canUseIndexedRecoveryRayApproximation(track, originState)) return false;
   const kerbOuter = track.width / 2 + (track.kerbWidth ?? 0);
@@ -362,7 +402,8 @@ function nearestRayTrackState(track, car, point, progressHint, precision = 'debu
   });
 }
 
-function minFinite(...values) {
-  const minimum = Math.min(...values.filter((value) => Number.isFinite(value)));
-  return Number.isFinite(minimum) ? minimum : null;
+function minFinite2(first, second) {
+  if (!Number.isFinite(first)) return Number.isFinite(second) ? second : null;
+  if (!Number.isFinite(second)) return first;
+  return first <= second ? first : second;
 }

package/src/environment/sensors/trackRays.js

@@ -1,4 +1,6 @@
 import { nearestTrackState } from '../../simulation/track/trackModel.js';
+import { normalizeAngle } from '../../simulation/simMath.js';
+import { offsetTrackPoint, pointAt, sampleIndexAtDistance } from '../../simulation/track/spatialQueries.js';
 import { pitOverrideAllowedForCar } from '../../simulation/track/trackStatePolicy.js';
 import { metersToSimUnits, simUnitsToMeters } from '../../simulation/units.js';
 import {
@@ -12,13 +14,18 @@ import { canUseIndexedRecoveryRayApproximation } from './rayGuards.js';
 import { degreesToRadians, getCarRayOrigin, getCarRayVector, pointOnRay } from './rayGeometry.js';
 import { findIndexedTrackBandBoundaries } from './indexedRayBands.js';
 
+const RAY_TRACK_STATE_REUSE_POSITION_TOLERANCE = metersToSimUnits(1);
+const RAY_TRACK_STATE_REUSE_PROGRESS_TOLERANCE = metersToSimUnits(0.25);
+const RAY_TRACK_STATE_REUSE_HEADING_TOLERANCE = 0.02;
+
 export function createTrackRayContext(car, snapshot, origin, precision = 'debug') {
   if (!Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
     return { origin, originState: null, precision };
   }
+  const reusedOriginState = reusableRayOriginState(snapshot.track, car, origin);
   return {
     origin,
-    originState: nearestRayTrackState(snapshot.track, car, origin, car.progress, precision),
+    originState: reusedOriginState ?? nearestRayTrackState(snapshot.track, car, origin, car.progress, precision),
     precision,
   };
 }
@@ -296,6 +303,113 @@ function nearestRayTrackState(track, car, point, progressHint, precision = 'debu
   });
 }
 
+function reusableRayOriginState(track, car, origin) {
+  const synthesizedState = synthesizedMainRoadRayOriginState(track, car, origin);
+  if (synthesizedState) return synthesizedState;
+  const trackState = car?.trackState;
+  if (!trackState || trackState.inPitLane) return null;
+  const mainRoadEdge = track.width / 2 + (track.kerbWidth ?? 0);
+  if (!Number.isFinite(trackState.crossTrackError) || trackState.crossTrackError > mainRoadEdge) return null;
+  if (
+    typeof car?.trackStatePoseX === 'number' &&
+    typeof car?.trackStatePoseY === 'number' &&
+    typeof car?.trackStatePoseHeading === 'number'
+  ) {
+    if (
+      car.trackStatePoseX !== car.x ||
+      car.trackStatePoseY !== car.y ||
+      car.trackStatePoseHeading !== car.heading
+    ) {
+      return null;
+    }
+    if (!Number.isInteger(trackState.segmentId) && Number.isFinite(trackState.distance)) {
+      trackState.segmentId = sampleIndexAtDistance(track, trackState.distance);
+    }
+  } else {
+    if (!Number.isFinite(trackState.distance) || !Number.isFinite(trackState.signedOffset)) return null;
+    const base = pointAt(track, trackState.distance);
+    const projected = offsetTrackPoint(base, trackState.signedOffset);
+    const dx = (origin?.x ?? car?.x ?? 0) - projected.x;
+    const dy = (origin?.y ?? car?.y ?? 0) - projected.y;
+    if ((dx * dx) + (dy * dy) > RAY_TRACK_STATE_REUSE_POSITION_TOLERANCE * RAY_TRACK_STATE_REUSE_POSITION_TOLERANCE) {
+      return null;
+    }
+    if (wrappedDistanceDelta(trackState.distance, car?.progress, track.length) > RAY_TRACK_STATE_REUSE_PROGRESS_TOLERANCE) {
+      return null;
+    }
+    if (Math.abs(normalizeAngle((trackState.heading ?? base.heading) - base.heading)) > RAY_TRACK_STATE_REUSE_HEADING_TOLERANCE) {
+      return null;
+    }
+    const segmentId = trackState.segmentId ?? sampleIndexAtDistance(track, trackState.distance);
+    return {
+      segmentId,
+      x: base.x,
+      y: base.y,
+      distance: base.distance,
+      heading: base.heading,
+      normalX: base.normalX,
+      normalY: base.normalY,
+      curvature: base.curvature,
+      signedOffset: trackState.signedOffset,
+      crossTrackError: trackState.crossTrackError,
+      surface: trackState.surface ?? 'track',
+      onTrack: trackState.surface === 'track' || trackState.surface === 'kerb',
+      distanceSquared: trackState.distanceSquared,
+      inPitLane: false,
+      pitLanePart: null,
+      pitBoxId: null,
+      mainTrackSignedOffset: trackState.mainTrackSignedOffset,
+      mainTrackCrossTrackError: trackState.mainTrackCrossTrackError,
+      pitLaneCrossTrackError: trackState.pitLaneCrossTrackError,
+    };
+  }
+  return trackState;
+}
+
+function synthesizedMainRoadRayOriginState(track, car, origin) {
+  if (!Number.isFinite(car?.progress) || !Number.isFinite(car?.signedOffset)) return null;
+  if (car?.inPitLane || car?.pitLanePart) return null;
+  const crossTrackError = Math.abs(car.signedOffset);
+  const mainRoadEdge = track.width / 2 + (track.kerbWidth ?? 0);
+  if (crossTrackError > mainRoadEdge) return null;
+  const base = pointAt(track, car.progress);
+  const projected = offsetTrackPoint(base, car.signedOffset);
+  const dx = (origin?.x ?? car?.x ?? 0) - projected.x;
+  const dy = (origin?.y ?? car?.y ?? 0) - projected.y;
+  if ((dx * dx) + (dy * dy) > RAY_TRACK_STATE_REUSE_POSITION_TOLERANCE * RAY_TRACK_STATE_REUSE_POSITION_TOLERANCE) {
+    return null;
+  }
+  const segmentId = car?.trackState?.segmentId ?? sampleIndexAtDistance(track, car.progress);
+  return {
+    segmentId,
+    x: base.x,
+    y: base.y,
+    distance: base.distance,
+    heading: base.heading,
+    normalX: base.normalX,
+    normalY: base.normalY,
+    curvature: base.curvature,
+    signedOffset: car.signedOffset,
+    crossTrackError,
+    surface: crossTrackError <= track.width / 2 ? 'track' : 'kerb',
+    onTrack: true,
+    distanceSquared: car?.trackState?.distanceSquared,
+    inPitLane: false,
+    pitLanePart: null,
+    pitBoxId: null,
+    mainTrackSignedOffset: car?.trackState?.mainTrackSignedOffset,
+    mainTrackCrossTrackError: car?.trackState?.mainTrackCrossTrackError,
+    pitLaneCrossTrackError: car?.trackState?.pitLaneCrossTrackError,
+  };
+}
+
+function wrappedDistanceDelta(first, second, totalLength) {
+  if (!Number.isFinite(first) || !Number.isFinite(second)) return Infinity;
+  if (!Number.isFinite(totalLength) || totalLength <= 0) return Math.abs(first - second);
+  const delta = Math.abs(first - second);
+  return Math.min(delta, totalLength - delta);
+}
+
 function refineStepsForPrecision(precision) {
   return precision === 'debug' ? TRACK_RAY_REFINE_STEPS : DRIVER_RAY_REFINE_STEPS;
 }

package/src/index.d.ts

@@ -337,6 +337,32 @@ export interface F1SimulatorTheme extends Omit<F1SimulatorThemePackage, 'compone
   >;
 }
 
+export type ResolvedPaddockThemeMode = Exclude<PaddockThemeMode, 'system'>;
+
+export interface ResolvedPaddockThemePackage {
+  tokens: Record<ResolvedPaddockThemeMode, F1SimulatorThemeTokens>;
+  components: Record<string, Partial<Record<string, PaddockThemeTokenName>>>;
+}
+
+export interface ResolvedPaddockTheme {
+  mode: PaddockThemeMode;
+  activeMode: ResolvedPaddockThemeMode;
+  use: string;
+  tokens: Record<ResolvedPaddockThemeMode, F1SimulatorThemeTokens>;
+  activeTokens: F1SimulatorThemeTokens;
+  components: Record<string, Partial<Record<string, PaddockThemeTokenName>>>;
+  themes: Record<string, ResolvedPaddockThemePackage>;
+  componentThemes: Record<string, PaddockThemeSelector>;
+  teamThemes: Record<string, PaddockThemeSelector>;
+  light: F1SimulatorThemeTokens;
+  dark: F1SimulatorThemeTokens;
+}
+
+export interface PaddockThemeSyncOptions {
+  attribute?: string;
+  map?: Record<string, PaddockThemeMode | F1SimulatorTheme>;
+}
+
 export interface F1SimulatorUiOptions {
   layoutPreset?: LayoutPreset;
   cameraControls?: CameraControlsMode;
@@ -1000,6 +1026,10 @@ export interface F1MountedSimulator {
   readonly expert: F1SimulatorExpertApi | null;
   destroy(): void;
   restart(nextOptions?: F1SimulatorRestartOptions): void;
+  setTheme(theme: F1SimulatorTheme): ResolvedPaddockTheme;
+  setThemeMode(mode: PaddockThemeMode): ResolvedPaddockTheme;
+  getTheme(): ResolvedPaddockTheme;
+  syncThemeFrom(source: Element, options?: PaddockThemeSyncOptions): () => void;
   selectDriver(driverId: string): void;
   setSafetyCarDeployed(deployed: boolean): void;
   setRedFlagDeployed(deployed: boolean): void;
@@ -1040,6 +1070,10 @@ export interface PaddockSimulatorController {
   start(): Promise<PaddockSimulatorController>;
   destroy(): void;
   restart(nextOptions?: F1SimulatorRestartOptions): void;
+  setTheme(theme: F1SimulatorTheme): ResolvedPaddockTheme;
+  setThemeMode(mode: PaddockThemeMode): ResolvedPaddockTheme;
+  getTheme(): ResolvedPaddockTheme;
+  syncThemeFrom(source: Element, options?: PaddockThemeSyncOptions): () => void;
   selectDriver(driverId: string): void;
   setSafetyCarDeployed(deployed: boolean): void;
   setRedFlagDeployed(deployed: boolean): void;
@@ -1062,10 +1096,13 @@ export interface PaddockSimulatorController {
 export const CHAMPIONSHIP_ENTRY_BLUEPRINTS: ChampionshipEntryBlueprint[];
 export const DEMO_PROJECT_DRIVERS: SimulatorDriver[];
 export const DEFAULT_F1_SIMULATOR_ASSETS: Required<F1SimulatorAssets>;
+export const DEFAULT_PADDOCK_THEME: F1SimulatorTheme;
 export const PADDOCK_SIMULATOR_PRESETS: Record<PaddockPresetName, {
   ui?: F1SimulatorUiOptions;
   theme?: F1SimulatorTheme;
 }>;
+export const PADDOCK_THEME_CSS_VARIABLES: Record<PaddockThemeTokenName, string>;
+export const PADDOCK_THEME_TOKEN_KEYS: readonly PaddockThemeTokenName[];
 
 export const REAL_F1_CAR_LENGTH_METERS: number;
 export const SIM_UNITS_PER_METER: number;
@@ -1081,6 +1118,12 @@ export function normalizeSimulatorDrivers(
   drivers: SimulatorDriver[],
   options?: { entries?: ChampionshipEntryBlueprint[]; caller?: string },
 ): NormalizedSimulatorDriver[];
+export function resolvePaddockTheme(theme?: F1SimulatorTheme): ResolvedPaddockTheme;
+export function applyPaddockTheme(
+  root: Element,
+  theme?: F1SimulatorTheme | ResolvedPaddockTheme,
+  context?: { selectedTeamId?: string | null },
+): void;
 
 export function metersToSimUnits(meters: number): number;
 export function simUnitsToMeters(simUnits: number): number;

package/src/index.js

@@ -2,6 +2,7 @@ import './styles.css';
 import { F1SimulatorApp } from './app/F1SimulatorApp.js';
 import { resolveF1SimulatorOptions } from './config/defaultOptions.js';
 import { mergeRestartOptions } from './config/restartOptions.js';
+import { createThemeSync, resolveRuntimeThemeModeOptions, resolveRuntimeThemeOptions } from './api/runtimeTheme.js';
 import { createF1SimulatorShell } from './ui/shellTemplate.js';
 export {
   createPaddockSimulator,
@@ -30,7 +31,14 @@ export {
 } from './data/championship.js';
 export { DEMO_PROJECT_DRIVERS } from './data/demoDrivers.js';
 export { DEFAULT_F1_SIMULATOR_ASSETS } from './config/defaultAssets.js';
-export { PADDOCK_SIMULATOR_PRESETS } from './config/defaultOptions.js';
+export {
+  DEFAULT_PADDOCK_THEME,
+  PADDOCK_SIMULATOR_PRESETS,
+  PADDOCK_THEME_CSS_VARIABLES,
+  PADDOCK_THEME_TOKEN_KEYS,
+  applyPaddockTheme,
+  resolvePaddockTheme,
+} from './config/defaultOptions.js';
 export { createPaddockDriverControllerLoop } from './environment/controllerLoop.js';
 export { normalizeSimulatorDrivers } from './data/normalizeDrivers.js';
 export { createProceduralTrack } from './simulation/track/trackModel.js';
@@ -76,7 +84,7 @@ export async function mountF1Simulator(root, options = {}) {
     return resolvedOptions;
   };
 
-  return {
+  const mountedSimulator = {
     get expert() {
       return app.expert ?? null;
     },
@@ -89,6 +97,22 @@ export async function mountF1Simulator(root, options = {}) {
       app.restart(nextResolvedOptions);
       resolvedOptions = nextResolvedOptions;
     },
+    setTheme(themeInput = {}) {
+      const nextResolvedOptions = resolveRuntimeThemeOptions(syncResolvedRuntimeOptions(), themeInput);
+      resolvedOptions = nextResolvedOptions;
+      return app.setTheme(nextResolvedOptions.theme);
+    },
+    setThemeMode(mode) {
+      const nextResolvedOptions = resolveRuntimeThemeModeOptions(syncResolvedRuntimeOptions(), mode);
+      resolvedOptions = nextResolvedOptions;
+      return app.setTheme(nextResolvedOptions.theme);
+    },
+    getTheme() {
+      return resolvedOptions.theme;
+    },
+    syncThemeFrom(source, options = {}) {
+      return createThemeSync(mountedSimulator, source, options);
+    },
     selectDriver(driverId) {
       app.selectCar(driverId, { focus: true });
     },
@@ -142,4 +166,5 @@ export async function mountF1Simulator(root, options = {}) {
       return app.getSnapshot();
     },
   };
+  return mountedSimulator;
 }

package/src/placeholder/index.d.ts

@@ -0,0 +1,11 @@
+export type PaddockLoadingPlaceholderVariant = 'lights' | 'custom';
+
+export interface PaddockLoadingPlaceholderOptions {
+  label?: string;
+  detail?: string;
+  className?: string;
+  variant?: PaddockLoadingPlaceholderVariant;
+  attributes?: Record<string, string | number | boolean | null | undefined>;
+}
+
+export function createPaddockLoadingPlaceholder(options?: PaddockLoadingPlaceholderOptions): string;