@inventure71/paddockjs 0.1.0

package/src/data/driverData.js

@@ -0,0 +1,71 @@
+import { normalizeCustomFields } from './customFields.js';
+
+const RATING_MINIMUM = 0;
+const RATING_NEUTRAL = 50;
+const RATING_MAXIMUM = 100;
+
+export const DRIVER_STAT_DEFINITIONS = {
+  pace: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 1, variance: 0.08 },
+  racecraft: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 0.78, variance: 0.16 },
+  aggression: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 0.5, variance: 0.34 },
+  riskTolerance: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 0.5, variance: 0.28 },
+  patience: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 0.5, variance: 0.28 },
+  consistency: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 0.75, variance: 0.16 },
+};
+
+function clampRating(value, label) {
+  const rating = Number(value);
+  if (!Number.isFinite(rating)) throw new Error(`Invalid driver rating for ${label}: ${value}`);
+  return Math.min(Math.max(rating, RATING_MINIMUM), RATING_MAXIMUM);
+}
+
+function applyRating(definition, value) {
+  const normalized = (value - definition.neutral) / (definition.maximum - definition.neutral);
+  return definition.base + normalized * definition.variance;
+}
+
+export class DriverData {
+  constructor({
+    pace = RATING_NEUTRAL,
+    racecraft = RATING_NEUTRAL,
+    aggression = RATING_NEUTRAL,
+    riskTolerance = RATING_NEUTRAL,
+    patience = RATING_NEUTRAL,
+    consistency = RATING_NEUTRAL,
+    customFields = [],
+  } = {}) {
+    this.pace = clampRating(pace, 'pace');
+    this.racecraft = clampRating(racecraft, 'racecraft');
+    this.aggression = clampRating(aggression, 'aggression');
+    this.riskTolerance = clampRating(riskTolerance, 'riskTolerance');
+    this.patience = clampRating(patience, 'patience');
+    this.consistency = clampRating(consistency, 'consistency');
+    this.customFields = normalizeCustomFields(customFields);
+  }
+
+  ratings() {
+    return {
+      pace: this.pace,
+      racecraft: this.racecraft,
+      aggression: this.aggression,
+      riskTolerance: this.riskTolerance,
+      patience: this.patience,
+      consistency: this.consistency,
+    };
+  }
+
+  toConstructorArgs() {
+    return {
+      ratings: this.ratings(),
+      customFields: this.customFields,
+      pace: applyRating(DRIVER_STAT_DEFINITIONS.pace, this.pace),
+      racecraft: applyRating(DRIVER_STAT_DEFINITIONS.racecraft, this.racecraft),
+      consistency: applyRating(DRIVER_STAT_DEFINITIONS.consistency, this.consistency),
+      personality: {
+        aggression: applyRating(DRIVER_STAT_DEFINITIONS.aggression, this.aggression),
+        riskTolerance: applyRating(DRIVER_STAT_DEFINITIONS.riskTolerance, this.riskTolerance),
+        patience: applyRating(DRIVER_STAT_DEFINITIONS.patience, this.patience),
+      },
+    };
+  }
+}

package/src/data/normalizeDrivers.js

@@ -0,0 +1,21 @@
+import { buildChampionshipDriverGrid } from './championship.js';
+
+export function normalizeSimulatorDrivers(drivers, { entries } = {}) {
+  if (!Array.isArray(drivers) || drivers.length === 0) {
+    throw new Error('mountF1Simulator requires a non-empty drivers array.');
+  }
+
+  drivers.forEach((driver, index) => {
+    if (!driver || typeof driver !== 'object') {
+      throw new Error(`Invalid simulator driver at index ${index}.`);
+    }
+    if (!driver.id) {
+      throw new Error(`Simulator driver at index ${index} is missing an id.`);
+    }
+    if (!driver.name) {
+      throw new Error(`Simulator driver "${driver.id}" is missing a name.`);
+    }
+  });
+
+  return buildChampionshipDriverGrid(drivers, entries);
+}

package/src/data/vehicleData.js

@@ -0,0 +1,81 @@
+import { normalizeCustomFields } from './customFields.js';
+
+const RATING_MINIMUM = 0;
+const RATING_NEUTRAL = 50;
+const RATING_MAXIMUM = 100;
+
+export const VEHICLE_STAT_DEFINITIONS = {
+  power: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 43000, variance: 3200, output: 'powerNewtons' },
+  braking: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 59000, variance: 4200, output: 'brakeNewtons' },
+  aero: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 6.1, variance: 0.35, output: 'downforceCoefficient' },
+  dragEfficiency: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 0.33, variance: 0.035, direction: -1, output: 'dragCoefficient' },
+  mechanicalGrip: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 2.35, variance: 0.18, output: 'tireGrip' },
+  weightControl: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 798, variance: 10, direction: -1, output: 'mass' },
+  tireCare: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 1, variance: 0.12, output: 'tireCare' },
+};
+
+function clampRating(value, label) {
+  const rating = Number(value);
+  if (!Number.isFinite(rating)) throw new Error(`Invalid vehicle rating for ${label}: ${value}`);
+  return Math.min(Math.max(rating, RATING_MINIMUM), RATING_MAXIMUM);
+}
+
+function applyRating(definition, value) {
+  const normalized = (value - definition.neutral) / (definition.maximum - definition.neutral);
+  const direction = definition.direction ?? 1;
+  return definition.base + normalized * definition.variance * direction;
+}
+
+export class VehicleData {
+  constructor({
+    id = null,
+    name = null,
+    power = RATING_NEUTRAL,
+    braking = RATING_NEUTRAL,
+    aero = RATING_NEUTRAL,
+    dragEfficiency = RATING_NEUTRAL,
+    mechanicalGrip = RATING_NEUTRAL,
+    weightControl = RATING_NEUTRAL,
+    tireCare = RATING_NEUTRAL,
+    customFields = [],
+  } = {}) {
+    this.id = id;
+    this.name = name;
+    this.power = clampRating(power, 'power');
+    this.braking = clampRating(braking, 'braking');
+    this.aero = clampRating(aero, 'aero');
+    this.dragEfficiency = clampRating(dragEfficiency, 'dragEfficiency');
+    this.mechanicalGrip = clampRating(mechanicalGrip, 'mechanicalGrip');
+    this.weightControl = clampRating(weightControl, 'weightControl');
+    this.tireCare = clampRating(tireCare, 'tireCare');
+    this.customFields = normalizeCustomFields(customFields);
+  }
+
+  ratings() {
+    return {
+      power: this.power,
+      braking: this.braking,
+      aero: this.aero,
+      dragEfficiency: this.dragEfficiency,
+      mechanicalGrip: this.mechanicalGrip,
+      weightControl: this.weightControl,
+      tireCare: this.tireCare,
+    };
+  }
+
+  toConstructorArgs() {
+    const ratings = this.ratings();
+    const values = Object.fromEntries(Object.entries(VEHICLE_STAT_DEFINITIONS).map(([key, definition]) => [
+      definition.output,
+      applyRating(definition, ratings[key]),
+    ]));
+
+    return {
+      id: this.id,
+      name: this.name,
+      ratings,
+      customFields: this.customFields,
+      ...values,
+    };
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,399 @@
+export type TireCompound = 'S' | 'M' | 'H';
+export type CameraMode = 'overview' | 'leader' | 'selected';
+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 LayoutPreset = 'standard' | 'left-tower-overlay';
+export type CameraControlsMode = 'embedded' | 'external' | false;
+export type PaddockPresetName = 'dashboard' | 'timing-overlay' | 'compact-race' | 'full-dashboard';
+
+export interface CustomField {
+  label: string;
+  value: string;
+}
+
+export type CustomFieldInput = CustomField[] | Record<string, string>;
+
+export interface TeamData {
+  id?: string;
+  name?: string;
+  color?: string;
+  icon?: string;
+}
+
+export interface SimulatorDriver {
+  id: string;
+  name: string;
+  color: string;
+  link?: string;
+  icon?: string;
+  code?: string;
+  timingName?: string;
+  tire?: TireCompound;
+  raceData?: string[];
+  customFields?: CustomFieldInput;
+  team?: TeamData | null;
+  driverNumber?: number;
+}
+
+export interface DriverRatings {
+  pace: number;
+  racecraft: number;
+  aggression: number;
+  riskTolerance: number;
+  patience: number;
+  consistency: number;
+}
+
+export interface VehicleRatings {
+  power: number;
+  braking: number;
+  aero: number;
+  dragEfficiency: number;
+  mechanicalGrip: number;
+  weightControl: number;
+  tireCare: number;
+}
+
+export interface DriverBlueprint extends Partial<DriverRatings> {
+  customFields?: CustomFieldInput;
+}
+
+export interface VehicleBlueprint extends Partial<VehicleRatings> {
+  id?: string | null;
+  name?: string | null;
+  customFields?: CustomFieldInput;
+}
+
+export interface DriverConstructorArgs {
+  ratings: DriverRatings;
+  customFields: CustomField[];
+  pace: number;
+  racecraft: number;
+  consistency: number;
+  personality: {
+    aggression: number;
+    riskTolerance: number;
+    patience: number;
+  };
+}
+
+export interface VehicleConstructorArgs {
+  id: string | null;
+  name: string | null;
+  ratings: VehicleRatings;
+  customFields: CustomField[];
+  powerNewtons: number;
+  brakeNewtons: number;
+  downforceCoefficient: number;
+  dragCoefficient: number;
+  tireGrip: number;
+  mass: number;
+  tireCare: number;
+}
+
+export class DriverData {
+  constructor(input?: DriverBlueprint);
+  readonly pace: number;
+  readonly racecraft: number;
+  readonly aggression: number;
+  readonly riskTolerance: number;
+  readonly patience: number;
+  readonly consistency: number;
+  readonly customFields: CustomField[];
+  ratings(): DriverRatings;
+  toConstructorArgs(): DriverConstructorArgs;
+}
+
+export class VehicleData {
+  constructor(input?: VehicleBlueprint);
+  readonly id: string | null;
+  readonly name: string | null;
+  readonly power: number;
+  readonly braking: number;
+  readonly aero: number;
+  readonly dragEfficiency: number;
+  readonly mechanicalGrip: number;
+  readonly weightControl: number;
+  readonly tireCare: number;
+  readonly customFields: CustomField[];
+  ratings(): VehicleRatings;
+  toConstructorArgs(): VehicleConstructorArgs;
+}
+
+export interface ChampionshipEntryBlueprint {
+  driverId: string;
+  driverNumber?: number;
+  timingName?: string;
+  driver?: DriverData | DriverBlueprint;
+  vehicle?: VehicleData | VehicleBlueprint;
+  team?: TeamData;
+}
+
+export interface NormalizedSimulatorDriver extends SimulatorDriver {
+  code: string;
+  timingCode: string;
+  raceName: string;
+  driverNumber: number;
+  team: TeamData | null;
+  pace: number;
+  racecraft: number;
+  consistency: number;
+  personality: DriverConstructorArgs['personality'];
+  vehicle: VehicleConstructorArgs;
+  constructorArgs: {
+    driver: DriverConstructorArgs;
+    vehicle: VehicleConstructorArgs;
+  };
+  championship: {
+    id: string;
+    name: string;
+    season: number;
+    entryIndex: number;
+    vehicleId: string | null;
+  };
+}
+
+export interface F1SimulatorTheme {
+  accentColor?: string;
+  greenColor?: string;
+  yellowColor?: string;
+  timingTowerMaxWidth?: string;
+  raceViewMinHeight?: string;
+}
+
+export interface F1SimulatorUiOptions {
+  layoutPreset?: LayoutPreset;
+  cameraControls?: CameraControlsMode;
+  showFps?: boolean;
+  showTimingTower?: boolean;
+  showTelemetry?: boolean;
+  telemetryIncludesOverview?: boolean;
+  showRaceDataPanel?: boolean;
+  raceDataBanners?: {
+    initial?: RaceBannerMode;
+    enabled?: true | false | RaceBannerEnabledMode[];
+  };
+  raceDataBannerSize?: RaceDataBannerSize;
+  timingTowerVerticalFit?: TimingTowerVerticalFit;
+}
+
+export interface TrackTextureAssets {
+  asphalt?: string;
+}
+
+export interface F1SimulatorAssets {
+  car?: string;
+  carOverview?: string;
+  driverHelmet?: string;
+  safetyCar?: string;
+  broadcastPanel?: string;
+  f1Logo?: string;
+  trackTextures?: TrackTextureAssets;
+}
+
+export interface TrackSnapshot {
+  seed?: number | null;
+  width?: number;
+  length?: number;
+  [key: string]: unknown;
+}
+
+export interface RaceEvent {
+  type: string;
+  at?: number;
+  [key: string]: unknown;
+}
+
+export interface CarSnapshot {
+  id: string;
+  rank: number;
+  code: string;
+  timingCode: string;
+  name: string;
+  color: string;
+  tire: TireCompound;
+  lap: number;
+  speedKph: number;
+  finished?: boolean;
+  finishTime?: number | null;
+  classifiedRank?: number | null;
+  intervalAheadSeconds?: number | null;
+  leaderGapSeconds?: number | null;
+  [key: string]: unknown;
+}
+
+export interface RaceClassificationEntry {
+  id: string;
+  rank: number;
+  code: string;
+  lap: number;
+  finished: boolean;
+  finishTime?: number | null;
+  [key: string]: unknown;
+}
+
+export interface RaceSnapshot {
+  time: number;
+  world: {
+    width: number;
+    height: number;
+    [key: string]: unknown;
+  };
+  track: TrackSnapshot;
+  totalLaps: number;
+  raceControl: {
+    mode: string;
+    finished: boolean;
+    finishedAt: number | null;
+    winner: CarSnapshot | null;
+    classification: RaceClassificationEntry[];
+    start: {
+      visible: boolean;
+      [key: string]: unknown;
+    };
+  };
+  safetyCar: {
+    deployed: boolean;
+    [key: string]: unknown;
+  };
+  rules: Record<string, unknown>;
+  events: RaceEvent[];
+  cars: CarSnapshot[];
+}
+
+export interface LifecycleErrorContext {
+  phase?: string;
+  callback?: string;
+}
+
+export interface F1SimulatorCallbacks {
+  onDriverOpen?: (driver: NormalizedSimulatorDriver) => void;
+  onLoadingChange?: (state: { loading: boolean; phase: string }) => void;
+  onReady?: (payload: { snapshot: RaceSnapshot }) => void;
+  onError?: (error: unknown, context: LifecycleErrorContext) => void;
+  onDriverSelect?: (driver: CarSnapshot, snapshot: RaceSnapshot) => void;
+  onRaceEvent?: (event: RaceEvent, snapshot: RaceSnapshot) => void;
+  onLapChange?: (payload: {
+    previousLeaderLap: number | null;
+    leaderLap: number;
+    leader: CarSnapshot | null;
+    snapshot: RaceSnapshot;
+  }) => void;
+  onRaceFinish?: (payload: {
+    winner: CarSnapshot | null;
+    classification: RaceClassificationEntry[];
+    snapshot: RaceSnapshot;
+  }) => void;
+}
+
+export interface F1SimulatorOptions extends F1SimulatorCallbacks {
+  preset?: PaddockPresetName;
+  drivers: SimulatorDriver[];
+  entries?: ChampionshipEntryBlueprint[];
+  seed?: number;
+  trackSeed?: number;
+  totalLaps?: number;
+  initialCameraMode?: CameraMode;
+  theme?: F1SimulatorTheme;
+  title?: string;
+  kicker?: string;
+  backLinkHref?: string;
+  backLinkLabel?: string;
+  showBackLink?: boolean;
+  ui?: F1SimulatorUiOptions;
+  assets?: F1SimulatorAssets;
+}
+
+export interface MountRaceCanvasOptions {
+  includeRaceDataPanel?: boolean;
+  includeTimingTower?: boolean;
+  timingTowerVerticalFit?: TimingTowerVerticalFit;
+}
+
+export interface MountTelemetryPanelOptions {
+  includeOverview?: boolean;
+}
+
+export interface F1MountedSimulator {
+  destroy(): void;
+  restart(nextOptions?: Partial<F1SimulatorOptions>): void;
+  selectDriver(driverId: string): void;
+  setSafetyCarDeployed(deployed: boolean): void;
+  callSafetyCar(): void;
+  clearSafetyCar(): void;
+  toggleSafetyCar(): void;
+  getSnapshot(): RaceSnapshot | null;
+}
+
+export interface PaddockSimulatorController {
+  mountRaceControls<T extends Element>(root: T): T;
+  mountCameraControls<T extends Element>(root: T): T;
+  mountSafetyCarControl<T extends Element>(root: T): T;
+  mountTimingTower<T extends Element>(root: T): T;
+  mountRaceCanvas<T extends Element>(root: T, options?: MountRaceCanvasOptions): T;
+  mountTelemetryPanel<T extends Element>(root: T, options?: MountTelemetryPanelOptions): T;
+  mountCarDriverOverview<T extends Element>(root: T): T;
+  mountRaceDataPanel<T extends Element>(root: T): T;
+  querySelector(selector: string): Element | null;
+  querySelectorAll(selector: string): Element[];
+  start(): Promise<PaddockSimulatorController>;
+  destroy(): void;
+  restart(nextOptions?: Partial<F1SimulatorOptions>): void;
+  selectDriver(driverId: string): void;
+  setSafetyCarDeployed(deployed: boolean): void;
+  callSafetyCar(): void;
+  clearSafetyCar(): void;
+  toggleSafetyCar(): void;
+  getSnapshot(): RaceSnapshot | null;
+}
+
+export const CHAMPIONSHIP_ENTRY_BLUEPRINTS: ChampionshipEntryBlueprint[];
+export const DEMO_PROJECT_DRIVERS: SimulatorDriver[];
+export const DEFAULT_F1_SIMULATOR_ASSETS: Required<F1SimulatorAssets>;
+export const PADDOCK_SIMULATOR_PRESETS: Record<PaddockPresetName, {
+  ui?: F1SimulatorUiOptions;
+  theme?: F1SimulatorTheme;
+}>;
+
+export const REAL_F1_CAR_LENGTH_METERS: number;
+export const SIM_UNITS_PER_METER: number;
+export const TARGET_F1_TOP_SPEED_KPH: number;
+export const VISUAL_CAR_LENGTH_METERS: number;
+
+export function buildChampionshipDriverGrid(
+  drivers?: SimulatorDriver[],
+  entries?: ChampionshipEntryBlueprint[],
+): NormalizedSimulatorDriver[];
+export function formatDriverNumber(driverNumber: number | string | null | undefined): string;
+export function normalizeSimulatorDrivers(
+  drivers: SimulatorDriver[],
+  options?: { entries?: ChampionshipEntryBlueprint[] },
+): NormalizedSimulatorDriver[];
+
+export function metersToSimUnits(meters: number): number;
+export function simUnitsToMeters(simUnits: number): number;
+export function kphToSimSpeed(kph: number): number;
+export function simSpeedToKph(simSpeed: number): number;
+export function simSpeedToMetersPerSecond(simSpeed: number): number;
+
+export function createPaddockSimulator(options: F1SimulatorOptions): PaddockSimulatorController;
+export function mountF1Simulator(root: Element, options: F1SimulatorOptions): Promise<F1MountedSimulator>;
+
+export function mountRaceControls<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
+export function mountCameraControls<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
+export function mountSafetyCarControl<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
+export function mountTimingTower<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
+export function mountRaceCanvas<T extends Element>(
+  root: T,
+  simulator: PaddockSimulatorController,
+  options?: MountRaceCanvasOptions,
+): T;
+export function mountTelemetryPanel<T extends Element>(
+  root: T,
+  simulator: PaddockSimulatorController,
+  options?: MountTelemetryPanelOptions,
+): T;
+export function mountCarDriverOverview<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
+export function mountRaceDataPanel<T extends Element>(root: T, simulator: PaddockSimulatorController): T;

package/src/index.js

@@ -0,0 +1,116 @@
+import './styles.css';
+import { F1SimulatorApp } from './app/F1SimulatorApp.js';
+import { resolveF1SimulatorOptions } from './config/defaultOptions.js';
+import { createF1SimulatorShell } from './ui/shellTemplate.js';
+export {
+  createPaddockSimulator,
+  mountCarDriverOverview,
+  mountCameraControls,
+  mountRaceCanvas,
+  mountRaceControls,
+  mountRaceDataPanel,
+  mountSafetyCarControl,
+  mountTelemetryPanel,
+  mountTimingTower,
+} from './api/PaddockSimulatorController.js';
+
+export {
+  CHAMPIONSHIP_ENTRY_BLUEPRINTS,
+  DriverData,
+  VehicleData,
+  buildChampionshipDriverGrid,
+  formatDriverNumber,
+} 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 { normalizeSimulatorDrivers } from './data/normalizeDrivers.js';
+export {
+  REAL_F1_CAR_LENGTH_METERS,
+  SIM_UNITS_PER_METER,
+  TARGET_F1_TOP_SPEED_KPH,
+  VISUAL_CAR_LENGTH_METERS,
+  kphToSimSpeed,
+  metersToSimUnits,
+  simSpeedToKph,
+  simSpeedToMetersPerSecond,
+  simUnitsToMeters,
+} from './simulation/units.js';
+
+function assertMountRoot(root) {
+  if (!(root instanceof Element)) {
+    throw new Error('mountF1Simulator requires a DOM element root.');
+  }
+}
+
+function mergeRestartOptions(previousOptions, nextOptions) {
+  const resetFromPreset = Object.hasOwn(nextOptions, 'preset');
+  const previousUi = resetFromPreset ? {} : previousOptions.ui;
+  const previousTheme = resetFromPreset ? {} : previousOptions.theme;
+  return {
+    ...previousOptions,
+    ...nextOptions,
+    ui: {
+      ...previousUi,
+      ...(nextOptions.ui ?? {}),
+      raceDataBanners: {
+        ...(previousUi.raceDataBanners ?? {}),
+        ...(nextOptions.ui?.raceDataBanners ?? {}),
+      },
+    },
+    theme: {
+      ...previousTheme,
+      ...(nextOptions.theme ?? {}),
+    },
+    assets: {
+      ...previousOptions.assets,
+      ...(nextOptions.assets ?? {}),
+      trackTextures: {
+        ...previousOptions.assets.trackTextures,
+        ...(nextOptions.assets?.trackTextures ?? {}),
+      },
+    },
+    drivers: nextOptions.drivers ?? previousOptions.drivers,
+    entries: nextOptions.entries ?? previousOptions.entries,
+  };
+}
+
+export async function mountF1Simulator(root, options = {}) {
+  assertMountRoot(root);
+
+  let resolvedOptions = resolveF1SimulatorOptions(options);
+  root.innerHTML = createF1SimulatorShell(resolvedOptions);
+  const shell = root.querySelector('[data-f1-simulator-shell]');
+  const app = new F1SimulatorApp(shell, resolvedOptions);
+  await app.init();
+
+  return {
+    destroy() {
+      app.destroy();
+      root.innerHTML = '';
+    },
+    restart(nextOptions = {}) {
+      resolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(resolvedOptions, nextOptions));
+      app.restart(resolvedOptions);
+    },
+    selectDriver(driverId) {
+      app.selectCar(driverId, { focus: true });
+    },
+    setSafetyCarDeployed(deployed) {
+      app.setSafetyCarDeployed(deployed);
+    },
+    callSafetyCar() {
+      app.setSafetyCarDeployed(true);
+    },
+    clearSafetyCar() {
+      app.setSafetyCarDeployed(false);
+    },
+    toggleSafetyCar() {
+      const active = app.getSnapshot()?.raceControl.mode === 'safety-car';
+      app.setSafetyCarDeployed(!active);
+    },
+    getSnapshot() {
+      return app.getSnapshot();
+    },
+  };
+}