@inventure71/paddockjs 0.2.0 → 0.3.0

package/examples/train-basic-policy.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+import { createPaddockEnvironment, createProgressReward } from '../src/environment/index.js';
+import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../src/data/championship.js';
+import { DEMO_PROJECT_DRIVERS } from '../src/data/demoDrivers.js';
+
+const DEFAULT_OPTIONS = Object.freeze({
+  generations: 4,
+  candidates: 5,
+  episodes: 1,
+  steps: 240,
+  frameSkip: 4,
+  seed: 71,
+  traffic: false,
+  evalOnly: false,
+});
+
+const INITIAL_POLICY = Object.freeze({
+  steeringHeading: -1.2,
+  steeringOffset: -0.35,
+  steeringRayBalance: 0.45,
+  throttleBias: 0.72,
+  throttleFrontClearance: 0.28,
+  throttleSpeedDamping: 0.18,
+  brakeBias: 0,
+  brakeFrontDanger: 0.65,
+  brakeOffTrack: 0.2,
+});
+
+const POLICY_KEYS = Object.keys(INITIAL_POLICY);
+
+main();
+
+function main() {
+  const options = parseCliArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const driverId = DEMO_PROJECT_DRIVERS[0].id;
+  const rng = createSeededRandom(options.seed);
+  const reward = createProgressReward();
+  const evaluate = (policy, seedOffset = 0) => evaluatePolicy({
+    policy,
+    driverId,
+    reward,
+    options,
+    seedOffset,
+  });
+
+  if (options.evalOnly) {
+    const baseline = evaluate(INITIAL_POLICY);
+    printSummary({ options, driverId, bestPolicy: INITIAL_POLICY, best: baseline });
+    return;
+  }
+
+  let bestPolicy = { ...INITIAL_POLICY };
+  let best = evaluate(bestPolicy);
+
+  console.log(formatGenerationLine(0, best));
+
+  for (let generation = 1; generation <= options.generations; generation += 1) {
+    const mutationScale = 0.45 / Math.sqrt(generation);
+    const candidates = [{ policy: bestPolicy, scoreSeedOffset: generation * 1000 }];
+
+    for (let index = 1; index < options.candidates; index += 1) {
+      candidates.push({
+        policy: mutatePolicy(bestPolicy, rng, mutationScale),
+        scoreSeedOffset: generation * 1000 + index * 100,
+      });
+    }
+
+    for (const candidate of candidates) {
+      const score = evaluate(candidate.policy, candidate.scoreSeedOffset);
+      if (score.averageReward > best.averageReward) {
+        best = score;
+        bestPolicy = candidate.policy;
+      }
+    }
+
+    console.log(formatGenerationLine(generation, best));
+  }
+
+  printSummary({ options, driverId, bestPolicy, best });
+}
+
+function evaluatePolicy({ policy, driverId, reward, options, seedOffset = 0 }) {
+  let totalReward = 0;
+  let totalDistanceMeters = 0;
+  let totalCollisions = 0;
+  let totalOffTrackSteps = 0;
+  let completedEpisodes = 0;
+
+  for (let episode = 0; episode < options.episodes; episode += 1) {
+    const env = createTrainingEnvironment({ driverId, reward, options, episode, seedOffset });
+    let result = env.reset();
+    let episodeReward = 0;
+
+    for (let step = 0; step < options.steps && !result.done; step += 1) {
+      const observation = result.observation[driverId];
+      const action = chooseAction(policy, observation);
+      result = env.step({ [driverId]: action });
+      episodeReward += result.reward?.[driverId] ?? 0;
+      totalCollisions += result.events.filter((event) => event.type === 'collision').length;
+      if (result.observation[driverId]?.object?.self?.onTrack === false) totalOffTrackSteps += 1;
+    }
+
+    const car = result.state.snapshot.cars.find((entry) => entry.id === driverId);
+    totalReward += episodeReward;
+    totalDistanceMeters += Number(car?.distanceMeters ?? 0);
+    completedEpisodes += 1;
+    env.destroy();
+  }
+
+  return {
+    averageReward: totalReward / Math.max(1, completedEpisodes),
+    averageDistanceMeters: totalDistanceMeters / Math.max(1, completedEpisodes),
+    collisions: totalCollisions,
+    offTrackSteps: totalOffTrackSteps,
+  };
+}
+
+function createTrainingEnvironment({ driverId, reward, options, episode, seedOffset }) {
+  const drivers = options.traffic ? DEMO_PROJECT_DRIVERS.slice(0, 8) : DEMO_PROJECT_DRIVERS.slice(0, 1);
+  return createPaddockEnvironment({
+    drivers,
+    entries: CHAMPIONSHIP_ENTRY_BLUEPRINTS,
+    controlledDrivers: [driverId],
+    seed: options.seed + seedOffset + episode,
+    trackSeed: options.seed + 2026 + seedOffset + episode,
+    totalLaps: 3,
+    frameSkip: options.frameSkip,
+    scenario: {
+      participants: options.traffic ? 'all' : 'controlled-only',
+      nonControlled: 'ai',
+    },
+    episode: {
+      maxSteps: options.steps,
+      endOnRaceFinish: true,
+    },
+    rules: {
+      standingStart: false,
+    },
+    reward,
+  });
+}
+
+function chooseAction(policy, observation) {
+  const self = observation.object.self;
+  const frontRay = getRayDistance(observation, 0);
+  const leftRay = getRayDistance(observation, -60);
+  const rightRay = getRayDistance(observation, 60);
+  const frontDanger = clamp01((35 - frontRay) / 35);
+  const rayBalanceMeters = rightRay - leftRay;
+
+  const steering = clamp(
+    policy.steeringHeading * self.trackHeadingErrorRadians +
+      policy.steeringOffset * (self.trackOffsetMeters / 12) +
+      policy.steeringRayBalance * (rayBalanceMeters / 120),
+    -1,
+    1,
+  );
+  const throttle = clamp01(
+    policy.throttleBias +
+      policy.throttleFrontClearance * (frontRay / 120) -
+      policy.throttleSpeedDamping * (self.speedKph / 320) -
+      (self.onTrack ? 0 : 0.35),
+  );
+  const brake = clamp01(
+    policy.brakeBias +
+      policy.brakeFrontDanger * frontDanger +
+      (self.onTrack ? 0 : policy.brakeOffTrack),
+  );
+
+  return { steering, throttle, brake };
+}
+
+function getRayDistance(observation, angleDegrees) {
+  const ray = observation.object.rays.find((entry) => entry.angleDegrees === angleDegrees);
+  return Number(ray?.track?.distanceMeters ?? ray?.lengthMeters ?? 120);
+}
+
+function mutatePolicy(policy, rng, scale) {
+  return Object.fromEntries(POLICY_KEYS.map((key) => [
+    key,
+    policy[key] + randomNormal(rng) * scale,
+  ]));
+}
+
+function parseCliArgs(argv) {
+  const options = { ...DEFAULT_OPTIONS };
+
+  for (const arg of argv) {
+    const [name, rawValue] = arg.split('=');
+    if (name === '--help' || name === '-h') options.help = true;
+    else if (name === '--eval-only') options.evalOnly = true;
+    else if (name === '--traffic') options.traffic = true;
+    else if (name === '--no-traffic') options.traffic = false;
+    else if (name === '--generations') options.generations = parsePositiveInt(rawValue, name);
+    else if (name === '--candidates') options.candidates = parsePositiveInt(rawValue, name);
+    else if (name === '--episodes') options.episodes = parsePositiveInt(rawValue, name);
+    else if (name === '--steps') options.steps = parsePositiveInt(rawValue, name);
+    else if (name === '--frame-skip') options.frameSkip = parsePositiveInt(rawValue, name);
+    else if (name === '--seed') options.seed = parsePositiveInt(rawValue, name);
+    else throw new Error(`Unknown option: ${name}`);
+  }
+
+  return options;
+}
+
+function parsePositiveInt(value, optionName) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${optionName} requires a positive integer value.`);
+  }
+  return parsed;
+}
+
+function createSeededRandom(seed) {
+  let state = seed >>> 0;
+  return function random() {
+    state += 0x6D2B79F5;
+    let value = state;
+    value = Math.imul(value ^ (value >>> 15), value | 1);
+    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function randomNormal(rng) {
+  const a = Math.max(Number.EPSILON, rng());
+  const b = Math.max(Number.EPSILON, rng());
+  return Math.sqrt(-2 * Math.log(a)) * Math.cos(2 * Math.PI * b);
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function clamp01(value) {
+  return clamp(value, 0, 1);
+}
+
+function formatGenerationLine(generation, score) {
+  return [
+    `generation=${generation}`,
+    `reward=${score.averageReward.toFixed(2)}`,
+    `distanceMeters=${score.averageDistanceMeters.toFixed(1)}`,
+    `collisions=${score.collisions}`,
+    `offTrackSteps=${score.offTrackSteps}`,
+  ].join(' ');
+}
+
+function printSummary({ options, driverId, bestPolicy, best }) {
+  console.log(JSON.stringify({
+    driverId,
+    options,
+    best,
+    bestPolicy,
+  }, null, 2));
+}
+
+function printHelp() {
+  console.log(`Usage: node examples/train-basic-policy.mjs [options]
+
+Options:
+  --generations=N   Random-search generations. Default: ${DEFAULT_OPTIONS.generations}
+  --candidates=N    Candidate policies per generation. Default: ${DEFAULT_OPTIONS.candidates}
+  --episodes=N      Episodes per policy evaluation. Default: ${DEFAULT_OPTIONS.episodes}
+  --steps=N         Maximum manual environment steps per episode. Default: ${DEFAULT_OPTIONS.steps}
+  --frame-skip=N    Simulator frames advanced by each step(action). Default: ${DEFAULT_OPTIONS.frameSkip}
+  --seed=N          Deterministic random seed. Default: ${DEFAULT_OPTIONS.seed}
+  --traffic         Keep built-in AI traffic on track during training.
+  --eval-only       Evaluate the starter policy without training.
+`);
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
-  "description": "A data-driven browser F1 simulator component for project portfolios.",
+  "description": "A data-driven browser F1 simulator component for host websites.",
   "license": "Apache-2.0",
   "author": "Matteo Giorgetti",
   "homepage": "https://github.com/Inventure71/PaddockJS#readme",
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.19.0"
   },
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -40,24 +40,30 @@
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
+    "./environment": {
+      "types": "./src/environment/index.d.ts",
+      "import": "./src/environment/index.js",
+      "default": "./src/environment/index.js"
+    },
     "./styles.css": "./src/styles.css"
   },
   "files": [
-    "AGENTS.md",
     "CHANGELOG.md",
+    "INSTALL_AND_UPDATE.md",
     "LICENSE",
     "assets",
-    "docs",
+    "docs/*.md",
+    "examples",
     "src/api",
     "src/app",
     "src/config",
     "src/data",
+    "src/environment",
     "src/rendering",
     "src/simulation",
     "src/ui",
     "src/index.d.ts",
     "src/index.js",
-    "src/standalone.js",
     "src/styles.css",
     "README.md"
   ],
@@ -72,7 +78,8 @@
     "showcase:ci": "npm --prefix local-preview ci && npm --prefix local-preview run build",
     "changeset": "changeset",
     "version-packages": "changeset version",
-    "release": "npm publish --provenance"
+    "release": "npm publish --provenance",
+    "example:train": "node examples/train-basic-policy.mjs"
   },
   "dependencies": {
     "pixi.js": "8.18.1"

package/src/api/PaddockSimulatorController.js

@@ -187,6 +187,10 @@ export class PaddockSimulatorController {
     return this;
   }
 
+  get expert() {
+    return this.app?.expert ?? null;
+  }
+
   destroy() {
     this.app?.destroy();
     this.app = null;
@@ -197,9 +201,10 @@ export class PaddockSimulatorController {
   }
 
   restart(nextOptions = {}) {
-    this.options = resolveF1SimulatorOptions(mergeResolvedOptions(this.options, nextOptions));
+    const nextResolvedOptions = resolveF1SimulatorOptions(mergeResolvedOptions(this.options, nextOptions));
+    this.app?.restart(nextResolvedOptions);
+    this.options = nextResolvedOptions;
     this.compositeRoot.applyCssVariables();
-    this.app?.restart(this.options);
   }
 
   selectDriver(driverId) {

package/src/app/BrowserExpertAdapter.js

@@ -0,0 +1,32 @@
+import { createEnvironmentRuntime } from '../environment/runtime.js';
+import { resolveEnvironmentOptions } from '../environment/options.js';
+
+export function createBrowserExpertAdapter(app, expertOptions = {}) {
+  let resolvedOptions = resolveEnvironmentOptions({
+    ...app.options,
+    ...expertOptions,
+    controlledDrivers: expertOptions.controlledDrivers,
+  });
+
+  return createEnvironmentRuntime({
+    getSimulation: () => app.sim,
+    setSimulation(nextSim) {
+      app.sim = nextSim;
+    },
+    createSimulation(nextOptions) {
+      app.applyExpertOptions(nextOptions);
+      return app.createRaceSimulation(nextOptions);
+    },
+    getOptions: () => resolvedOptions,
+    setOptions(nextOptions) {
+      resolvedOptions = nextOptions;
+    },
+    afterReset(result) {
+      app.renderTrack();
+      app.renderExpertFrame(result.state.snapshot, { observation: result.observation });
+    },
+    afterStep(result) {
+      app.renderExpertFrame(result.state.snapshot, { observation: result.observation });
+    },
+  });
+}

package/src/app/F1SimulatorApp.js

@@ -2,14 +2,16 @@ import { Application, Assets, Container, Graphics, Sprite, Texture } from 'pixi.
 import { DRIVER_STAT_DEFINITIONS, formatDriverNumber, VEHICLE_STAT_DEFINITIONS } from '../data/championship.js';
 import { applyPaddockThemeCssVariables } from '../config/defaultOptions.js';
 import { normalizeCustomFields } from '../data/customFields.js';
+import { getCarRayOrigin, getCarRayVector } from '../environment/sensors.js';
 import { ProceduralTrackAsset } from '../rendering/proceduralTrackAsset.js';
 import { createRenderSnapshot } from '../rendering/renderSnapshot.js';
-import { createRaceSimulation } from '../simulation/raceSimulation.js';
+import { createRaceSimulation, FIXED_STEP } from '../simulation/raceSimulation.js';
 import { clamp } from '../simulation/simMath.js';
 import { offsetTrackPoint, pointAt, WORLD } from '../simulation/trackModel.js';
+import { metersToSimUnits } from '../simulation/units.js';
+import { createBrowserExpertAdapter } from './BrowserExpertAdapter.js';
 import { querySimulatorDom, setText, setTextAll } from './domBindings.js';
 
-const FIXED_STEP = 1 / 60;
 const TARGET_RENDER_FPS = 60;
 const TARGET_FRAME_MS = 1000 / TARGET_RENDER_FPS;
 const FRAME_PACING_EPSILON_MS = 0.75;
@@ -34,6 +36,9 @@ const SHOW_ALL_TOP_RESERVED = 92;
 const SHOW_ALL_BOTTOM_RESERVED = 132;
 const DRS_TRAIL_TTL = 0.68;
 const DRS_TRAIL_MIN_DISTANCE = 10;
+const SENSOR_RAY_TRACK_COLOR = 0xf1c65b;
+const SENSOR_RAY_TRACK_ENTRY_COLOR = 0x68d8ff;
+const SENSOR_RAY_CAR_COLOR = 0xff4d5f;
 const RACE_DATA_SELECTED_VISIBLE_MS = 5200;
 const RADIO_BREAK_MIN_MS = 4800;
 const RADIO_BREAK_MAX_MS = 11800;
@@ -116,6 +121,43 @@ function smoothAngle(current, target, amount) {
   return current + diff * amount;
 }
 
+function destroyDisplayChildren(container) {
+  container?.removeChildren?.().forEach((child) => {
+    child.destroy?.({ children: true, texture: false, textureSource: false });
+  });
+}
+
+function expertVisualizesRays(expertOptions) {
+  const setting = expertOptions?.visualizeSensors;
+  if (setting === true) return true;
+  if (!setting || setting === false) return false;
+  return Boolean(setting.rays);
+}
+
+function pointFromRay(origin, ray, distance) {
+  return {
+    x: origin.x + ray.x * distance,
+    y: origin.y + ray.y * distance,
+  };
+}
+
+function hasOwnOption(options, key) {
+  return Object.hasOwn(options ?? {}, key);
+}
+
+function expertOptionsChanged(nextExpertOptions, currentExpertOptions) {
+  return nextExpertOptions !== currentExpertOptions;
+}
+
+function assetSetsEqual(first = {}, second = {}) {
+  const firstTrackTextures = first.trackTextures ?? {};
+  const secondTrackTextures = second.trackTextures ?? {};
+  const assetKeys = ['car', 'carOverview', 'driverHelmet', 'safetyCar', 'broadcastPanel', 'f1Logo'];
+  const textureKeys = new Set([...Object.keys(firstTrackTextures), ...Object.keys(secondTrackTextures)]);
+  return assetKeys.every((key) => first[key] === second[key]) &&
+    [...textureKeys].every((key) => firstTrackTextures[key] === secondTrackTextures[key]);
+}
+
 export class F1SimulatorApp {
   constructor(root, options) {
     this.root = root;
@@ -134,12 +176,15 @@ export class F1SimulatorApp {
     this.visibilityChangeHandler = null;
     this.visibilityObserver = null;
     this.tickerCallback = null;
+    this.expert = null;
+    this.expertMode = Boolean(options.expert?.enabled);
     this.sim = null;
     this.app = null;
     this.worldLayer = null;
     this.trackAsset = null;
     this.drsLayer = null;
     this.trailLayer = null;
+    this.sensorLayer = null;
     this.carLayer = null;
     this.textures = {};
     this.carSprites = new Map();
@@ -213,29 +258,36 @@ export class F1SimulatorApp {
       this.worldLayer = new Container();
       this.drsLayer = new Container();
       this.trailLayer = new Graphics();
+      this.sensorLayer = new Graphics();
       this.carLayer = new Container();
       this.app.stage.addChild(this.worldLayer);
 
       await this.loadAssets();
       this.trackAsset = new ProceduralTrackAsset({ textures: this.textures, world: WORLD });
-      this.worldLayer.addChild(this.trackAsset.container, this.drsLayer, this.trailLayer, this.carLayer);
+      this.worldLayer.addChild(this.trackAsset.container, this.drsLayer, this.trailLayer, this.sensorLayer, this.carLayer);
       this.createCars();
       this.bindControls();
       this.renderTrack();
       const snapshot = this.sim.snapshot();
       this.updateDom(snapshot);
+      if (this.expertMode) {
+        this.expert = createBrowserExpertAdapter(this, this.options.expert);
+      }
       this.completeComponentLoading();
       this.emitHostCallback('onLoadingChange', { loading: false, phase: 'ready' });
       this.emitHostCallback('onReady', { snapshot });
       this.resizeHandler = () => this.applyCamera(this.sim.snapshot());
       window.addEventListener('resize', this.resizeHandler, { signal: this.abortController.signal });
-      this.tickerCallback = () => this.tick();
-      this.app.ticker.add(this.tickerCallback);
       this.observeLayoutResize();
-      this.observeRuntimeVisibility();
+      if (!this.expertMode) {
+        this.tickerCallback = () => this.tick();
+        this.app.ticker.add(this.tickerCallback);
+        this.observeRuntimeVisibility();
+      }
     } catch (error) {
       this.emitHostCallback('onLoadingChange', { loading: false, phase: 'error' });
       this.emitHostCallback('onError', error, { phase: 'init' });
+      this.destroy();
       throw error;
     }
   }
@@ -264,12 +316,12 @@ export class F1SimulatorApp {
     });
   }
 
-  createRaceSimulation() {
+  createRaceSimulation(options = this.options) {
     return createRaceSimulation({
-      seed: this.options.seed,
-      trackSeed: this.trackSeed,
-      drivers: this.drivers,
-      totalLaps: this.options.totalLaps,
+      seed: options.seed,
+      trackSeed: options.trackSeed ?? this.trackSeed,
+      drivers: options.drivers ?? this.drivers,
+      totalLaps: options.totalLaps,
     });
   }
 
@@ -418,10 +470,6 @@ export class F1SimulatorApp {
     this.readouts.telemetryDrawerToggle?.addEventListener('click', () => {
       this.setTelemetryDrawerOpen(!this.telemetryDrawerOpen);
     }, eventOptions);
-
-    this.readouts.telemetryDrawerClose?.addEventListener('click', () => {
-      this.setTelemetryDrawerOpen(false);
-    }, eventOptions);
   }
 
   setTelemetryDrawerOpen(open) {
@@ -484,6 +532,7 @@ export class F1SimulatorApp {
   }
 
   syncRuntimeTicker() {
+    if (this.expertMode) return;
     if (!this.app?.ticker) return;
 
     const shouldRun = this.runtimeViewportVisible && this.runtimeDocumentVisible;
@@ -507,6 +556,7 @@ export class F1SimulatorApp {
   }
 
   tick() {
+    if (this.expertMode) return;
     const now = performance.now();
     if (now < this.nextGameFrameTime - FRAME_PACING_EPSILON_MS) return;
 
@@ -549,8 +599,20 @@ export class F1SimulatorApp {
     }
   }
 
+  renderExpertFrame(snapshot = this.sim?.snapshot(), { observation } = {}) {
+    if (!snapshot) return;
+    const renderSnapshot = createRenderSnapshot(snapshot, 0);
+    this.applyCamera(renderSnapshot);
+    this.renderDrsTrails(renderSnapshot);
+    this.renderExpertSensorRays(renderSnapshot, observation);
+    this.renderCars(renderSnapshot);
+    this.updateDom(snapshot, { emitLifecycle: false });
+    this.lastDomUpdateTime = performance.now();
+  }
+
   renderTrack() {
-    this.drsLayer.removeChildren();
+    destroyDisplayChildren(this.drsLayer);
+    this.sensorLayer?.clear();
     const snapshot = this.sim.snapshot();
     const track = snapshot.track;
 
@@ -606,6 +668,60 @@ export class F1SimulatorApp {
     }
   }
 
+  renderExpertSensorRays(snapshot, observation) {
+    if (!this.sensorLayer) return;
+    this.sensorLayer.clear();
+    if (!this.expertMode || !expertVisualizesRays(this.options.expert)) return;
+
+    const controlledDrivers = this.options.expert?.controlledDrivers ?? [];
+    if (!controlledDrivers.length || !observation) return;
+
+    const carsById = new Map(snapshot.cars.map((car) => [car.id, car]));
+    controlledDrivers.forEach((driverId) => {
+      const car = carsById.get(driverId);
+      const rays = observation?.[driverId]?.object?.rays;
+      if (!car || !Array.isArray(rays) || rays.length === 0) return;
+
+      const origin = getCarRayOrigin(car);
+
+      rays.forEach((ray) => {
+        const rayVector = getCarRayVector(car, Number(ray.angleDegrees) || 0);
+        const totalDistanceMeters = Math.max(0, Number(ray.lengthMeters) || 0);
+        const trackDistanceMeters = Math.max(0, Number(ray.track?.distanceMeters) || totalDistanceMeters);
+        const carDistanceMeters = Math.max(0, Number(ray.car?.distanceMeters) || totalDistanceMeters);
+        const trackHit = Boolean(ray.track?.hit) && trackDistanceMeters <= totalDistanceMeters;
+        const carHit = Boolean(ray.car?.hit) && carDistanceMeters <= totalDistanceMeters;
+        const fullEnd = pointFromRay(origin, rayVector, metersToSimUnits(totalDistanceMeters));
+
+        this.sensorLayer
+          .moveTo(origin.x, origin.y)
+          .lineTo(fullEnd.x, fullEnd.y)
+          .stroke({ width: 2, color: 0xffffff, alpha: 0.18, cap: 'round' });
+
+        if (!trackHit && !carHit) return;
+
+        const carIsClosest = carHit && (!trackHit || carDistanceMeters <= trackDistanceMeters);
+        const hitDistanceMeters = carIsClosest ? carDistanceMeters : trackDistanceMeters;
+        const hitEnd = pointFromRay(origin, rayVector, metersToSimUnits(hitDistanceMeters));
+        const hitColor = carIsClosest
+          ? SENSOR_RAY_CAR_COLOR
+          : ray.track?.kind === 'entry'
+            ? SENSOR_RAY_TRACK_ENTRY_COLOR
+            : SENSOR_RAY_TRACK_COLOR;
+
+        this.sensorLayer
+          .moveTo(origin.x, origin.y)
+          .lineTo(hitEnd.x, hitEnd.y)
+          .stroke({ width: carIsClosest ? 5 : 3.4, color: hitColor, alpha: carIsClosest ? 0.9 : 0.76, cap: 'round' });
+        this.sensorLayer
+          .circle(hitEnd.x, hitEnd.y, carIsClosest ? 7 : 5)
+          .fill({ color: hitColor, alpha: 0.92 })
+          .circle(hitEnd.x, hitEnd.y, carIsClosest ? 10 : 8)
+          .stroke({ width: 1.5, color: 0x10131a, alpha: 0.72 });
+      });
+    });
+  }
+
   renderDrsTrails(snapshot) {
     if (!this.trailLayer) return;
 
@@ -1357,7 +1473,7 @@ export class F1SimulatorApp {
     });
   }
 
-  restart(nextOptions = {}) {
+  applyExpertOptions(nextOptions = {}) {
     this.options = {
       ...this.options,
       ...nextOptions,
@@ -1379,16 +1495,32 @@ export class F1SimulatorApp {
       },
     };
     this.assets = this.options.assets;
-    this.raceDataBannerConfig = this.options.ui?.raceDataBanners ?? this.raceDataBannerConfig;
-    this.root.style.setProperty('--broadcast-panel-surface', `url('${this.assets.broadcastPanel}')`);
-    applyPaddockThemeCssVariables(this.root, this.options.theme);
+    if (hasOwnOption(nextOptions, 'trackSeed')) {
+      this.trackSeed = this.options.trackSeed ?? createMountTrackSeed();
+    }
     if (nextOptions.drivers) {
       this.drivers = nextOptions.drivers;
       this.driverById = new Map(this.drivers.map((driver) => [driver.id, driver]));
       this.root.style.setProperty('--paddock-entry-count', String(this.drivers.length));
       this.createCars();
     }
+  }
+
+  restart(nextOptions = {}) {
+    if (hasOwnOption(nextOptions, 'assets') && !assetSetsEqual(nextOptions.assets, this.options.assets)) {
+      throw new Error('PaddockJS restart() does not support changing assets. Destroy and mount a new simulator with the new assets.');
+    }
+    if (hasOwnOption(nextOptions, 'expert') && expertOptionsChanged(nextOptions.expert, this.options.expert)) {
+      throw new Error('PaddockJS restart() does not support changing expert mode. Destroy and mount a new simulator with the new expert options.');
+    }
+    this.applyExpertOptions(nextOptions);
+    this.raceDataBannerConfig = this.options.ui?.raceDataBanners ?? this.raceDataBannerConfig;
+    this.root.style.setProperty('--broadcast-panel-surface', `url('${this.assets.broadcastPanel}')`);
+    applyPaddockThemeCssVariables(this.root, this.options.theme);
     this.sim = this.createRaceSimulation();
+    if (this.expertMode) {
+      this.expert = createBrowserExpertAdapter(this, this.options.expert);
+    }
     this.selectedId = this.drivers[0]?.id ?? null;
     this.lastTimingMarkup = null;
     this.lastOverviewRenderKey = null;