@inventure71/paddockjs 0.3.0 → 1.0.0

package/src/app/domBindings.js

@@ -6,7 +6,9 @@ export function querySimulatorDom(root) {
     startLightsLabel: root.querySelector('[data-start-lights-label]'),
     towerLap: root.querySelector('[data-tower-lap-readout]'),
     towerTotalLaps: root.querySelector('[data-tower-total-laps]'),
-    towerSafetyBanner: root.querySelector('[data-tower-safety-banner]'),
+    towerRaceControlBanner: root.querySelector('[data-tower-race-control-banner]'),
+    towerRaceControlKicker: root.querySelector('[data-tower-race-control-kicker]'),
+    towerRaceControlTitle: root.querySelector('[data-tower-race-control-title]'),
     timingGapLabel: root.querySelector('[data-timing-gap-label]'),
     lap: root.querySelector('[data-lap-readout]'),
     drs: root.querySelector('[data-drs-readout]'),
@@ -45,12 +47,17 @@ export function querySimulatorDom(root) {
     telemetryDrawerWorkbench: root.querySelector('[data-race-telemetry-drawer]'),
     telemetryDrawer: root.querySelector('[data-telemetry-drawer]'),
     telemetryDrawerToggle: root.querySelector('[data-telemetry-drawer-toggle]'),
+    stewardMessage: root.querySelector('[data-steward-message]'),
+    stewardMessageKicker: root.querySelector('[data-steward-message-kicker]'),
+    stewardMessageTitle: root.querySelector('[data-steward-message-title]'),
+    stewardMessageDetail: root.querySelector('[data-steward-message-detail]'),
     raceDataPanel: root.querySelector('[data-race-data-panel]'),
     raceDataKicker: root.querySelector('[data-race-data-kicker]'),
     raceDataTitle: root.querySelector('[data-race-data-title]'),
     raceDataNumber: root.querySelector('[data-race-data-number]'),
     raceDataSubtitle: root.querySelector('[data-race-data-subtitle]'),
     raceDataOpen: root.querySelector('[data-race-data-open]'),
+    raceDataDismiss: root.querySelector('[data-race-data-dismiss]'),
     finishPanel: root.querySelector('[data-race-finish-panel]'),
     finishWinner: root.querySelector('[data-race-finish-winner]'),
     finishClassification: root.querySelector('[data-race-finish-classification]'),
@@ -65,6 +72,8 @@ export function querySimulatorDom(root) {
     timingGapModeButtons: root.querySelectorAll('[data-timing-gap-mode]'),
     cameraButtons: root.querySelectorAll('[data-camera-mode]'),
     overviewModeButtons: root.querySelectorAll('[data-overview-mode]'),
+    bannerMuteButtons: root.querySelectorAll('[data-race-data-banners-muted]'),
+    simulationSpeedButtons: root.querySelectorAll('[data-simulation-speed]'),
     zoomInButton: root.querySelector('[data-zoom-in]'),
     zoomOutButton: root.querySelector('[data-zoom-out]'),
     readouts,

package/src/config/defaultOptions.js

@@ -13,7 +13,7 @@ export const DEFAULT_F1_SIMULATOR_OPTIONS = {
   showBackLink: true,
   ui: {
     layoutPreset: 'standard',
-    cameraControls: 'embedded',
+    cameraControls: 'external',
     showFps: true,
     showTimingTower: true,
     showTelemetry: true,
@@ -46,7 +46,7 @@ export const PADDOCK_SIMULATOR_PRESETS = {
   dashboard: {
     ui: {
       layoutPreset: 'standard',
-      cameraControls: 'embedded',
+      cameraControls: 'external',
       showFps: true,
       showTimingTower: true,
       showTelemetry: true,
@@ -74,7 +74,7 @@ export const PADDOCK_SIMULATOR_PRESETS = {
   'compact-race': {
     ui: {
       layoutPreset: 'standard',
-      cameraControls: 'embedded',
+      cameraControls: 'external',
       showFps: false,
       showTimingTower: false,
       showTelemetry: false,
@@ -110,7 +110,7 @@ export const PADDOCK_THEME_CSS_VARIABLES = {
   raceViewMinHeight: '--paddock-race-view-min-height',
 };
 
-const SUPPORTED_CAMERA_MODES = new Set(['overview', 'leader', 'selected', 'show-all']);
+const SUPPORTED_CAMERA_MODES = new Set(['overview', 'leader', 'selected', 'show-all', 'pit']);
 
 export function resolveF1SimulatorOptions(options = {}) {
   const presetName = Object.hasOwn(PADDOCK_SIMULATOR_PRESETS, options.preset)

package/src/environment/actions.js

@@ -4,6 +4,7 @@ import { VEHICLE_LIMITS } from '../simulation/vehiclePhysics.js';
 export function resolveActionMap(actions = {}, controlledDrivers = [], { policy = 'strict' } = {}) {
   const errors = [];
   const controlsByDriver = {};
+  const pitIntentByDriver = {};
 
   controlledDrivers.forEach((driverId) => {
     const action = actions?.[driverId];
@@ -13,9 +14,11 @@ export function resolveActionMap(actions = {}, controlledDrivers = [], { policy
     }
     const normalized = normalizeAction(action, driverId, policy, errors);
     if (normalized) controlsByDriver[driverId] = normalized;
+    const pitIntent = normalizePitIntentAction(action, driverId, policy, errors);
+    if (pitIntent != null) pitIntentByDriver[driverId] = pitIntent;
   });
 
-  return { controlsByDriver, errors };
+  return { controlsByDriver, pitIntentByDriver, errors };
 }
 
 export function normalizeAction(action, driverId = 'unknown', policy = 'strict', errors = []) {
@@ -39,7 +42,27 @@ function finiteActionValue(value, message, policy, errors) {
   return null;
 }
 
-function handleActionError(message, policy, errors) {
+function normalizePitIntentAction(action, driverId, policy, errors) {
+  if (!Object.hasOwn(action, 'pitIntent')) return null;
+  const number = Number(action.pitIntent);
+  if (Number.isInteger(number) && number >= 0 && number <= 2) {
+    const pitCompound = normalizePitCompoundAction(action, driverId, policy, errors);
+    if (pitCompound === false) return null;
+    return pitCompound == null ? number : { intent: number, targetCompound: pitCompound };
+  }
+  handleActionError(`Invalid pitIntent action for controlled driver: ${driverId}`, policy, errors);
+  return null;
+}
+
+function normalizePitCompoundAction(action, driverId, policy, errors) {
+  if (!Object.hasOwn(action, 'pitCompound') && !Object.hasOwn(action, 'pitTargetCompound')) return null;
+  const value = action.pitCompound ?? action.pitTargetCompound;
+  if (typeof value === 'string' && value.trim()) return value.trim();
+  handleActionError(`Invalid pitCompound action for controlled driver: ${driverId}`, policy, errors);
+  return false;
+}
+
+export function handleActionError(message, policy, errors) {
   if (policy === 'strict') throw new Error(message);
   errors.push(message);
 }

package/src/environment/evaluation.js

@@ -0,0 +1,184 @@
+import { simUnitsToMeters } from '../simulation/units.js';
+import { createPaddockEnvironment } from './runtime.js';
+
+export const DEFAULT_EVALUATION_CASES = Object.freeze([
+  {
+    name: 'cornering',
+    seed: 7101,
+    trackSeed: 2601,
+    maxSteps: 420,
+    scenario: { preset: 'cornering' },
+  },
+  {
+    name: 'off-track-recovery',
+    seed: 7102,
+    trackSeed: 2602,
+    maxSteps: 360,
+    scenario: { preset: 'off-track-recovery' },
+  },
+  {
+    name: 'overtaking-pack',
+    seed: 7103,
+    trackSeed: 2603,
+    maxSteps: 600,
+    scenario: { preset: 'overtaking-pack' },
+  },
+  {
+    name: 'pit-entry',
+    seed: 7104,
+    trackSeed: 2604,
+    maxSteps: 480,
+    scenario: { preset: 'pit-entry' },
+  },
+]);
+
+export function runEnvironmentEvaluation({
+  baseOptions,
+  policy,
+  cases = DEFAULT_EVALUATION_CASES,
+  createEnvironment = createPaddockEnvironment,
+} = {}) {
+  if (!baseOptions || typeof baseOptions !== 'object') {
+    throw new Error('PaddockJS environment evaluation requires baseOptions.');
+  }
+  if (!policy) {
+    throw new Error('PaddockJS environment evaluation requires a policy function or object with predict().');
+  }
+
+  return {
+    cases: cases.map((evaluationCase) => runEvaluationCase({
+      baseOptions,
+      policy,
+      evaluationCase,
+      createEnvironment,
+    })),
+  };
+}
+
+export function createEvaluationTracker(initialResult) {
+  const initialCars = carsById(initialResult.state.snapshot);
+  const metrics = Object.fromEntries(initialResult.info.controlledDrivers.map((driverId) => {
+    const car = initialCars.get(driverId);
+    return [driverId, {
+      distanceMeters: 0,
+      lapProgressMeters: lapProgressMetersFromSnapshotCar(car),
+      offTrackSteps: car && car.surface !== 'track' ? 1 : 0,
+      contactCount: 0,
+      recoverySuccess: false,
+      passCount: 0,
+      lapTimeSeconds: null,
+      startedOffTrack: Boolean(car && car.surface !== 'track'),
+      startPosition: car?.rank ?? null,
+      bestPosition: car?.rank ?? null,
+      startDistanceMeters: cumulativeDistanceMetersFromSnapshotCar(car),
+    }];
+  }));
+
+  return {
+    update(result) {
+      const currentCars = carsById(result.state.snapshot);
+      result.info.controlledDrivers.forEach((driverId) => {
+        const car = currentCars.get(driverId);
+        const entry = metrics[driverId];
+        if (!car || !entry) return;
+        entry.distanceMeters = Math.max(0, cumulativeDistanceMetersFromSnapshotCar(car) - entry.startDistanceMeters);
+        entry.lapProgressMeters = lapProgressMetersFromSnapshotCar(car);
+        if (car.surface !== 'track') entry.offTrackSteps += 1;
+        if (entry.startedOffTrack && car.surface === 'track') entry.recoverySuccess = true;
+        if (Number.isFinite(car.rank)) {
+          entry.bestPosition = entry.bestPosition == null ? car.rank : Math.min(entry.bestPosition, car.rank);
+          entry.passCount = entry.startPosition == null ? 0 : Math.max(0, entry.startPosition - entry.bestPosition);
+        }
+        const completedLaps = car.lapTelemetry?.completedLaps ?? 0;
+        if (completedLaps > 0 && entry.lapTimeSeconds == null) {
+          entry.lapTimeSeconds = result.info.elapsedSeconds;
+        }
+      });
+      result.events.forEach((event) => {
+        if (event.type !== 'collision') return;
+        Object.keys(metrics).forEach((driverId) => {
+          if (event.driverId === driverId || event.carId === driverId || event.otherCarId === driverId || event.driverIds?.includes?.(driverId)) {
+            metrics[driverId].contactCount += 1;
+          }
+        });
+      });
+    },
+    finish() {
+      return Object.fromEntries(Object.entries(metrics).map(([driverId, entry]) => [
+        driverId,
+        {
+          distanceMeters: entry.distanceMeters,
+          lapProgressMeters: entry.lapProgressMeters,
+          offTrackSteps: entry.offTrackSteps,
+          contactCount: entry.contactCount,
+          recoverySuccess: entry.recoverySuccess,
+          passCount: entry.passCount,
+          lapTimeSeconds: entry.lapTimeSeconds,
+        },
+      ]));
+    },
+  };
+}
+
+function cumulativeDistanceMetersFromSnapshotCar(car) {
+  const distance = Number(car?.distanceMeters ?? car?.raceDistanceMeters);
+  if (Number.isFinite(distance)) return distance;
+  return simUnitsToMeters(car?.raceDistance ?? 0);
+}
+
+function lapProgressMetersFromSnapshotCar(car) {
+  const progressMeters = Number(car?.lapProgressMeters ?? car?.progressMeters);
+  if (Number.isFinite(progressMeters)) return progressMeters;
+  return simUnitsToMeters(car?.progress ?? 0);
+}
+
+function runEvaluationCase({ baseOptions, policy, evaluationCase, createEnvironment }) {
+  const env = createEnvironment({
+    ...baseOptions,
+    seed: evaluationCase.seed ?? baseOptions.seed,
+    trackSeed: evaluationCase.trackSeed ?? baseOptions.trackSeed,
+    scenario: {
+      ...(baseOptions.scenario ?? {}),
+      ...(evaluationCase.scenario ?? {}),
+    },
+  });
+  let result = env.reset();
+  const tracker = createEvaluationTracker(result);
+  const maxSteps = Math.max(1, Math.floor(evaluationCase.maxSteps ?? baseOptions.episode?.maxSteps ?? 1000));
+  let steps = 0;
+  while (!result.done && steps < maxSteps) {
+    const actions = Object.fromEntries(result.info.controlledDrivers.map((driverId) => [
+      driverId,
+      predictAction(policy, result.observation[driverId], {
+        driverId,
+        caseName: evaluationCase.name,
+        step: steps,
+        result,
+      }),
+    ]));
+    result = env.step(actions);
+    tracker.update(result);
+    steps += 1;
+  }
+  env.destroy?.();
+  return {
+    name: evaluationCase.name,
+    seed: evaluationCase.seed ?? baseOptions.seed,
+    trackSeed: evaluationCase.trackSeed ?? baseOptions.trackSeed,
+    steps,
+    done: result.done,
+    endReason: result.info.endReason,
+    metrics: tracker.finish(),
+  };
+}
+
+function predictAction(policy, observation, context) {
+  const action = typeof policy === 'function'
+    ? policy(observation, context)
+    : policy.predict(observation, context);
+  return action ?? { steering: 0, throttle: 0, brake: 1 };
+}
+
+function carsById(snapshot) {
+  return new Map(snapshot.cars.map((car) => [car.id, car]));
+}

package/src/environment/index.d.ts

@@ -1,10 +1,20 @@
 export type TireCompound = 'S' | 'M' | 'H';
+export type PaddockPitIntent = 0 | 1 | 2;
+export type PaddockScenarioPreset = 'cornering' | 'off-track-recovery' | 'overtaking-pack' | 'pit-entry';
 
 export interface TeamData {
   id?: string;
   name?: string;
   color?: string;
   icon?: string;
+  pitCrew?: PaddockPitCrewStats;
+  pitCrewStats?: PaddockPitCrewStats;
+}
+
+export interface PaddockPitCrewStats {
+  speed?: number;
+  consistency?: number;
+  reliability?: number;
 }
 
 export interface SimulatorDriver {
@@ -37,6 +47,49 @@ export interface RaceEvent {
   [key: string]: unknown;
 }
 
+export type PaddockRulesetName = 'paddock' | 'custom' | 'grandPrix2025' | 'fia2025';
+
+export interface PaddockPenaltyEntry {
+  id: string;
+  type: string;
+  at: number;
+  lap: number;
+  driverId: string;
+  strictness: number;
+  status: PaddockPenaltyStatus;
+  penaltySeconds: number;
+  pendingPenaltySeconds?: number;
+  consequences: PaddockPenaltyConsequence[];
+  serviceType?: 'driveThrough' | 'stopGo' | null;
+  serviceRequired?: boolean;
+  serviceServedAt?: number | null;
+  appliedAt?: number;
+  cancelledAt?: number;
+  unserved?: boolean;
+  positionDrop?: number;
+  gridDrop?: number;
+  disqualified?: boolean;
+  reason?: string;
+  otherCarId?: string;
+  aheadDriverId?: string;
+  atFaultDriverId?: string;
+  sharedFault?: boolean;
+  impactSpeedKph?: number;
+  impactSpeedThresholdKph?: number;
+  [key: string]: unknown;
+}
+
+export type PaddockPenaltyConsequence =
+  | { type: 'warning' }
+  | { type: 'time'; seconds: number }
+  | { type: 'driveThrough'; conversionSeconds?: number }
+  | { type: 'stopGo'; seconds?: number; conversionSeconds?: number }
+  | { type: 'positionDrop'; positions: number }
+  | { type: 'gridDrop'; positions: number }
+  | { type: 'disqualification' };
+
+export type PaddockPenaltyStatus = 'issued' | 'served' | 'applied' | 'cancelled';
+
 export interface RaceSnapshot {
   time: number;
   totalLaps: number;
@@ -48,6 +101,7 @@ export interface RaceSnapshot {
   track: Record<string, unknown>;
   cars: Array<Record<string, unknown>>;
   events: RaceEvent[];
+  penalties: PaddockPenaltyEntry[];
   [key: string]: unknown;
 }
 
@@ -55,10 +109,88 @@ export interface PaddockAction {
   steering: number;
   throttle: number;
   brake: number;
+  pitIntent?: PaddockPitIntent;
+  pitCompound?: TireCompound | string;
+  pitTargetCompound?: TireCompound | string;
 }
 
 export type PaddockActionMap = Record<string, PaddockAction>;
 
+export interface PaddockRaceRules {
+  ruleset?: PaddockRulesetName;
+  profile?: PaddockRulesetName;
+  modules?: {
+    pitStops?: {
+      enabled?: boolean;
+      pitLaneSpeedLimitKph?: number;
+      defaultStopSeconds?: number;
+      variability?: {
+        enabled?: boolean;
+        perfect?: boolean;
+        speedImpactSeconds?: number;
+        consistencyJitterSeconds?: number;
+        issueChance?: number;
+        issueMaxDelaySeconds?: number;
+      };
+      doubleStacking?: boolean;
+      maxConcurrentPitLaneCars?: number;
+      minimumPitLaneGapMeters?: number;
+      tirePitRequestThresholdPercent?: number;
+      tirePitCommitThresholdPercent?: number;
+    };
+    tireStrategy?: {
+      enabled?: boolean;
+      compounds?: TireCompound[];
+      mandatoryDistinctDryCompounds?: number | null;
+    };
+    penalties?: {
+      enabled?: boolean;
+      stewardStrictness?: number;
+      trackLimits?: {
+        strictness?: number;
+        warningsBeforePenalty?: number;
+        relaxedMarginMeters?: number;
+        timePenaltySeconds?: number;
+        consequences?: PaddockPenaltyConsequence[];
+      };
+      collision?: {
+        strictness?: number;
+        timePenaltySeconds?: number;
+        consequences?: PaddockPenaltyConsequence[];
+        minimumSeverity?: number;
+        relaxedSeverityMargin?: number;
+        minimumImpactSpeedKph?: number;
+        relaxedImpactSpeedKph?: number;
+      };
+      tireRequirement?: {
+        strictness?: number;
+        timePenaltySeconds?: number;
+        consequences?: PaddockPenaltyConsequence[];
+      };
+      pitLaneSpeeding?: {
+        strictness?: number;
+        speedLimitKph?: number;
+        marginKph?: number;
+        relaxedMarginKph?: number;
+        timePenaltySeconds?: number;
+        consequences?: PaddockPenaltyConsequence[];
+      };
+    };
+    weather?: { enabled?: boolean };
+    reliability?: { enabled?: boolean };
+    fuelLoad?: { enabled?: boolean };
+  };
+  drsDetectionSeconds?: number;
+  safetyCarSpeed?: number;
+  safetyCarLeadDistance?: number;
+  safetyCarGap?: number;
+  collisionRestitution?: number;
+  standingStart?: boolean;
+  startLightCount?: number;
+  startLightInterval?: number;
+  startLightsOutHold?: number;
+}
+
 export interface PaddockSensorRayResult {
   angleDegrees: number;
   angleRadians: number;
@@ -87,6 +219,12 @@ export interface PaddockNearbyCarObservation {
   sameLap: boolean;
 }
 
+export interface PaddockTrackLookaheadObservation {
+  distanceMeters: number;
+  curvature: number;
+  headingDeltaRadians: number;
+}
+
 export interface PaddockDriverObservationObject {
   self: {
     id: string;
@@ -103,14 +241,32 @@ export interface PaddockDriverObservationObject {
     trackHeadingErrorRadians: number;
     onTrack: boolean;
     surface: string;
+    inPitLane: boolean;
+    pitLanePart: 'entry' | 'fast-lane' | 'working-lane' | 'exit' | 'service-box' | 'garage-box' | null;
+    pitBoxId: string | null;
     tireEnergy: number | null;
+    pitIntent: PaddockPitIntent;
+    pitTargetCompound: TireCompound | string | null;
+    pitStopStatus: 'pending' | 'entering' | 'queued' | 'servicing' | 'exiting' | 'completed' | null;
+    pitStopPhase: 'entry' | 'queue' | 'queue-release' | 'penalty' | 'service' | 'exit' | null;
+    pitStopServiceRemainingSeconds: number | null;
+    pitStopPenaltyServiceRemainingSeconds: number | null;
+    pitStopsCompleted: number;
   };
   race: {
     position: number;
     totalCars: number;
     raceMode: string;
+    pitLaneOpen: boolean;
+    redFlag: boolean;
     totalLaps: number;
   };
+  track: {
+    lengthMeters: number;
+    widthMeters: number;
+    curvature: number;
+    lookahead: PaddockTrackLookaheadObservation[];
+  };
   rays: PaddockSensorRayResult[];
   nearbyCars: PaddockNearbyCarObservation[];
   events: RaceEvent[];
@@ -137,10 +293,14 @@ export interface PaddockEnvironmentOptions {
   trackSeed?: number;
   totalLaps?: number;
   frameSkip?: number;
+  rules?: PaddockRaceRules;
   actionPolicy?: 'strict' | 'report';
   scenario?: {
     participants?: 'all' | 'controlled-only' | string[];
     nonControlled?: 'ai';
+    preset?: PaddockScenarioPreset;
+    placements?: Record<string, PaddockScenarioPlacement>;
+    traffic?: PaddockScenarioTrafficPlacement[];
   };
   sensors?: {
     rays?: {
@@ -157,6 +317,9 @@ export interface PaddockEnvironmentOptions {
     };
   };
   sensorsByDriver?: Record<string, PaddockEnvironmentOptions['sensors']>;
+  observation?: {
+    lookaheadMeters?: number[];
+  };
   episode?: {
     maxSteps?: number;
     endOnRaceFinish?: boolean;
@@ -164,6 +327,23 @@ export interface PaddockEnvironmentOptions {
   reward?: (payload: PaddockRewardContext) => number;
 }
 
+export interface PaddockScenarioPlacement {
+  distanceMeters?: number;
+  startDistanceMeters?: number;
+  offsetMeters?: number;
+  speedKph?: number;
+  headingErrorRadians?: number;
+}
+
+export interface PaddockScenarioTrafficPlacement {
+  driverId: string;
+  relativeTo: string;
+  deltaDistanceMeters?: number;
+  offsetMeters?: number;
+  speedKph?: number;
+  headingErrorRadians?: number;
+}
+
 export interface PaddockRewardContext {
   driverId: string;
   previous: RaceSnapshot | null;
@@ -195,12 +375,14 @@ export interface PaddockActionSpec {
       steering: { min: -1; max: 1; unit: 'normalized' };
       throttle: { min: 0; max: 1; unit: 'normalized' };
       brake: { min: 0; max: 1; unit: 'normalized' };
+      pitIntent: { values: [0, 1, 2]; unit: 'request'; optional: true };
+      pitCompound: { values: string[]; unit: 'compound'; optional: true };
     };
   };
 }
 
 export interface PaddockObservationSpec {
-  version: 1;
+  version: 2;
   controlledDrivers: string[];
   object: Record<string, unknown>;
   vector: {
@@ -208,6 +390,81 @@ export interface PaddockObservationSpec {
   };
 }
 
+export interface PaddockRolloutTransition {
+  observation: Record<string, PaddockDriverObservation>;
+  action: PaddockActionMap;
+  reward: null | Record<string, number>;
+  nextObservation: Record<string, PaddockDriverObservation>;
+  terminated: boolean;
+  truncated: boolean;
+  info: PaddockEnvironmentResult['info'];
+}
+
+export interface PaddockRolloutRecorder {
+  recordStep(
+    previousResult: PaddockEnvironmentResult,
+    action: PaddockActionMap,
+    nextResult: PaddockEnvironmentResult
+  ): PaddockRolloutTransition;
+  clear(): void;
+  toJSON(): PaddockRolloutTransition[];
+}
+
+export interface PaddockEvaluationCase {
+  name: string;
+  seed?: number;
+  trackSeed?: number;
+  maxSteps?: number;
+  scenario?: PaddockEnvironmentOptions['scenario'];
+}
+
+export interface PaddockEvaluationDriverMetrics {
+  distanceMeters: number;
+  lapProgressMeters: number;
+  offTrackSteps: number;
+  contactCount: number;
+  recoverySuccess: boolean;
+  passCount: number;
+  lapTimeSeconds: number | null;
+}
+
+export interface PaddockEvaluationCaseReport {
+  name: string;
+  seed?: number;
+  trackSeed?: number;
+  steps: number;
+  done: boolean;
+  endReason: string | null;
+  metrics: Record<string, PaddockEvaluationDriverMetrics>;
+}
+
+export interface PaddockEvaluationReport {
+  cases: PaddockEvaluationCaseReport[];
+}
+
+export type PaddockPolicyLike =
+  | ((observation: PaddockDriverObservation, context: Record<string, unknown>) => PaddockAction)
+  | { predict(observation: PaddockDriverObservation, context: Record<string, unknown>): PaddockAction };
+
+export interface PaddockEnvironmentWorkerMessage {
+  id?: string | number | null;
+  type: 'reset' | 'step' | 'getActionSpec' | 'getObservationSpec' | 'getObservation' | 'getState' | 'destroy' | string;
+  options?: Partial<PaddockEnvironmentOptions>;
+  actions?: PaddockActionMap;
+}
+
+export interface PaddockEnvironmentWorkerResponse {
+  id: string | number | null;
+  ok: boolean;
+  type: string;
+  result?: unknown;
+  error?: string;
+}
+
+export interface PaddockEnvironmentWorkerProtocol {
+  handle(message: PaddockEnvironmentWorkerMessage): PaddockEnvironmentWorkerResponse;
+}
+
 export interface PaddockEnvironmentResult {
   observation: Record<string, PaddockDriverObservation>;
   reward: null | Record<string, number>;
@@ -239,3 +496,26 @@ export interface PaddockEnvironment {
 
 export function createPaddockEnvironment(options: PaddockEnvironmentOptions): PaddockEnvironment;
 export function createProgressReward(options?: PaddockProgressRewardOptions): (context: PaddockRewardContext) => number;
+export function createRolloutRecorder(): PaddockRolloutRecorder;
+export function createRolloutTransition(
+  previousResult: PaddockEnvironmentResult,
+  action: PaddockActionMap,
+  nextResult: PaddockEnvironmentResult
+): PaddockRolloutTransition;
+export const ENVIRONMENT_SCENARIO_PRESETS: readonly PaddockScenarioPreset[];
+export const DEFAULT_EVALUATION_CASES: readonly PaddockEvaluationCase[];
+export function createEvaluationTracker(initialResult: PaddockEnvironmentResult): {
+  update(result: PaddockEnvironmentResult): void;
+  finish(): Record<string, PaddockEvaluationDriverMetrics>;
+};
+export function runEnvironmentEvaluation(options: {
+  baseOptions: PaddockEnvironmentOptions;
+  policy: PaddockPolicyLike;
+  cases?: PaddockEvaluationCase[];
+  createEnvironment?: (options: PaddockEnvironmentOptions) => PaddockEnvironment;
+}): PaddockEvaluationReport;
+export function createEnvironmentWorkerProtocol(env: PaddockEnvironment): PaddockEnvironmentWorkerProtocol;
+export function handleEnvironmentMessage(
+  env: PaddockEnvironment,
+  message: PaddockEnvironmentWorkerMessage
+): PaddockEnvironmentWorkerResponse;