@inventure71/paddockjs 3.0.0 → 4.0.0

package/examples/python/README.md

@@ -14,6 +14,8 @@ It is not a trainer and not a model/checkpoint format owner. It only shows trans
 - Preview latest-frame HTTP endpoint (for polling visualizers)
   - `http://127.0.0.1:8787/preview/frame`
 
+Policy HTTP uses protocol version `2`. `POST /policy/reset` receives static metadata (`actionSpec`, `observationSpec`, configuration) once per session. `POST /policy/decide-batch` is compact and receives `driverIds`, `vectors`, `previousActions`, `metrics`, and `events`; it does not receive rich observation objects, schemas, snapshots, or track metadata every decision.
+
 ## Run
 
 ```bash
@@ -55,6 +57,10 @@ Subclass `BasePolicyServer` and override:
 
 Use `broadcast_preview_frame(snapshot, observation, meta)` to push authoritative frames to the browser renderer.
 
+Inside `decide_batch(ctx)`, compact per-driver fields are aligned arrays:
+`ctx["vectors"][index]` belongs to `ctx["driverIds"][index]`. The base example's
+`compact_values_by_driver(ctx, "vectors")` helper maps them back to driver ids.
+
 ## Important Boundary
 
 - This server does not step the simulator by itself.

package/examples/python/base_policy_server.py

@@ -10,6 +10,9 @@ This file is intentionally minimal and transport-focused:
   - /preview (broadcasts {snapshot, observation, meta})
 
 Extend `BasePolicyServer` and override hook methods to plug your own model/runtime.
+Policy HTTP uses protocolVersion 2. Reset receives static specs/configuration;
+decide-batch receives compact per-driver vectors instead of rich observations.
+Compact per-driver fields are arrays aligned with driverIds.
 """
 
 from __future__ import annotations
@@ -33,6 +36,20 @@ def _zero_action() -> Dict[str, float]:
     }
 
 
+def compact_values_by_driver(context: Mapping[str, Any], field: str) -> Dict[str, Any]:
+    """Map a compact aligned field such as vectors/metrics back to driver ids."""
+    driver_ids = list(context.get("driverIds") or [])
+    values = context.get(field) or []
+    if isinstance(values, Mapping):
+        return {driver_id: values.get(driver_id) for driver_id in driver_ids}
+    if not isinstance(values, list):
+        return {driver_id: None for driver_id in driver_ids}
+    return {
+        driver_id: values[index] if index < len(values) else None
+        for index, driver_id in enumerate(driver_ids)
+    }
+
+
 @dataclass
 class ServerState:
     session_id: int = 0
@@ -70,6 +87,8 @@ class BasePolicyServer:
     async def decide_batch(self, context: Mapping[str, Any]) -> Dict[str, Dict[str, float]]:
         """Return per-driver controls for one batched policy step."""
         driver_ids = list(context.get("driverIds") or [])
+        vectors_by_driver = compact_values_by_driver(context, "vectors")
+        _ = vectors_by_driver
         return {driver_id: _zero_action() for driver_id in driver_ids}
 
     async def publish_preview_frame(self, frame: Mapping[str, Any]) -> None:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "type": "module",
   "description": "A data-driven browser F1 simulator component for host websites.",
   "license": "Apache-2.0",
@@ -45,6 +45,11 @@
       "import": "./src/environment/index.js",
       "default": "./src/environment/index.js"
     },
+    "./data": {
+      "types": "./src/data/index.d.ts",
+      "import": "./src/data/index.js",
+      "default": "./src/data/index.js"
+    },
     "./styles.css": "./src/styles.css"
   },
   "files": [
@@ -75,13 +80,15 @@
     "test": "node scripts/run-vitest.mjs --slow",
     "test:fast": "node scripts/run-vitest.mjs",
     "types:check": "tsc -p tsconfig.types.json --noEmit",
-    "check": "npm run test:fast && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run showcase:ci && npm run browser:smoke:quick -- --skip-build",
-    "check:release": "npm test && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run showcase:ci && npm run browser:smoke:full -- --skip-build",
+    "docs:check": "node scripts/docs-check.mjs",
+    "check": "npm run docs:check && npm run test:fast && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run showcase:ci && npm run browser:smoke:quick -- --skip-build",
+    "check:release": "npm run docs:check && npm test && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run showcase:ci && npm run browser:smoke:full -- --skip-build",
     "pack:dry": "npm pack --dry-run",
     "consumer:smoke": "node scripts/consumer-package-smoke.mjs",
     "browser:smoke": "node smoke/browser-smoke.mjs",
     "browser:smoke:quick": "node smoke/browser-smoke.mjs --quick",
     "browser:smoke:full": "node smoke/browser-smoke.mjs --full",
+    "benchmark:runtime": "node scripts/benchmark-runtime-efficiency.mjs",
     "showcase:install": "npm --prefix local-preview ci",
     "showcase:dev": "npm --prefix local-preview run dev",
     "showcase:build": "npm --prefix local-preview run build",

package/src/api/PaddockSimulatorController.js

@@ -22,6 +22,7 @@ import { applyPaddockThemeCssVariables, resolveF1SimulatorOptions } from '../con
 import { formatCssUrl } from '../config/cssValues.js';
 import { mergeRestartOptions } from '../config/restartOptions.js';
 import { getNextTimingGapMode, normalizeTimingGapMode } from '../config/timingGapMode.js';
+import { createThemeSync, resolveRuntimeThemeModeOptions, resolveRuntimeThemeOptions } from './runtimeTheme.js';
 
 function assertMountTarget(root, label) {
   if (!root || typeof root !== 'object' || !('innerHTML' in root)) {
@@ -29,10 +30,10 @@ function assertMountTarget(root, label) {
   }
 }
 
-function setPackageCssVariables(root, assets, theme) {
+function setPackageCssVariables(root, assets, theme, context = {}) {
   root.classList?.add?.('f1-sim-component');
   root.style?.setProperty?.('--broadcast-panel-surface', formatCssUrl(assets.broadcastPanel));
-  applyPaddockThemeCssVariables(root, theme);
+  applyPaddockThemeCssVariables(root, theme, context);
 }
 
 function createCompositeRoot(getRoots, getOptions) {
@@ -41,6 +42,9 @@ function createCompositeRoot(getRoots, getOptions) {
       setProperty(name, value) {
         getRoots().forEach((root) => root.style?.setProperty?.(name, value));
       },
+      removeProperty(name) {
+        getRoots().forEach((root) => root.style?.removeProperty?.(name));
+      },
     },
     querySelector(selector) {
       for (const root of getRoots()) {
@@ -58,9 +62,9 @@ function createCompositeRoot(getRoots, getOptions) {
     removeAttribute(name) {
       getRoots().forEach((root) => root.removeAttribute?.(name));
     },
-    applyCssVariables() {
+    applyCssVariables(context = {}) {
       const options = getOptions();
-      getRoots().forEach((root) => setPackageCssVariables(root, options.assets, options.theme));
+      getRoots().forEach((root) => setPackageCssVariables(root, options.assets, options.theme, context));
     },
   };
 }
@@ -69,38 +73,41 @@ export class PaddockSimulatorController {
   constructor(options = {}) {
     this.options = resolveF1SimulatorOptions(options);
     this.roots = new Map();
+    this.mountRenderers = new Map();
     this.layoutSupportCleanups = new Map();
     this.app = null;
     this.compositeRoot = createCompositeRoot(() => [...this.roots.values()], () => this.options);
   }
 
-  mountComponent(root, key, markup) {
+  mountComponent(root, key, createMarkup) {
     assertMountTarget(root, `mount ${key}`);
     if (this.app) {
       throw new Error('Mount PaddockJS components before calling start().');
     }
-    root.innerHTML = markup;
+    const render = typeof createMarkup === 'function' ? createMarkup : () => createMarkup;
+    root.innerHTML = render();
     setPackageCssVariables(root, this.options.assets, this.options.theme);
     this.layoutSupportCleanups.get(key)?.();
     this.layoutSupportCleanups.set(key, installLayoutSupport(root));
     this.roots.set(key, root);
+    this.mountRenderers.set(key, render);
     return root;
   }
 
   mountRaceControls(root) {
-    return this.mountComponent(root, 'race-controls', createRaceControlsMarkup(this.options));
+    return this.mountComponent(root, 'race-controls', () => createRaceControlsMarkup(this.options));
   }
 
   mountCameraControls(root) {
-    return this.mountComponent(root, 'camera-controls', createCameraControlsMarkup(this.options));
+    return this.mountComponent(root, 'camera-controls', () => createCameraControlsMarkup(this.options));
   }
 
   mountSafetyCarControl(root) {
-    return this.mountComponent(root, 'safety-car-control', createSafetyCarControlMarkup(this.options));
+    return this.mountComponent(root, 'safety-car-control', () => createSafetyCarControlMarkup(this.options));
   }
 
   mountTimingTower(root) {
-    return this.mountComponent(root, 'timing-tower', createTimingTowerMarkup(this.options));
+    return this.mountComponent(root, 'timing-tower', () => createTimingTowerMarkup(this.options));
   }
 
   mountRaceCanvas(root, {
@@ -110,7 +117,7 @@ export class PaddockSimulatorController {
     timingTowerVerticalFit,
     responsiveNarrowLayout,
   } = {}) {
-    return this.mountComponent(root, 'race-canvas', createRaceCanvasMarkup({
+    return this.mountComponent(root, 'race-canvas', () => createRaceCanvasMarkup({
       ...this.options,
       includeRaceDataPanel,
       includeTimingTower,
@@ -121,39 +128,39 @@ export class PaddockSimulatorController {
   }
 
   mountTelemetryPanel(root, { includeOverview } = {}) {
-    return this.mountComponent(root, 'telemetry-stack', createTelemetryPanelMarkup(this.options, { includeOverview }));
+    return this.mountComponent(root, 'telemetry-stack', () => createTelemetryPanelMarkup(this.options, { includeOverview }));
   }
 
   mountTelemetryCore(root) {
-    return this.mountComponent(root, 'telemetry-core', createTelemetryCoreMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-core', () => createTelemetryCoreMarkup(this.options));
   }
 
   mountTelemetrySectors(root) {
-    return this.mountComponent(root, 'telemetry-sectors', createTelemetrySectorsMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-sectors', () => createTelemetrySectorsMarkup(this.options));
   }
 
   mountTelemetryLapTimes(root) {
-    return this.mountComponent(root, 'telemetry-lap-times', createTelemetryLapTimesMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-lap-times', () => createTelemetryLapTimesMarkup(this.options));
   }
 
   mountTelemetrySectorTimes(root) {
-    return this.mountComponent(root, 'telemetry-sector-times', createTelemetrySectorTimesMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-sector-times', () => createTelemetrySectorTimesMarkup(this.options));
   }
 
   mountTelemetrySectorBanner(root) {
-    return this.mountComponent(root, 'telemetry-sector-banner', createTelemetrySectorBannerMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-sector-banner', () => createTelemetrySectorBannerMarkup(this.options));
   }
 
   mountRaceTelemetryDrawer(root, options = {}) {
-    return this.mountComponent(root, 'race-telemetry-drawer', createRaceTelemetryDrawerMarkup(this.options, options));
+    return this.mountComponent(root, 'race-telemetry-drawer', () => createRaceTelemetryDrawerMarkup(this.options, options));
   }
 
   mountCarDriverOverview(root) {
-    return this.mountComponent(root, 'car-driver-overview', createCarDriverOverviewMarkup(this.options));
+    return this.mountComponent(root, 'car-driver-overview', () => createCarDriverOverviewMarkup(this.options));
   }
 
   mountRaceDataPanel(root) {
-    return this.mountComponent(root, 'race-data-panel', createRaceDataPanelMarkup({
+    return this.mountComponent(root, 'race-data-panel', () => createRaceDataPanelMarkup({
       ...this.options,
       standalone: true,
     }));
@@ -188,6 +195,17 @@ export class PaddockSimulatorController {
       root.innerHTML = '';
     });
     this.roots.clear();
+    this.mountRenderers.clear();
+  }
+
+  rerenderMountedComponents() {
+    this.roots.forEach((root, key) => {
+      const render = this.mountRenderers.get(key);
+      if (render) root.innerHTML = render();
+      setPackageCssVariables(root, this.options.assets, this.options.theme);
+      this.layoutSupportCleanups.get(key)?.();
+      this.layoutSupportCleanups.set(key, installLayoutSupport(root));
+    });
   }
 
   syncOptionsFromRunningApp() {
@@ -207,12 +225,50 @@ export class PaddockSimulatorController {
     const currentOptions = this.app ? this.syncOptionsFromRunningApp() : this.options;
     const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(currentOptions, nextOptions));
     if (this.app) {
-      this.app.restart(nextResolvedOptions);
+      const previousOptions = this.options;
       this.options = nextResolvedOptions;
+      try {
+        this.app.restart(nextResolvedOptions);
+      } catch (error) {
+        this.options = previousOptions;
+        throw error;
+      }
       return;
     }
     this.options = nextResolvedOptions;
-    this.compositeRoot.applyCssVariables();
+    this.rerenderMountedComponents();
+  }
+
+  setTheme(themeInput = {}) {
+    const currentOptions = this.app ? this.syncOptionsFromRunningApp() : this.options;
+    const nextResolvedOptions = resolveRuntimeThemeOptions(currentOptions, themeInput);
+    this.options = nextResolvedOptions;
+    if (this.app?.setTheme) {
+      this.app.setTheme(nextResolvedOptions.theme);
+    } else {
+      this.compositeRoot.applyCssVariables();
+    }
+    return nextResolvedOptions.theme;
+  }
+
+  setThemeMode(mode) {
+    const currentOptions = this.app ? this.syncOptionsFromRunningApp() : this.options;
+    const nextResolvedOptions = resolveRuntimeThemeModeOptions(currentOptions, mode);
+    this.options = nextResolvedOptions;
+    if (this.app?.setTheme) {
+      this.app.setTheme(nextResolvedOptions.theme);
+    } else {
+      this.compositeRoot.applyCssVariables();
+    }
+    return nextResolvedOptions.theme;
+  }
+
+  getTheme() {
+    return this.options.theme;
+  }
+
+  syncThemeFrom(source, options = {}) {
+    return createThemeSync(this, source, options);
   }
 
   selectDriver(driverId) {

package/src/api/runtimeTheme.js

@@ -0,0 +1,59 @@
+import { resolveF1SimulatorOptions } from '../config/defaultOptions.js';
+import { mergeThemeInputs } from '../config/themeOptions.js';
+
+export function resolveRuntimeThemeOptions(currentOptions, themeInput = {}) {
+  return resolveF1SimulatorOptions({
+    ...currentOptions,
+    theme: mergeThemeInputs(currentOptions?.theme, themeInput),
+  });
+}
+
+export function resolveRuntimeThemeModeOptions(currentOptions, mode) {
+  return resolveRuntimeThemeOptions(currentOptions, { mode });
+}
+
+export function createThemeSync(simulator, source, {
+  attribute = 'data-theme',
+  map,
+} = {}) {
+  if (!source || typeof source !== 'object') {
+    throw new Error('syncThemeFrom requires a DOM element or attribute source.');
+  }
+
+  const readValue = () => {
+    const rawValue = typeof source.getAttribute === 'function'
+      ? source.getAttribute(attribute)
+      : source?.dataset?.[attributeToDatasetKey(attribute)];
+    if (map && Object.hasOwn(map, rawValue)) return map[rawValue];
+    return rawValue;
+  };
+
+  const sync = () => {
+    const value = readValue();
+    if (value && typeof value === 'object') {
+      simulator.setTheme(value);
+      return;
+    }
+    simulator.setThemeMode(typeof value === 'string' && value !== '' ? value : 'dark');
+  };
+
+  sync();
+
+  const Observer = globalThis.MutationObserver;
+  if (typeof Observer !== 'function' || typeof source.getAttribute !== 'function') {
+    return () => {};
+  }
+
+  const observer = new Observer(sync);
+  observer.observe(source, {
+    attributes: true,
+    attributeFilter: [attribute],
+  });
+  return () => observer.disconnect();
+}
+
+function attributeToDatasetKey(attribute) {
+  return String(attribute)
+    .replace(/^data-/, '')
+    .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}

package/src/app/F1SimulatorApp.js

@@ -301,7 +301,8 @@ export class F1SimulatorApp {
       this.emitHostCallback('onReady', { snapshot });
       this.resizeHandler = () => {
         this.syncTimingPanelDisclosureState();
-        this.applyCamera(this.sim.snapshotRender?.() ?? this.sim.snapshot());
+        this.renderSourceSnapshotBuffer ??= {};
+        this.applyCamera(this.sim.snapshotRenderInto?.(this.renderSourceSnapshotBuffer) ?? this.sim.snapshotRender?.() ?? this.sim.snapshot());
       };
       window.addEventListener('resize', this.resizeHandler, { signal: this.abortController.signal });
       this.observeLayoutResize();
@@ -606,7 +607,8 @@ export class F1SimulatorApp {
 
   syncRendererToCurrentLayout({ render = false } = {}) {
     this.resizeRendererToCanvasHost();
-    const snapshot = this.sim?.snapshotRender?.() ?? this.sim?.snapshot?.();
+    this.renderSourceSnapshotBuffer ??= {};
+    const snapshot = this.sim?.snapshotRenderInto?.(this.renderSourceSnapshotBuffer) ?? this.sim?.snapshotRender?.() ?? this.sim?.snapshot?.();
     if (!snapshot) return;
     const renderSnapshot = interpolateRenderSnapshotInto(
       this.renderSnapshotBuffer,
@@ -1191,7 +1193,26 @@ export class F1SimulatorApp {
     const contextKey = selectedTeamId ?? '';
     if (this.lastThemeContextKey === contextKey) return;
     this.lastThemeContextKey = contextKey;
-    applyPaddockThemeCssVariables(this.root, this.options.theme, { selectedTeamId });
+    const context = { selectedTeamId };
+    if (typeof this.root?.applyCssVariables === 'function') {
+      this.root.applyCssVariables(context);
+      return;
+    }
+    applyPaddockThemeCssVariables(this.root, this.options.theme, context);
+  }
+
+  setTheme(theme) {
+    this.options = {
+      ...this.options,
+      theme,
+    };
+    this.lastThemeContextKey = null;
+    this.syncThemeContext(this.getSnapshot());
+    return this.options.theme;
+  }
+
+  getTheme() {
+    return this.options.theme;
   }
 
   getSelectedTeamId(snapshot = null) {

package/src/app/readouts/timingTowerRenderer.js

@@ -125,6 +125,195 @@ export function syncTimingGapModeControls({ readouts, buttons, timingGapMode })
   });
 }
 
+function timingGapForCar(car, raceMode, timingGapMode) {
+  if (isDnfCar(car)) return 'DNF';
+  if (isWavedFlagCar(car) && raceMode !== 'finished') return 'WAVED';
+  if (raceMode === 'finished') return car.rank === 1 ? 'Winner' : 'FIN';
+  if (raceMode === 'safety-car' && car.rank > 1) return 'SC';
+  if (raceMode === 'pre-start') return car.rank === 1 ? 'Pole' : 'Grid';
+  if (car.rank > 1) return formatRaceGap(car, timingGapMode);
+  return 'Leader';
+}
+
+function timingRowModel({ car, driver, raceMode, selectedId, timingGapMode, penalty }) {
+  const dnf = isDnfCar(car);
+  const tire = car.tire ?? driver?.tire ?? 'M';
+  const timingCode = car.timingCode ?? driver?.timingCode ?? car.code;
+  const team = car.team ?? driver?.team ?? null;
+  const icon = team?.icon ?? car.icon ?? driver?.icon ?? timingCode;
+  const driverColor = formatCssColor(car.color);
+  const iconColor = formatCssColor(team?.color ?? car.color, driverColor);
+  const penaltyLabel = penalty ? formatPenaltyBadgeLabel(penalty) : '';
+
+  return {
+    id: car.id,
+    rank: car.rank,
+    name: car.name,
+    selected: car.id === selectedId,
+    dnf,
+    gap: timingGapForCar(car, raceMode, timingGapMode),
+    tire,
+    tireClass: getTireClass(tire),
+    timingCode,
+    icon,
+    driverColor,
+    iconColor,
+    penaltyLabel,
+  };
+}
+
+function timingRowKey(row) {
+  return [
+    row.id,
+    row.rank,
+    row.name,
+    row.selected ? 1 : 0,
+    row.dnf ? 1 : 0,
+    row.gap,
+    row.tire,
+    row.tireClass,
+    row.timingCode,
+    row.icon,
+    row.driverColor,
+    row.iconColor,
+    row.penaltyLabel,
+  ].join('\u001f');
+}
+
+function timingRowsKey(rows) {
+  return rows.map(timingRowKey).join('\u001e');
+}
+
+function renderTimingRowMarkup(row) {
+  const penaltyBadge = row.penaltyLabel
+    ? `<span class="timing-penalty-badge" aria-label="${escapeHtml(row.penaltyLabel)}" title="${escapeHtml(row.penaltyLabel)}">!</span>`
+    : '';
+
+  return `
+        <li>
+          <button class="timing-row ${row.selected ? 'is-selected' : ''} ${row.dnf ? 'is-dnf' : ''}" type="button"
+            data-driver-id="${escapeHtml(row.id)}" aria-label="Select ${escapeHtml(row.name)}"
+            style="--driver-color: ${escapeHtml(row.driverColor)}">
+            <span class="timing-position">${row.rank}</span>
+            <span class="timing-icon timing-team-icon" aria-hidden="true" style="--team-color: ${escapeHtml(row.iconColor)}">${escapeHtml(row.icon)}</span>
+            <span class="timing-name" title="${escapeHtml(row.name)}"><span>${escapeHtml(row.timingCode)}</span>${penaltyBadge}</span>
+            <span class="timing-gap">${escapeHtml(row.gap)}</span>
+            <span class="timing-tire timing-tire--${row.tireClass}">${escapeHtml(row.tire)}</span>
+          </button>
+        </li>
+      `;
+}
+
+function canPatchTimingRows(timingList) {
+  return Boolean(
+    timingList?.ownerDocument?.createElement &&
+    typeof timingList.appendChild === 'function' &&
+    timingList.children,
+  );
+}
+
+function createTimingRowView(document) {
+  const item = document.createElement('li');
+  const button = document.createElement('button');
+  const position = document.createElement('span');
+  const icon = document.createElement('span');
+  const name = document.createElement('span');
+  const code = document.createElement('span');
+  const gap = document.createElement('span');
+  const tire = document.createElement('span');
+
+  item.appendChild(button);
+  button.appendChild(position);
+  button.appendChild(icon);
+  button.appendChild(name);
+  name.appendChild(code);
+  button.appendChild(gap);
+  button.appendChild(tire);
+
+  return {
+    item,
+    button,
+    position,
+    icon,
+    name,
+    code,
+    gap,
+    tire,
+    penaltyBadge: null,
+  };
+}
+
+function setStyleProperty(element, name, value) {
+  if (typeof element.style?.setProperty === 'function') {
+    element.style.setProperty(name, value);
+  } else {
+    element.setAttribute?.('style', `${name}: ${value}`);
+  }
+}
+
+function updateTimingRowView(view, row) {
+  view.button.className = `timing-row ${row.selected ? 'is-selected' : ''} ${row.dnf ? 'is-dnf' : ''}`;
+  view.button.setAttribute('type', 'button');
+  view.button.setAttribute('data-driver-id', row.id);
+  view.button.setAttribute('aria-label', `Select ${row.name}`);
+  setStyleProperty(view.button, '--driver-color', row.driverColor);
+
+  view.position.className = 'timing-position';
+  view.position.textContent = String(row.rank);
+
+  view.icon.className = 'timing-icon timing-team-icon';
+  view.icon.setAttribute('aria-hidden', 'true');
+  setStyleProperty(view.icon, '--team-color', row.iconColor);
+  view.icon.textContent = String(row.icon ?? '');
+
+  view.name.className = 'timing-name';
+  view.name.setAttribute('title', row.name);
+  view.code.textContent = String(row.timingCode ?? '');
+
+  if (row.penaltyLabel) {
+    if (!view.penaltyBadge) {
+      view.penaltyBadge = view.name.ownerDocument.createElement('span');
+      view.name.appendChild(view.penaltyBadge);
+    }
+    view.penaltyBadge.className = 'timing-penalty-badge';
+    view.penaltyBadge.setAttribute('aria-label', row.penaltyLabel);
+    view.penaltyBadge.setAttribute('title', row.penaltyLabel);
+    view.penaltyBadge.textContent = '!';
+  } else if (view.penaltyBadge) {
+    view.penaltyBadge.remove();
+    view.penaltyBadge = null;
+  }
+
+  view.gap.className = 'timing-gap';
+  view.gap.textContent = String(row.gap);
+
+  view.tire.className = `timing-tire timing-tire--${row.tireClass}`;
+  view.tire.textContent = String(row.tire ?? '');
+}
+
+function patchTimingRows(timingList, rows) {
+  const rowViews = timingList.__paddockTimingRowViews ?? new Map();
+  timingList.__paddockTimingRowViews = rowViews;
+  const seen = new Set();
+
+  rows.forEach((row) => {
+    let view = rowViews.get(row.id);
+    if (!view) {
+      view = createTimingRowView(timingList.ownerDocument);
+      rowViews.set(row.id, view);
+    }
+    seen.add(row.id);
+    updateTimingRowView(view, row);
+    timingList.appendChild(view.item);
+  });
+
+  rowViews.forEach((view, id) => {
+    if (seen.has(id)) return;
+    view.item.remove();
+    rowViews.delete(id);
+  });
+}
+
 export function renderTimingTower({
   timingList,
   cars,
@@ -138,48 +327,20 @@ export function renderTimingTower({
 }) {
   if (!timingList) return lastTimingMarkup;
   const penaltyByDriver = timingPenaltyBadgesEnabled ? getPenaltyByDriver(penalties) : new Map();
-  const timingMarkup = cars.map((car) => {
-    const driver = driverById.get(car.id);
-    const dnf = isDnfCar(car);
-    let gap = 'Leader';
-    if (dnf) {
-      gap = 'DNF';
-    } else if (isWavedFlagCar(car) && raceMode !== 'finished') {
-      gap = 'WAVED';
-    } else if (raceMode === 'finished') {
-      gap = car.rank === 1 ? 'Winner' : 'FIN';
-    } else if (raceMode === 'safety-car' && car.rank > 1) {
-      gap = 'SC';
-    } else if (raceMode === 'pre-start') {
-      gap = car.rank === 1 ? 'Pole' : 'Grid';
-    } else if (car.rank > 1) {
-      gap = formatRaceGap(car, timingGapMode);
-    }
-    const tire = car.tire ?? driver?.tire ?? 'M';
-    const timingCode = car.timingCode ?? driver?.timingCode ?? car.code;
-    const team = car.team ?? driver?.team ?? null;
-    const icon = team?.icon ?? car.icon ?? driver?.icon ?? timingCode;
-    const driverColor = formatCssColor(car.color);
-    const iconColor = formatCssColor(team?.color ?? car.color, driverColor);
-    const penalty = penaltyByDriver.get(car.id);
-    const penaltyBadge = penalty
-      ? `<span class="timing-penalty-badge" aria-label="${escapeHtml(formatPenaltyBadgeLabel(penalty))}" title="${escapeHtml(formatPenaltyBadgeLabel(penalty))}">!</span>`
-      : '';
-
-    return `
-        <li>
-          <button class="timing-row ${car.id === selectedId ? 'is-selected' : ''} ${dnf ? 'is-dnf' : ''}" type="button"
-            data-driver-id="${escapeHtml(car.id)}" aria-label="Select ${escapeHtml(car.name)}"
-            style="--driver-color: ${escapeHtml(driverColor)}">
-            <span class="timing-position">${car.rank}</span>
-            <span class="timing-icon timing-team-icon" aria-hidden="true" style="--team-color: ${escapeHtml(iconColor)}">${escapeHtml(icon)}</span>
-            <span class="timing-name" title="${escapeHtml(car.name)}"><span>${escapeHtml(timingCode)}</span>${penaltyBadge}</span>
-            <span class="timing-gap">${escapeHtml(gap)}</span>
-            <span class="timing-tire timing-tire--${getTireClass(tire)}">${escapeHtml(tire)}</span>
-          </button>
-        </li>
-      `;
-  }).join('');
+  const rows = cars.map((car) => timingRowModel({
+    car,
+    driver: driverById.get(car.id),
+    raceMode,
+    selectedId,
+    timingGapMode,
+    penalty: penaltyByDriver.get(car.id),
+  }));
+  if (canPatchTimingRows(timingList)) {
+    patchTimingRows(timingList, rows);
+    return timingRowsKey(rows);
+  }
+
+  const timingMarkup = rows.map(renderTimingRowMarkup).join('');
   if (timingMarkup !== lastTimingMarkup || timingList.innerHTML !== timingMarkup) {
     timingList.innerHTML = timingMarkup;
     return timingMarkup;