@inventure71/paddockjs 2.0.1 → 4.0.0

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,
   };
 }
@@ -43,6 +50,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 +74,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 +173,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 +185,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,16 +298,116 @@ 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 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) {
@@ -308,6 +419,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 +444,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 +528,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);
 }

package/src/index.d.ts

@@ -2,6 +2,7 @@ import type {
   PaddockActionSpec,
   PaddockDriverControllerLoop,
   PaddockDriverControllerLoopOptions,
+  PaddockEnvironmentOptions,
   PaddockObservationSpec,
   PaddockParticipantInteraction as EnvPaddockParticipantInteraction,
   PaddockParticipantInteractionsOptions as EnvPaddockParticipantInteractionsOptions,
@@ -23,7 +24,7 @@ export type {
 } from './environment/index.js';
 
 export type TireCompound = 'S' | 'M' | 'H';
-export type PaddockPhysicsMode = 'arcade' | 'simulator';
+export type PaddockPhysicsMode = 'arcade' | 'advanced';
 export type PaddockWarmupPolicy = 'config-change' | 'always' | 'never';
 export type PaddockProceduralTrackProfile = 'race' | 'training-short' | 'training-medium' | 'training-technical';
 
@@ -81,11 +82,12 @@ export type PaddockPitIntentRequest = PaddockPitIntent | {
   pitTargetCompound?: TireCompound | string;
   targetTire?: TireCompound | string;
 };
-export type CameraMode = 'overview' | 'leader' | 'selected' | 'show-all' | 'pit';
+export type CameraMode = 'overview' | 'leader' | 'selected' | 'driver' | 'show-all' | 'pit';
 export type RaceBannerMode = 'project' | 'radio' | 'hidden';
 export type RaceBannerEnabledMode = 'project' | 'radio';
 export type RaceDataBannerSize = 'auto' | 'custom';
 export type TimingTowerVerticalFit = 'expand-race-view' | 'scroll';
+export type TimingGapMode = 'interval' | 'leader';
 export type LayoutPreset = 'standard' | 'left-tower-overlay';
 export type CameraControlsMode = 'embedded' | 'external' | false;
 export type PaddockPresetName = 'dashboard' | 'timing-overlay' | 'compact-race' | 'full-dashboard';
@@ -111,6 +113,7 @@ export interface TeamData {
   name?: string;
   color?: string;
   icon?: string;
+  theme?: PaddockThemeSelector;
   pitCrew?: PaddockPitCrewStats;
   pitCrewStats?: PaddockPitCrewStats;
 }
@@ -254,12 +257,110 @@ export interface NormalizedSimulatorDriver extends SimulatorDriver {
   };
 }
 
-export interface F1SimulatorTheme {
-  accentColor?: string;
-  greenColor?: string;
-  yellowColor?: string;
-  timingTowerMaxWidth?: string;
-  raceViewMinHeight?: string;
+export type PaddockThemeMode = 'dark' | 'light' | 'system';
+export type PaddockThemeSelector = 'default' | 'active' | 'selectedTeam' | 'team' | `team:${string}` | string;
+export type PaddockThemeTokenValue = string | { light?: string; dark?: string };
+export type PaddockThemeTokenName =
+  | 'primary'
+  | 'primaryText'
+  | 'secondary'
+  | 'secondaryText'
+  | 'surface'
+  | 'surfaceRaised'
+  | 'surfacePanel'
+  | 'text'
+  | 'mutedText'
+  | 'border'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'info'
+  | 'yellowFlag'
+  | 'greenFlag'
+  | 'redFlag'
+  | 'safetyCar'
+  | 'drsActive'
+  | 'pitLane'
+  | 'track'
+  | 'trackEdge'
+  | 'timingTowerMaxWidth'
+  | 'raceViewMinHeight';
+
+export interface F1SimulatorThemeTokens extends Partial<Record<PaddockThemeTokenName, PaddockThemeTokenValue>> {
+  /** Compatibility alias for `primary`. Prefer `tokens.primary` in new 3.0.0 code. */
+  accentColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `greenFlag`. Prefer `tokens.greenFlag` or `tokens.success`. */
+  greenColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `yellowFlag`. Prefer `tokens.yellowFlag` or `tokens.warning`. */
+  yellowColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `info`. */
+  blueColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `redFlag`. Prefer `tokens.redFlag` or `tokens.danger`. */
+  raceControlRedColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `surface`. */
+  surfaceColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `surfaceRaised`. */
+  surfaceRaisedColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `surfacePanel`. */
+  surfacePanelColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `border`. */
+  lineColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `border`. */
+  lineStrongColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `text`. */
+  textColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `mutedText`. */
+  mutedTextColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `track`. */
+  trackColor?: PaddockThemeTokenValue;
+  /** Compatibility alias for `trackEdge`. */
+  trackEdgeColor?: PaddockThemeTokenValue;
+}
+
+export interface F1SimulatorThemePackage extends F1SimulatorThemeTokens {
+  extends?: string;
+  tokens?: F1SimulatorThemeTokens;
+  components?: Record<string, Partial<Record<string, PaddockThemeTokenName>>>;
+  light?: F1SimulatorThemeTokens;
+  dark?: F1SimulatorThemeTokens;
+}
+
+export interface F1SimulatorTheme extends Omit<F1SimulatorThemePackage, 'components'> {
+  mode?: PaddockThemeMode;
+  use?: string;
+  themes?: Record<string, F1SimulatorThemePackage>;
+  componentThemes?: Record<string, PaddockThemeSelector | { theme: PaddockThemeSelector }>;
+  teamThemes?: Record<string, PaddockThemeSelector | { theme: PaddockThemeSelector }>;
+  components?: Record<
+    string,
+    PaddockThemeSelector | { theme: PaddockThemeSelector } | Partial<Record<string, PaddockThemeTokenName>>
+  >;
+}
+
+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 {
@@ -277,10 +378,15 @@ export interface F1SimulatorUiOptions {
   };
   raceDataBannerSize?: RaceDataBannerSize;
   raceDataTelemetryDetail?: boolean;
+  driverCamera?: boolean;
   penaltyBanners?: boolean;
   timingPenaltyBadges?: boolean;
   simulationSpeedControl?: boolean;
   timingTowerVerticalFit?: TimingTowerVerticalFit;
+  timingGapMode?: TimingGapMode;
+  timingGapModeToggle?: boolean;
+  timingEntryVerticalPadding?: number;
+  responsiveNarrowLayout?: boolean;
 }
 
 export interface F1SimulatorDebugOptions {
@@ -638,6 +744,18 @@ export interface WheelSurfaceSnapshot {
   fullyOutsideWhiteLine: boolean;
 }
 
+export interface CarTrackStateSnapshot {
+  distance: number;
+  signedOffset: number;
+  crossTrackError: number;
+  surface: string;
+  inPitLane: boolean;
+  pitLanePart: 'entry' | 'fast-lane' | 'working-lane' | 'exit' | 'service-box' | 'garage-box' | null;
+  pitBoxId: string | null;
+  curvature: number;
+  heading: number;
+}
+
 export interface CarSnapshot {
   id: string;
   rank: number | null;
@@ -683,6 +801,7 @@ export interface CarSnapshot {
   stabilityState?: PaddockStabilityState;
   signedOffset?: number;
   crossTrackError?: number;
+  trackState?: CarTrackStateSnapshot | null;
   inPitLane?: boolean;
   wheels?: WheelSurfaceSnapshot[];
   pitLanePart?: 'entry' | 'fast-lane' | 'working-lane' | 'exit' | 'service-box' | 'garage-box' | null;
@@ -791,6 +910,7 @@ export interface F1SimulatorExpertOptions {
   enabled: boolean;
   controlledDrivers: string[];
   frameSkip?: number;
+  episode?: PaddockEnvironmentOptions['episode'];
   visualizeSensors?: boolean | {
     rays?: boolean;
     drivers?: 'selected' | 'all' | string[];
@@ -862,7 +982,6 @@ export interface F1SimulatorOptions extends F1SimulatorCallbacks {
   seed?: number;
   trackSeed?: number;
   trackGeneration?: PaddockProceduralTrackOptions;
-  trackQueryIndex?: boolean;
   warmup?: PaddockWarmupOptions | boolean;
   totalLaps?: number;
   physicsMode?: PaddockPhysicsMode;
@@ -889,6 +1008,7 @@ export interface MountRaceCanvasOptions {
   includeTimingTower?: boolean;
   includeTelemetrySectorBanner?: boolean;
   timingTowerVerticalFit?: TimingTowerVerticalFit;
+  responsiveNarrowLayout?: boolean;
 }
 
 export interface MountTelemetryPanelOptions {
@@ -899,12 +1019,17 @@ export interface MountRaceTelemetryDrawerOptions {
   timingTowerVerticalFit?: TimingTowerVerticalFit;
   drawerInitiallyOpen?: boolean;
   raceDataTelemetryDetail?: boolean;
+  responsiveNarrowLayout?: boolean;
 }
 
 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;
@@ -916,6 +1041,9 @@ export interface F1MountedSimulator {
   getPitIntent(driverId: string): PaddockPitIntent;
   getPitTargetCompound(driverId: string): TireCompound | string | null;
   getSimulationSpeed(): number;
+  setTimingGapMode(mode: TimingGapMode): TimingGapMode;
+  getTimingGapMode(): TimingGapMode;
+  toggleTimingGapMode(): TimingGapMode;
   servePenalty(penaltyId: string): PaddockPenaltyEntry | null;
   cancelPenalty(penaltyId: string): PaddockPenaltyEntry | null;
   getSnapshot(): RaceSnapshot | null;
@@ -942,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;
@@ -953,6 +1085,9 @@ export interface PaddockSimulatorController {
   getPitIntent(driverId: string): PaddockPitIntent;
   getPitTargetCompound(driverId: string): TireCompound | string | null;
   getSimulationSpeed(): number;
+  setTimingGapMode(mode: TimingGapMode): TimingGapMode;
+  getTimingGapMode(): TimingGapMode;
+  toggleTimingGapMode(): TimingGapMode;
   servePenalty(penaltyId: string): PaddockPenaltyEntry | null;
   cancelPenalty(penaltyId: string): PaddockPenaltyEntry | null;
   getSnapshot(): RaceSnapshot | null;
@@ -961,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;
@@ -980,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';
@@ -61,7 +69,22 @@ export async function mountF1Simulator(root, options = {}) {
   const app = new F1SimulatorApp(shell, resolvedOptions);
   await app.init();
 
-  return {
+  const syncResolvedTimingGapMode = (timingGapMode) => {
+    resolvedOptions = {
+      ...resolvedOptions,
+      ui: {
+        ...resolvedOptions.ui,
+        timingGapMode,
+      },
+    };
+    return timingGapMode;
+  };
+  const syncResolvedRuntimeOptions = () => {
+    syncResolvedTimingGapMode(app.getTimingGapMode());
+    return resolvedOptions;
+  };
+
+  const mountedSimulator = {
     get expert() {
       return app.expert ?? null;
     },
@@ -70,10 +93,26 @@ export async function mountF1Simulator(root, options = {}) {
       root.innerHTML = '';
     },
     restart(nextOptions = {}) {
-      const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(resolvedOptions, nextOptions));
+      const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(syncResolvedRuntimeOptions(), nextOptions));
       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 });
     },
@@ -108,6 +147,15 @@ export async function mountF1Simulator(root, options = {}) {
     getSimulationSpeed() {
       return app.simulationSpeed;
     },
+    setTimingGapMode(mode) {
+      return syncResolvedTimingGapMode(app.setTimingGapMode(mode));
+    },
+    getTimingGapMode() {
+      return app.getTimingGapMode();
+    },
+    toggleTimingGapMode() {
+      return syncResolvedTimingGapMode(app.toggleTimingGapMode());
+    },
     servePenalty(penaltyId) {
       return app.servePenalty(penaltyId);
     },
@@ -118,4 +166,5 @@ export async function mountF1Simulator(root, options = {}) {
       return app.getSnapshot();
     },
   };
+  return mountedSimulator;
 }