@inventure71/paddockjs 4.1.0 → 4.3.0

package/src/app/F1SimulatorApp.js

@@ -1,6 +1,7 @@
 import { Application, Container, Graphics } from 'pixi.js';
 import { applyPaddockThemeCssVariables } from '../config/defaultOptions.js';
 import { formatCssUrl } from '../config/cssValues.js';
+import { createRuntimeSeed } from '../config/runtimeSeed.js';
 import { getNextTimingGapMode, normalizeTimingGapMode } from '../config/timingGapMode.js';
 import { ProceduralTrackAsset } from '../rendering/proceduralTrackAsset.js';
 import { interpolateRenderSnapshotInto } from '../rendering/renderSnapshot.js';
@@ -8,7 +9,15 @@ import { createRaceSimulation, FIXED_STEP } from '../simulation/raceSimulation.j
 import { clamp } from '../simulation/simMath.js';
 import { WORLD } from '../simulation/track/trackModel.js';
 import { CameraController } from './camera/cameraController.js';
+import { GridWalkController } from './gridWalk/GridWalkController.js';
+import { bindWorkbenchControls, bindCameraWheelControls } from './controls/workbenchBindings.js';
+import {
+  renderTelemetryDrawerDisclosure,
+  isTimingPanelDisclosureMode,
+  syncTimingPanelDisclosureState,
+} from './controls/workbenchDisclosure.js';
 import { createBrowserExpertAdapter } from './BrowserExpertAdapter.js';
+import { HostLifecycleEmitter } from './HostLifecycleEmitter.js';
 import { installLayoutSupport } from './layoutSupport.js';
 import { installRaceOverlayClearanceSupport } from './raceOverlayClearanceSupport.js';
 import { querySimulatorDom, resolveNodes } from './domBindings.js';
@@ -27,11 +36,7 @@ import {
 } from './readouts/timingTowerRenderer.js';
 import { renderCarDriverOverview } from './readouts/carOverviewRenderer.js';
 import { renderLapTelemetry, renderTelemetryReadouts } from './readouts/telemetryRenderer.js';
-import {
-  renderRaceFinish,
-  renderRaceStatusReadouts,
-  renderStartLights,
-} from './readouts/raceStatusRenderer.js';
+import { renderRaceStatusReadouts } from './readouts/raceStatusRenderer.js';
 import {
   updateCameraControlButtons,
   updateModeButtons,
@@ -39,7 +44,6 @@ import {
 } from './readouts/controlStateRenderer.js';
 import {
   createPenaltyStewardMessage,
-  createWarningStewardMessage,
   renderActiveStewardMessage,
   updateStewardMessageState,
 } from './banners/stewardMessageController.js';
@@ -47,26 +51,21 @@ import {
   hideRaceDataPanel,
   getProjectRadioQuote,
   RACE_DATA_SELECTED_VISIBLE_MS,
-  RADIO_SCHEDULE_CATCHUP_LIMIT_MS,
   renderProjectRadio,
   renderRaceData,
   resetRaceDataBannerState,
   scheduleRadioBreak,
-  scheduleRadioPopup,
   shouldAutoHideActiveRaceData,
   getNextRadioBreakTime,
+  updateRadioSchedule,
 } from './banners/raceDataBannerController.js';
 import { runFrameLoopTick } from './runtime/frameLoop.js';
 import { observeRuntimeVisibility, syncRuntimeTicker } from './runtime/runtimeVisibility.js';
-import { TARGET_FRAME_MS, domUpdateIntervalForSpeed, timingUpdateIntervalForSpeed } from './runtime/runtimeTiming.js';
+import { configureRuntimeTicker, domUpdateIntervalForSpeed, timingUpdateIntervalForSpeed } from './runtime/runtimeTiming.js';
+import { assertRuntimeStartupActive, createPixiStartupLifecycle, RuntimeStartupCancelledError } from './runtime/pixiStartupLifecycle.js';
 import { normalizeWarmupOptions } from '../simulation/warmup/runtimeWarmup.js';
 
 const SIMULATION_SPEED_STEPS = [1, 2, 3, 4, 5, 10];
-const DRS_DRAG_REDUCTION_PERCENT = 58;
-
-function uniqueNodes(nodes = []) {
-  return [...new Set([...nodes].filter(Boolean))];
-}
 
 function normalizeRuntimeSnapshot(snapshot, totalLaps) {
   const source = snapshot && typeof snapshot === 'object' ? snapshot : {};
@@ -102,16 +101,6 @@ function normalizeRuntimeSnapshot(snapshot, totalLaps) {
   };
 }
 
-function createMountTrackSeed() {
-  const values = new Uint32Array(1);
-  try {
-    globalThis.crypto?.getRandomValues?.(values);
-  } catch {
-    values[0] = 0;
-  }
-  return (values[0] || Math.floor(Date.now() + performance.now() * 1000)) >>> 0;
-}
-
 function hasOwnOption(options, key) {
   return Object.hasOwn(options ?? {}, key);
 }
@@ -120,6 +109,10 @@ function expertOptionsChanged(nextExpertOptions, currentExpertOptions) {
   return nextExpertOptions !== currentExpertOptions;
 }
 
+function timingRaceMode(snapshot) {
+  return snapshot?.raceControl?.finished ? 'finished' : snapshot?.raceControl?.mode;
+}
+
 function withSelectedExpertSensorDriver(visualizeSensors, selectedDriverId) {
   if (!visualizeSensors) return visualizeSensors;
   if (visualizeSensors === true) return { rays: true, selectedDriverId };
@@ -144,6 +137,7 @@ export class F1SimulatorApp {
   constructor(root, options) {
     this.root = root;
     this.options = options;
+    this.hostLifecycle = new HostLifecycleEmitter(() => this.options, () => this.destroyed ? false : this.sim);
     this.drivers = options.drivers;
     this.driverById = new Map(this.drivers.map((driver) => [driver.id, driver]));
     this.assets = options.assets;
@@ -155,6 +149,7 @@ export class F1SimulatorApp {
     this.syncThemeContext();
     Object.assign(this, querySimulatorDom(root));
     this.abortController = new AbortController();
+    this.destroyed = false;
     this.resizeHandler = null;
     this.layoutResizeObserver = null;
     this.layoutSupportCleanup = installLayoutSupport(root);
@@ -168,6 +163,8 @@ export class F1SimulatorApp {
     this.expertMode = Boolean(options.expert?.enabled);
     this.sim = null;
     this.app = null;
+    this.pixiStartupLifecycle = null;
+    this.destroyCleanupErrors = null;
     this.worldLayer = null;
     this.trackAsset = null;
     this.drsLayer = null;
@@ -184,19 +181,24 @@ export class F1SimulatorApp {
       carSprites: this.carSprites,
       carHitAreas: this.carHitAreas,
       serviceCountdownLabels: this.serviceCountdownLabels,
-      onSelectCar: (driverId) => this.selectCar(driverId, { focus: true }),
+      onSelectCar: (driverId, event) => {
+        if (this.gridWalk?.active) {
+          this.gridWalk.navigation.selectOnRelease(driverId, event);
+          return;
+        }
+        this.selectCar(driverId, { focus: true });
+      },
     });
     this.drsTrails = new Map();
     this.drsTrailRenderer = new DrsTrailRenderer({ trails: this.drsTrails });
     this.replayGhostRenderer = new ReplayGhostRenderer();
     this.pitLaneStatusRenderer = new PitLaneStatusRenderer();
-    this.trackSeed = options.trackSeed ?? createMountTrackSeed();
+    this.trackSeed = options.trackSeed ?? createRuntimeSeed();
     this.raceDataBannerConfig = options.ui?.raceDataBanners ?? { initial: 'project', enabled: ['project', 'radio'] };
     this.raceDataBannersMuted = false;
     this.penaltyBannerEnabled = Boolean(options.ui?.penaltyBanners);
     this.timingPenaltyBadgesEnabled = Boolean(options.ui?.timingPenaltyBadges);
     this.activeRaceDataId = null;
-    this.activePenaltyBanner = null;
     this.lastPenaltyBannerId = null;
     this.activeStewardMessage = null;
     this.lastStewardMessageKey = null;
@@ -220,7 +222,6 @@ export class F1SimulatorApp {
     this.simulationSpeed = 1;
     this.accumulator = 0;
     this.lastTime = performance.now();
-    this.nextGameFrameTime = this.lastTime + TARGET_FRAME_MS;
     this.lastDomUpdateTime = 0;
     this.lastTimingRenderTime = 0;
     this.lastTimingRaceMode = null;
@@ -238,9 +239,6 @@ export class F1SimulatorApp {
       lastSample: this.lastTime,
     };
     this.renderSnapshotBuffer = {};
-    this.lastLeaderLap = null;
-    this.emittedRaceEventKeys = new Set();
-    this.raceFinishEmitted = false;
     this.timingGapMode = normalizeTimingGapMode(options.ui?.timingGapMode);
     this.telemetryDrawerOpen = Boolean(
       this.readouts.telemetryDrawerWorkbench?.classList?.contains?.('is-telemetry-open'),
@@ -250,19 +248,30 @@ export class F1SimulatorApp {
   async init() {
     this.emitHostCallback('onLoadingChange', { loading: true, phase: 'initializing' });
     try {
+      assertRuntimeStartupActive(this);
       if (!this.canvasHost) {
         throw new Error('F1 simulator canvas host is missing.');
       }
 
       this.sim = this.createRaceSimulation();
-      this.app = new Application();
-      await this.app.init({
+      const application = new Application();
+      const lifecycleEmitter = this.hostLifecycle;
+      const startup = createPixiStartupLifecycle(application, (error) => {
+        if (this.destroyCleanupErrors) this.destroyCleanupErrors.push(error);
+        else lifecycleEmitter?.emitCallback('onError', error, { phase: 'destroy' });
+      });
+      this.app = application;
+      this.pixiStartupLifecycle = startup;
+      await startup.initialize({
         resizeTo: this.canvasHost,
+        autoStart: false,
         antialias: true,
         autoDensity: true,
         resolution: Math.min(window.devicePixelRatio || 1, 2),
         backgroundAlpha: 0,
       });
+      assertRuntimeStartupActive(this);
+      configureRuntimeTicker(application.ticker);
       this.canvasHost.appendChild(this.app.canvas);
 
       this.worldLayer = new Container();
@@ -274,7 +283,9 @@ export class F1SimulatorApp {
       this.carLayer = new Container();
       this.app.stage.addChild(this.worldLayer);
 
-      await this.loadAssets();
+      const textures = await this.loadAssets();
+      assertRuntimeStartupActive(this);
+      this.textures = textures;
       this.trackAsset = new ProceduralTrackAsset({ textures: this.textures, world: WORLD });
       this.worldLayer.addChild(
         this.trackAsset.container,
@@ -286,6 +297,10 @@ export class F1SimulatorApp {
         this.carLayer,
       );
       this.createCars();
+      if (this.options.gridWalk?.enabled) {
+        this.gridWalk = new GridWalkController(this);
+        this.gridWalk.sync({ updateTicker: false });
+      }
       this.bindControls();
       this.syncTimingPanelDisclosureState();
       this.renderTrack();
@@ -298,7 +313,9 @@ export class F1SimulatorApp {
       this.renderInitialFrame(snapshot);
       this.completeComponentLoading();
       this.emitHostCallback('onLoadingChange', { loading: false, phase: 'ready' });
+      assertRuntimeStartupActive(this);
       this.emitHostCallback('onReady', { snapshot });
+      assertRuntimeStartupActive(this);
       this.resizeHandler = () => {
         this.syncTimingPanelDisclosureState();
         this.renderSourceSnapshotBuffer ??= {};
@@ -315,27 +332,18 @@ export class F1SimulatorApp {
         this.observeRuntimeVisibility();
       }
     } catch (error) {
-      this.emitHostCallback('onLoadingChange', { loading: false, phase: 'error' });
-      this.emitHostCallback('onError', error, { phase: 'init' });
+      const cancelled = this.destroyed;
+      if (!(error instanceof RuntimeStartupCancelledError) && !this.destroyed) {
+        this.emitHostCallback('onLoadingChange', { loading: false, phase: 'error' });
+        this.emitHostCallback('onError', error, { phase: 'init' });
+      }
       this.destroy();
-      throw error;
+      throw cancelled ? new RuntimeStartupCancelledError() : error;
     }
   }
 
   emitHostCallback(name, ...args) {
-    const callback = this.options?.[name];
-    if (typeof callback !== 'function') return;
-    try {
-      callback(...args);
-    } catch (error) {
-      if (name !== 'onError' && typeof this.options?.onError === 'function') {
-        try {
-          this.options.onError(error, { callback: name });
-        } catch {
-          // Host callbacks should not break the simulator runtime.
-        }
-      }
-    }
+    this.hostLifecycle?.emitCallback(name, ...args);
   }
 
   completeComponentLoading() {
@@ -362,7 +370,7 @@ export class F1SimulatorApp {
   }
 
   async loadAssets() {
-    this.textures = await loadAppTextures(this.assets);
+    return loadAppTextures(this.assets);
   }
 
   createCars() {
@@ -376,106 +384,54 @@ export class F1SimulatorApp {
 
   bindControls() {
     const eventOptions = { signal: this.abortController.signal };
-
-    this.safetyButtons.forEach((button) => {
-      button.addEventListener('click', () => {
+    bindWorkbenchControls({
+      safetyButtons: this.safetyButtons,
+      restartButton: this.restartButton,
+      restartButtons: this.restartButtons,
+      cameraButtons: this.cameraButtons,
+      zoomInButton: this.zoomInButton,
+      zoomInButtons: this.zoomInButtons,
+      zoomOutButton: this.zoomOutButton,
+      zoomOutButtons: this.zoomOutButtons,
+      simulationSpeedButtons: this.simulationSpeedButtons,
+      bannerMuteButtons: this.bannerMuteButtons,
+      overviewModeButtons: this.overviewModeButtons,
+      timingGapModeButtons: this.timingGapModeButtons,
+      timingLists: this.timingLists,
+      timingPanelToggles: this.readouts.timingPanelToggles,
+      raceDataOpens: this.readouts.raceDataOpens,
+      openButton: this.openButton,
+      raceDataDismisses: this.readouts.raceDataDismisses,
+      raceDataDismiss: this.readouts.raceDataDismiss,
+      telemetryDrawerToggle: this.readouts.telemetryDrawerToggle,
+    }, {
+      toggleSafetyCar: () => {
         const next = this.sim.snapshot().raceControl.mode !== 'safety-car';
         this.setSafetyCarDeployed(next);
-      }, eventOptions);
-    });
-
-    this.restartButton?.addEventListener('click', () => {
-      this.sim = this.createRaceSimulation();
-      this.selectedId = this.drivers[0]?.id ?? null;
-      this.resetRaceDataBannerState(performance.now());
-      this.syncSafetyCarControls(false);
-      this.drsTrails.clear();
-      this.trailLayer?.clear();
-      this.lastTimingRenderTime = 0;
-      this.lastTimingRaceMode = null;
-      this.lastTimingPenaltyKey = '';
-      this.lastTimingOrderKey = '';
-      this.renderTrack();
-    }, eventOptions);
-
-    this.cameraButtons.forEach((button) => {
-      button.addEventListener('click', () => {
-        this.setCameraMode(button.dataset.cameraMode);
-      }, eventOptions);
-    });
-
-    this.zoomInButton?.addEventListener('click', () => {
-      this.adjustCameraZoom(1);
-    }, eventOptions);
-
-    this.zoomOutButton?.addEventListener('click', () => {
-      this.adjustCameraZoom(-1);
-    }, eventOptions);
-
-    this.simulationSpeedButtons?.forEach((button) => {
-      button.addEventListener('click', () => {
-        this.cycleSimulationSpeed();
-      }, eventOptions);
-    });
-    this.updateSimulationSpeedControls();
-
-    this.bannerMuteButtons?.forEach((button) => {
-      button.addEventListener('click', () => {
+      },
+      restart: () => this.restart(),
+      setCameraMode: (mode) => this.setCameraMode(mode),
+      adjustCameraZoom: (direction) => this.adjustCameraZoom(direction),
+      cycleSimulationSpeed: () => this.cycleSimulationSpeed(),
+      updateSimulationSpeedControls: () => this.updateSimulationSpeedControls(),
+      toggleRaceDataBanners: () => {
         this.setRaceDataBannersMuted(!this.raceDataBannersMuted);
-      }, eventOptions);
-    });
-
-    this.overviewModeButtons.forEach((button) => {
-      button.addEventListener('click', () => {
-        this.overviewMode = button.dataset.overviewMode === 'driver' ? 'driver' : 'vehicle';
+      },
+      setOverviewMode: (mode) => {
+        this.overviewMode = mode;
         const selected = this.sim?.snapshot().cars.find((car) => car.id === this.selectedId);
         this.renderCarDriverOverview(selected);
-      }, eventOptions);
-    });
-
-    this.timingGapModeButtons.forEach((button) => {
-      button.addEventListener('click', () => {
-        this.toggleTimingGapMode();
-      }, eventOptions);
-    });
-
-    this.timingLists?.forEach?.((timingList) => {
-      timingList.addEventListener?.('pointerdown', (event) => {
-        const row = event.target instanceof Element ? event.target.closest('[data-driver-id]') : null;
-        if (!row) return;
-        this.selectCar(row.dataset.driverId, { focus: true });
-      }, eventOptions);
-    });
-
-    this.readouts.timingPanelToggles?.forEach?.((toggle) => {
-      toggle.addEventListener?.('click', () => {
-        const racePanel = toggle.closest?.('.sim-canvas-panel');
-        this.setTimingPanelOpen(!racePanel?.classList?.contains?.('is-timing-panel-open'), racePanel);
-      }, eventOptions);
-    });
-
-    const raceDataOpenButtons = uniqueNodes(this.readouts.raceDataOpens?.length
-      ? this.readouts.raceDataOpens
-      : [this.openButton]);
-    raceDataOpenButtons.forEach((button) => button.addEventListener('click', () => {
-      const driver = this.driverById.get(this.activeRaceDataId ?? this.selectedId);
-      if (!driver) return;
-      this.options.onDriverOpen?.(driver);
-    }, eventOptions));
-
-    const raceDataDismissButtons = uniqueNodes(this.readouts.raceDataDismisses?.length
-      ? this.readouts.raceDataDismisses
-      : [this.readouts.raceDataDismiss]);
-    raceDataDismissButtons.forEach((button) => button.addEventListener('click', (event) => {
-      event.preventDefault();
-      event.stopPropagation();
-      this.dismissRaceDataPanel(performance.now());
-    }, eventOptions));
-
-    this.readouts.telemetryDrawerToggle?.addEventListener('click', () => {
-      this.setTelemetryDrawerOpen(!this.telemetryDrawerOpen);
-    }, eventOptions);
-
+      },
+      toggleTimingGapMode: () => this.toggleTimingGapMode(),
+      selectCar: (id) => this.selectCar(id, { focus: true }),
+      setTimingPanelOpen: (open, panel) => this.setTimingPanelOpen(open, panel),
+      openDriver: () => {
+        const driver = this.driverById.get(this.activeRaceDataId ?? this.selectedId);
+        if (driver) this.emitHostCallback('onDriverOpen', driver);
+      },
+      dismissRaceDataPanel: (now) => this.dismissRaceDataPanel(now),
+      toggleTelemetryDrawer: () => this.setTelemetryDrawerOpen(!this.telemetryDrawerOpen),
+    }, eventOptions.signal);
     this.bindCameraWheelControls(eventOptions);
   }
 
@@ -511,31 +467,20 @@ export class F1SimulatorApp {
   }
 
   bindCameraWheelControls(eventOptions) {
-    if (!this.canvasHost?.addEventListener) return;
-    this.canvasHost.addEventListener('wheel', (event) => {
-      event.preventDefault?.();
-      this.adjustCameraZoom(event.deltaY > 0 ? -1 : 1);
-    }, { ...eventOptions, passive: false });
+    bindCameraWheelControls(this.canvasHost, (direction) => {
+      const before = this.camera.zoom;
+      return this.adjustCameraZoom(direction) !== before;
+    }, eventOptions,
+      () => !this.gridWalk?.active);
   }
 
   setTelemetryDrawerOpen(open) {
     this.telemetryDrawerOpen = Boolean(open);
-    this.readouts.telemetryDrawerWorkbench?.classList?.toggle?.('is-telemetry-open', this.telemetryDrawerOpen);
-    if (this.telemetryDrawerOpen) {
-      this.readouts.telemetryDrawer?.removeAttribute?.('inert');
-      this.readouts.telemetryDrawer?.setAttribute?.('aria-hidden', 'false');
-    } else {
-      this.readouts.telemetryDrawer?.setAttribute?.('inert', '');
-      this.readouts.telemetryDrawer?.setAttribute?.('aria-hidden', 'true');
-    }
-    this.readouts.telemetryDrawerToggle?.setAttribute?.('aria-expanded', String(this.telemetryDrawerOpen));
-    if (this.readouts.telemetryDrawerToggle) {
-      this.readouts.telemetryDrawerToggle.textContent = this.telemetryDrawerOpen ? 'Close' : 'Telemetry';
-      this.readouts.telemetryDrawerToggle.setAttribute(
-        'aria-label',
-        this.telemetryDrawerOpen ? 'Close telemetry' : 'Open telemetry',
-      );
-    }
+    renderTelemetryDrawerDisclosure({
+      workbench: this.readouts.telemetryDrawerWorkbench,
+      drawer: this.readouts.telemetryDrawer,
+      toggle: this.readouts.telemetryDrawerToggle,
+    }, this.telemetryDrawerOpen);
     this.invalidateCameraSafeArea();
     this.syncRendererToCurrentLayout({ render: true });
     this.scheduleLayoutResizeSync(380);
@@ -550,29 +495,15 @@ export class F1SimulatorApp {
   }
 
   isTimingPanelDisclosureMode(toggle = this.readouts.timingPanelToggle) {
-    if (!toggle) return false;
-    const style = getComputedStyle(toggle);
-    return style.display !== 'none' && style.visibility !== 'hidden';
+    return isTimingPanelDisclosureMode(toggle);
   }
 
   syncTimingPanelDisclosureState(targetPanel = null) {
-    const toggles = [...(this.readouts.timingPanelToggles ?? [])];
-    for (const toggle of toggles) {
-      const racePanel = toggle.closest?.('.sim-canvas-panel');
-      if (targetPanel && racePanel !== targetPanel) continue;
-      const tower = racePanel?.querySelector?.('[data-timing-tower]');
-      const disclosureMode = this.isTimingPanelDisclosureMode(toggle);
-      const open = disclosureMode && Boolean(racePanel?.classList?.contains?.('is-timing-panel-open'));
-      racePanel?.classList?.toggle?.('is-timing-panel-open', open);
-      if (!disclosureMode || open) {
-        tower?.removeAttribute?.('inert');
-        tower?.setAttribute?.('aria-hidden', 'false');
-      } else {
-        tower?.setAttribute?.('inert', '');
-        tower?.setAttribute?.('aria-hidden', 'true');
-      }
-      toggle.setAttribute?.('aria-expanded', String(open));
-    }
+    syncTimingPanelDisclosureState({
+      toggles: this.readouts.timingPanelToggles,
+      targetPanel,
+      isDisclosureMode: (toggle) => this.isTimingPanelDisclosureMode(toggle),
+    });
   }
 
   setRaceDataBannersMuted(muted, now = performance.now()) {
@@ -586,6 +517,7 @@ export class F1SimulatorApp {
       this.resetRaceDataBannerState(now);
     }
     this.updateBannerMuteControls();
+    if (this.gridWalk?.active) this.gridWalk.sync();
   }
 
   resizeRendererToCanvasHost() {
@@ -606,6 +538,11 @@ export class F1SimulatorApp {
   }
 
   syncRendererToCurrentLayout({ render = false } = {}) {
+    if (this.gridWalk?.active) {
+      this.gridWalk.render();
+      return;
+    }
+    this.gridWalk?.syncLayout();
     this.resizeRendererToCanvasHost();
     this.renderSourceSnapshotBuffer ??= {};
     const snapshot = this.sim?.snapshotRenderInto?.(this.renderSourceSnapshotBuffer) ?? this.sim?.snapshotRender?.() ?? this.sim?.snapshot?.();
@@ -626,10 +563,15 @@ export class F1SimulatorApp {
 
   scheduleLayoutResizeSync(durationMs = 360) {
     if (typeof requestAnimationFrame !== 'function') return;
-    const startedAt = performance.now();
+    this.layoutResizeSyncUntil = Math.max(
+      this.layoutResizeSyncUntil ?? 0,
+      performance.now() + durationMs,
+    );
+    if (this.layoutResizeFrame != null) return;
     const run = (timestamp = performance.now()) => {
+      this.layoutResizeFrame = null;
       this.syncRendererToCurrentLayout({ render: true });
-      if (timestamp - startedAt < durationMs) {
+      if (timestamp < this.layoutResizeSyncUntil) {
         this.layoutResizeFrame = requestAnimationFrame(run);
       }
     };
@@ -664,7 +606,6 @@ export class F1SimulatorApp {
   resetFrameClock(now = performance.now()) {
     this.accumulator = 0;
     this.lastTime = now;
-    this.nextGameFrameTime = now + TARGET_FRAME_MS;
     this.fps.current = 0;
     this.fps.frames = 0;
     this.fps.lastSample = now;
@@ -675,7 +616,10 @@ export class F1SimulatorApp {
   }
 
   renderExpertFrame(snapshot = this.sim?.snapshot(), { forceDomUpdate = false, observation } = {}) {
-    if (!snapshot) return;
+    if (this.destroyed || !snapshot) return;
+    const simulation = this.sim;
+    this.emitSnapshotLifecycle(snapshot);
+    if (this.destroyed || this.sim !== simulation) return;
     const now = performance.now();
     this.sampleFps(now);
     const renderSnapshot = interpolateRenderSnapshotInto(this.renderSnapshotBuffer, snapshot, 0);
@@ -709,6 +653,7 @@ export class F1SimulatorApp {
   }
 
   renderCars(snapshot) {
+    if (this.gridWalk?.active) snapshot = this.gridWalk.session.snapshot;
     this.replayGhostRenderer.render(snapshot, {
       textures: this.textures,
       replayGhostLayer: this.replayGhostLayer,
@@ -716,13 +661,10 @@ export class F1SimulatorApp {
     this.carRenderer.renderCars(snapshot, {
       textures: this.textures,
       carLayer: this.carLayer,
+      snapToPose: Boolean(this.gridWalk?.active),
     });
   }
 
-  renderServiceCountdownLabel(car) {
-    this.carRenderer.renderServiceCountdownLabel(car);
-  }
-
   renderExpertSensorRays(snapshot, observation) {
     renderExpertSensorRays({
       snapshot,
@@ -740,9 +682,14 @@ export class F1SimulatorApp {
     this.drsTrailRenderer.render(snapshot, this.trailLayer);
   }
 
-  applyCamera(snapshot, { immediate = false } = {}) {
+  applyCamera(snapshot, { immediate = false, elapsedMs } = {}) {
+    if (this.gridWalk?.active) {
+      this.gridWalk.applyCamera();
+      return;
+    }
     this.cameraController.applyToWorldLayer(this.worldLayer, snapshot, {
       immediate,
+      elapsedMs,
       selectedId: this.selectedId,
     });
   }
@@ -771,11 +718,9 @@ export class F1SimulatorApp {
     return this.cameraController.getPitBounds(pitLane);
   }
 
-  getPitCameraFrame(pitLane, height, baseScale, safeArea, screenCenterX, minimumScale = null) {
-    return this.cameraController.getPitFrame(pitLane, height, baseScale, safeArea, screenCenterX, minimumScale);
-  }
-
   updateDom(snapshot, { emitLifecycle = true } = {}) {
+    if (this.destroyed) return;
+    const simulation = this.sim;
     snapshot = normalizeRuntimeSnapshot(snapshot, this.totalLaps);
     const leader = snapshot.cars[0];
     const selected = snapshot.cars.find((car) => car.id === this.selectedId) ?? leader;
@@ -784,6 +729,7 @@ export class F1SimulatorApp {
     const now = performance.now();
 
     if (emitLifecycle) this.emitSnapshotLifecycle(snapshot);
+    if (this.destroyed || this.sim !== simulation) return;
     this.syncThemeContext(snapshot);
 
     if (
@@ -810,18 +756,19 @@ export class F1SimulatorApp {
 
     this.updateCameraControls(snapshot);
     this.syncTimingGapModeControls();
+    const currentTimingRaceMode = timingRaceMode(snapshot);
     const timingPenaltyKey = this.getTimingPenaltyKey(snapshot.penalties ?? []);
     const timingOrderKey = this.getTimingOrderKey(snapshot.cars);
     const timingUpdateInterval = timingUpdateIntervalForSpeed(this.simulationSpeed);
     if (
       now - this.lastTimingRenderTime >= timingUpdateInterval ||
-      this.lastTimingRaceMode !== snapshot.raceControl.mode ||
+      this.lastTimingRaceMode !== currentTimingRaceMode ||
       this.lastTimingPenaltyKey !== timingPenaltyKey ||
       this.lastTimingOrderKey !== timingOrderKey
     ) {
-      this.renderTiming(snapshot.cars, snapshot.raceControl.mode, snapshot.penalties ?? []);
+      this.renderTiming(snapshot.cars, currentTimingRaceMode, snapshot.penalties ?? []);
       this.lastTimingRenderTime = now;
-      this.lastTimingRaceMode = snapshot.raceControl.mode;
+      this.lastTimingRaceMode = currentTimingRaceMode;
       this.lastTimingPenaltyKey = timingPenaltyKey;
       this.lastTimingOrderKey = timingOrderKey;
     }
@@ -838,48 +785,11 @@ export class F1SimulatorApp {
   }
 
   emitSnapshotLifecycle(snapshot) {
-    const leader = snapshot.cars[0];
-    const leaderLap = leader?.lap;
-    if (Number.isFinite(leaderLap)) {
-      if (this.lastLeaderLap != null && leaderLap !== this.lastLeaderLap) {
-        this.emitHostCallback('onLapChange', {
-          previousLeaderLap: this.lastLeaderLap,
-          leaderLap,
-          leader,
-          snapshot,
-        });
-      }
-      this.lastLeaderLap = leaderLap;
-    }
-
-    this.emitRaceEvents(snapshot.events, snapshot);
-
-    if (snapshot.raceControl.finished && !this.raceFinishEmitted) {
-      this.raceFinishEmitted = true;
-      this.emitHostCallback('onRaceFinish', {
-        winner: snapshot.raceControl.winner,
-        classification: snapshot.raceControl.classification ?? [],
-        snapshot,
-      });
-    }
+    this.hostLifecycle?.emitSnapshot(snapshot);
   }
 
   emitRaceEvents(events = [], snapshot) {
-    events.forEach((event) => {
-      const key = `${event.type}:${event.at ?? snapshot.time}:${event.carId ?? ''}:${event.otherCarId ?? ''}:${event.winnerId ?? ''}`;
-      if (this.emittedRaceEventKeys.has(key)) return;
-      this.emittedRaceEventKeys.add(key);
-      this.emitHostCallback('onRaceEvent', event, snapshot);
-    });
-  }
-
-  renderRaceFinish(snapshot) {
-    this.lastFinishClassificationMarkup = renderRaceFinish({
-      readouts: this.readouts,
-      snapshot,
-      driverById: this.driverById,
-      lastFinishClassificationMarkup: this.lastFinishClassificationMarkup,
-    });
+    this.hostLifecycle?.emitRaceEvents(events, snapshot);
   }
 
   sampleFps(now) {
@@ -891,25 +801,29 @@ export class F1SimulatorApp {
     this.fps.lastSample = now;
   }
 
-  renderStartLights(raceControl) {
-    renderStartLights(this.readouts, this.startLightNodes, raceControl);
-  }
-
   selectCar(id, { focus = false } = {}) {
+    if (!this.driverById.has(id)) return;
     this.selectedId = id;
     this.activeRaceDataId = this.isRaceDataBannerEnabled('project') ? id : null;
     this.lastRaceDataInteraction = performance.now();
     if (this.isRaceDataBannerEnabled('radio')) this.scheduleRadioBreak(this.lastRaceDataInteraction);
-    if (focus) {
+    if (focus && !this.gridWalk?.active) {
       this.setCameraMode('selected');
     }
     this.lastTimingRenderTime = 0;
-    const snapshot = this.sim.snapshot();
+    const simulation = this.sim;
+    const snapshot = simulation.snapshot();
     this.updateDom(snapshot);
+    if (this.destroyed || this.sim !== simulation) return;
     const driver = this.driverById.get(id);
     if (driver) this.emitHostCallback('onDriverSelect', driver, snapshot);
+    if (!this.destroyed && this.sim === simulation) this.gridWalk?.select(id, { focus });
   }
 
+  setView(view) { return this.gridWalk?.setView(view) ?? false; }
+
+  getView() { return this.gridWalk?.session.view ?? 'race'; }
+
   renderTiming(cars, raceMode, penalties = []) {
     this.syncTimingGapModeControls();
     this.lastTimingMarkup = renderTimingTowers({
@@ -943,7 +857,7 @@ export class F1SimulatorApp {
     this.lastTimingRenderTime = 0;
     this.syncTimingGapModeControls();
     const snapshot = this.sim?.snapshot?.();
-    if (snapshot) this.renderTiming(snapshot.cars, snapshot.raceControl.mode, snapshot.penalties ?? []);
+    if (snapshot) this.renderTiming(snapshot.cars, timingRaceMode(snapshot), snapshot.penalties ?? []);
     return this.timingGapMode;
   }
 
@@ -977,7 +891,6 @@ export class F1SimulatorApp {
     renderTelemetryReadouts({
       readouts: this.readouts,
       car,
-      driverById: this.driverById,
     });
     this.renderCarDriverOverview(car);
     this.renderLapTelemetry(car.lapTelemetry);
@@ -1072,51 +985,24 @@ export class F1SimulatorApp {
     return createPenaltyStewardMessage(penalty, this.driverById);
   }
 
-  createWarningStewardMessage(event) {
-    return createWarningStewardMessage(event, this.driverById);
-  }
-
   renderActiveStewardMessage() {
     renderActiveStewardMessage(this.readouts, this.activeStewardMessage);
   }
 
   updateRadioSchedule(now) {
-    if (!this.isRaceDataBannerEnabled('radio')) {
-      this.radioState.visible = false;
-      this.radioState.nextChangeAt = Number.POSITIVE_INFINITY;
-      return;
-    }
-    if (
-      Number.isFinite(this.radioState.nextChangeAt) &&
-      now - this.radioState.nextChangeAt > RADIO_SCHEDULE_CATCHUP_LIMIT_MS
-    ) {
-      if (this.radioState.visible) this.scheduleRadioBreak(now);
-      else this.scheduleRadioPopup(now);
-      return;
-    }
-    while (now >= this.radioState.nextChangeAt) {
-      if (this.radioState.visible) {
-        this.scheduleRadioBreak(this.radioState.nextChangeAt);
-      } else {
-        this.scheduleRadioPopup(this.radioState.nextChangeAt);
-      }
-    }
-  }
-
-  scheduleRadioBreak(now) {
-    scheduleRadioBreak({
+    updateRadioSchedule({
       radioState: this.radioState,
       now,
+      drivers: this.drivers,
       isEnabled: (kind) => this.isRaceDataBannerEnabled(kind),
       nextRandom: () => this.nextRadioRandom(),
     });
   }
 
-  scheduleRadioPopup(now) {
-    scheduleRadioPopup({
+  scheduleRadioBreak(now) {
+    scheduleRadioBreak({
       radioState: this.radioState,
       now,
-      drivers: this.drivers,
       isEnabled: (kind) => this.isRaceDataBannerEnabled(kind),
       nextRandom: () => this.nextRadioRandom(),
     });
@@ -1245,7 +1131,7 @@ export class F1SimulatorApp {
     this.totalLaps = this.options.totalLaps;
     this.assets = this.options.assets;
     if (hasOwnOption(nextOptions, 'trackSeed')) {
-      this.trackSeed = this.options.trackSeed ?? createMountTrackSeed();
+      this.trackSeed = this.options.trackSeed ?? createRuntimeSeed();
     }
     if (nextOptions.drivers) {
       this.drivers = nextOptions.drivers;
@@ -1276,6 +1162,10 @@ export class F1SimulatorApp {
     this.lastThemeContextKey = null;
     this.syncThemeContext();
     this.sim = this.createRaceSimulation();
+    this.gridWalk?.destroy();
+    this.gridWalk = null;
+    this.gridWalk = this.options.gridWalk?.enabled ? new GridWalkController(this) : null;
+    this.gridWalk?.sync();
     if (this.expertMode) {
       this.expert = createBrowserExpertAdapter(this, this.options.expert);
     }
@@ -1287,18 +1177,19 @@ export class F1SimulatorApp {
     this.lastTimingRaceMode = null;
     this.lastTimingPenaltyKey = '';
     this.lastTimingOrderKey = '';
-    this.activePenaltyBanner = null;
     this.lastPenaltyBannerId = null;
     this.activeStewardMessage = null;
     this.lastStewardMessageKey = null;
-    this.lastLeaderLap = null;
-    this.emittedRaceEventKeys.clear();
-    this.raceFinishEmitted = false;
+    this.hostLifecycle.reset();
     this.renderTrack();
     const snapshot = this.sim.snapshot();
     this.updateDom(snapshot);
     this.lastDomUpdateTime = performance.now();
+    // Restart may create fresh surfaces around the already-ready renderer.
+    // Complete their loading state before measuring the final display frame.
+    this.completeComponentLoading();
     this.renderInitialFrame(snapshot);
+    this.syncRuntimeTicker();
   }
 
   setSafetyCarDeployed(deployed) {
@@ -1348,34 +1239,88 @@ export class F1SimulatorApp {
   }
 
   destroy() {
-    this.abortController.abort();
+    if (this.destroyed) return;
+    this.destroyed = true;
+    const lifecycleEmitter = this.hostLifecycle;
+    const cleanupErrors = [];
+    this.destroyCleanupErrors = cleanupErrors;
+    const cleanup = (run) => {
+      try { run(); } catch (error) { cleanupErrors.push(error); }
+    };
+    cleanup(() => this.gridWalk?.destroy());
+    this.gridWalk = null;
+    cleanup(() => this.abortController?.abort?.());
     if (this.layoutResizeFrame && typeof cancelAnimationFrame === 'function') {
-      cancelAnimationFrame(this.layoutResizeFrame);
+      cleanup(() => cancelAnimationFrame(this.layoutResizeFrame));
     }
     this.layoutResizeFrame = null;
+    this.layoutResizeSyncUntil = 0;
     if (this.runtimeVisibilitySyncFrame && typeof cancelAnimationFrame === 'function') {
-      cancelAnimationFrame(this.runtimeVisibilitySyncFrame);
+      cleanup(() => cancelAnimationFrame(this.runtimeVisibilitySyncFrame));
     }
     this.runtimeVisibilitySyncFrame = null;
-    this.layoutResizeObserver?.disconnect?.();
+    cleanup(() => this.layoutResizeObserver?.disconnect?.());
     this.layoutResizeObserver = null;
-    this.layoutSupportCleanup?.();
+    cleanup(() => this.layoutSupportCleanup?.());
     this.layoutSupportCleanup = null;
-    this.raceOverlayClearanceCleanup?.();
+    cleanup(() => this.raceOverlayClearanceCleanup?.());
     this.raceOverlayClearanceCleanup = null;
-    this.visibilityObserver?.disconnect?.();
+    cleanup(() => this.visibilityObserver?.disconnect?.());
     this.visibilityObserver = null;
     if (this.app && this.tickerCallback) {
-      this.app.ticker.remove(this.tickerCallback);
+      cleanup(() => this.app.ticker.remove(this.tickerCallback));
     }
-    this.expert?.destroy?.();
+    cleanup(() => this.expert?.destroy?.());
     this.expert = null;
-    this.replayGhostRenderer.destroy();
-    this.app?.destroy(true, { children: true, texture: false });
+    cleanup(() => this.replayGhostRenderer?.destroy?.());
+    if (this.pixiStartupLifecycle) cleanup(() => this.pixiStartupLifecycle.destroy());
+    else cleanup(() => this.app?.destroy(true, { children: true, texture: false }));
+    this.pixiStartupLifecycle = null;
     this.app = null;
     this.carSprites.clear();
     this.carHitAreas.clear();
     this.serviceCountdownLabels.clear();
     this.drsTrails.clear();
+    this.sim = null;
+    this.root = null;
+    this.canvasHost = null;
+    this.readouts = {};
+    this.safetyButtons = [];
+    this.restartButton = null;
+    this.restartButtons = [];
+    this.openButton = null;
+    this.timingList = null;
+    this.timingLists = [];
+    this.timingGapModeButtons = [];
+    this.cameraButtons = [];
+    this.overviewModeButtons = [];
+    this.bannerMuteButtons = [];
+    this.simulationSpeedButtons = [];
+    this.zoomInButton = null;
+    this.zoomInButtons = [];
+    this.zoomOutButton = null;
+    this.zoomOutButtons = [];
+    this.startLightNodes = [];
+    this.worldLayer = null;
+    this.trackAsset = null;
+    this.drsLayer = null;
+    this.trailLayer = null;
+    this.sensorLayer = null;
+    this.pitLaneStatusLayer = null;
+    this.replayGhostLayer = null;
+    this.carLayer = null;
+    this.textures = {};
+    this.renderSnapshotBuffer = null;
+    this.renderSourceSnapshotBuffer = null;
+    this.cameraController = null;
+    this.camera = null;
+    this.carRenderer = null;
+    this.drsTrailRenderer = null;
+    this.replayGhostRenderer = null;
+    this.pitLaneStatusRenderer = null;
+    this.hostLifecycle = null;
+    this.abortController = null;
+    this.destroyCleanupErrors = null;
+    cleanupErrors.forEach((error) => lifecycleEmitter?.emitCallback('onError', error, { phase: 'destroy' }));
   }
 }