@inventure71/paddockjs 4.1.0 → 4.3.0

package/src/app/runtime/frameLoop.js

@@ -3,27 +3,24 @@ import { FIXED_STEP } from '../../simulation/raceSimulation.js';
 import { clamp } from '../../simulation/simMath.js';
 import {
   domUpdateIntervalForSpeed,
-  FRAME_PACING_EPSILON_MS,
   maxSimulationStepsForFrame,
   MAX_FRAME_CATCHUP_COUNT,
   TARGET_FRAME_MS,
 } from './runtimeTiming.js';
 
 export function runFrameLoopTick(app) {
-  if (app.expertMode) return;
+  if (app.destroyed || app.expertMode) return;
+  const simulation = app.sim;
   const now = performance.now();
-  if (now < app.nextGameFrameTime - FRAME_PACING_EPSILON_MS) return;
-
-  const elapsedFrameCount = clamp(
-    Math.floor((now - app.nextGameFrameTime + FRAME_PACING_EPSILON_MS) / TARGET_FRAME_MS) + 1,
-    1,
-    MAX_FRAME_CATCHUP_COUNT,
-  );
-  const frameSeconds = (TARGET_FRAME_MS * elapsedFrameCount) / 1000;
-  app.nextGameFrameTime += TARGET_FRAME_MS * elapsedFrameCount;
-  if (now - app.nextGameFrameTime > TARGET_FRAME_MS * MAX_FRAME_CATCHUP_COUNT) {
-    app.nextGameFrameTime = now + TARGET_FRAME_MS;
+  if (app.gridWalk?.tick(now)) {
+    app.lastTime = now;
+    return;
   }
+  // Pixi owns draw pacing. A second frame gate can draw stale poses, and
+  // rounding wall time to whole frames destroys the interpolation remainder.
+  const elapsedMs = clamp(now - app.lastTime, 0, TARGET_FRAME_MS * MAX_FRAME_CATCHUP_COUNT);
+  const elapsedFrameCount = elapsedMs / TARGET_FRAME_MS;
+  const frameSeconds = elapsedMs / 1000;
   app.lastTime = now;
   app.sampleFps(now);
   app.accumulator += frameSeconds * app.simulationSpeed;
@@ -31,23 +28,27 @@ export function runFrameLoopTick(app) {
   let simulationSteps = 0;
   const stepEvents = [];
   const maxSimulationSteps = maxSimulationStepsForFrame(app.simulationSpeed, elapsedFrameCount);
-  while (app.accumulator >= FIXED_STEP && simulationSteps < maxSimulationSteps) {
+  while (app.accumulator >= FIXED_STEP - 1e-10 && simulationSteps < maxSimulationSteps) {
     app.sim.step(FIXED_STEP);
     if (Array.isArray(app.sim.events) && app.sim.events.length > 0) {
       stepEvents.push(...app.sim.events);
     }
-    app.accumulator -= FIXED_STEP;
+    app.accumulator = Math.max(0, app.accumulator - FIXED_STEP);
     simulationSteps += 1;
   }
 
   if (app.accumulator >= FIXED_STEP) {
     app.accumulator %= FIXED_STEP;
-    app.nextGameFrameTime = now + TARGET_FRAME_MS;
   }
 
   const shouldUpdateDom = now - app.lastDomUpdateTime >= domUpdateIntervalForSpeed(app.simulationSpeed);
   const fullSnapshot = stepEvents.length > 0 || shouldUpdateDom ? app.sim.snapshot() : null;
   if (stepEvents.length > 0) app.emitRaceEvents(stepEvents, fullSnapshot);
+  // Host lifecycle callbacks may synchronously unmount or restart the race.
+  // Do not render a disposed scene or deliver the old snapshot to its successor.
+  if (app.destroyed || app.sim !== simulation) return;
+  if (fullSnapshot) app.emitSnapshotLifecycle(fullSnapshot);
+  if (app.destroyed || app.sim !== simulation) return;
   const renderSource = fullSnapshot ??
     app.sim.snapshotRenderInto?.(app.renderSourceSnapshotBuffer ?? {}) ??
     app.sim.snapshotRender?.() ??
@@ -59,7 +60,7 @@ export function runFrameLoopTick(app) {
     clamp(app.accumulator / FIXED_STEP, 0, 1),
   );
   app.renderSnapshotBuffer = renderSnapshot;
-  app.applyCamera(renderSnapshot);
+  app.applyCamera(renderSnapshot, { elapsedMs });
   app.renderDrsTrails(renderSnapshot);
   app.renderPitLaneStatus(renderSnapshot);
   app.renderCars(renderSnapshot);

package/src/app/runtime/pixiStartupLifecycle.js

@@ -0,0 +1,94 @@
+import { ResizePlugin, TickerPlugin } from 'pixi.js';
+
+export class RuntimeStartupCancelledError extends Error {
+  constructor() {
+    super('PaddockJS initialization was cancelled before completion.');
+    this.name = 'RuntimeStartupCancelledError';
+  }
+}
+
+export function assertRuntimeStartupActive(app) {
+  if (app.destroyed) throw new RuntimeStartupCancelledError();
+}
+
+function releaseInitializedPixiPlugins(application, onCleanupError) {
+  // Runtime init owns Pixi's private ticker and resize target. Init can fail
+  // between these plugins, so calling Application.destroy() is unsafe here.
+  if (application.ticker) {
+    try {
+      TickerPlugin.destroy.call(application);
+    } catch (error) {
+      onCleanupError(error);
+    }
+  }
+  if (typeof application._cancelResize === 'function') {
+    try {
+      ResizePlugin.destroy.call(application);
+    } catch (error) {
+      onCleanupError(error);
+    }
+  }
+}
+
+// Pixi's application plugins cannot be destroyed until their async init has settled.
+export function createPixiStartupLifecycle(application, onCleanupError = () => {}) {
+  let initializing = false;
+  let initialized = false;
+  let releaseRequested = false;
+  let released = false;
+
+  function release() {
+    if (initializing || released) return;
+    released = true;
+    let rendererCleanupNeeded = true;
+    if (initialized) {
+      try {
+        application.destroy(true, { children: true, texture: false });
+        return;
+      } catch (error) {
+        // Pixi clears stage immediately before calling renderer.destroy().
+        // A renderer failure must be reported without invoking that disposer twice.
+        rendererCleanupNeeded = application.stage != null;
+        onCleanupError(error);
+      }
+    }
+    // Renderer discovery or an application plugin can fail before all plugins
+    // are installed. Release only the instance-owned plugins that reached init.
+    releaseInitializedPixiPlugins(application, onCleanupError);
+    try {
+      if (!application.stage?.destroyed) application.stage?.destroy?.({ children: true, texture: false });
+    } catch (error) {
+      onCleanupError(error);
+    } finally {
+      application.stage = null;
+      try {
+        if (rendererCleanupNeeded) application.renderer?.destroy?.(true);
+      } catch (error) {
+        onCleanupError(error);
+      } finally {
+        application.renderer = null;
+      }
+    }
+  }
+
+  return {
+    async initialize(options) {
+      initializing = true;
+      try {
+        await application.init(options);
+        initialized = true;
+        // Pixi defaults to owning touch gestures. Let the host page scroll;
+        // Grid Walk opts into dragging through its own scoped touch-action CSS.
+        if (application.renderer.events) application.renderer.events.autoPreventDefault = false;
+        application.canvas.style?.removeProperty('touch-action');
+      } finally {
+        initializing = false;
+        if (releaseRequested) release();
+      }
+    },
+    destroy() {
+      releaseRequested = true;
+      release();
+    },
+  };
+}

package/src/app/runtime/runtimeTiming.js

@@ -2,13 +2,16 @@ import { clamp } from '../../simulation/simMath.js';
 
 export const TARGET_RENDER_FPS = 60;
 export const TARGET_FRAME_MS = 1000 / TARGET_RENDER_FPS;
-export const FRAME_PACING_EPSILON_MS = 0.75;
 export const MAX_FRAME_CATCHUP_COUNT = 4;
 export const BASE_MAX_SIMULATION_STEPS_PER_RENDER = 5;
 export const HARD_MAX_SIMULATION_STEPS_PER_RENDER = 60;
 export const DOM_UPDATE_INTERVAL_MS = 100;
 export const TIMING_UPDATE_INTERVAL_MS = 250;
 
+export function configureRuntimeTicker(ticker) {
+  if (ticker) ticker.maxFPS = TARGET_RENDER_FPS;
+}
+
 export function maxSimulationStepsForFrame(simulationSpeed, elapsedFrameCount) {
   const speed = Math.max(1, Number(simulationSpeed) || 1);
   const frameCount = Math.max(1, Number(elapsedFrameCount) || 1);

package/src/app/runtime/runtimeVisibility.js

@@ -68,7 +68,8 @@ export function syncRuntimeTicker(app) {
   const ticker = app.app?.ticker;
   if (!ticker) return;
 
-  const shouldRun = app.runtimeViewportVisible && app.runtimeDocumentVisible;
+  const shouldRun = app.runtimeViewportVisible && app.runtimeDocumentVisible &&
+    (!app.gridWalk?.active || app.gridWalk.needsAnimation);
   const tickerRunning = typeof ticker.started === 'boolean'
     ? ticker.started
     : app.runtimeTickerRunning;
@@ -76,7 +77,11 @@ export function syncRuntimeTicker(app) {
 
   app.runtimeTickerRunning = shouldRun;
   if (shouldRun) {
-    app.resetFrameClock();
+    if (app.gridWalk) {
+      // Grid Walk pauses retain the fractional fixed step across ticker stops.
+      app.lastTime = performance.now();
+      app.gridWalk.lastTime = app.lastTime;
+    } else app.resetFrameClock();
     ticker.start?.();
   } else {
     ticker.stop?.();

package/src/config/cssValues.js

@@ -1,4 +1,4 @@
-import { normalizeCssColorToken } from './themeOptions.js';
+import { normalizeCssColorToken } from './theme/cssTokens.js';
 
 export const DEFAULT_SAFE_DRIVER_COLOR = '#e10600';
 

package/src/config/defaultOptions.js

@@ -1,124 +1,17 @@
+import { DEFAULT_F1_SIMULATOR_OPTIONS, PADDOCK_SIMULATOR_PRESETS } from './simulatorDefaults.js';
+import { resolveSimulatorUiOptions } from './uiOptions.js';
+export { DEFAULT_F1_SIMULATOR_OPTIONS, PADDOCK_SIMULATOR_PRESETS } from './simulatorDefaults.js';
 import { resolveF1SimulatorAssets } from './defaultAssets.js';
 import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../data/championship.js';
 import { normalizeSimulatorDrivers } from '../data/normalizeDrivers.js';
 import { normalizePhysicsMode } from '../simulation/vehicle/vehiclePhysics.js';
 import { normalizeWarmupOptions } from '../simulation/warmup/runtimeWarmup.js';
 import {
-  DEFAULT_PADDOCK_THEME_INPUT,
-  applyPaddockThemeCssVariables,
   mergeThemeInputs,
   normalizePaddockTheme,
 } from './themeOptions.js';
-import { normalizeTimingGapMode } from './timingGapMode.js';
 import { normalizePublicUrlOption } from './urlOptions.js';
 
-export const DEFAULT_F1_SIMULATOR_OPTIONS = {
-  seed: 1971,
-  physicsMode: 'arcade',
-  warmup: {
-    enabled: true,
-    policy: 'config-change',
-  },
-  totalLaps: 10,
-  initialCameraMode: 'leader',
-  title: 'F1 Simulator Lab',
-  kicker: 'Race Control',
-  backLinkHref: 'projects.html',
-  backLinkLabel: 'Projects',
-  showBackLink: true,
-  ui: {
-    layoutPreset: 'standard',
-    cameraControls: 'external',
-    showFps: true,
-    showTimingTower: true,
-    showTelemetry: true,
-    telemetryIncludesOverview: true,
-    telemetryModules: {
-      core: true,
-      sectors: true,
-      lapTimes: true,
-      sectorTimes: true,
-    },
-    showRaceDataPanel: true,
-    raceDataTelemetryDetail: false,
-    driverCamera: false,
-    raceDataBanners: {
-      initial: 'project',
-      enabled: ['project', 'radio'],
-    },
-    raceDataBannerSize: 'custom',
-    timingTowerVerticalFit: 'expand-race-view',
-    timingGapMode: 'interval',
-    timingGapModeToggle: true,
-    timingEntryVerticalPadding: 5,
-    responsiveNarrowLayout: true,
-  },
-  debug: {
-    physicsModeIndicator: false,
-  },
-  theme: DEFAULT_PADDOCK_THEME_INPUT,
-};
-
-export const PADDOCK_SIMULATOR_PRESETS = {
-  dashboard: {
-    ui: {
-      layoutPreset: 'standard',
-      cameraControls: 'external',
-      showFps: true,
-      showTimingTower: true,
-      showTelemetry: true,
-      showRaceDataPanel: true,
-      raceDataBannerSize: 'custom',
-      timingTowerVerticalFit: 'expand-race-view',
-    },
-  },
-  'timing-overlay': {
-    ui: {
-      layoutPreset: 'left-tower-overlay',
-      cameraControls: 'external',
-      showFps: false,
-      showTimingTower: true,
-      showTelemetry: true,
-      showRaceDataPanel: true,
-      raceDataBannerSize: 'auto',
-      timingTowerVerticalFit: 'expand-race-view',
-      raceDataBanners: {
-        initial: 'project',
-        enabled: ['project', 'radio'],
-      },
-    },
-  },
-  'compact-race': {
-    ui: {
-      layoutPreset: 'standard',
-      cameraControls: 'external',
-      showFps: false,
-      showTimingTower: false,
-      showTelemetry: false,
-      showRaceDataPanel: true,
-      raceDataBannerSize: 'auto',
-      timingTowerVerticalFit: 'scroll',
-    },
-    theme: {
-      timingTowerMaxWidth: '340px',
-      raceViewMinHeight: '460px',
-    },
-  },
-  'full-dashboard': {
-    ui: {
-      layoutPreset: 'standard',
-      cameraControls: 'external',
-      showFps: true,
-      showTimingTower: true,
-      showTelemetry: true,
-      telemetryIncludesOverview: true,
-      showRaceDataPanel: true,
-      raceDataBannerSize: 'custom',
-      timingTowerVerticalFit: 'expand-race-view',
-    },
-  },
-};
-
 export {
   DEFAULT_PADDOCK_THEME,
   PADDOCK_THEME_CSS_VARIABLES,
@@ -130,12 +23,10 @@ export {
 
 const SUPPORTED_CAMERA_MODES = new Set(['overview', 'leader', 'selected', 'driver', 'show-all', 'pit']);
 
-function normalizeNonNegativeFiniteNumber(value, fallback) {
-  const numericValue = Number(value);
-  return Number.isFinite(numericValue) && numericValue >= 0 ? numericValue : fallback;
-}
-
 export function resolveF1SimulatorOptions(options = {}) {
+  if (options.gridWalk?.enabled && options.expert?.enabled) {
+    throw new Error('Grid Walk requires normal browser playback; expert mode owns its own simulation lifecycle.');
+  }
   const presetName = Object.hasOwn(PADDOCK_SIMULATOR_PRESETS, options.preset)
     ? options.preset
     : null;
@@ -145,39 +36,7 @@ export function resolveF1SimulatorOptions(options = {}) {
   const initialCameraMode = SUPPORTED_CAMERA_MODES.has(options.initialCameraMode)
     ? options.initialCameraMode
     : DEFAULT_F1_SIMULATOR_OPTIONS.initialCameraMode;
-  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.raceDataBanners.enabled = normalizeEnabledBanners(ui.raceDataBanners.enabled);
-  ui.telemetryModules = normalizeTelemetryModules(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);
+  const ui = resolveSimulatorUiOptions(requestedUi, presetUi, initialCameraMode);
   const debug = {
     ...DEFAULT_F1_SIMULATOR_OPTIONS.debug,
     ...(preset.debug ?? {}),
@@ -211,6 +70,11 @@ export function resolveF1SimulatorOptions(options = {}) {
     physicsMode: normalizePhysicsMode(options.physicsMode ?? preset.physicsMode),
     warmup: normalizeWarmupOptions(mergedOptions.warmup, 'browser'),
     initialCameraMode,
+    gridWalk: {
+      enabled: options.gridWalk?.enabled === true,
+      initialView: options.gridWalk?.initialView === 'race' ? 'race' : 'grid-walk',
+      ambientMotion: options.gridWalk?.ambientMotion !== false,
+    },
     ui,
     debug,
     theme,
@@ -230,28 +94,3 @@ function collectDriverTeamThemes(drivers = []) {
   });
   return Object.keys(teamThemes).length > 0 ? { teamThemes } : {};
 }
-
-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'))];
-}
-
-function normalizeTelemetryModules(value) {
-  const defaults = DEFAULT_F1_SIMULATOR_OPTIONS.ui.telemetryModules;
-  const names = Object.keys(defaults);
-  if (value === false) {
-    return Object.fromEntries(names.map((name) => [name, false]));
-  }
-  if (value === true || value == null) return { ...defaults };
-  if (Array.isArray(value)) {
-    const requested = new Set(value);
-    return Object.fromEntries(names.map((name) => [name, requested.has(name)]));
-  }
-  if (typeof value !== 'object') return { ...defaults };
-  return Object.fromEntries(names.map((name) => [
-    name,
-    value[name] == null ? defaults[name] : Boolean(value[name]),
-  ]));
-}

package/src/config/restartOptions.js

@@ -8,6 +8,7 @@ export function mergeRestartOptions(previousOptions, nextOptions = {}) {
   return {
     ...previousOptions,
     ...nextOptions,
+    gridWalk: { ...previousOptions.gridWalk, ...nextOptions.gridWalk },
     ui: {
       ...previousUi,
       ...(nextOptions.ui ?? {}),

package/src/config/runtimeSeed.js

@@ -0,0 +1,10 @@
+export function createRuntimeSeed() {
+  const values = new Uint32Array(1);
+  try {
+    globalThis.crypto?.getRandomValues?.(values);
+  } catch {
+    values[0] = 0;
+  }
+  const highResolutionTime = globalThis.performance?.now?.() ?? 0;
+  return (values[0] || Math.floor(Date.now() + highResolutionTime * 1000)) >>> 0;
+}

package/src/config/simulatorDefaults.js

@@ -0,0 +1,106 @@
+import { DEFAULT_PADDOCK_THEME_INPUT } from './theme/themeTokens.js';
+import { DEFAULT_TELEMETRY_MODULES } from './telemetryModules.js';
+
+export const DEFAULT_F1_SIMULATOR_OPTIONS = {
+  seed: 1971,
+  physicsMode: 'arcade',
+  warmup: {
+    enabled: true,
+    policy: 'config-change',
+  },
+  totalLaps: 10,
+  initialCameraMode: 'leader',
+  gridWalk: { enabled: false, initialView: 'grid-walk', ambientMotion: true },
+  title: 'F1 Simulator Lab',
+  kicker: 'Race Control',
+  backLinkHref: 'projects.html',
+  backLinkLabel: 'Projects',
+  showBackLink: true,
+  ui: {
+    layoutPreset: 'standard',
+    cameraControls: 'external',
+    viewControls: 'switch',
+    showFps: true,
+    showTimingTower: true,
+    showTelemetry: true,
+    telemetryIncludesOverview: true,
+    telemetryModules: { ...DEFAULT_TELEMETRY_MODULES },
+    showRaceDataPanel: true,
+    raceDataTelemetryDetail: false,
+    driverCamera: false,
+    raceDataBanners: {
+      initial: 'project',
+      enabled: ['project', 'radio'],
+    },
+    raceDataBannerSize: 'custom',
+    timingTowerVerticalFit: 'expand-race-view',
+    timingGapMode: 'interval',
+    timingGapModeToggle: true,
+    timingEntryVerticalPadding: 5,
+    responsiveNarrowLayout: true,
+  },
+  debug: {
+    physicsModeIndicator: false,
+  },
+  theme: DEFAULT_PADDOCK_THEME_INPUT,
+};
+
+export const PADDOCK_SIMULATOR_PRESETS = {
+  dashboard: {
+    ui: {
+      layoutPreset: 'standard',
+      cameraControls: 'external',
+      showFps: true,
+      showTimingTower: true,
+      showTelemetry: true,
+      showRaceDataPanel: true,
+      raceDataBannerSize: 'custom',
+      timingTowerVerticalFit: 'expand-race-view',
+    },
+  },
+  'timing-overlay': {
+    ui: {
+      layoutPreset: 'left-tower-overlay',
+      cameraControls: 'external',
+      showFps: false,
+      showTimingTower: true,
+      showTelemetry: true,
+      showRaceDataPanel: true,
+      raceDataBannerSize: 'auto',
+      timingTowerVerticalFit: 'expand-race-view',
+      raceDataBanners: {
+        initial: 'project',
+        enabled: ['project', 'radio'],
+      },
+    },
+  },
+  'compact-race': {
+    ui: {
+      layoutPreset: 'standard',
+      cameraControls: 'external',
+      showFps: false,
+      showTimingTower: false,
+      showTelemetry: false,
+      showRaceDataPanel: true,
+      raceDataBannerSize: 'auto',
+      timingTowerVerticalFit: 'scroll',
+    },
+    theme: {
+      timingTowerMaxWidth: '340px',
+      raceViewMinHeight: '460px',
+    },
+  },
+  'full-dashboard': {
+    ui: {
+      layoutPreset: 'standard',
+      cameraControls: 'external',
+      showFps: true,
+      showTimingTower: true,
+      showTelemetry: true,
+      telemetryIncludesOverview: true,
+      showRaceDataPanel: true,
+      raceDataBannerSize: 'custom',
+      timingTowerVerticalFit: 'expand-race-view',
+    },
+  },
+};

package/src/config/telemetryModules.js

@@ -0,0 +1,20 @@
+export const DEFAULT_TELEMETRY_MODULES = Object.freeze({
+  core: true,
+  sectors: true,
+  lapTimes: true,
+  sectorTimes: true,
+});
+
+export function normalizeTelemetryModules(value, defaults = DEFAULT_TELEMETRY_MODULES) {
+  const names = Object.keys(defaults);
+  if (value === false) return Object.fromEntries(names.map((name) => [name, false]));
+  if (value === true || value == null || typeof value !== 'object') return { ...defaults };
+  if (Array.isArray(value)) {
+    const requested = new Set(value);
+    return Object.fromEntries(names.map((name) => [name, requested.has(name)]));
+  }
+  return Object.fromEntries(names.map((name) => [
+    name,
+    value[name] == null ? defaults[name] : Boolean(value[name]),
+  ]));
+}

package/src/config/theme/cssTokens.js

@@ -0,0 +1,85 @@
+const GENERATED_COLOR_CACHE = new Map();
+
+export function normalizeCssColorToken(value, fallback = null) {
+  if (typeof value !== 'string') return fallback;
+  const candidate = value.trim();
+  if (
+    candidate === '' ||
+    /[\u0000-\u001F\u007F;]/.test(candidate) ||
+    /[{};]/.test(candidate) ||
+    /\b(?:url|expression)\s*\(/i.test(candidate)
+  ) return fallback;
+
+  if (/^#[0-9a-f]{3}(?:[0-9a-f]{3})?$/i.test(candidate)) return normalizeHexColor(candidate);
+  if (/^(?:rgb|rgba|hsl|hsla)\([0-9\s.,%/+*-]+\)$/i.test(candidate)) return candidate;
+  if (/^(?:transparent|currentcolor|black|white|red|green|blue|yellow|orange|purple|pink|gray|grey)$/i.test(candidate)) {
+    return candidate.toLowerCase();
+  }
+  return fallback;
+}
+
+export function normalizeCssSizeToken(value, fallback = null) {
+  if (typeof value !== 'string' && typeof value !== 'number') return fallback;
+  const candidate = String(value).trim();
+  if (
+    candidate === '' ||
+    /[\u0000-\u001F\u007F;]/.test(candidate) ||
+    /[{};]/.test(candidate) ||
+    /\b(?:url|expression)\s*\(/i.test(candidate)
+  ) return fallback;
+  return candidate;
+}
+
+export function deriveModeColor(mode, key, value) {
+  const cacheKey = `${mode}:${key}:${value}`;
+  if (GENERATED_COLOR_CACHE.has(cacheKey)) return GENERATED_COLOR_CACHE.get(cacheKey);
+
+  const rgb = parseHexColor(value);
+  const generated = rgb ? rgbToHex(adjustRgbForMode(rgb, mode)) : value;
+  GENERATED_COLOR_CACHE.set(cacheKey, generated);
+  return generated;
+}
+
+function parseHexColor(value) {
+  const normalized = normalizeCssColorToken(value, null);
+  if (!normalized?.startsWith?.('#')) return null;
+  const hex = normalized.slice(1);
+  const expanded = hex.length === 3
+    ? hex.split('').map((char) => `${char}${char}`).join('')
+    : hex;
+  return {
+    r: Number.parseInt(expanded.slice(0, 2), 16),
+    g: Number.parseInt(expanded.slice(2, 4), 16),
+    b: Number.parseInt(expanded.slice(4, 6), 16),
+  };
+}
+
+function normalizeHexColor(value) {
+  const hex = value.slice(1);
+  if (hex.length === 3) {
+    return `#${hex.split('').map((char) => `${char}${char}`).join('')}`.toLowerCase();
+  }
+  return value.toLowerCase();
+}
+
+function adjustRgbForMode(rgb, mode) {
+  const amount = mode === 'light' ? 0.18 : -0.18;
+  return {
+    r: adjustChannel(rgb.r, amount),
+    g: adjustChannel(rgb.g, amount),
+    b: adjustChannel(rgb.b, amount),
+  };
+}
+
+function adjustChannel(channel, amount) {
+  const target = amount > 0 ? 255 : 0;
+  return Math.round(channel + (target - channel) * Math.abs(amount));
+}
+
+function rgbToHex({ r, g, b }) {
+  return `#${[r, g, b].map((channel) => clampColorChannel(channel).toString(16).padStart(2, '0')).join('')}`;
+}
+
+function clampColorChannel(value) {
+  return Math.max(0, Math.min(255, Math.round(value)));
+}