@inventure71/paddockjs 4.1.0 → 4.3.0

package/src/config/timingGapMode.js

@@ -1,5 +1,3 @@
-export const TIMING_GAP_MODES = new Set(['interval', 'leader']);
-
 export function normalizeTimingGapMode(value) {
   return value === 'leader' ? 'leader' : 'interval';
 }

package/src/config/uiOptions.js

@@ -0,0 +1,53 @@
+import { DEFAULT_F1_SIMULATOR_OPTIONS } from './simulatorDefaults.js';
+import { normalizeTelemetryModules } from './telemetryModules.js';
+import { normalizeTimingGapMode } from './timingGapMode.js';
+
+export function resolveSimulatorUiOptions(requestedUi = {}, presetUi = {}, initialCameraMode = 'leader') {
+  const ui = {
+    ...DEFAULT_F1_SIMULATOR_OPTIONS.ui,
+    ...presetUi,
+    ...requestedUi,
+    raceDataBanners: {
+      ...DEFAULT_F1_SIMULATOR_OPTIONS.ui.raceDataBanners,
+      ...(presetUi.raceDataBanners ?? {}),
+      ...(requestedUi.raceDataBanners ?? {}),
+    },
+  };
+  ui.driverCamera = Boolean(ui.driverCamera || initialCameraMode === 'driver');
+  ui.viewControls = ui.viewControls === 'toggle' ? 'toggle' : 'switch';
+  ui.raceDataBanners.enabled = normalizeEnabledBanners(ui.raceDataBanners.enabled);
+  ui.telemetryModules = normalizeTelemetryModules(ui.telemetryModules, DEFAULT_F1_SIMULATOR_OPTIONS.ui.telemetryModules);
+  if (!['project', 'radio', 'hidden'].includes(ui.raceDataBanners.initial)) {
+    ui.raceDataBanners.initial = DEFAULT_F1_SIMULATOR_OPTIONS.ui.raceDataBanners.initial;
+  }
+  if (ui.raceDataBanners.initial !== 'hidden' && !ui.raceDataBanners.enabled.includes(ui.raceDataBanners.initial)) {
+    ui.raceDataBanners.initial = 'hidden';
+  }
+  if (!['expand-race-view', 'scroll'].includes(ui.timingTowerVerticalFit)) {
+    ui.timingTowerVerticalFit = DEFAULT_F1_SIMULATOR_OPTIONS.ui.timingTowerVerticalFit;
+  }
+  ui.timingGapMode = normalizeTimingGapMode(ui.timingGapMode);
+  ui.timingGapModeToggle = ui.timingGapModeToggle !== false;
+  ui.timingEntryVerticalPadding = normalizeNonNegativeFiniteNumber(
+    ui.timingEntryVerticalPadding,
+    DEFAULT_F1_SIMULATOR_OPTIONS.ui.timingEntryVerticalPadding,
+  );
+  ui.responsiveNarrowLayout = ui.responsiveNarrowLayout !== false;
+  if (!['auto', 'custom'].includes(ui.raceDataBannerSize)) {
+    ui.raceDataBannerSize = DEFAULT_F1_SIMULATOR_OPTIONS.ui.raceDataBannerSize;
+  }
+  ui.raceDataTelemetryDetail = Boolean(ui.raceDataTelemetryDetail);
+  return ui;
+}
+
+function normalizeNonNegativeFiniteNumber(value, fallback) {
+  const numericValue = Number(value);
+  return Number.isFinite(numericValue) && numericValue >= 0 ? numericValue : fallback;
+}
+
+function normalizeEnabledBanners(value) {
+  if (value === false) return [];
+  if (value === true || value == null) return [...DEFAULT_F1_SIMULATOR_OPTIONS.ui.raceDataBanners.enabled];
+  if (!Array.isArray(value)) return [...DEFAULT_F1_SIMULATOR_OPTIONS.ui.raceDataBanners.enabled];
+  return [...new Set(value.filter((item) => item === 'project' || item === 'radio'))];
+}

package/src/data/championship.js

@@ -1,147 +1,26 @@
 import { DriverData } from './driverData.js';
 import { DEMO_PROJECT_DRIVERS } from './demoDrivers.js';
 import { VehicleData } from './vehicleData.js';
-import { DEFAULT_DARK_THEME_TOKENS, normalizeCssColorToken } from '../config/themeOptions.js';
+import { normalizeEntryPresentation } from './entryPresentation.js';
+import { DEFAULT_DARK_THEME_TOKENS } from '../config/theme/themeTokens.js';
+import { normalizeCssColorToken } from '../config/theme/cssTokens.js';
+import { CHAMPIONSHIP, CHAMPIONSHIP_ENTRY_BLUEPRINTS, CHAMPIONSHIP_DRIVER_ENTRIES } from './championshipDefaults.js';
+import { normalizeTeam, pickUniqueTimingCode } from './entryIdentity.js';
 
 export { DriverData, DRIVER_STAT_DEFINITIONS } from './driverData.js';
 export { VehicleData, VEHICLE_STAT_DEFINITIONS } from './vehicleData.js';
-
-export const CHAMPIONSHIP = {
-  id: 'project-race-2026',
-  name: 'Project Race',
-  season: 2026,
-};
-
-export const CHAMPIONSHIP_ENTRY_BLUEPRINTS = [
-  {
-    driverId: 'budget',
-    driverNumber: 71,
-    timingName: 'Budget',
-    driver: new DriverData({ pace: 52, racecraft: 74, aggression: 38, riskTolerance: 47, patience: 81, consistency: 86 }),
-    vehicle: new VehicleData({ id: 'budget-bb01', name: 'BB-01 Ledger', power: 48, braking: 72, aero: 55, dragEfficiency: 66, mechanicalGrip: 63, weightControl: 58, tireCare: 82 }),
-  },
-  {
-    driverId: 'noir',
-    driverNumber: 13,
-    timingName: 'Noir',
-    driver: new DriverData({ pace: 68, racecraft: 83, aggression: 61, riskTolerance: 72, patience: 57, consistency: 64 }),
-    vehicle: new VehicleData({ id: 'noir-nn13', name: 'NN-13 Shadow', power: 64, braking: 60, aero: 73, dragEfficiency: 57, mechanicalGrip: 69, weightControl: 54, tireCare: 51 }),
-  },
-  {
-    driverId: 'vinyl',
-    driverNumber: 33,
-    timingName: 'HoloVinyl',
-    driver: new DriverData({ pace: 71, racecraft: 66, aggression: 52, riskTolerance: 59, patience: 62, consistency: 58 }),
-    vehicle: new VehicleData({ id: 'vinyl-hv33', name: 'HV-33 Groove', power: 70, braking: 49, aero: 58, dragEfficiency: 74, mechanicalGrip: 52, weightControl: 68, tireCare: 46 }),
-  },
-  {
-    driverId: 'drsorriso',
-    driverNumber: 55,
-    timingName: 'DrSorriso',
-    driver: new DriverData({ pace: 46, racecraft: 69, aggression: 44, riskTolerance: 43, patience: 76, consistency: 73 }),
-    vehicle: new VehicleData({ id: 'sorriso-ds55', name: 'DS-55 Intake', power: 54, braking: 67, aero: 62, dragEfficiency: 49, mechanicalGrip: 71, weightControl: 45, tireCare: 69 }),
-  },
-  {
-    driverId: 'victoria',
-    driverNumber: 11,
-    timingName: 'VictorIA',
-    driver: new DriverData({ pace: 78, racecraft: 79, aggression: 58, riskTolerance: 65, patience: 55, consistency: 68 }),
-    vehicle: new VehicleData({ id: 'victoria-vi11', name: 'VI-11 Vector', power: 76, braking: 58, aero: 65, dragEfficiency: 63, mechanicalGrip: 61, weightControl: 60, tireCare: 48 }),
-  },
-  {
-    driverId: 'reminderz',
-    driverNumber: 7,
-    timingName: 'ReminderZ',
-    driver: new DriverData({ pace: 41, racecraft: 61, aggression: 34, riskTolerance: 39, patience: 85, consistency: 80 }),
-    vehicle: new VehicleData({ id: 'reminderz-rz07', name: 'RZ-07 Recall', power: 42, braking: 76, aero: 50, dragEfficiency: 72, mechanicalGrip: 58, weightControl: 63, tireCare: 88 }),
-  },
-  {
-    driverId: 'clipclop',
-    driverNumber: 14,
-    timingName: 'ClipClop',
-    driver: new DriverData({ pace: 73, racecraft: 88, aggression: 76, riskTolerance: 78, patience: 48, consistency: 61 }),
-    vehicle: new VehicleData({ id: 'clipclop-cc14', name: 'CC-14 Sync', power: 68, braking: 63, aero: 59, dragEfficiency: 61, mechanicalGrip: 78, weightControl: 56, tireCare: 44 }),
-  },
-  {
-    driverId: 'evolve',
-    driverNumber: 23,
-    timingName: 'Evolve',
-    driver: new DriverData({ pace: 56, racecraft: 70, aggression: 63, riskTolerance: 61, patience: 58, consistency: 52 }),
-    vehicle: new VehicleData({ id: 'evolve-ev23', name: 'EV-23 Morph', power: 60, braking: 53, aero: 79, dragEfficiency: 46, mechanicalGrip: 66, weightControl: 49, tireCare: 57 }),
-  },
-  {
-    driverId: 'clash',
-    driverNumber: 47,
-    timingName: 'Clash',
-    driver: new DriverData({ pace: 44, racecraft: 67, aggression: 70, riskTolerance: 69, patience: 42, consistency: 59 }),
-    vehicle: new VehicleData({ id: 'clash-cr47', name: 'CR-47 Arena', power: 57, braking: 48, aero: 52, dragEfficiency: 55, mechanicalGrip: 73, weightControl: 52, tireCare: 64 }),
-  },
-  {
-    driverId: 'core',
-    driverNumber: 91,
-    timingName: 'Core',
-    driver: new DriverData({ pace: 82, racecraft: 85, aggression: 67, riskTolerance: 74, patience: 53, consistency: 72 }),
-    vehicle: new VehicleData({ id: 'core-ai91', name: 'AI-91 Core', power: 80, braking: 61, aero: 72, dragEfficiency: 59, mechanicalGrip: 75, weightControl: 51, tireCare: 50 }),
-  },
-];
-
-export const CHAMPIONSHIP_DRIVER_ENTRIES = CHAMPIONSHIP_ENTRY_BLUEPRINTS.map((entry) => ({
-  driverId: entry.driverId,
-  driverNumber: entry.driverNumber,
-  timingName: entry.timingName,
-}));
-
-const LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
-
-function normalizeLetters(value) {
-  return String(value ?? '')
-    .normalize('NFKD')
-    .replace(/[\u0300-\u036f]/g, '')
-    .replace(/[^a-zA-Z]/g, '')
-    .toUpperCase();
-}
-
-function timingCodeCandidates(source) {
-  const letters = normalizeLetters(source);
-  if (!letters) return ['XXX'];
-  if (letters.length <= 3) return [letters.padEnd(3, 'X')];
-
-  const candidates = [letters.slice(0, 3)];
-  for (let index = 1; index <= letters.length - 3; index += 1) {
-    candidates.push(letters.slice(index, index + 3));
-  }
-  candidates.push(`${letters[0]}${letters[1]}${letters[letters.length - 1]}`);
-  return [...new Set(candidates)];
-}
-
-function pickUniqueTimingCode(source, usedCodes) {
-  for (const candidate of timingCodeCandidates(source)) {
-    if (!usedCodes.has(candidate)) {
-      usedCodes.add(candidate);
-      return candidate;
-    }
-  }
-
-  const letters = normalizeLetters(source).padEnd(2, 'X');
-  for (const suffix of LETTERS) {
-    const candidate = `${letters[0]}${letters[1]}${suffix}`;
-    if (!usedCodes.has(candidate)) {
-      usedCodes.add(candidate);
-      return candidate;
-    }
-  }
-
-  throw new Error(`Unable to create a unique three-letter timing code for "${source}"`);
-}
+export { CHAMPIONSHIP, CHAMPIONSHIP_ENTRY_BLUEPRINTS, CHAMPIONSHIP_DRIVER_ENTRIES } from './championshipDefaults.js';
+export { formatDriverNumber } from './entryIdentity.js';
 
 function assertUniqueDriverNumbers(entries) {
-  const seen = new Set();
+  const seen = new Map();
   entries.forEach((entry) => {
     if (entry.driverNumber == null) return;
+    const driverId = entry.driverId ?? entry.id;
     if (seen.has(entry.driverNumber)) {
-      throw new Error(`Duplicate championship driver number: ${entry.driverNumber}`);
+      throw new Error(`Duplicate championship driver number: ${entry.driverNumber} (${seen.get(entry.driverNumber)} and ${driverId})`);
     }
-    seen.add(entry.driverNumber);
+    seen.set(entry.driverNumber, driverId);
   });
 }
 
@@ -170,29 +49,6 @@ function buildVehicleConstructorArgs(entry) {
   return vehicle.toConstructorArgs();
 }
 
-export function formatDriverNumber(driverNumber) {
-  return String(driverNumber ?? '').padStart(2, '0');
-}
-
-function normalizeTeamIcon(source) {
-  const letters = normalizeLetters(source);
-  return letters.slice(0, 2).padEnd(2, 'X');
-}
-
-function normalizeTeam(team, driver, timingCode) {
-  const source = team ?? driver.team;
-  if (!source) return null;
-  const name = source.name ?? source.id ?? `${driver.name ?? timingCode} Team`;
-  const id = (source.id ?? normalizeLetters(name).toLowerCase()) || `${driver.id}-team`;
-  return {
-    ...source,
-    id,
-    name,
-    color: normalizeCssColorToken(source.color ?? driver.color, driver.color),
-    icon: source.icon ?? normalizeTeamIcon(source.name ?? source.id ?? timingCode ?? driver.name),
-  };
-}
-
 export function buildChampionshipDriverGrid(drivers = DEMO_PROJECT_DRIVERS, entries = CHAMPIONSHIP_DRIVER_ENTRIES) {
   assertUniqueEntryDriverIds(entries);
   assertUniqueDriverNumbers(entries);
@@ -201,7 +57,7 @@ export function buildChampionshipDriverGrid(drivers = DEMO_PROJECT_DRIVERS, entr
   const blueprintByDriverId = new Map(CHAMPIONSHIP_ENTRY_BLUEPRINTS.map((entry) => [entry.driverId, entry]));
   const usedTimingCodes = new Set();
 
-  return drivers.map((driver, index) => {
+  const grid = drivers.map((driver, index) => {
     const safeDriver = {
       ...driver,
       color: normalizeCssColorToken(driver.color, DEFAULT_DARK_THEME_TOKENS.primary),
@@ -217,6 +73,7 @@ export function buildChampionshipDriverGrid(drivers = DEMO_PROJECT_DRIVERS, entr
 
     return {
       ...safeDriver,
+      presentation: normalizeEntryPresentation(safeDriver, entry.presentation ?? safeDriver.presentation),
       code: timingCode,
       timingCode,
       raceName: timingCode,
@@ -226,6 +83,7 @@ export function buildChampionshipDriverGrid(drivers = DEMO_PROJECT_DRIVERS, entr
       racecraft: driverArgs.racecraft,
       consistency: driverArgs.consistency,
       personality: driverArgs.personality,
+      driverModel: safeDriver.driverModel ?? driverArgs.driverModel ?? vehicleArgs.driverModel ?? null,
       vehicle: vehicleArgs,
       constructorArgs: {
         driver: driverArgs,
@@ -238,6 +96,6 @@ export function buildChampionshipDriverGrid(drivers = DEMO_PROJECT_DRIVERS, entr
       },
     };
   });
+  assertUniqueDriverNumbers(grid);
+  return grid;
 }
-
-export const CHAMPIONSHIP_PROJECT_DRIVERS = buildChampionshipDriverGrid();

package/src/data/championshipDefaults.js

@@ -0,0 +1,87 @@
+import { DriverData } from './driverData.js';
+import { VehicleData } from './vehicleData.js';
+
+export const CHAMPIONSHIP = {
+  id: 'project-race-2026',
+  name: 'Project Race',
+  season: 2026,
+};
+
+export const CHAMPIONSHIP_ENTRY_BLUEPRINTS = [
+  {
+    driverId: 'budget',
+    driverNumber: 71,
+    timingName: 'Budget',
+    driver: new DriverData({ pace: 52, racecraft: 74, aggression: 38, riskTolerance: 47, patience: 81, consistency: 86 }),
+    vehicle: new VehicleData({ id: 'budget-bb01', name: 'BB-01 Ledger', power: 48, braking: 72, aero: 55, dragEfficiency: 66, mechanicalGrip: 63, weightControl: 58, tireCare: 82 }),
+  },
+  {
+    driverId: 'noir',
+    driverNumber: 13,
+    timingName: 'Noir',
+    driver: new DriverData({ pace: 68, racecraft: 83, aggression: 61, riskTolerance: 72, patience: 57, consistency: 64 }),
+    vehicle: new VehicleData({ id: 'noir-nn13', name: 'NN-13 Shadow', power: 64, braking: 60, aero: 73, dragEfficiency: 57, mechanicalGrip: 69, weightControl: 54, tireCare: 51 }),
+  },
+  {
+    driverId: 'vinyl',
+    driverNumber: 33,
+    timingName: 'HoloVinyl',
+    driver: new DriverData({ pace: 71, racecraft: 66, aggression: 52, riskTolerance: 59, patience: 62, consistency: 58 }),
+    vehicle: new VehicleData({ id: 'vinyl-hv33', name: 'HV-33 Groove', power: 70, braking: 49, aero: 58, dragEfficiency: 74, mechanicalGrip: 52, weightControl: 68, tireCare: 46 }),
+  },
+  {
+    driverId: 'drsorriso',
+    driverNumber: 55,
+    timingName: 'DrSorriso',
+    driver: new DriverData({ pace: 46, racecraft: 69, aggression: 44, riskTolerance: 43, patience: 76, consistency: 73 }),
+    vehicle: new VehicleData({ id: 'sorriso-ds55', name: 'DS-55 Intake', power: 54, braking: 67, aero: 62, dragEfficiency: 49, mechanicalGrip: 71, weightControl: 45, tireCare: 69 }),
+  },
+  {
+    driverId: 'victoria',
+    driverNumber: 11,
+    timingName: 'VictorIA',
+    driver: new DriverData({ pace: 78, racecraft: 79, aggression: 58, riskTolerance: 65, patience: 55, consistency: 68 }),
+    vehicle: new VehicleData({ id: 'victoria-vi11', name: 'VI-11 Vector', power: 76, braking: 58, aero: 65, dragEfficiency: 63, mechanicalGrip: 61, weightControl: 60, tireCare: 48 }),
+  },
+  {
+    driverId: 'reminderz',
+    driverNumber: 7,
+    timingName: 'ReminderZ',
+    driver: new DriverData({ pace: 41, racecraft: 61, aggression: 34, riskTolerance: 39, patience: 85, consistency: 80 }),
+    vehicle: new VehicleData({ id: 'reminderz-rz07', name: 'RZ-07 Recall', power: 42, braking: 76, aero: 50, dragEfficiency: 72, mechanicalGrip: 58, weightControl: 63, tireCare: 88 }),
+  },
+  {
+    driverId: 'clipclop',
+    driverNumber: 14,
+    timingName: 'ClipClop',
+    driver: new DriverData({ pace: 73, racecraft: 88, aggression: 76, riskTolerance: 78, patience: 48, consistency: 61 }),
+    vehicle: new VehicleData({ id: 'clipclop-cc14', name: 'CC-14 Sync', power: 68, braking: 63, aero: 59, dragEfficiency: 61, mechanicalGrip: 78, weightControl: 56, tireCare: 44 }),
+  },
+  {
+    driverId: 'evolve',
+    driverNumber: 23,
+    timingName: 'Evolve',
+    driver: new DriverData({ pace: 56, racecraft: 70, aggression: 63, riskTolerance: 61, patience: 58, consistency: 52 }),
+    vehicle: new VehicleData({ id: 'evolve-ev23', name: 'EV-23 Morph', power: 60, braking: 53, aero: 79, dragEfficiency: 46, mechanicalGrip: 66, weightControl: 49, tireCare: 57 }),
+  },
+  {
+    driverId: 'clash',
+    driverNumber: 47,
+    timingName: 'Clash',
+    driver: new DriverData({ pace: 44, racecraft: 67, aggression: 70, riskTolerance: 69, patience: 42, consistency: 59 }),
+    vehicle: new VehicleData({ id: 'clash-cr47', name: 'CR-47 Arena', power: 57, braking: 48, aero: 52, dragEfficiency: 55, mechanicalGrip: 73, weightControl: 52, tireCare: 64 }),
+  },
+  {
+    driverId: 'core',
+    driverNumber: 91,
+    timingName: 'Core',
+    driver: new DriverData({ pace: 82, racecraft: 85, aggression: 67, riskTolerance: 74, patience: 53, consistency: 72 }),
+    vehicle: new VehicleData({ id: 'core-ai91', name: 'AI-91 Core', power: 80, braking: 61, aero: 72, dragEfficiency: 59, mechanicalGrip: 75, weightControl: 51, tireCare: 50 }),
+  },
+];
+
+export const CHAMPIONSHIP_DRIVER_ENTRIES = CHAMPIONSHIP_ENTRY_BLUEPRINTS.map((entry) => ({
+  driverId: entry.driverId,
+  driverNumber: entry.driverNumber,
+  timingName: entry.timingName,
+}));

package/src/data/driverData.js

@@ -1,8 +1,6 @@
 import { normalizeCustomFields } from './customFields.js';
 
-const RATING_MINIMUM = 0;
-const RATING_NEUTRAL = 50;
-const RATING_MAXIMUM = 100;
+import { RATING_MINIMUM, RATING_NEUTRAL, RATING_MAXIMUM, clampRating, applyRating } from './ratingScale.js';
 
 export const DRIVER_STAT_DEFINITIONS = {
   pace: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 1, variance: 0.08 },
@@ -13,17 +11,6 @@ export const DRIVER_STAT_DEFINITIONS = {
   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,
@@ -33,14 +20,16 @@ export class DriverData {
     patience = RATING_NEUTRAL,
     consistency = RATING_NEUTRAL,
     customFields = [],
+    driverModel = null,
   } = {}) {
-    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.pace = clampRating(pace, 'pace', 'driver');
+    this.racecraft = clampRating(racecraft, 'racecraft', 'driver');
+    this.aggression = clampRating(aggression, 'aggression', 'driver');
+    this.riskTolerance = clampRating(riskTolerance, 'riskTolerance', 'driver');
+    this.patience = clampRating(patience, 'patience', 'driver');
+    this.consistency = clampRating(consistency, 'consistency', 'driver');
     this.customFields = normalizeCustomFields(customFields);
+    this.driverModel = driverModel;
   }
 
   ratings() {
@@ -58,6 +47,7 @@ export class DriverData {
     return {
       ratings: this.ratings(),
       customFields: this.customFields,
+      driverModel: this.driverModel,
       pace: applyRating(DRIVER_STAT_DEFINITIONS.pace, this.pace),
       racecraft: applyRating(DRIVER_STAT_DEFINITIONS.racecraft, this.racecraft),
       consistency: applyRating(DRIVER_STAT_DEFINITIONS.consistency, this.consistency),

package/src/data/entryIdentity.js

@@ -0,0 +1,67 @@
+import { normalizeCssColorToken } from '../config/theme/cssTokens.js';
+
+const LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+function normalizeLetters(value) {
+  return String(value ?? '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-zA-Z]/g, '')
+    .toUpperCase();
+}
+
+function timingCodeCandidates(source) {
+  const letters = normalizeLetters(source);
+  if (!letters) return ['XXX'];
+  if (letters.length <= 3) return [letters.padEnd(3, 'X')];
+
+  const candidates = [letters.slice(0, 3)];
+  for (let index = 1; index <= letters.length - 3; index += 1) {
+    candidates.push(letters.slice(index, index + 3));
+  }
+  candidates.push(`${letters[0]}${letters[1]}${letters[letters.length - 1]}`);
+  return [...new Set(candidates)];
+}
+
+export function pickUniqueTimingCode(source, usedCodes) {
+  for (const candidate of timingCodeCandidates(source)) {
+    if (!usedCodes.has(candidate)) {
+      usedCodes.add(candidate);
+      return candidate;
+    }
+  }
+
+  const letters = normalizeLetters(source).padEnd(2, 'X');
+  for (const suffix of LETTERS) {
+    const candidate = `${letters[0]}${letters[1]}${suffix}`;
+    if (!usedCodes.has(candidate)) {
+      usedCodes.add(candidate);
+      return candidate;
+    }
+  }
+
+  throw new Error(`Unable to create a unique three-letter timing code for "${source}"`);
+}
+
+export function formatDriverNumber(driverNumber) {
+  return String(driverNumber ?? '').padStart(2, '0');
+}
+
+function normalizeTeamIcon(source) {
+  const letters = normalizeLetters(source);
+  return letters.slice(0, 2).padEnd(2, 'X');
+}
+
+export function normalizeTeam(team, driver, timingCode) {
+  const source = team ?? driver.team;
+  if (!source) return null;
+  const name = source.name ?? source.id ?? `${driver.name ?? timingCode} Team`;
+  const id = (source.id ?? normalizeLetters(name).toLowerCase()) || `${driver.id}-team`;
+  return {
+    ...source,
+    id,
+    name,
+    color: normalizeCssColorToken(source.color ?? driver.color, driver.color),
+    icon: source.icon ?? normalizeTeamIcon(source.name ?? source.id ?? timingCode ?? driver.name),
+  };
+}

package/src/data/entryPresentation.js

@@ -0,0 +1,23 @@
+import { normalizePublicUrlOption } from '../config/urlOptions.js';
+
+function text(value, fallback = '') {
+  return typeof value === 'string' ? value : fallback;
+}
+
+function lines(value) {
+  return Array.isArray(value) ? value.filter((line) => typeof line === 'string' && line.trim()) : [];
+}
+
+export function normalizeEntryPresentation(driver, source = driver.presentation ?? {}) {
+  const image = source?.image;
+  const imageSrc = normalizePublicUrlOption(image?.src, '');
+  return {
+    name: text(source?.name).trim() || driver.name,
+    summary: text(source?.summary, text(driver.raceData?.[0])),
+    technologies: lines(source?.technologies),
+    details: lines(source?.details ?? driver.raceData?.slice(1)),
+    image: imageSrc ? { src: imageSrc, alt: text(image.alt) } : null,
+    href: normalizePublicUrlOption(source?.href ?? driver.link, ''),
+    linkLabel: text(source?.linkLabel).trim() || 'Open project',
+  };
+}

package/src/data/entryTypes.d.ts

@@ -0,0 +1,160 @@
+import type { TeamData } from './teamTypes.js';
+
+export type TireCompound = 'S' | 'M' | 'H';
+export interface CustomField {
+  label: string;
+  value: string;
+}
+
+export type CustomFieldInput = CustomField[] | Record<string, string>;
+export interface EntryPresentation {
+  name?: string;
+  summary?: string;
+  technologies?: string[];
+  details?: string[];
+  image?: { src: string; alt?: string } | null;
+  href?: string;
+  linkLabel?: string;
+}
+
+export interface SimulatorDriver {
+  presentation?: EntryPresentation;
+  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;
+  driverModel?: unknown;
+}
+
+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;
+  driverModel?: unknown;
+}
+
+export interface VehicleBlueprint extends Partial<VehicleRatings> {
+  id?: string | null;
+  name?: string | null;
+  customFields?: CustomFieldInput;
+  driverModel?: unknown;
+}
+
+export interface DriverConstructorArgs {
+  ratings: DriverRatings;
+  customFields: CustomField[];
+  driverModel: unknown | null;
+  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[];
+  driverModel: unknown | null;
+  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[];
+  readonly driverModel: unknown | null;
+  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[];
+  readonly driverModel: unknown | null;
+  ratings(): VehicleRatings;
+  toConstructorArgs(): VehicleConstructorArgs;
+}
+
+export interface ChampionshipEntryBlueprint {
+  presentation?: EntryPresentation;
+  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;
+  };
+}