@inventure71/paddockjs 2.0.0 → 3.0.0

package/src/app/raceOverlayClearanceSupport.js

@@ -0,0 +1,158 @@
+const CLEARANCE_CLASS = 'sim-canvas-panel--needs-banner-clearance';
+import { createRafScheduler } from './layoutScheduler.js';
+
+const CLEARANCE_VAR = '--race-overlay-banner-clearance';
+const OVERLAY_GAP_PX = 12;
+
+function parsePixelValue(value, fallback = 0) {
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function isVisible(element) {
+  if (!element || element.hidden || element.classList?.contains('is-hidden')) return false;
+  const rect = element.getBoundingClientRect();
+  const style = getComputedStyle(element);
+  return rect.width > 0 &&
+    rect.height > 0 &&
+    style.display !== 'none' &&
+    style.visibility !== 'hidden';
+}
+
+function relativeBounds(panel, element) {
+  const panelRect = panel.getBoundingClientRect();
+  const rect = element.getBoundingClientRect();
+  return {
+    left: rect.left - panelRect.left,
+    right: rect.right - panelRect.left,
+    top: rect.top - panelRect.top,
+    bottom: rect.bottom - panelRect.top,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+function timingEntryBounds(panel, tower) {
+  const panelRect = panel.getBoundingClientRect();
+  const towerStyle = getComputedStyle(tower);
+  const towerRect = tower.getBoundingClientRect();
+  const towerOpenLeft = parsePixelValue(towerStyle.left, towerRect.left - panelRect.left);
+
+  return Array.from(tower.querySelectorAll?.('.timing-row') ?? [])
+    .filter(isVisible)
+    .map((row) => {
+      const rowRect = row.getBoundingClientRect();
+      const rowLeftInTower = rowRect.left - towerRect.left;
+      const left = towerOpenLeft + rowLeftInTower;
+      return {
+        left,
+        right: left + rowRect.width,
+        top: rowRect.top - panelRect.top,
+        bottom: rowRect.bottom - panelRect.top,
+      };
+    });
+}
+
+function rectanglesOverlap(first, second) {
+  return first.left < second.right &&
+    first.right > second.left &&
+    first.top < second.bottom &&
+    first.bottom > second.top;
+}
+
+function createPanelOverlayRecord(panel) {
+  return {
+    panel,
+    tower: panel.querySelector?.('[data-timing-tower]') ?? null,
+    banner: panel.querySelector?.('[data-race-data-panel]') ?? null,
+    toggle: panel.querySelector?.('[data-timing-panel-toggle]') ?? null,
+  };
+}
+
+function syncPanelOverlayClearance(record) {
+  const { panel, tower, banner, toggle } = record;
+  if (!panel.classList?.contains('sim-canvas-panel--responsive-narrow')) {
+    panel.classList?.remove(CLEARANCE_CLASS);
+    panel.style?.removeProperty(CLEARANCE_VAR);
+    return;
+  }
+
+  const toggleStyle = toggle ? getComputedStyle(toggle) : null;
+  const timingRevealMode = Boolean(toggle && toggleStyle?.display !== 'none' && toggleStyle?.visibility !== 'hidden');
+  if (!timingRevealMode || !tower || !isVisible(banner)) {
+    panel.classList?.remove(CLEARANCE_CLASS);
+    panel.style?.removeProperty(CLEARANCE_VAR);
+    return;
+  }
+
+  const currentClearance = parsePixelValue(getComputedStyle(panel).getPropertyValue(CLEARANCE_VAR), 0);
+  const bannerBounds = relativeBounds(panel, banner);
+  const bannerWithoutClearance = {
+    ...bannerBounds,
+    top: bannerBounds.top - currentClearance,
+    bottom: bannerBounds.bottom - currentClearance,
+  };
+  const needsClearance = timingEntryBounds(panel, tower)
+    .some((entryBounds) => rectanglesOverlap(entryBounds, bannerWithoutClearance));
+
+  panel.classList?.toggle(CLEARANCE_CLASS, needsClearance);
+  if (!needsClearance) {
+    panel.style?.removeProperty(CLEARANCE_VAR);
+    return;
+  }
+
+  const panelRect = panel.getBoundingClientRect();
+  const bannerRect = banner.getBoundingClientRect();
+  const clearance = Math.max(0, Math.ceil(panelRect.bottom - bannerRect.top + OVERLAY_GAP_PX));
+  panel.style?.setProperty(CLEARANCE_VAR, `${clearance}px`);
+}
+
+function raceCanvasPanels(root) {
+  const queryRoot = root?.querySelectorAll ? root : null;
+  if (!queryRoot) return [];
+  const panels = [];
+  if (root.matches?.('.sim-canvas-panel--with-timing-tower')) panels.push(root);
+  panels.push(...queryRoot.querySelectorAll('.sim-canvas-panel--with-timing-tower'));
+  return [...new Set(panels)];
+}
+
+export function installRaceOverlayClearanceSupport(root) {
+  const panelRecords = raceCanvasPanels(root).map(createPanelOverlayRecord);
+  if (panelRecords.length === 0) return () => {};
+
+  const syncPanels = () => panelRecords.forEach(syncPanelOverlayClearance);
+  const scheduler = createRafScheduler(syncPanels);
+
+  scheduler.runNow();
+
+  const resizeObserver = typeof ResizeObserver === 'function'
+    ? new ResizeObserver(scheduler.queue)
+    : null;
+  panelRecords.forEach(({ panel, tower, banner }) => {
+    resizeObserver?.observe(panel);
+    if (tower) resizeObserver?.observe(tower);
+    if (banner) resizeObserver?.observe(banner);
+  });
+
+  const mutationObserver = typeof MutationObserver === 'function'
+    ? new MutationObserver(scheduler.queue)
+    : null;
+  panelRecords.forEach(({ panel }) => {
+    mutationObserver?.observe(panel, {
+      attributes: true,
+      attributeFilter: ['aria-hidden', 'class', 'hidden', 'style'],
+      childList: true,
+      subtree: true,
+    });
+  });
+
+  if (typeof requestAnimationFrame === 'function') {
+    scheduler.queue();
+  }
+
+  return () => {
+    resizeObserver?.disconnect();
+    mutationObserver?.disconnect();
+    scheduler.cancel();
+  };
+}

package/src/app/readouts/carOverviewRenderer.js

@@ -1,6 +1,7 @@
 import { DRIVER_STAT_DEFINITIONS, formatDriverNumber, VEHICLE_STAT_DEFINITIONS } from '../../data/championship.js';
 import { normalizeCustomFields } from '../../data/customFields.js';
-import { setText } from '../domBindings.js';
+import { setStyleProperty, setText } from '../domBindings.js';
+import { formatCssColor } from './readoutFormatters.js';
 
 const VEHICLE_OVERVIEW_FIELDS = [
   ['power', 'Power'],
@@ -82,8 +83,9 @@ export function renderCarDriverOverview({
   });
   if (overviewKey === lastOverviewRenderKey) return lastOverviewRenderKey;
 
-  readouts.carOverview?.style.setProperty('--driver-color', car.color);
-  readouts.carOverviewDiagram?.style.setProperty('--driver-color', car.color);
+  const driverColor = formatCssColor(car.color);
+  setStyleProperty(readouts.carOverview, '--driver-color', driverColor);
+  setStyleProperty(readouts.carOverviewDiagram, '--driver-color', driverColor);
   if (readouts.carOverviewTitle) {
     readouts.carOverviewTitle.textContent = mode === 'driver' ? 'Driver overview' : 'Car overview';
   }
@@ -96,14 +98,20 @@ export function renderCarDriverOverview({
   }
   if (readouts.carOverviewNumber) readouts.carOverviewNumber.textContent = driverNumber;
   if (readouts.carOverviewCoreStat) readouts.carOverviewCoreStat.textContent = mode === 'driver' ? 'Driver' : 'Car';
-  readouts.carOverviewFields.forEach((fieldNode, index) => {
+  const fieldBindings = readouts.carOverviewFieldBindings?.length
+    ? readouts.carOverviewFieldBindings
+    : [...(readouts.carOverviewFields ?? [])].map((fieldNode) => ({
+      field: fieldNode,
+      label: fieldNode.querySelector?.('[data-overview-field-label]') ?? null,
+      value: fieldNode.querySelector?.('[data-overview-field-value]') ?? null,
+    }));
+  fieldBindings.forEach((fieldBinding, index) => {
     const field = displayFields[index];
+    const fieldNode = fieldBinding.field;
     fieldNode.hidden = !field;
     if (!field) return;
-    const labelNode = fieldNode.querySelector('[data-overview-field-label]');
-    const valueNode = fieldNode.querySelector('[data-overview-field-value]');
-    setText(labelNode, field.label);
-    setText(valueNode, field.value);
+    setText(fieldBinding.label, field.label);
+    setText(fieldBinding.value, field.value);
   });
   return overviewKey;
 }

package/src/app/readouts/controlStateRenderer.js

@@ -9,7 +9,7 @@ export function updateCameraControlButtons({ camera, cameraButtons, snapshot, ha
   cameraButtons.forEach((button) => {
     const mode = button.dataset.cameraMode;
     const isAvailable = isCameraModeAvailable(mode, snapshot);
-    if (mode === 'pit') {
+    if (mode === 'pit' || mode === 'driver') {
       button.hidden = !isAvailable;
       button.disabled = !isAvailable;
       button.setAttribute('aria-hidden', String(!isAvailable));

package/src/app/readouts/raceStatusRenderer.js

@@ -1,6 +1,12 @@
 import { getRaceControlStatusBanner } from '../../ui/raceControlStatusBanner.js';
-import { setText } from '../domBindings.js';
-import { escapeHtml } from './readoutFormatters.js';
+import { resolveNodes, setStyleProperty, setText } from '../domBindings.js';
+import { escapeHtml, formatCssColor } from './readoutFormatters.js';
+
+function setTextEvery(nodes, node, value) {
+  resolveNodes(nodes, node).forEach((target) => {
+    if (target.textContent !== value) target.textContent = value;
+  });
+}
 
 export function renderStartLights(readouts, startLightNodes, raceControl) {
   const panel = readouts.startLights;
@@ -33,7 +39,7 @@ export function renderRaceFinish({ readouts, snapshot, driverById, lastFinishCla
   const winner = snapshot.raceControl.winner;
   const winnerDriver = winner ? driverById.get(winner.id) : null;
   const winnerName = winnerDriver?.name ?? winner?.name ?? 'Winner';
-  panel.style.setProperty('--driver-color', winner?.color ?? winnerDriver?.color ?? 'var(--red)');
+  setStyleProperty(panel, '--driver-color', formatCssColor(winner?.color ?? winnerDriver?.color));
   setText(readouts.finishWinner, winnerName);
 
   if (readouts.finishClassification) {
@@ -84,26 +90,29 @@ export function renderRaceStatusReadouts({
           : 'var(--green)';
   }
   if (readouts.lap) readouts.lap.textContent = `${leader?.lap ?? 1}/${snapshot.totalLaps}`;
-  if (readouts.towerLap) readouts.towerLap.textContent = leader?.lap ?? 1;
-  if (readouts.towerTotalLaps) readouts.towerTotalLaps.textContent = snapshot.totalLaps;
-  if (readouts.timingTower) {
-    readouts.timingTower.classList.toggle('is-safety-car', snapshot.raceControl.mode === 'safety-car');
-    readouts.timingTower.classList.toggle('is-red-flag', snapshot.raceControl.mode === 'red-flag');
-    readouts.timingTower.classList.toggle('is-pre-start', snapshot.raceControl.mode === 'pre-start');
-  }
-  if (readouts.towerRaceControlBanner) {
+  setTextEvery(readouts.towerLaps, readouts.towerLap, leader?.lap ?? 1);
+  setTextEvery(readouts.towerTotalLapsAll, readouts.towerTotalLaps, snapshot.totalLaps);
+  resolveNodes(readouts.timingTowers, readouts.timingTower).forEach((timingTower) => {
+    timingTower.classList.toggle('is-safety-car', snapshot.raceControl.mode === 'safety-car');
+    timingTower.classList.toggle('is-red-flag', snapshot.raceControl.mode === 'red-flag');
+    timingTower.classList.toggle('is-pre-start', snapshot.raceControl.mode === 'pre-start');
+  });
+  const raceControlBanners = resolveNodes(readouts.towerRaceControlBanners, readouts.towerRaceControlBanner);
+  if (raceControlBanners.length > 0) {
     const raceControlBanner = getRaceControlStatusBanner(snapshot.raceControl.mode);
-    readouts.towerRaceControlBanner.hidden = !raceControlBanner;
-    readouts.towerRaceControlBanner.classList?.toggle?.('is-safety-car', raceControlBanner?.status === 'safety-car');
-    readouts.towerRaceControlBanner.classList?.toggle?.('is-red-flag', raceControlBanner?.status === 'red-flag');
-    if (raceControlBanner && readouts.towerRaceControlBanner.dataset) {
-      readouts.towerRaceControlBanner.dataset.raceControlStatus = raceControlBanner.status;
-    } else if (readouts.towerRaceControlBanner.dataset) {
-      delete readouts.towerRaceControlBanner.dataset.raceControlStatus;
-    }
+    raceControlBanners.forEach((banner) => {
+      banner.hidden = !raceControlBanner;
+      banner.classList?.toggle?.('is-safety-car', raceControlBanner?.status === 'safety-car');
+      banner.classList?.toggle?.('is-red-flag', raceControlBanner?.status === 'red-flag');
+      if (raceControlBanner && banner.dataset) {
+        banner.dataset.raceControlStatus = raceControlBanner.status;
+      } else if (banner.dataset) {
+        delete banner.dataset.raceControlStatus;
+      }
+    });
     if (raceControlBanner) {
-      setText(readouts.towerRaceControlKicker, raceControlBanner.kicker);
-      setText(readouts.towerRaceControlTitle, raceControlBanner.title);
+      setTextEvery(readouts.towerRaceControlKickers, readouts.towerRaceControlKicker, raceControlBanner.kicker);
+      setTextEvery(readouts.towerRaceControlTitles, readouts.towerRaceControlTitle, raceControlBanner.title);
     }
   }
   if (readouts.drs) {

package/src/app/readouts/readoutFormatters.js

@@ -1,3 +1,5 @@
+export { formatCssColor } from '../../config/cssValues.js';
+
 export function escapeHtml(value) {
   return String(value ?? '')
     .replaceAll('&', '&')

package/src/app/readouts/telemetryRenderer.js

@@ -1,20 +1,26 @@
-import { setTextAll, setText } from '../domBindings.js';
+import { setStyleProperty, setTextAll, setText } from '../domBindings.js';
 import { clamp } from '../../simulation/simMath.js';
 import { formatDriverNumber } from '../../data/championship.js';
-import { formatTelemetryGap, formatTelemetryTime, setPerformanceClass } from './readoutFormatters.js';
+import {
+  formatCssColor,
+  formatTelemetryGap,
+  formatTelemetryTime,
+  setPerformanceClass,
+} from './readoutFormatters.js';
 
 export function renderTelemetryReadouts({ readouts, car, driverById }) {
   if (!car) return;
   const driver = driverById.get(car.id);
   const drsState = car.drsActive ? 'OPEN' : car.drsEligible ? 'READY' : 'OFF';
   const surface = (car.surface ?? 'track').toUpperCase();
+  const driverColor = formatCssColor(car.color);
 
   setTextAll(readouts.selectedCode, car.code);
   readouts.selectedCode?.forEach?.((node) => {
-    node.style.color = car.color;
+    node.style.color = driverColor;
   });
   readouts.telemetrySectorBanners?.forEach?.((node) => {
-    node.style.setProperty('--driver-color', car.color);
+    setStyleProperty(node, '--driver-color', driverColor);
   });
   setTextAll(readouts.selectedName, car.name);
   setTextAll(readouts.speed, `${Math.round(car.speedKph)} km/h`);
@@ -69,9 +75,7 @@ export function renderLapTelemetry(readouts, telemetry) {
     const fill = clamp((progress ?? 0) * 100, 0, 100);
     const sectorComplete = fill >= 99.9;
     const fillValue = `${fill.toFixed(1)}%`;
-    if (bar.style.getPropertyValue('--sector-fill') !== fillValue) {
-      bar.style.setProperty('--sector-fill', fillValue);
-    }
+    setStyleProperty(bar, '--sector-fill', fillValue);
     bar.classList.toggle('is-active', isActive);
     bar.classList.toggle('is-complete', sectorComplete);
     setPerformanceClass(bar, isCompletedCurrentSector ? telemetry.sectorPerformance?.current?.[index] : null);
@@ -84,11 +88,16 @@ export function renderLapTelemetry(readouts, telemetry) {
     const isActive = index === activeIndex;
     const isCompletedCurrentSector = index < activeIndex;
     const hasLiveSectors = Array.isArray(telemetry.liveSectors);
+    const activeSectorCompleted = isActive &&
+      Number.isFinite(telemetry.liveSectors?.[index]) &&
+      (telemetry.sectorProgress?.[index] ?? 0) >= 0.999;
     const value = index > activeIndex
       ? null
       : hasLiveSectors
         ? isActive
-          ? telemetry.currentSectorElapsed ?? telemetry.liveSectors[index]
+          ? activeSectorCompleted
+            ? telemetry.liveSectors[index]
+            : telemetry.currentSectorElapsed ?? telemetry.liveSectors[index]
           : telemetry.liveSectors[index]
         : isActive && !Number.isFinite(telemetry.currentSectors?.[index])
           ? telemetry.currentSectorElapsed

package/src/app/readouts/timingTowerRenderer.js

@@ -1,5 +1,12 @@
-import { setText } from '../domBindings.js';
-import { escapeHtml, formatLapGap, formatRaceGap, getTireClass } from './readoutFormatters.js';
+import { getNextTimingGapMode, getTimingGapModeLabel, normalizeTimingGapMode } from '../../config/timingGapMode.js';
+import { setText, setTextAll } from '../domBindings.js';
+import {
+  escapeHtml,
+  formatCssColor,
+  formatLapGap,
+  formatRaceGap,
+  getTireClass,
+} from './readoutFormatters.js';
 
 function formatPenaltyHeadline(penalty) {
   const serviceType = penalty?.serviceType;
@@ -104,12 +111,17 @@ export function getTimingOrderKey(cars = [], { timingGapMode = 'interval' } = {}
 }
 
 export function syncTimingGapModeControls({ readouts, buttons, timingGapMode }) {
-  const label = timingGapMode === 'leader' ? 'Gap' : 'Int';
-  setText(readouts.timingGapLabel, label);
+  const normalizedMode = normalizeTimingGapMode(timingGapMode);
+  const label = getTimingGapModeLabel(normalizedMode);
+  const nextLabel = getTimingGapModeLabel(getNextTimingGapMode(normalizedMode));
+  setTextAll(readouts.timingGapLabels ?? readouts.timingGapLabel, label);
   buttons.forEach((button) => {
-    const active = button.dataset.timingGapMode === timingGapMode;
-    button.setAttribute('aria-pressed', String(active));
-    button.classList?.toggle?.('is-active', active);
+    const leaderMode = normalizedMode === 'leader';
+    setText(button, label);
+    button.setAttribute('aria-pressed', String(leaderMode));
+    button.setAttribute('aria-label', `Timing gap mode ${label}; switch to ${nextLabel}`);
+    button.setAttribute('title', `Switch to ${nextLabel}`);
+    button.classList?.toggle?.('is-active', leaderMode);
   });
 }
 
@@ -147,7 +159,8 @@ export function renderTimingTower({
     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 iconColor = team?.color ?? car.color;
+    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>`
@@ -157,7 +170,7 @@ export function renderTimingTower({
         <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(car.color)}">
+            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>
@@ -167,11 +180,50 @@ export function renderTimingTower({
         </li>
       `;
   }).join('');
-  if (timingMarkup !== lastTimingMarkup) {
+  if (timingMarkup !== lastTimingMarkup || timingList.innerHTML !== timingMarkup) {
     timingList.innerHTML = timingMarkup;
     return timingMarkup;
   }
   return lastTimingMarkup;
 }
 
+export function renderTimingTowers({
+  timingLists,
+  timingList,
+  cars,
+  raceMode,
+  penalties = [],
+  driverById,
+  selectedId,
+  timingGapMode,
+  timingPenaltyBadgesEnabled,
+  lastTimingMarkup,
+}) {
+  const candidateLists = typeof timingLists?.forEach === 'function'
+    ? [...timingLists]
+    : [];
+  const lists = candidateLists.length > 0
+    ? candidateLists
+    : timingList
+      ? [timingList]
+      : [];
+  if (lists.length === 0) return lastTimingMarkup;
+
+  let nextTimingMarkup = lastTimingMarkup;
+  lists.forEach((list) => {
+    nextTimingMarkup = renderTimingTower({
+      timingList: list,
+      cars,
+      raceMode,
+      penalties,
+      driverById,
+      selectedId,
+      timingGapMode,
+      timingPenaltyBadgesEnabled,
+      lastTimingMarkup: nextTimingMarkup,
+    });
+  });
+  return nextTimingMarkup;
+}
+
 export { formatLapGap, formatRaceGap };

package/src/app/runtime/runtimeVisibility.js

@@ -1,11 +1,31 @@
 export function observeRuntimeVisibility(app) {
   if (!app.canvasHost) return;
 
+  const syncViewportVisibility = () => {
+    app.runtimeViewportVisible = isRuntimeViewportVisible(app.canvasHost);
+    app.syncRuntimeTicker();
+  };
+  const scheduleViewportVisibilitySync = () => {
+    if (app.runtimeVisibilitySyncFrame) return;
+    if (typeof globalThis.requestAnimationFrame !== 'function') {
+      syncViewportVisibility();
+      return;
+    }
+    app.runtimeVisibilitySyncFrame = globalThis.requestAnimationFrame(() => {
+      app.runtimeVisibilitySyncFrame = null;
+      syncViewportVisibility();
+    });
+  };
+
   if (typeof IntersectionObserver === 'function') {
     app.visibilityObserver?.disconnect?.();
     app.visibilityObserver = new IntersectionObserver((entries) => {
       const entry = entries.find((item) => item.target === app.canvasHost) ?? entries[0];
-      app.runtimeViewportVisible = Boolean(entry?.isIntersecting || entry?.intersectionRatio > 0);
+      app.runtimeViewportVisible = Boolean(
+        entry?.isIntersecting ||
+        entry?.intersectionRatio > 0 ||
+        isRuntimeViewportVisible(app.canvasHost),
+      );
       app.syncRuntimeTicker();
     }, {
       root: null,
@@ -25,21 +45,62 @@ export function observeRuntimeVisibility(app) {
     });
   }
 
+  syncViewportVisibility();
+  globalThis.addEventListener?.('scroll', scheduleViewportVisibilitySync, {
+    passive: true,
+    signal: app.abortController.signal,
+  });
+  globalThis.addEventListener?.('resize', scheduleViewportVisibilitySync, {
+    passive: true,
+    signal: app.abortController.signal,
+  });
+  globalThis.addEventListener?.('focus', syncViewportVisibility, {
+    signal: app.abortController.signal,
+  });
+  globalThis.addEventListener?.('pageshow', syncViewportVisibility, {
+    signal: app.abortController.signal,
+  });
   app.syncRuntimeTicker();
 }
 
 export function syncRuntimeTicker(app) {
   if (app.expertMode) return;
-  if (!app.app?.ticker) return;
+  const ticker = app.app?.ticker;
+  if (!ticker) return;
 
   const shouldRun = app.runtimeViewportVisible && app.runtimeDocumentVisible;
-  if (shouldRun === app.runtimeTickerRunning) return;
+  const tickerRunning = typeof ticker.started === 'boolean'
+    ? ticker.started
+    : app.runtimeTickerRunning;
+  if (shouldRun === app.runtimeTickerRunning && shouldRun === tickerRunning) return;
 
   app.runtimeTickerRunning = shouldRun;
   if (shouldRun) {
     app.resetFrameClock();
-    app.app.ticker.start?.();
+    ticker.start?.();
   } else {
-    app.app.ticker.stop?.();
+    ticker.stop?.();
   }
 }
+
+function isRuntimeViewportVisible(element) {
+  const rect = element?.getBoundingClientRect?.();
+  if (!rect) return true;
+
+  const top = Number(rect.top);
+  const bottom = Number(rect.bottom);
+  const left = Number(rect.left);
+  const right = Number(rect.right);
+  const width = Number(rect.width ?? right - left);
+  const height = Number(rect.height ?? bottom - top);
+  if (![top, bottom, left, right, width, height].every(Number.isFinite)) return true;
+  if (width <= 0 || height <= 0) return false;
+
+  const viewportHeight = globalThis.innerHeight || globalThis.document?.documentElement?.clientHeight || 0;
+  const viewportWidth = globalThis.innerWidth || globalThis.document?.documentElement?.clientWidth || 0;
+  const margin = 240;
+  return bottom >= -margin &&
+    top <= viewportHeight + margin &&
+    right >= -margin &&
+    left <= viewportWidth + margin;
+}

package/src/config/cssValues.js

@@ -0,0 +1,16 @@
+import { normalizeCssColorToken } from './themeOptions.js';
+
+export const DEFAULT_SAFE_DRIVER_COLOR = '#e10600';
+
+export function formatCssColor(value, fallback = DEFAULT_SAFE_DRIVER_COLOR) {
+  return normalizeCssColorToken(value, fallback);
+}
+
+export function formatCssUrl(value) {
+  const raw = String(value ?? '');
+  const escaped = raw
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', '\\"')
+    .replace(/[\u0000-\u001F\u007F]/g, '');
+  return `url("${escaped}")`;
+}