@inventure71/paddockjs 0.2.0 → 1.0.0

package/docs/rules.md

@@ -7,15 +7,105 @@ This file documents the rules currently implemented by the simulator. If the rac
 Default rules are defined in `src/simulation/raceSimulation.js` as `DEFAULT_RULES`:
 
 - DRS detection gap: `1` second.
-- Safety car speed: `46` world units per second.
-- Safety car lead distance: `122` world units.
-- Safety car queue gap: `128` world units.
+- Safety car speed: `166 km/h`.
+- Safety car lead distance: about `55m`.
+- Safety car queue gap: about `22m`.
 - Collision restitution: `0.18`.
 - Standing start enabled by default.
 - Start lights: `5`.
 - Start light interval: `0.72` seconds.
 - Lights-out hold: `0.78` seconds.
 
+Race rules are normalized before the simulation starts. Hosts can choose a package ruleset preset with `rules.ruleset` or `rules.profile`:
+
+- `paddock`: the simplified package default.
+- `grandPrix2025`: a 2024-2025-era grand-prix-style preset.
+- `fia2025`: an alias for `grandPrix2025` for hosts that prefer that name.
+- `custom`: starts from the package defaults and applies host-provided module options.
+
+The preset only chooses defaults. Explicit `rules.modules` values override the preset.
+
+## Rule Modules
+
+Advanced race behavior is organized under `rules.modules` so hosts can enable, disable, or tune each system independently:
+
+```js
+rules: {
+  ruleset: 'fia2025',
+  modules: {
+    pitStops: {
+      enabled: true,
+      pitLaneSpeedLimitKph: 80,
+      defaultStopSeconds: 2.8,
+      maxConcurrentPitLaneCars: 3,
+      minimumPitLaneGapMeters: 20,
+      doubleStacking: false,
+      tirePitRequestThresholdPercent: 50,
+      tirePitCommitThresholdPercent: 30,
+    },
+    tireStrategy: {
+      enabled: true,
+      compounds: ['S', 'M', 'H'],
+      mandatoryDistinctDryCompounds: 2,
+    },
+    penalties: {
+      enabled: true,
+      stewardStrictness: 0.85,
+      trackLimits: { strictness: 0.85, consequences: [{ type: 'time', seconds: 5 }] },
+      collision: { strictness: 0.65, consequences: [{ type: 'time', seconds: 5 }] },
+      tireRequirement: { strictness: 1, consequences: [{ type: 'time', seconds: 10 }] },
+      pitLaneSpeeding: { strictness: 1, speedLimitKph: 80 },
+    },
+    weather: { enabled: false },
+    reliability: { enabled: false },
+    fuelLoad: { enabled: true },
+  },
+}
+```
+
+The current implementation normalizes and exposes all module config, records a penalty ledger, enforces collision penalties, track-limit penalties, tire-requirement penalties, and pit-lane speeding penalties, creates/renders pit-lane geometry for every track, treats pit-lane asphalt, working-lane service areas, and garage boxes as legal drivable surfaces, and runs a first automated pit-stop pass when `pitStops.enabled` is true. Weather effects, reliability failures, and fuel-load performance effects are staged behind the module contract and are not fully simulated yet.
+
+## Steward Strictness
+
+Penalty subsections use `strictness` from `0` to `1` instead of a boolean:
+
+- `1`: enforce close to the configured rule.
+- `0`: do not enforce that subsection.
+- Values between `0` and `1` increase the margin before a rule applies.
+
+The simulator clamps invalid strictness values into the `0..1` range. `penalties.stewardStrictness` multiplies each subsection strictness, so hosts can make all stewards more lenient or stricter while still preserving per-rule tuning.
+
+Supported penalty subsections:
+
+- `trackLimits`
+- `collision`
+- `tireRequirement`
+- `pitLaneSpeeding`
+
+Track-limit enforcement uses the white line as the legal edge. The steward checks the four wheel contact patches and records a violation only when all four patches are fully beyond the same side of the white line by more than the strictness-adjusted margin. Touching the line, riding a kerb, or having only some wheels beyond the line is not enough. Kerbs remain a different surface for grip/drag, but they are inside track limits. Warning decisions are emitted as `track-limits` events with `decision: 'warning'`, `violationCount`, and `warningsBeforePenalty`; penalty decisions are also recorded in `snapshot.penalties` and emitted as `penalty` events in the same step. The active-excursion state remains continuous, so staying fully outside for several frames counts as one excursion until at least one wheel returns inside/legal.
+
+The built-in driver AI is expected to respect that same white-line rule through normal control inputs. Its racing-line planner keeps a centerline comfort margin for the car footprint, and the controller progressively lifts, applies mild braking when needed, and steers back inward when the car approaches the legal edge. This does not let the car defy physics; it only changes when the default AI chooses to brake, coast, and steer. Kerbs still allow normal recovery speed rather than gravel-style stopping behavior.
+
+Pit-lane surfaces are legal road for track-limit purposes. `pit-entry`, `pit-lane`, `pit-exit`, and `pit-box` track states set `inPitLane: true`, so ray sensors, runoff response, and the track-limit steward do not treat normal pit entry, service, or exit as off-track excursions.
+
+Penalty decisions are recorded in `snapshot.penalties` and emitted as `penalty` events in the same step. Each entry includes the penalty type, driver id, strictness, status, penalty seconds, pending service conversion seconds, lap, timestamp, and rule-specific context. Multiple time penalties for the same driver are additive: two separate +5s entries produce `penaltySeconds: 10` on that car's snapshot and classification adjustment.
+
+Each penalty subsection can define `consequences`. Supported consequences are:
+
+- `{ type: 'warning' }`
+- `{ type: 'time', seconds: 5 }`
+- `{ type: 'time', seconds: 10 }`
+- `{ type: 'time', seconds: 20 }`
+- `{ type: 'driveThrough', conversionSeconds: 20 }`
+- `{ type: 'stopGo', seconds: 10, conversionSeconds: 30 }`
+- `{ type: 'positionDrop', positions: 1 }`
+- `{ type: 'gridDrop', positions: 3 }`
+- `{ type: 'disqualification' }`
+
+Penalty status is part of the simulation model. Immediate consequences use `applied`; drive-through and stop-go consequences start as `issued`, can become `served` through the controller API or pit-stop service, can be `cancelled`, and convert to `applied` time penalties if still unserved when final classification is built. During a pit stop, eligible penalties are served before tire work starts: applied time penalties add their seconds as a stationary hold, stop-go penalties add their configured `seconds`, and drive-through penalties are marked served by the pit-lane traversal without adding stationary hold time.
+
+`penaltySeconds` is derived from applied time consequences for compatibility with timing/UI consumers. Rules without explicit consequences default to their existing time penalty seconds. If a time or stop-go penalty is served in the pit box, those seconds are spent before the tire change and the penalty no longer contributes to final adjusted time. At final classification, remaining time consequences and unserved service conversions are added to the driver's finish time; the classified order is sorted by `finishTime + penaltySeconds`, with raw finish order used only as a tie-breaker. Position-drop consequences then move classified drivers down by the configured number of places, and disqualified drivers are classified after non-disqualified finishers. Grid-drop consequences apply during `pre-start` by moving the driver down the grid.
+
 ## Race Modes
 
 The simulator has three race-control modes:
@@ -28,9 +118,11 @@ Safety car deployment is ignored during `pre-start`.
 
 ## Standing Start
 
+Every race initializes cars into staggered two-column start slots on the normalized start straight. Standing starts use compact grid spacing. Already-released green starts keep wider rolling-start longitudinal gaps, but still alternate left/right slot offsets instead of placing every car on the centerline. `standingStart` controls whether those slots are locked behind start lights or immediately released into green-flag running.
+
 When standing start is enabled:
 
-- Cars begin in staggered grid slots.
+- Procedural tracks normalize the start/finish area into an explicit straight so the grid and immediate launch area are not placed on a curved segment.
 - Cars stay locked until the start-light sequence releases them.
 - Start lights increment over time.
 - When lights go out, cars release and race mode becomes `green`.
@@ -43,27 +135,28 @@ Race order is based on `raceDistance`, descending. Ties fall back to original dr
 
 During safety car, order is frozen at deployment time. That prevents passing from reshuffling the timing tower while the safety car is active.
 
-Timing history is sampled per car and used to estimate:
+The simulation builds hidden timing lines around every track at an F1-style mini-sector spacing target of roughly `150m..200m`. Timing history is sampled per car and timing-line crossing timestamps are used to calculate:
 
 - Interval to the car ahead as `intervalAheadSeconds` / `gapAheadSeconds`.
-- Cumulative gap to the leader as `leaderGapSeconds`.
+- Direct same-lead-lap gap to the leader as `leaderGapSeconds`.
+- Whole-lap deficits as `intervalAheadLaps` / `gapAheadLaps` and `leaderGapLaps`.
 - DRS detection timing.
 
-The timing tower can switch at runtime between `Int` mode, which displays interval to the car ahead, and `Gap` mode, which displays cumulative gap to the leader. Timing continues to be calculated during pre-start, safety-car, and post-finish states even when the UI shows state labels such as `Grid`, `SC`, or `FIN`.
+Seconds gaps are the difference between when two cars crossed the same timing line. The race engine falls back to timing-history interpolation only before the cars have a shared timing-line sample. The timing tower can switch at runtime between `Int` mode, which displays interval to the car ahead, and `Gap` mode, which displays direct gap to the leader. When the relevant gap is one or more whole laps, the tower shows `+1`, `+2`, and so on instead of a misleading seconds estimate. Timing continues to be calculated during pre-start, safety-car, and post-finish states even when the UI shows state labels such as `Grid`, `SC`, or `FIN`.
 
 ## Units
 
-The race engine uses simulator units internally. `src/simulation/units.js` converts simulator distance and speed to public meter and km/h values. The current speed calibration maps the simulation maximum speed to an F1-like `330 km/h`; rendered car sprite dimensions are a visual scale and are not used as the physical distance scale.
+The race engine uses simulator units internally. `src/simulation/units.js` converts simulator distance and speed to public meter and km/h values. Public timer, lap-time, sector-time, gap-time, penalty-time, and service-countdown values are seconds. Public distance values with a `Meters` suffix are meters. The current speed calibration maps the simulation maximum speed to an F1-like `330 km/h`; rendered car sprite dimensions are a visual scale and are not used as the physical distance scale.
 
 ## Laps
 
 Lap is computed from each car's cumulative race distance over the track length. Total laps are provided by mount options and default to `10`.
 
-Each track is automatically divided into three equal sectors. Sector and lap telemetry is recorded when a car's cumulative race distance crosses a sector boundary or start/finish boundary. Timing values are stored in seconds and exposed on each car snapshot as `lapTelemetry`.
+Each track is automatically divided into three equal sectors. Sector and lap telemetry is recorded when a car's cumulative race distance crosses a sector boundary or start/finish boundary. Completed current-lap sector split times before the active sector are exposed as `currentSectors`, while `liveSectors` keeps only the active sector's elapsed time updated before the boundary is crossed and clears any future-sector values. `sectorProgress` is recomputed every snapshot as the live S1/S2/S3 fill state for the current lap, so sector-map UI does not derive progress from completed split state or keep stale future sectors lit. Timing values are stored in seconds and exposed on each car snapshot as `lapTelemetry`.
 
-Each car is marked `finished` when it reaches `track.length * totalLaps`. The first finisher becomes `winner`, receives classified rank `1`, and emits a `car-finish` event, but the race keeps running until every car has crossed the finish distance.
+Each car is marked `finished` when it reaches `track.length * totalLaps`. It receives a frozen provisional `finishRank`, exposes `raceStatus: 'waved-flag'` / `wavedFlag: true`, and emits a `car-finish` event. The first finisher becomes provisional `winner`, but the race keeps running until every car has crossed the finish distance. While the field is still finishing, timing order keeps already-finished cars in provisional finish order ahead of cars still running, so a waved-through car cannot lose timing-table position just because another car circulates farther before final classification.
 
-When all cars have finished, the simulator records `finishedAt` and final `classification`, emits a `race-finish` event, freezes order to the classified result, deploys the safety car, and switches race mode to `safety-car`. Finished cars keep circulating under safety-car behavior instead of hard-stopping. The current implementation does not yet implement pit stops, penalties, or championship scoring.
+When all cars have finished, the simulator records `finishedAt` and final `classification`, emits a `race-finish` event, freezes order to the classified result after outstanding penalties and classification consequences, deploys the safety car, and switches race mode to `safety-car`. Finished cars keep circulating under safety-car behavior instead of hard-stopping. The current implementation does not yet implement championship scoring.
 
 ## DRS
 
@@ -72,7 +165,7 @@ DRS behavior:
 - DRS is disabled during safety car.
 - Each track has DRS zones.
 - A car latches into a DRS zone when it crosses that zone start.
-- A car becomes DRS eligible if it was close enough to the car ahead at the relevant detection crossing.
+- A car becomes DRS eligible if it was close enough to the physically-ahead car at the relevant detection crossing, including lapped traffic.
 - The current detection window is controlled by `drsDetectionSeconds`.
 - When eligible inside the latched zone, `drsActive` becomes true.
 
@@ -93,7 +186,9 @@ Safety car behavior:
 - Race order freezes.
 - DRS state is cleared for all cars.
 - Driver aggression is reduced.
-- Cars target a queue slot behind the safety car.
+- The safety car tracks a target about `55m` ahead of the leader instead of continuously pulling away once that target is reached.
+- Cars target compact frozen-order queue slots about `22m` apart behind the safety car.
+- Safety-car queueing uses conservative corner speed and centerline correction so the train stays on the resized meter-calibrated track.
 - Timing values continue to be calculated, but gaps in the timing tower display as `SC` for non-leaders.
 
 When safety car is cleared:
@@ -121,9 +216,19 @@ Green-flag behavior uses:
 - Patience.
 - Current tire energy.
 - Track curvature.
+- Capped preview curvature for braking decisions.
+- Forward track-heading feed-forward for corner entry.
 - Nearby traffic.
 - Preferred and available lane offsets.
 
+The built-in racing controller still drives through normal vehicle inputs only. It chooses a forward racing target, blends steering from the target angle, upcoming track heading, lateral offset, edge recovery pressure, and a corner-apex racing-line offset, then sends clamped steering/throttle/brake values into the vehicle physics integrator. It is expected to use the available track width and kerbs on generated circuits, including sharp generated turns. When heading alignment or steering load shows the car cannot yet carry throttle through a corner, throttle is cut before braking is requested so the controller does not fight itself. It does not snap car position, override heading, or bypass steering-rate/yaw-rate limits.
+
+Traffic decisions use real meter-scaled gaps and lateral spacing, not raw simulator-size constants. A trailing car inside the attack window commits toward a visible passing lane instead of sitting on the centerline. A leading car with a close rear threat can defend the threatened side before the rival is fully alongside. Side-by-side overlap still creates spacing pressure so defensive and attacking moves are expressed as target-line choices and normal steering/brake/throttle inputs, not as collision avoidance teleports or artificial position overrides.
+
+Rejoin behavior also remains physics-driven. When a car leaves the legal racing surface, the controller enters a short recovery hold and keeps using rejoin controls after the center point first reaches track or kerb until heading and edge margin are stable. That prevents the car from immediately returning to full racing throttle while still pointed across the track. Recovery targets look forward along the racing surface, bias inward from the edge, and request bounded surface-specific speeds for track, kerb, grass, gravel, and barrier states.
+
+Tire energy can degrade to 1%. The vehicle physics layer converts tire energy into a nonlinear grip factor, so degradation has a visible performance cost across the full 100% to 1% range while still leaving a damaged car controllable enough to return to the pits.
+
 ## Vehicle Physics
 
 Vehicle physics live in `src/simulation/vehiclePhysics.js`.
@@ -149,34 +254,50 @@ Track state can classify a car as on:
 
 - `track`
 - `kerb`
+- `pit-entry`
+- `pit-lane`
+- `pit-exit`
+- `pit-box`
 - `gravel`
 - `grass`
 - `barrier`
 
 Surface affects grip, drag, and rolling resistance.
 
+Surface physics is wheel-based. `src/simulation/wheelSurface.js` classifies each wheel contact patch against the track model and the car uses the worst current surface for physics: `barrier > gravel > grass > kerb > pit-box > pit-lane > pit-entry/pit-exit > track`. Normal main-track running uses an analytic signed-offset fast path from cached wheel geometry, while pit-lane and pit-connector edge cases use full patch sampling. One wheel on gravel slows the car with gravel behavior even if the other three wheels are on asphalt. In addition, `vehiclePhysics.js` compares left-side and right-side wheel resistance and applies a small capped yaw-rate bias toward the slower side, so asymmetric gravel/grass/kerb contact can tug the car toward the dirty side without becoming a full tire-force simulation. One wheel on kerb reports `kerb` and applies kerb-level grip/drag without causing a track-limit violation by itself. Pit entry, pit lane, pit exit, and pit-box surfaces remain legal drivable surfaces.
+
+When pit stops are enabled, each team is assigned one shared service area in the working lane plus two garage boxes. Driver pairs share the service area, and the service area, queue slot, and garage boxes inherit the team color from `driver.team.color` when present, otherwise the lead driver's color. The current automatic stop plan distributes pit calls across available race laps as bounded pit trains, then lets opportunistic cars join the entry only when fewer than `pitStops.maxConcurrentPitLaneCars` are active and the nearest active pit-lane car is at least `pitStops.minimumPitLaneGapMeters` ahead; committed cars enter at the next pit-entry window and can queue in the working lane if their team service area is busy. Built-in AI cars also request stops from tire condition: below `pitStops.tirePitRequestThresholdPercent` they request `pitIntent: 1`, and below `pitStops.tirePitCommitThresholdPercent` they request `pitIntent: 2`. Expert-controlled cars do not receive those tire-threshold automatic calls; their model or host must request the stop with `pitIntent`. Hosts and expert actions can change a pending stop with `pitIntent`: `0` clears the pending call, `1` stays active until a free-enough pit-entry window appears, and `2` commits to entering at the next pit-entry window even if capacity or gap checks would block mode `1`. The same request may include a target compound, either through `setPitIntent(driverId, intent, targetCompound)` or expert action `pitCompound`; invalid compounds are rejected. Pit intent and target compound are locked while the car is entering, queued, servicing, or exiting, and intent resets to `0` after pit exit. Completed stops can be re-armed by later tire condition or host intent, so pit stops are not one-use per race. Safety-car mode does not block pit intent. Closed pit-lane race-control state keeps pending calls on track until `setPitLaneOpen(true)`, while red-flag state freezes cars and closes the effective pit lane until cleared. If the gap is too small for mode `1`, the following car stays on the main track and retries later rather than being forced to stop in the lane. Allowed cars steer through a forward main-track approach into the pit-entry road, slow to the configured limiter speed before the main pit-lane start, follow the main fast lane, pass through the team-colored queue point, hold for any pit-served penalties, hold for the resolved tire-service time, change to the requested compound or default alternate compound, add that compound to `usedTireCompounds`, then steer back to the racing surface through `pit-exit`. While a car is stationary in service, the browser renderer shows a small countdown above it: red `+Ns` for pit-served penalty hold time and yellow `Ns` for normal pit-service time. The queue point is a rolling gate when the active service area is free, so the car continues into service without a full stop. If a team-mate is already servicing or still exiting from the active service area, the arriving car targets the queue point behind that service area, holds a bounded approach speed until the final capture distance, waits without obstructing the main fast lane, then follows a short queue-release route only after the active service area is physically clear; this keeps both the queue stop and the move into service continuous instead of snapping the car between slots or crawling through the last several meters. Cars whose position is controlled by pit entry, queue, service, or exit logic are not laterally displaced by generic collision correction; if another car overlaps one, the movable car is corrected away while the pit-controlled car stays on its authored route or stop point. `pitStops.variability.enabled` optionally adjusts service time from `team.pitCrew.speed`, `team.pitCrew.consistency`, and `team.pitCrew.reliability`; `pitStops.variability.perfect: true` forces `pitStops.defaultStopSeconds` for training. The pit limiter applies only on the straight main pit lane and working lane between the lane start and lane end; the pit-entry connector road and pit-exit connector road are legal pit-lane surfaces but are not speed-limited by `pitStops.pitLaneSpeedLimitKph`, although automatic entry routing caps connector overspeed so worn-tire cars can still reach the limiter and assigned service area.
+
 ## Contact And Collision Handling
 
 Collision handling uses:
 
-- Oriented bounding-box overlap checks.
-- Longitudinal spacing checks.
+- Shared vehicle geometry from `src/simulation/vehicleGeometry.js`.
+- A body collision hull for car-vs-car contact.
+- Four wheel/contact-patch shapes for surface and track-limit state, not for car-vs-car contact.
+- Track-progress candidate pruning before narrow-phase checks.
+- SAT overlap checks for body/body contact.
+- Swept broadphase and conservative substep checks so fast cars cannot tunnel through each other between fixed steps.
 - Limited position correction.
 - Contact velocity response.
 - Yaw nudges.
 - Contact cooldown.
 
-The goal is believable traffic spacing and visible contact response, not full rigid-body simulation.
+The collision footprint intentionally matches the visible main car body instead of the transparent sprite rectangle. Empty sprite corners and wheel-only overlap do not count as car-vs-car contact. Longitudinal protection can only assist after swept body geometry confirms a real shape contact; it cannot invent a collision from spacing alone. Contact events expose `firstShapeId`, `secondShapeId`, `contactType`, `depth`, and `timeOfImpact` for debug views and host callbacks.
+
+When collision stewarding is enabled, fresh contact is reviewed against impact severity, closing speed, and whether one car clearly hit another from behind. Physical track order is used for rear-contact fault, so lapped traffic is judged by who is actually ahead on the circuit rather than by cumulative race distance. Low-speed/light contact is treated as a racing incident. For meaningful rear contact, the trailing car receives the only penalty and the entry records `aheadDriverId`, `atFaultDriverId`, `impactSpeedKph`, and the configured impact-speed threshold. If rear-contact responsibility is unclear, both involved cars receive shared-fault collision penalties with `sharedFault: true`. Collision penalties are independent from the existing physical contact response.
+
+When tire-requirement stewarding is enabled, a finished car is reviewed once against `tireStrategy.mandatoryDistinctDryCompounds`. Cars start with their initial tire in `usedTireCompounds`; completed automatic pit stops add the changed compound, so a strict two-compound rule can be satisfied by the current pit-stop module.
 
 ## Known Non-Goals For Now
 
 These are not currently implemented:
 
-- Pit stops.
-- Tire compound strategy.
+- Strategic pit-call timing beyond the current first automatic stop.
+- Double stacking and pit-crew conflicts.
+- Manual tire strategy selection beyond changing to the first different configured compound.
 - Fuel load strategy.
 - Weather.
-- Penalties.
 - Mechanical failures.
 - Race finish ceremony.
 - Multiplayer controls.

package/docs/system_specs.md

@@ -23,6 +23,22 @@ import {
 } from '@inventure71/paddockjs';
 ```
 
+Headless expert environment import:
+
+```js
+import {
+  createPaddockEnvironment,
+  createRolloutRecorder,
+  runEnvironmentEvaluation,
+} from '@inventure71/paddockjs/environment';
+```
+
+The environment subpath is the only public headless training import. It must stay free of DOM, PixiJS, CSS, and browser app dependencies.
+`createProgressReward()` is published from the same subpath only as non-canonical demo reward code for examples and smoke tests. It must remain optional and replaceable; environment stepping must continue to work with a custom `reward(context)` callback or no reward callback.
+Ray observations expose track-transition distance and car distance per ray. Track transitions use `kind: 'exit'` when the ray starts on track and reaches the border, `kind: 'entry'` when the ray starts off track and reaches the road again, and `kind: null` with max distance when no transition is visible.
+The package must not own model training, model persistence, model registries, or trained policy behavior. The supported contract is: external code reads observations, returns normalized actions, and advances either the headless environment or browser expert mode.
+The shared expert runtime exposes `getActionSpec()` and `getObservationSpec()` so external code can inspect controlled drivers, action ranges, sensor layout, nearby-car limits, track lookahead fields, and the versioned vector schema before connecting a model. Environment reset may apply deterministic scenario placement presets or explicit placement/traffic layouts; model steps may not mutate position and still use normalized actions only. Neutral rollout recording, deterministic evaluation metrics, and the JSON worker protocol are environment utilities, not training algorithms.
+
 All-in-one mount call:
 
 ```js
@@ -50,6 +66,7 @@ const simulator = await mountF1Simulator(root, {
   onRaceEvent,
   onLapChange,
   onRaceFinish,
+  expert,
 });
 ```
 
@@ -73,7 +90,6 @@ simulator.mountTimingTower(timingRoot);
 simulator.mountRaceCanvas(canvasRoot, {
   includeRaceDataPanel: true,
   includeTimingTower: true,
-  includeTelemetrySectorBanner: true,
   timingTowerVerticalFit: 'scroll',
 });
 simulator.mountTelemetryPanel(telemetryRoot);
@@ -84,20 +100,27 @@ simulator.mountTelemetryLapTimes(lapTimesRoot);
 simulator.mountTelemetrySectorTimes(sectorTimesRoot);
 simulator.mountRaceTelemetryDrawer(raceWorkbenchRoot, {
   timingTowerVerticalFit: 'expand-race-view',
+  raceDataTelemetryDetail: true,
 });
 
 await simulator.start();
+simulator.setPitIntent('budget', 2, 'H'); // committed automatic pit request with target tire
+const pitIntent = simulator.getPitIntent('budget');
+const targetCompound = simulator.getPitTargetCompound('budget');
+simulator.setPitLaneOpen(false);
+simulator.setRedFlagDeployed(true);
 ```
 
 Standalone helper functions are also exported for host code that prefers function calls:
 
 ```js
 mountRaceControls(root, simulator);
+mountCameraControls(root, simulator);
+mountSafetyCarControl(root, simulator);
 mountTimingTower(root, simulator);
 mountRaceCanvas(root, simulator, {
   includeRaceDataPanel: true,
   includeTimingTower: true,
-  includeTelemetrySectorBanner: true,
   timingTowerVerticalFit: 'scroll',
 });
 mountTelemetryPanel(root, simulator);
@@ -106,7 +129,10 @@ mountTelemetrySectors(root, simulator);
 mountTelemetrySectorBanner(root, simulator);
 mountTelemetryLapTimes(root, simulator);
 mountTelemetrySectorTimes(root, simulator);
-mountRaceTelemetryDrawer(root, simulator);
+mountRaceTelemetryDrawer(root, simulator, {
+  raceDataTelemetryDetail: true,
+});
+mountCarDriverOverview(root, simulator);
 mountRaceDataPanel(root, simulator);
 ```
 
@@ -126,7 +152,7 @@ Returned controller:
   mountTelemetrySectorBanner(root),
   mountTelemetryLapTimes(root),
   mountTelemetrySectorTimes(root),
-  mountRaceTelemetryDrawer(root, { timingTowerVerticalFit, drawerInitiallyOpen }),
+  mountRaceTelemetryDrawer(root, { timingTowerVerticalFit, drawerInitiallyOpen, raceDataTelemetryDetail }),
   mountRaceDataPanel(root),
   start(),
 
@@ -135,10 +161,18 @@ Returned controller:
   restart(nextOptions),
   selectDriver(driverId),
   setSafetyCarDeployed(deployed),
+  setRedFlagDeployed(deployed),
+  setPitLaneOpen(open),
+  setPitIntent(driverId, intent, targetCompound),
+  getPitIntent(driverId),
+  getPitTargetCompound(driverId),
+  servePenalty(penaltyId),
+  cancelPenalty(penaltyId),
   callSafetyCar(),
   clearSafetyCar(),
   toggleSafetyCar(),
   getSnapshot(),
+  expert,
 }
 ```
 
@@ -151,33 +185,50 @@ Returned controller:
 - The race canvas is required before `start()` because PixiJS needs a canvas host.
 - Timing tower, telemetry, controls, and race-data panels are optional from a runtime safety perspective; omitted panels simply do not render their readouts.
 - Timing tower entries are fixed rows stacked from the top of the timing list. Row vertical position must be based on rank/index, never distributed by available height or total entry count.
-- Timing tower entries display team icons. The tower can switch at runtime between interval-to-car-ahead timing and cumulative gap-to-leader timing.
-- Snapshots expose calibrated display units through `speedKph`, `distanceMeters`, and `gapMeters`; internal physics remains in simulator units.
-- Snapshots expose automatic three-sector track metadata through `track.sectors` and per-car lap/sector timing through `car.lapTelemetry`, including sector performance classes for overall-best, personal-best, and slower completed sector times.
+- Timing tower entries display team icons. The tower can switch at runtime between interval-to-car-ahead timing and direct gap-to-leader timing. Seconds gaps are calculated from hidden timing-line crossings, and whole-lap deficits display as `+N`.
+- Snapshots expose calibrated display units through `speedKph`, `distanceMeters`, and `gapMeters`; internal physics remains in simulator units. Public timer, lap-time, sector-time, gap-time, penalty-time, and service-countdown values are seconds.
+- Snapshots expose automatic three-sector track metadata through `track.sectors` and per-car lap/sector timing through `car.lapTelemetry`, including completed current-lap sector splits before the active sector, live active-sector elapsed time, per-sector progress, and sector performance classes for overall-best, personal-best, and slower completed sector times. Future-sector timing/progress entries are cleared so banner and sidebar telemetry cannot display stale split values from another lap or state.
 - Entries can include optional `team` metadata. Team color defaults to car color when omitted.
 - Mounted package surfaces show a package-owned red start-light loading overlay until `start()` finishes PixiJS, asset, control, and initial readout initialization.
 - `preset` is a preset-first API. Presets are resolved before explicit host overrides so hosts can use `dashboard`, `timing-overlay`, `compact-race`, or `full-dashboard` as a starting point and still override specific `ui` or `theme` fields.
 - `theme` is the public sizing/color contract. It maps to package CSS variables for `accentColor`, `greenColor`, `yellowColor`, `timingTowerMaxWidth`, and `raceViewMinHeight`.
-- Camera controls can be embedded in the race canvas, externally mounted, or omitted by `ui.cameraControls`.
-- Telemetry surfaces are detached package components: core scalar readouts, sector graph, broadcast sector banner, lap-time table, and sector-time table. The broadcast sector banner shows the selected car identity, uses the selected car color for its frame/label, and keeps sector performance colors inside the sector bars. `mountTelemetryPanel()` is only a stack template around those detached pieces, and `ui.telemetryModules` controls which pieces appear in stack/drawer templates.
-- `mountRaceTelemetryDrawer()` creates a package-owned race workbench: race canvas, embedded timing tower, safety-car control, lower-third banner, and a right-side telemetry drawer. The drawer opens smoothly, takes width from the race view instead of overlaying it, and is inert/hidden to interaction when closed.
+- `initialCameraMode` accepts `'overview'`, `'leader'`, `'selected'`, `'show-all'`, or `'pit'`; invalid values fall back to `'leader'`. The overview camera frames the active generated track bounds with package-owned padding and pit-lane extent. The pit camera frames the operational `track.pitLane` lane, boxes, service areas, and queue areas instead of the longer entry/exit access roads, zooms out when needed to keep that pit-lane work area inside the active race-view safe area, and its control is hidden/disabled if the active track has no pit lane. Zoom buttons and wheel zoom work in every camera mode, including overview, show-all, and pit, but cannot zoom farther out than the active track frame.
+- Camera controls default to external placement so they do not cover the race view. They can still be embedded in the race canvas by setting `ui.cameraControls: 'embedded'`, externally mounted, or omitted with `false`. Generated camera controls include a `Mute banners` toggle that is off by default and temporarily suppresses project/radio lower-thirds while active.
+- Telemetry surfaces are detached package components: core scalar readouts, sector graph, broadcast sector banner, lap-time table, and sector-time table. The broadcast sector banner shows the selected car identity, uses the selected car color for its frame/label, and keeps sector performance colors inside the sector bars. It is an explicitly mounted independent surface, not the default telemetry-drawer lower-third. `mountTelemetryPanel()` is the stack template around those detached pieces, owns vertical scrolling when constrained, and `ui.telemetryModules` controls which pieces appear in stack/drawer templates.
+- `mountRaceTelemetryDrawer()` creates a package-owned race workbench: external top controls, race canvas, embedded timing tower, lower-third banner, top steward message, safety-car control, and a right-side telemetry drawer. The top row holds camera controls, banner mute, safety car, and telemetry toggle outside the canvas. Pass `{ raceDataTelemetryDetail: true }` when the drawer lower-third should include compact project telemetry detail. The drawer opens smoothly, takes width from the race view instead of overlaying it, is inert/hidden to interaction when closed, and embeds the same `telemetry-stack` component used by standalone telemetry panels.
 - The FPS readout can be shown or hidden with `ui.showFps`.
 - `ui.layoutPreset: 'left-tower-overlay'` is a package-owned preset that creates a left broadcast gutter inside the race view, places the timing tower there at the same width as the default timing-board column, frames the PixiJS camera around the remaining usable race area, and keeps camera controls and start lights out of the tower area. In the combined shell, project and radio lower-thirds stay inside the race window while being allowed to cover the timing sidebar.
-- `ui.raceDataBanners.initial` controls the starting lower-third (`'project'`, `'radio'`, or `'hidden'`), and `ui.raceDataBanners.enabled` controls which lower-third types can appear.
+- `ui.raceDataBanners.initial` controls the starting lower-third (`'project'`, `'radio'`, or `'hidden'`), and `ui.raceDataBanners.enabled` controls which lower-third types can appear. The runtime banner mute state temporarily disables project/radio lower-thirds without changing these configured allow-lists.
+- Project and radio lower-third pills include a package-owned top-right close button that dismisses the current pill early. The next pill appears only through normal driver selection or radio scheduling.
 - `ui.raceDataBannerSize` controls lower-third sizing: `'custom'` keeps the default CSS-variable-driven banner size for host tuning, while `'auto'` uses the race space to the right of the timing board when wide enough and overlaps the timing board only when space is constrained.
+- `ui.raceDataTelemetryDetail` adds compact S1/S2/S3 sector detail to the project lower-third while keeping radio mode unchanged.
 - `ui.timingTowerVerticalFit` controls vertical tower behavior in the combined overlay preset: `'expand-race-view'` grows the race window to fit the tower, while `'scroll'` crops the tower area and scrolls timing rows inside it. The same values are accepted as `mountRaceCanvas()` options when `includeTimingTower` embeds the tower in the race canvas.
-- Hosts may scale the whole mounted simulator through the container. The horizontal proportions inside package-owned presets are not public API and should not be configurable through raw width or ratio options. The camera reads the current canvas dimensions so wider or taller host windows reveal more of the race view without needing host-owned camera math. The timing tower has a package-owned max width because overly wide timing boards degrade readability; standalone hosts can constrain vertical height through the mount container and let the timing entries scroll internally. Mobile and narrow embeds are handled by package CSS: timing boards stack full-width when they no longer work as side gutters, camera controls are repositioned into the remaining race area, and full-width timing boards do not reserve horizontal camera gutter space.
+- Hosts may scale the whole mounted simulator through the container. The horizontal proportions inside package-owned presets are not public API and should not be configurable through raw width or ratio options. The camera reads the current canvas dimensions so wider or taller host windows reveal more of the race view without needing host-owned camera math, and the renderer keeps grass coverage beyond the simulated world so deep zoom-out does not show host background. The timing tower has a package-owned max width because overly wide timing boards degrade readability; standalone hosts can constrain vertical height through the mount container and let the timing entries scroll internally. Mobile and narrow embeds are handled by package CSS: timing boards stack full-width when they no longer work as side gutters, camera controls stay in external control rows when mounted, and full-width timing boards do not reserve horizontal camera gutter space.
 - The host does not need to provide simulator assets.
 - The host passes data, not internal DOM.
+- Host driver IDs and entry `driverId` values must be unique. Entries may omit `driverNumber`; provided numbers must be unique.
+- `totalLaps` is normalized to a finite positive integer before simulation so invalid input cannot produce zero-lap, negative-lap, or non-finite snapshots.
+- `restart(nextOptions)` can change race data and deterministic seeds such as `trackSeed`, but it does not support changing asset URLs. Asset changes require `destroy()` and a fresh mount because PixiJS texture loading is an initialization boundary.
 - `onDriverOpen(driver)` is the navigation boundary.
 - Lifecycle callbacks are optional: `onLoadingChange`, `onReady`, `onError`, `onDriverSelect`, `onRaceEvent`, `onLapChange`, and `onRaceFinish`. Host callback failures are routed to `onError` when possible and must not stop the simulator loop.
-- Race completion is part of the simulation snapshot. Cars receive individual `finished`, `finishTime`, and `classifiedRank` values as they cross the finish distance. The first finisher sets `raceControl.winner`; final `raceControl.classification` and `raceControl.finished` are set only after every car finishes. At that point race control switches to `safety-car`, the final order freezes, and the field keeps circulating under safety-car behavior.
-- The simulator must stay interactive after being installed through `npm install ../PaddockJS`.
+- Race completion is part of the simulation snapshot. Cars receive individual `finished`, `finishTime`, `finishRank`, `status: 'waved-flag'`, `raceStatus: 'waved-flag'`, `wavedFlag`, `penaltySeconds`, `adjustedFinishTime`, and `classifiedRank` values as they cross the finish distance. The first finisher sets a provisional `raceControl.winner`; already-finished cars remain frozen in provisional finish order while the remaining cars complete the distance. Final `raceControl.classification` and `raceControl.finished` are set only after every car finishes. Final classification converts unserved drive-through and stop-go penalties into configured time, sorts by `finishTime + penaltySeconds`, applies position-drop and disqualification consequences, then race control switches to `safety-car`, the final order freezes to the classified result, and the field keeps circulating under safety-car behavior.
+- Race rules support package presets and custom module config. Supported rulesets are `paddock`, `grandPrix2025`, `fia2025`, and `custom`. Advanced modules include pit stops, tire strategy, penalties, weather, reliability, and fuel load. The current simulator normalizes all module config, creates/renders track-owned pit-lane geometry on an explicit start/finish straight, treats pit-lane asphalt, working-lane service areas, and garage boxes as legal drivable surfaces, runs automatic bounded pit-train entry/service/exit through the main fast lane and shared team service areas when pit stops are enabled, lets host/expert pit calls choose a target tire compound, uses the team queue point as a rolling gate when the service area is free, queues a second team car behind the active service area and moves it forward through a queue-release route only after the active service area is physically clear, keeps pit-route approach speed bounded until the final queue/service capture instead of crawling through open route, optionally varies pit-service time from team pit-crew stats with a perfect-training override, supports pit-lane open/closed state plus red flags, requests pit stops from configurable tire-energy thresholds, applies nonlinear tire-grip degradation down to 1%, applies the pit speed limiter only on the main pit lane/working lane, enforces pit-lane speeding on speed-limited pit-lane parts but not on entry/exit connectors, keeps the safety car about `55m` ahead of the leader with compact `22m` frozen-order queue slots, lets the built-in driver AI ride kerbs, attack, defend, and recover through normal steering/throttle/brake decisions with short controller-state commitments for rejoin and attack decisions, and enforces stewarded penalties for collisions, track limits, pit-lane speeding, and tire requirements.
+- Penalty subsections use `strictness` from `0` to `1`, not only boolean enablement. `strictness: 0` means the subsection is not enforced; `strictness: 1` applies the configured rule margin. Steward decisions are exposed as `penalty` events and as top-level `snapshot.penalties`. Penalty entries include normalized consequences and lifecycle status. Immediate consequences apply time, grid, position, or disqualification effects directly; drive-through and stop-go consequences remain issued until served, cancelled, or converted at final classification.
+- The browser UI can opt into top steward messages with `ui.penaltyBanners` and timing-row penalty badges with `ui.timingPenaltyBadges`. Steward messages render track-limit warning events and penalty decisions from the simulation; time-penalty messages put the penalty seconds in a large left chip and use penalty-colored backgrounds, while warnings use warning-colored backgrounds. Timing-row `!` badges are rendered only from `snapshot.penalties`; warning events do not count. UI code must not recalculate steward decisions.
+- The simulator must stay interactive after being installed through `npm install @inventure71/paddockjs`.
 - The package must build correctly through a browser bundler that supports JavaScript modules, CSS imports, and image imports.
 - The simulation should remain deterministic for the same seed, track seed, drivers, entries, and rules.
-- When `trackSeed` is omitted in a browser mount, the simulator creates a fresh procedural circuit for that mount. Explicit `trackSeed` values are deterministic and cached by seed for repeated mounts.
+- When `trackSeed` is omitted in a browser mount, the simulator creates a fresh procedural circuit for that mount. Explicit `trackSeed` values are deterministic and cached by seed for repeated mounts. Procedural generation rejects circuits with excessive local heading jumps or turn accumulation so the built-in physics-driven AI can push the generated layout without requiring pose correction.
 - The renderer should target a paced 60 FPS simulation/render loop.
 - The render loop should pause while the race canvas is offscreen or the document is hidden, then resume without catching up the elapsed hidden time. Layout measurements needed for overlay camera safe areas should be cached between resize/layout invalidations. Runtime DOM updates should skip unchanged text/markup so visible embeds do not rewrite stable readouts every frame.
+- Restart and rerender paths must destroy replaced PixiJS display children while preserving shared loaded textures.
+- Restart supports race/data/seed changes but does not support asset URL changes or browser expert mode changes. Texture loading and ticker ownership are mount-time boundaries; hosts must destroy and mount again to change either boundary.
+- Expert environment code can create a headless `createPaddockEnvironment()` from the `@inventure71/paddockjs/environment` subpath. It requires explicit `controlledDrivers`, accepts normalized actions `{ steering, throttle, brake }` plus optional `pitIntent` and `pitCompound`, advances only through `step(actions)`, and returns environment-loop JavaScript results with `observation`, `reward`, `terminated`, `truncated`, `done`, `events`, `state`, and `info`. Controlled drivers do not receive tire-threshold automatic pit calls; they request automatic pit service through `pitIntent`, may choose the target tire through `pitCompound`, and observe pit-lane/service/race-control state in `observation[driverId].object.self` and `.race`. `pitIntent: 0` is a no-op clear request and does not fail when pit stops are disabled. `self.onTrack` follows wheel-level legality, so track, kerb, and legal pit-lane/box surfaces are on-track while gravel/grass/barrier are off-track. Environment scenarios may set reset positions with `preset`, `placements`, and relative `traffic`; this is setup data, not a policy action.
+- Expert ray sensors originate from the controlled car center. The default compact set is `[-135, -60, -20, 0, 20, 60, 135, 180]`, giving forward, side, and rear awareness while staying small. Rays detect track edges against the actual track geometry and detect car hits by ray-to-car-footprint intersection.
+- Browser expert mode is opt-in with `expert: { enabled: true, controlledDrivers, frameSkip }`. When enabled, the returned controller exposes `expert.reset()`, `expert.step(actions)`, `expert.getObservation()`, and `expert.getState()`.
+- Browser expert mode wraps the same `RaceSimulation` instance that the visual canvas renders. It must not create a parallel simulation for the same mount.
+- Browser expert mode disables automatic ticker-driven simulation advancement. The visual canvas updates only after explicit expert `reset()` or `step(actions)` calls.
+- Browser expert mode may opt into `expert.visualizeSensors: true` or `expert.visualizeSensors: { rays: true }`. When enabled, ray sensors render in the race canvas world layer from the controlled cars, using the same observation result produced by explicit expert steps.
 
 ## Current Visible Features
 
@@ -206,7 +257,8 @@ Returned controller:
 - A host build tool that handles CSS and image imports. Vite is the currently verified bundler.
 - `pixi.js` available through the package dependency graph.
 
-Raw Node imports are not a supported runtime check because the package imports CSS and image assets. Verify through a browser bundler and host page instead.
+Raw Node imports of the package root are not a supported runtime check because the browser component entry imports CSS and image assets. The `@inventure71/paddockjs/environment` subpath is the supported browser-free import path for headless JavaScript training.
+The repository starter loop is executable with `node examples/train-basic-policy.mjs`. It imports the public environment subpath and self-contained example data from `examples/trainingData.mjs`. It is a dependency-free example that trains/evaluates a tiny policy against the environment contract; it is not a packaged Gymnasium bridge or a recommended final RL algorithm. The package exposes a JSON-serializable worker protocol wrapper so external processes can bridge to the JavaScript environment without PaddockJS choosing Python, Gymnasium, PettingZoo, model storage, or training infrastructure.
 
 ## Verification
 
@@ -220,16 +272,18 @@ Expected:
 
 - All Vitest tests pass.
 - `npm pack --dry-run` succeeds and includes source files plus bundled assets.
+- A packed tarball installs and builds inside a fresh temporary Vite consumer app.
+- The tracked showcase host builds.
+- Chromium browser smoke verifies desktop/mobile canvas rendering, package-panel overflow constraints, public API buttons, and visual policy-runner stepping.
 
-Run from the portfolio host:
+Run from a browser host that consumes the published package:
 
 ```bash
-npm install ../PaddockJS
+npm install @inventure71/paddockjs@latest
 npm run check
 ```
 
 Expected:
 
-- PaddockJS tests pass through the host script.
-- The host F1 bundle builds.
+- The host bundle builds with PaddockJS resolved from npm.
 - Browser smoke shows shell, canvas, driver rows, FPS readout, and working `Open project` navigation.