@inventure71/paddockjs 2.0.1 → 3.0.0

package/src/config/timingGapMode.js

@@ -0,0 +1,13 @@
+export const TIMING_GAP_MODES = new Set(['interval', 'leader']);
+
+export function normalizeTimingGapMode(value) {
+  return value === 'leader' ? 'leader' : 'interval';
+}
+
+export function getTimingGapModeLabel(mode) {
+  return normalizeTimingGapMode(mode) === 'leader' ? 'Gap' : 'Int';
+}
+
+export function getNextTimingGapMode(mode) {
+  return normalizeTimingGapMode(mode) === 'leader' ? 'interval' : 'leader';
+}

package/src/config/urlOptions.js

@@ -0,0 +1,25 @@
+const SAFE_ABSOLUTE_URL_PROTOCOLS = new Set(['http:', 'https:']);
+
+export function normalizePublicUrlOption(value, fallback) {
+  const fallbackValue = typeof fallback === 'string' && fallback.trim() !== ''
+    ? fallback.trim()
+    : '';
+  if (typeof value !== 'string') return fallbackValue;
+
+  const candidate = value.trim();
+  if (candidate === '') return fallbackValue;
+  if (/[\u0000-\u001F\u007F]/.test(candidate)) return fallbackValue;
+  if (candidate.includes('\\')) return fallbackValue;
+  if (candidate.startsWith('#')) return candidate;
+  if (candidate.startsWith('//')) return fallbackValue;
+
+  const schemeMatch = /^[A-Za-z][A-Za-z0-9+.-]*:/.exec(candidate);
+  if (!schemeMatch) return candidate;
+
+  try {
+    const url = new URL(candidate);
+    return SAFE_ABSOLUTE_URL_PROTOCOLS.has(url.protocol) ? candidate : fallbackValue;
+  } catch {
+    return fallbackValue;
+  }
+}

package/src/data/championship.js

@@ -1,6 +1,7 @@
 import { DriverData } from './driverData.js';
 import { DEMO_PROJECT_DRIVERS } from './demoDrivers.js';
 import { VehicleData } from './vehicleData.js';
+import { DEFAULT_DARK_THEME_TOKENS, normalizeCssColorToken } from '../config/themeOptions.js';
 
 export { DriverData, DRIVER_STAT_DEFINITIONS } from './driverData.js';
 export { VehicleData, VEHICLE_STAT_DEFINITIONS } from './vehicleData.js';
@@ -187,7 +188,7 @@ function normalizeTeam(team, driver, timingCode) {
     ...source,
     id,
     name,
-    color: source.color ?? driver.color,
+    color: normalizeCssColorToken(source.color ?? driver.color, driver.color),
     icon: source.icon ?? normalizeTeamIcon(source.name ?? source.id ?? timingCode ?? driver.name),
   };
 }
@@ -201,22 +202,26 @@ export function buildChampionshipDriverGrid(drivers = DEMO_PROJECT_DRIVERS, entr
   const usedTimingCodes = new Set();
 
   return drivers.map((driver, index) => {
+    const safeDriver = {
+      ...driver,
+      color: normalizeCssColorToken(driver.color, DEFAULT_DARK_THEME_TOKENS.primary),
+    };
     const entry = {
-      ...(blueprintByDriverId.get(driver.id) ?? {}),
-      ...(entryByDriverId.get(driver.id) ?? {}),
+      ...(blueprintByDriverId.get(safeDriver.id) ?? {}),
+      ...(entryByDriverId.get(safeDriver.id) ?? {}),
     };
-    const timingCode = pickUniqueTimingCode(entry.timingName ?? driver.timingName ?? driver.name ?? driver.code, usedTimingCodes);
-    const driverNumber = entry.driverNumber ?? driver.driverNumber ?? index + 1;
-    const driverArgs = buildDriverConstructorArgs({ driverId: driver.id, ...entry });
-    const vehicleArgs = buildVehicleConstructorArgs({ driverId: driver.id, ...entry });
+    const timingCode = pickUniqueTimingCode(entry.timingName ?? safeDriver.timingName ?? safeDriver.name ?? safeDriver.code, usedTimingCodes);
+    const driverNumber = entry.driverNumber ?? safeDriver.driverNumber ?? index + 1;
+    const driverArgs = buildDriverConstructorArgs({ driverId: safeDriver.id, ...entry });
+    const vehicleArgs = buildVehicleConstructorArgs({ driverId: safeDriver.id, ...entry });
 
     return {
-      ...driver,
+      ...safeDriver,
       code: timingCode,
       timingCode,
       raceName: timingCode,
       driverNumber,
-      team: normalizeTeam(entry.team, driver, timingCode),
+      team: normalizeTeam(entry.team, safeDriver, timingCode),
       pace: driverArgs.pace,
       racecraft: driverArgs.racecraft,
       consistency: driverArgs.consistency,

package/src/environment/controllerLoop.js

@@ -168,8 +168,7 @@ export function createPaddockDriverControllerLoop({
 
   function stop() {
     running = false;
-    if (scheduled && typeof scheduled.cancel === 'function') scheduled.cancel();
-    else if (typeof scheduled === 'number' && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(scheduled);
+    cancelScheduled(scheduled);
     scheduled = null;
   }
 
@@ -250,9 +249,24 @@ function now() {
     : Date.now();
 }
 
+function cancelScheduled(handle) {
+  if (handle == null) return;
+  if (typeof handle.cancel === 'function') {
+    handle.cancel();
+    return;
+  }
+  if (typeof handle === 'number') {
+    if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(handle);
+    if (typeof clearTimeout === 'function') clearTimeout(handle);
+  }
+}
+
 function defaultScheduler() {
   if (typeof requestAnimationFrame === 'function') {
-    return (callback) => requestAnimationFrame(callback);
+    return (callback) => {
+      const id = requestAnimationFrame(callback);
+      return { cancel: () => cancelAnimationFrame(id) };
+    };
   }
   return (callback) => {
     const id = setTimeout(callback, 0);

package/src/environment/index.d.ts

@@ -1,5 +1,5 @@
 export type TireCompound = 'S' | 'M' | 'H';
-export type PaddockPhysicsMode = 'arcade' | 'simulator';
+export type PaddockPhysicsMode = 'arcade' | 'advanced';
 export type PaddockProceduralTrackProfile = 'race' | 'training-short' | 'training-medium' | 'training-technical';
 
 export interface PaddockProceduralTrackOptions {
@@ -478,7 +478,6 @@ export interface PaddockEnvironmentOptions {
   seed?: number;
   trackSeed?: number;
   trackGeneration?: PaddockProceduralTrackOptions;
-  trackQueryIndex?: boolean;
   totalLaps?: number;
   frameSkip?: number;
   physicsMode?: PaddockPhysicsMode;

package/src/environment/options.js

@@ -8,7 +8,7 @@ import { normalizeRayOptions } from './sensors.js';
 
 const DEFAULT_SEED = 1971;
 const DEFAULT_FRAME_SKIP = 1;
-const DEFAULT_MAX_STEPS = 10000;
+const DEFAULT_MAX_STEPS = 1_000_000;
 const RESULT_STATE_OUTPUTS = new Set(['full', 'minimal', 'none']);
 const RESET_OBSERVATION_SCOPES = new Set(['all', 'reset']);
 

package/src/environment/runtime.js

@@ -38,15 +38,11 @@ export function createPaddockEnvironment(options = {}) {
 }
 
 function createSimulationWithEnvironmentScenario(options) {
-  const simulationOptions = {
-    ...options,
-    trackQueryIndex: shouldUseTrackQueryIndex(options),
-  };
   runWarmupWithGuard({
-    options: simulationOptions,
+    options,
     surface: 'environment',
     execute: ({ warmup }) => {
-      const warmupSimulation = createRaceSimulation(disableWarmupOptions(simulationOptions, warmup.surface));
+      const warmupSimulation = createRaceSimulation(disableWarmupOptions(options, warmup.surface));
       initializeControlledPitIntentForSimulation(warmupSimulation, options);
       applyEnvironmentScenario(warmupSimulation, options);
       applyControlledRunoffResponse(warmupSimulation, options);
@@ -59,17 +55,13 @@ function createSimulationWithEnvironmentScenario(options) {
       });
     },
   });
-  const sim = createRaceSimulation(disableWarmupOptions(simulationOptions, 'environment'));
+  const sim = createRaceSimulation(disableWarmupOptions(options, 'environment'));
   initializeControlledPitIntentForSimulation(sim, options);
   applyEnvironmentScenario(sim, options);
   applyControlledRunoffResponse(sim, options);
   return sim;
 }
 
-function shouldUseTrackQueryIndex(options) {
-  return options.trackQueryIndex !== false;
-}
-
 export function createEnvironmentRuntime(host) {
   const episodeState = createEpisodeState();
 

package/src/environment/scenarios.js

@@ -233,7 +233,7 @@ function placementToCarState(track, currentCar, placement, { physicsMode = 'arca
   };
   if (speed != null) {
     partial.speed = speed;
-    if (physicsMode === 'simulator') {
+    if (physicsMode === 'advanced') {
       partial.velocityX = Math.cos(heading) * speed;
       partial.velocityY = Math.sin(heading) * speed;
     } else {

package/src/environment/sensors/surfaceRays.js

@@ -47,29 +47,27 @@ export function estimateSurfaceHits(
     ? context.originState
     : nearestRayTrackState(snapshot.track, car, origin, car.progress, precision);
   const originHits = surfaceHitsAtOrigin(requested, originState);
-  if (!usesSampledDriverContract(car, precision)) {
-    const indexedHits = estimateIndexedSurfaceHits({
-      car,
-      track: snapshot.track,
-      ray,
-      origin,
-      vector,
-      requested,
-      originState,
-      precision,
-      sharedRayQuery,
-    });
-    if (indexedHits) return { ...misses, ...indexedHits, ...originHits };
-    const analyticHits = estimateAnalyticSurfaceHits({
-      car,
-      track: snapshot.track,
-      ray,
-      vector,
-      requested,
-      originState,
-    });
-    if (analyticHits) return { ...misses, ...analyticHits, ...originHits };
-  }
+  const indexedHits = estimateIndexedSurfaceHits({
+    car,
+    track: snapshot.track,
+    ray,
+    origin,
+    vector,
+    requested,
+    originState,
+    precision,
+    sharedRayQuery,
+  });
+  if (indexedHits) return { ...misses, ...indexedHits, ...originHits };
+  const analyticHits = estimateAnalyticSurfaceHits({
+    car,
+    track: snapshot.track,
+    ray,
+    vector,
+    requested,
+    originState,
+  });
+  if (analyticHits) return { ...misses, ...analyticHits, ...originHits };
 
   const pending = new Set(requested);
   Object.keys(originHits).forEach((channel) => {
@@ -165,7 +163,6 @@ function estimateAnalyticSurfaceHits({ car, track, ray, vector, requested, origi
 function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested, originState, precision, 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);
@@ -191,8 +188,16 @@ function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested
     const boundaryDistance = channel === 'kerb'
       ? minFinite(boundaries.trackEdgeDistance, boundaries.kerbOuterDistance)
       : boundaries.kerbOuterDistance;
-    if (boundaryDistance == null) return null;
-    const hitDistance = precision === 'debug' || usesMainTrackOnlyRays(car)
+    if (boundaryDistance == null) {
+      if (usesMainTrackOnlyRays(car) && channel === 'illegalSurface') {
+        hits[channel] = createSurfaceMiss(ray.lengthMeters);
+        continue;
+      }
+      if (canSampleRecoverySurface(track, originState, vector)) return null;
+      hits[channel] = createSurfaceMiss(ray.lengthMeters);
+      continue;
+    }
+    const hitDistance = usesMainTrackOnlyRays(car) || refineStepsForPrecision(precision) <= 0 || precision === 'debug'
       ? boundaryDistance
       : sampledIndexedSurfaceDistance({
         track,
@@ -341,19 +346,22 @@ function matchesSurfaceChannel(channel, state) {
   return false;
 }
 
+function canSampleRecoverySurface(track, originState, vector) {
+  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return false;
+  const kerbOuter = track.width / 2 + (track.kerbWidth ?? 0);
+  const offset = originState.signedOffset ?? 0;
+  if (Math.abs(offset) <= kerbOuter) return false;
+  const lateral = vector.x * originState.normalX + vector.y * originState.normalY;
+  if (Math.abs(lateral) < 0.05) return false;
+  return offset > 0 ? lateral < 0 : lateral > 0;
+}
+
 function nearestRayTrackState(track, car, point, progressHint, precision = 'debug') {
-  const useBatchTrainingIndexMode = usesMainTrackOnlyRays(car);
   return nearestTrackState(track, point, progressHint, {
     allowPitOverride: pitOverrideAllowedForCar(car),
-    indexMode: usesSampledDriverContract(car, precision) ? 'legacy' : useBatchTrainingIndexMode ? 'sample' : undefined,
-    hintMaxDistance: useBatchTrainingIndexMode ? Infinity : undefined,
   });
 }
 
-function usesSampledDriverContract(car, precision) {
-  return precision === 'driver' && !usesMainTrackOnlyRays(car);
-}
-
 function minFinite(...values) {
   const minimum = Math.min(...values.filter((value) => Number.isFinite(value)));
   return Number.isFinite(minimum) ? minimum : null;

package/src/environment/sensors/trackRays.js

@@ -43,6 +43,18 @@ export function estimateTrackHit(
     ? context.originState
     : nearestRayTrackState(snapshot.track, car, origin, car.progress, precision);
   const includePitLane = Boolean(car.inPitLane || car.pitLanePart || originState.inPitLane);
+  const indexedHit = estimateIndexedTrackHit({
+    car,
+    track: snapshot.track,
+    origin,
+    originState,
+    ray,
+    lengthMeters,
+    includePitLane,
+    precision,
+    sharedRayQuery,
+  });
+  if (indexedHit) return indexedHit;
   const directionalAnalyticHit = canUseDirectionalAnalyticTrackHit({ car, track: snapshot.track, originState, ray, includePitLane })
     ? estimateAnalyticMainTrackHit({
       car,
@@ -55,20 +67,6 @@ export function estimateTrackHit(
     })
     : null;
   if (directionalAnalyticHit) return directionalAnalyticHit;
-  if (!usesSampledDriverContract(car, precision)) {
-    const indexedHit = estimateIndexedTrackHit({
-      car,
-      track: snapshot.track,
-      origin,
-      originState,
-      ray,
-      lengthMeters,
-      includePitLane,
-      precision,
-      sharedRayQuery,
-    });
-    if (indexedHit) return indexedHit;
-  }
   const analyticHit = estimateAnalyticMainTrackHit({
     car,
     track: snapshot.track,
@@ -168,7 +166,6 @@ function canUseDirectionalAnalyticTrackHit({ car, track, originState, ray, inclu
 
 function estimateIndexedTrackHit({ car, track, origin, originState, ray, lengthMeters, includePitLane, precision, sharedRayQuery }) {
   if (includePitLane || (!usesMainTrackOnlyRays(car) && isNearPitConnector(track, originState))) return null;
-  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return null;
   const trackHalfWidth = track.width / 2;
   const inside = Math.abs(originState.signedOffset ?? 0) <= trackHalfWidth;
   const boundaries = findIndexedTrackBandBoundaries(
@@ -181,21 +178,28 @@ function estimateIndexedTrackHit({ car, track, origin, originState, ray, lengthM
     sharedRayQuery,
   );
   if (!boundaries.available) return null;
-  if (boundaries.trackEdgeDistance == null) return null;
+  if (boundaries.trackEdgeDistance == null) {
+    if (usesMainTrackOnlyRays(car)) return createTrackMiss(lengthMeters);
+    return canSampleRecoveryTransition(track, originState, ray)
+      ? null
+      : createTrackMiss(lengthMeters);
+  }
   const kind = inside ? 'exit' : 'entry';
-  const hitDistance = validatedIndexedTransitionDistance({
-    track,
-    car,
-    origin,
-    ray,
-    progressHint: car.progress,
-    distance: boundaries.trackEdgeDistance,
-    maxDistance: metersToSimUnits(lengthMeters),
-    kind,
-    includePitLane,
-    precision,
-    originInside: inside,
-  });
+  const hitDistance = usesMainTrackOnlyRays(car)
+    ? boundaries.trackEdgeDistance
+    : validatedIndexedTransitionDistance({
+      track,
+      car,
+      origin,
+      ray,
+      progressHint: car.progress,
+      distance: boundaries.trackEdgeDistance,
+      maxDistance: metersToSimUnits(lengthMeters),
+      kind,
+      includePitLane,
+      precision,
+      originInside: inside,
+    });
   if (hitDistance == null) return null;
   return {
     hit: true,
@@ -287,18 +291,11 @@ function refineTrackTransitionDistance(
 }
 
 function nearestRayTrackState(track, car, point, progressHint, precision = 'debug') {
-  const useBatchTrainingIndexMode = usesMainTrackOnlyRays(car);
   return nearestTrackState(track, point, progressHint, {
     allowPitOverride: pitOverrideAllowedForCar(car),
-    indexMode: usesSampledDriverContract(car, precision) ? 'legacy' : useBatchTrainingIndexMode ? 'sample' : undefined,
-    hintMaxDistance: useBatchTrainingIndexMode ? Infinity : undefined,
   });
 }
 
-function usesSampledDriverContract(car, precision) {
-  return precision === 'driver' && !usesMainTrackOnlyRays(car);
-}
-
 function refineStepsForPrecision(precision) {
   return precision === 'debug' ? TRACK_RAY_REFINE_STEPS : DRIVER_RAY_REFINE_STEPS;
 }
@@ -308,6 +305,16 @@ function isInsideTrackBorder(state, track, includePitLane = true) {
   return state.crossTrackError <= track.width / 2;
 }
 
+function canSampleRecoveryTransition(track, originState, ray) {
+  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return false;
+  const trackHalfWidth = track.width / 2;
+  const offset = originState.signedOffset ?? 0;
+  if (Math.abs(offset) <= trackHalfWidth) return false;
+  const lateral = ray.x * originState.normalX + ray.y * originState.normalY;
+  if (Math.abs(lateral) < 0.05) return false;
+  return offset > 0 ? lateral < 0 : lateral > 0;
+}
+
 function validatedIndexedTransitionDistance({
   track,
   car,
@@ -323,19 +330,8 @@ function validatedIndexedTransitionDistance({
 }) {
   const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
   const refineSteps = refineStepsForPrecision(precision);
-  if (refineSteps <= 0 && usesMainTrackOnlyRays(car)) return distance;
   if (refineSteps <= 0) {
-    return sampledIndexedTransitionDistance({
-      track,
-      car,
-      origin,
-      ray,
-      progressHint,
-      distance,
-      maxDistance,
-      kind,
-      includePitLane,
-    });
+    return distance;
   }
 
   const windows = [step * 1.5, step * 8];
@@ -418,7 +414,6 @@ function refineValidatedTransitionDistance(track, car, origin, ray, progressHint
 function validatedInsideTrackBorder(track, car, origin, ray, distance, progressHint, includePitLane) {
   const state = nearestTrackState(track, pointOnRay(origin, ray, distance), progressHint, {
     allowPitOverride: pitOverrideAllowedForCar(car),
-    indexMode: 'legacy',
   });
   return isInsideTrackBorder(state, track, includePitLane);
 }