@inventure71/paddockjs 0.1.0 → 0.3.0

package/docs/data_contract.md

@@ -67,15 +67,282 @@ simulator.mountCameraControls(cameraControlsRoot);
 simulator.mountSafetyCarControl(safetyCarRoot);
 simulator.mountTimingTower(timingRoot);
 simulator.mountTelemetryPanel(telemetryRoot);
+simulator.mountTelemetryCore(coreTelemetryRoot);
+simulator.mountTelemetrySectors(sectorGraphRoot);
+simulator.mountTelemetrySectorBanner(sectorBannerRoot);
+simulator.mountTelemetryLapTimes(lapTimesRoot);
+simulator.mountTelemetrySectorTimes(sectorTimesRoot);
+simulator.mountRaceTelemetryDrawer(raceWorkbenchRoot, {
+  timingTowerVerticalFit: 'expand-race-view',
+  raceDataTelemetryDetail: true,
+});
 simulator.mountCarDriverOverview(overviewRoot);
 simulator.mountRaceDataPanel(raceDataRoot);
 ```
 
+## Expert Environment Contract
+
+Headless training code imports the browser-free environment subpath:
+
+```js
+import { createPaddockEnvironment, createProgressReward } from '@inventure71/paddockjs/environment';
+
+const env = createPaddockEnvironment({
+  drivers,
+  entries,
+  controlledDrivers: ['budget'],
+  seed: 71,
+  trackSeed: 2026,
+  totalLaps: 3,
+  frameSkip: 2,
+  scenario: {
+    participants: 'all',
+    nonControlled: 'ai',
+  },
+  reward: createProgressReward(),
+});
+
+let result = env.reset();
+result = env.step({
+  budget: { steering: 0, throttle: 1, brake: 0 },
+});
+```
+
+`controlledDrivers` is required. It supports one or many externally controlled cars. Non-controlled participants use the built-in driver AI in the first `0.3.0` environment slice.
+
+First-slice scenario support:
+
+```js
+scenario: {
+  participants: 'all' | 'controlled-only' | ['budget', 'alpha'],
+  nonControlled: 'ai',
+}
+```
+
+Static obstacles, custom placements, ghost cars, debug mutation, assisted controls, and Python Gymnasium wrappers are intentionally deferred.
+
+Actions use normalized low-level controls:
+
+```js
+{
+  budget: {
+    steering: -1, // full left
+    throttle: 1,
+    brake: 0,
+  },
+}
+```
+
+`steering` maps to the simulator's internal steering limit. `throttle` and `brake` are clamped from `0` to `1`.
+
+The recommended policy convention is `policy.predict(driverObservation) -> { steering, throttle, brake }`. This is a convention, not a base class. Users can wrap any model or algorithm behind that shape.
+
+The environment exposes specs for external training code:
+
+```js
+const actionSpec = env.getActionSpec();
+const observationSpec = env.getObservationSpec();
+```
+
+`actionSpec` describes controlled drivers and normalized action ranges. `observationSpec` describes object observation fields, ray layout, nearby-car limits, and vector schema.
+
+`createProgressReward()` is a starter reward helper, not the only reward contract. It returns a callback compatible with `reward(context)` and combines:
+
+- forward progress in meters from `state.snapshot.cars[].distanceMeters`
+- on-track speed in `current.object.self.speedKph`
+- off-track penalty from `current.object.self.onTrack`
+- collision penalty from global/per-driver step events
+- steering and brake smoothness penalties from the submitted normalized action
+
+Weights are explicit and overridable:
+
+```js
+const reward = createProgressReward({
+  weights: {
+    progress: 1,
+    speed: 0.01,
+    offTrack: -2,
+    collision: -10,
+    steering: -0.03,
+    brake: -0.02,
+  },
+});
+```
+
+Custom reward functions receive the same context:
+
+```js
+reward({ driverId, previous, current, action, events, state }) {
+  return current.object.self.speedKph / 100;
+}
+```
+
+`step(actions)` returns a JavaScript object designed for environment loops:
+
+```js
+{
+  observation: {
+    budget: {
+      object: {
+        self: {
+          speedKph,
+          speedMetersPerSecond,
+          headingRadians,
+          steeringAngleRadians,
+          throttle,
+          brake,
+          lap,
+          completedLaps,
+          lapProgressMeters,
+          trackOffsetMeters,
+          trackHeadingErrorRadians,
+          onTrack,
+          surface,
+          tireEnergy,
+        },
+        race: {
+          position,
+          totalCars,
+          raceMode,
+          totalLaps,
+        },
+        rays,
+        nearbyCars,
+        events,
+      },
+      vector,
+      schema,
+      events,
+    },
+  },
+  reward,
+  terminated,
+  truncated,
+  done,
+  events,
+  state: {
+    snapshot,
+  },
+  info: {
+    step,
+    elapsedSeconds,
+    seed,
+    trackSeed,
+    controlledDrivers,
+    actionErrors,
+    endReason,
+  },
+}
+```
+
+Observation objects use physical units such as kph, meters/second, meters, and radians. Optional `vector` values use fixed documented scaling from `schema`; they do not use hidden per-car normalization. Full simulator truth remains available under `state.snapshot`.
+
+Default rays use a compact center-origin set with forward, side, and rear awareness:
+
+```js
+[-135, -60, -20, 0, 20, 60, 135, 180]
+```
+
+Track distances are sampled against the actual track model. When the ray starts inside the track border, `track.kind: 'exit'` means the distance is where the ray leaves the valid road. When the ray starts outside the track border, `track.kind: 'entry'` means the distance is where the ray re-enters the valid road. If no track transition is visible within the ray length, `track.hit` is `false`, `track.distanceMeters` equals `lengthMeters`, and `track.kind` is `null`. Car hits require the ray to intersect the other car's footprint and also return max distance when no car is visible:
+
+```js
+{
+  angleDegrees,
+  angleRadians,
+  lengthMeters,
+  track: {
+    hit,
+    distanceMeters,
+    kind, // 'exit' | 'entry' | null
+  },
+  car: {
+    hit,
+    distanceMeters,
+    driverId,
+    relativeSpeedKph,
+  },
+}
+```
+
+Nearby-car observations are car-relative:
+
+```js
+{
+  id,
+  relativeForwardMeters,
+  relativeRightMeters,
+  relativeDistanceMeters,
+  relativeSpeedKph,
+  relativeHeadingRadians,
+  ahead,
+  sameLap,
+}
+```
+
+If no `reward` callback is provided, `result.reward` is `null`. If provided, rewards are returned by controlled driver ID.
+
+Browser expert mode is opt-in through the browser mount API:
+
+```js
+const simulator = await mountF1Simulator(root, {
+  drivers,
+  entries,
+  expert: {
+    enabled: true,
+    controlledDrivers: ['budget'],
+    frameSkip: 4,
+    visualizeSensors: {
+      rays: true,
+    },
+  },
+});
+
+simulator.expert.reset();
+simulator.expert.step({
+  budget: { steering: 0, throttle: 1, brake: 0 },
+});
+```
+
+When browser expert mode is enabled, automatic ticker simulation advancement is disabled. The visual canvas advances only when host code calls `simulator.expert.reset()` or `simulator.expert.step(actions)`. Browser expert mode is a mount-time option; `restart(nextOptions)` rejects `expert` changes. Destroy and mount a new simulator to switch between built-in ticker control and expert stepping.
+
+`expert.visualizeSensors` is a browser-only visual debugging option. When `visualizeSensors: true` or `visualizeSensors: { rays: true }` is set, the simulator draws the controlled drivers' ray sensors in the Pixi world layer from the cars' current positions. Ray lengths and hit markers are based on the same observation data returned from the expert environment result.
+
+## Lap Telemetry Snapshot
+
+Each `car.lapTelemetry` snapshot includes current/last/best lap and sector timing, plus sector performance classes used by package UI:
+
+```js
+{
+  currentLap,
+  currentSector,
+  currentLapTime,
+  currentSectorElapsed,
+  currentSectorProgress,
+  currentSectors,
+  lastLapTime,
+  bestLapTime,
+  lastSectors,
+  bestSectors,
+  completedLaps,
+  sectorPerformance: {
+    current: ['overall-best', 'personal-best', null],
+    last: [null, 'slower', null],
+    best: ['overall-best', null, 'personal-best'],
+  },
+}
+```
+
+`overall-best` means fastest sector time currently known across the field, `personal-best` means that driver's own fastest non-overall sector, and `slower` marks a completed sector that is slower than the driver's personal best. Missing or in-progress sector values are `null`.
+
 ## Required Options
 
-`drivers` is required and must be a non-empty array.
+`drivers` is required and must be a non-empty array. Driver `id` values must be unique.
+
+`totalLaps` is optional. Values are normalized to a finite positive integer, with invalid or non-positive input falling back to a one-lap race.
 
-`trackSeed` is optional. If omitted, each mounted browser simulator creates a fresh procedural circuit. Passing a `trackSeed` makes the track deterministic; repeated procedural seeds are cached so multiple mounts can reuse the same generated track definition.
+`trackSeed` is optional. If omitted, each mounted browser simulator creates a fresh procedural circuit. Passing a `trackSeed` makes the track deterministic; repeated procedural seeds are cached so multiple mounts can reuse the same generated track definition. Calling `restart({ trackSeed })` rebuilds the simulation on the deterministic circuit for that seed.
+
+`initialCameraMode` is optional and accepts `'overview'`, `'leader'`, `'selected'`, or `'show-all'`. Invalid values fall back to `'leader'`.
 
 Each driver must have:
 
@@ -161,7 +428,7 @@ Entries are optional. If omitted, defaults are used.
 }
 ```
 
-Entries match drivers by `driverId`.
+Entries match drivers by `driverId`. Entry `driverId` values must be unique. `driverNumber` is optional; if omitted, PaddockJS falls back to stable grid order. When `driverNumber` is provided, values must be unique.
 The car/driver overview primarily renders the existing driver and vehicle rating components from `driver` and `vehicle`. `team` is optional team-level metadata for race identity and future pit behavior; `color` defaults to the driver/car color, and `icon` defaults from the team name or timing code. The timing tower uses the team icon in the car/team column. `driver.customFields`, `vehicle.customFields`, and top-level driver `customFields` are accepted as extra metadata after those defined components.
 
 ## Rating Rules
@@ -253,12 +520,20 @@ ui: {
   showFps: true,
   showTimingTower: true,
   showTelemetry: true,
+  telemetryIncludesOverview: true,
+  telemetryModules: {
+    core: true,
+    sectors: true,
+    lapTimes: true,
+    sectorTimes: true,
+  },
   showRaceDataPanel: true,
   raceDataBanners: {
     initial: 'project',
     enabled: ['project', 'radio'],
   },
   raceDataBannerSize: 'custom',
+  raceDataTelemetryDetail: false,
   timingTowerVerticalFit: 'expand-race-view',
 }
 ```
@@ -268,12 +543,15 @@ ui: {
 - `showFps`: controls whether the race canvas renders the FPS readout.
 - `showRaceDataPanel`: controls whether the precombined shell includes the project/radio lower-third inside the race window.
 - `showTimingTower`, `showTelemetry`: reserved component visibility flags for host layout decisions.
+- `telemetryIncludesOverview`: controls whether the telemetry stack template embeds the car/driver overview. Composable hosts can also pass `mountTelemetryPanel(root, { includeOverview: false })`.
+- `telemetryModules`: controls optional telemetry surfaces inside stack/drawer templates. The default object enables `core` scalar readouts, `sectors` progress bars, `lapTimes`, and `sectorTimes`. It can also be `false` to disable all telemetry modules, or an array such as `['sectors', 'lapTimes']` to render only named modules. These modules are also individually mountable with `mountTelemetryCore`, `mountTelemetrySectors`, `mountTelemetryLapTimes`, and `mountTelemetrySectorTimes`.
 - `raceDataBanners.initial`: `'project'`, `'radio'`, or `'hidden'`. This controls which lower-third appears first in the precombined shell.
 - `raceDataBanners.enabled`: array containing `'project'` and/or `'radio'`. Disabled banner types never appear, including after driver selection.
 - `raceDataBannerSize`: `'custom'` preserves the default lower-third geometry and exposes package CSS variables for host tuning. `'auto'` uses the race space to the right of the timing board when there is enough room and falls back to full lower-third overlap when there is not.
+- `raceDataTelemetryDetail`: when `true`, the project lower-third includes compact S1/S2/S3 sector progress and timing readouts. Radio mode keeps the normal quote layout. The separate `mountTelemetrySectorBanner()` component remains available for hosts that explicitly want an independent sector banner.
 - `timingTowerVerticalFit`: `'expand-race-view'` lets the combined race window grow to contain the timing tower. `'scroll'` keeps the race window height and scrolls the timing list inside the cropped tower. The same values can be passed to `mountRaceCanvas(root, { includeTimingTower: true, timingTowerVerticalFit })` for an embedded composable timing tower.
 
-No UI option exists for raw timing-tower width, max width, or horizontal ratio. The timing tower is capped by the package CSS variable `--timing-board-max-width` because very wide timing boards read poorly. Host pages can scale the whole simulator by changing the mount container, but package-owned layout presets keep their internal proportions inside PaddockJS. For standalone timing towers, give the mount root a fixed height when a fixed vertical footprint is needed; the package keeps the frame inside that height and scrolls only the timing entries.
+No UI option exists for raw timing-tower width, max width, or horizontal ratio. The timing tower is capped by the package CSS variable `--timing-board-max-width` because very wide timing boards read poorly. Host pages can scale the whole simulator by changing the mount container, but package-owned layout presets keep their internal proportions inside PaddockJS. For standalone timing towers, give the mount root a fixed height when a fixed vertical footprint is needed; the package keeps the frame inside that height and scrolls only the timing entries. Narrow hosts are handled internally: side-gutter timing towers become stacked/full-width, embedded timing towers stop behaving like desktop side overlays, and the camera safe area stops reserving a left gutter when the measured timing board is effectively full-width.
 
 ## Theme And Sizing Contract
 
@@ -315,7 +593,39 @@ After every car completes `totalLaps`, `getSnapshot()` returns:
 }
 ```
 
-Cars also include `team`, `speedKph`, `distanceMeters`, `gapAheadMeters`, `gapAheadSeconds`, `intervalAheadSeconds`, `leaderGapSeconds`, `finished`, `finishTime`, and `classifiedRank`. `gapAheadSeconds` and `intervalAheadSeconds` are the interval to the car directly ahead. `leaderGapSeconds` is the cumulative gap to P1. The first car to finish sets `raceControl.winner` and receives a `car-finish` event, but the race keeps running until all cars finish. After final classification, the field continues under safety-car behavior.
+Cars also include `team`, `speedKph`, `distanceMeters`, `gapAheadMeters`, `gapAheadSeconds`, `intervalAheadSeconds`, `leaderGapSeconds`, `finished`, `finishTime`, `classifiedRank`, and `lapTelemetry`. `gapAheadSeconds` and `intervalAheadSeconds` are the interval to the car directly ahead. `leaderGapSeconds` is the cumulative gap to P1. The first car to finish sets `raceControl.winner` and receives a `car-finish` event, but the race keeps running until all cars finish. After final classification, the field continues under safety-car behavior.
+
+## Track And Lap Telemetry Snapshot
+
+Every built track is automatically divided into three equal sectors. `snapshot.track.sectors` exposes:
+
+```js
+[
+  { index: 1, id: 's1', label: 'S1', start, end, startRatio, endRatio, length },
+  { index: 2, id: 's2', label: 'S2', start, end, startRatio, endRatio, length },
+  { index: 3, id: 's3', label: 'S3', start, end, startRatio, endRatio, length },
+]
+```
+
+Each car exposes `lapTelemetry`:
+
+```js
+{
+  currentLap,
+  currentSector,
+  currentLapTime,
+  currentSectorElapsed,
+  currentSectorProgress,
+  currentSectors: [s1Time, s2Time, s3Time],
+  lastLapTime,
+  bestLapTime,
+  lastSectors: [s1Time, s2Time, s3Time],
+  bestSectors: [s1Time, s2Time, s3Time],
+  completedLaps,
+}
+```
+
+Times are seconds or `null` when no timing exists yet. `currentSectorProgress` is `0..1` within the active sector.
 
 ## Unit Conversion
 
@@ -324,6 +634,7 @@ The simulation keeps its internal physics in simulator units. Public speed and d
 - `simUnitsToMeters(simUnits)`
 - `metersToSimUnits(meters)`
 - `simSpeedToKph(simUnitsPerSecond)`
+- `simSpeedToMetersPerSecond(simUnitsPerSecond)`
 - `kphToSimSpeed(kph)`
 
 The current calibrated speed scale maps `VEHICLE_LIMITS.maxSpeed` to an F1-like `330 km/h`. Rendered car sprite size remains a visual scale and is intentionally larger than physical car length for readability.
@@ -337,7 +648,7 @@ const simulator = await mountF1Simulator(root, options);
 Controller methods:
 
 - `destroy()`: removes listeners, destroys PixiJS runtime, clears the host root.
-- `restart(nextOptions)`: restarts the simulation with merged options.
+- `restart(nextOptions)`: restarts the simulation with merged non-asset options. Use `destroy()` and mount a new simulator to change bundled or host-provided asset URLs.
 - `selectDriver(driverId)`: selects and focuses a driver.
 - `setSafetyCarDeployed(deployed)`: toggles safety car state.
 - `callSafetyCar()`: deploys the safety car.
@@ -351,8 +662,13 @@ Composable controllers additionally expose:
 - `mountCameraControls(root)`: renders package-owned camera mode and zoom controls outside the race canvas.
 - `mountSafetyCarControl(root)`: renders a package-owned safety-car button that binds to the same race-control state as other safety buttons.
 - `mountTimingTower(root)`: renders the timing tower component.
-- `mountRaceCanvas(root, { includeRaceDataPanel, includeTimingTower, timingTowerVerticalFit })`: renders the PixiJS canvas host, optional FPS, start lights, and optionally embedded camera controls. Pass `includeRaceDataPanel: true` to place the project/radio lower-third inside the race window so it shares race-canvas clipping and layering. Pass `includeTimingTower: true` to place the timing tower inside the race canvas; `timingTowerVerticalFit: 'expand-race-view'` grows the canvas to the tower height, while `'scroll'` keeps the canvas height and scrolls timing rows inside the tower frame. This is required before `start()`.
-- `mountTelemetryPanel(root, { includeOverview })`: renders selected-car text telemetry. It includes the car/driver overview by default unless `includeOverview: false` is passed or `ui.telemetryIncludesOverview` is `false`.
+- `mountRaceCanvas(root, { includeRaceDataPanel, includeTimingTower, includeTelemetrySectorBanner, timingTowerVerticalFit })`: renders the PixiJS canvas host, optional FPS, start lights, and optionally embedded camera controls. Pass `includeRaceDataPanel: true` to place the project/radio lower-third inside the race window so it shares race-canvas clipping and layering. Pass `includeTelemetrySectorBanner: true` only when the host intentionally wants the independent sector lower-third in addition to the project/radio banner. Pass `includeTimingTower: true` to place the timing tower inside the race canvas; `timingTowerVerticalFit: 'expand-race-view'` grows the canvas to the tower height, while `'scroll'` keeps the canvas height and scrolls timing rows inside the tower frame. This is required before `start()`.
+- `mountTelemetryPanel(root, { includeOverview })`: renders the package-owned telemetry stack template. The stack is only a composition of detached telemetry surfaces; it includes the car/driver overview by default unless `includeOverview: false` is passed or `ui.telemetryIncludesOverview` is `false`.
+- `mountTelemetryCore(root)`: renders selected-car scalar telemetry only.
+- `mountTelemetrySectors(root)`: renders the live sector progress graph only.
+- `mountTelemetryLapTimes(root)`: renders current, last, and best lap timing only.
+- `mountTelemetrySectorTimes(root)`: renders last and best sector timing only.
+- `mountRaceTelemetryDrawer(root, { timingTowerVerticalFit, drawerInitiallyOpen, raceDataTelemetryDetail })`: renders a template that combines race canvas, embedded timing tower, the project/radio lower-third, safety-car control, and a right-side telemetry drawer. Pass `raceDataTelemetryDetail: true` when this template should put compact S1/S2/S3 detail in the project lower-third instead of mounting a second sector popup. The drawer uses the detached telemetry components and takes layout space from the race window when opened.
 - `mountCarDriverOverview(root)`: renders the package-owned car/driver overview as a separate component with a Car/Driver toggle, center visual, and linked stat cells from the existing driver/vehicle rating components.
 - `mountRaceDataPanel(root)`: renders the project/race-data lower-third as a separate component for hosts that intentionally want it outside the race canvas.
 - `start()`: initializes PixiJS, binds mounted controls, and starts the simulation loop.

package/docs/data_model.md

@@ -151,6 +151,7 @@ Team metadata is copied onto the same normalized driver object. `team.color` def
 simUnitsToMeters(simUnits);
 metersToSimUnits(meters);
 simSpeedToKph(simUnitsPerSecond);
+simSpeedToMetersPerSecond(simUnitsPerSecond);
 kphToSimSpeed(kph);
 ```
 

package/docs/index.md

@@ -8,6 +8,7 @@ Use these docs as the package source of truth:
 - [Rules](rules.md): race-control behavior, DRS, safety car, starts, ordering, contact handling, and simulation rules.
 - [Concepts](concepts.md): vocabulary used by the simulator.
 - [Data Contract](data_contract.md): shape of host-provided drivers, car pairings, ratings, assets, and callbacks.
+- [Bring Your Own Model](training.md): environment contract, policy convention, and visual playback loop.
 - [Architecture](architecture.md): module ownership and data/control flow.
 - [Data Model Notes](data_model.md): lower-level simulator data model notes kept with package docs.
 - [Learnings](learnings.md): implementation lessons and layout verification rules learned from simulator integration issues.

package/docs/rules.md

@@ -59,6 +59,8 @@ The race engine uses simulator units internally. `src/simulation/units.js` conve
 
 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 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.
 
 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.

package/docs/system_specs.md

@@ -23,6 +23,18 @@ import {
 } from '@inventure71/paddockjs';
 ```
 
+Headless expert environment import:
+
+```js
+import { createPaddockEnvironment, createProgressReward } 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 as a starter callback for JavaScript training loops. 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, and vector schema before connecting a model.
+
 All-in-one mount call:
 
 ```js
@@ -50,6 +62,7 @@ const simulator = await mountF1Simulator(root, {
   onRaceEvent,
   onLapChange,
   onRaceFinish,
+  expert,
 });
 ```
 
@@ -76,6 +89,15 @@ simulator.mountRaceCanvas(canvasRoot, {
   timingTowerVerticalFit: 'scroll',
 });
 simulator.mountTelemetryPanel(telemetryRoot);
+simulator.mountTelemetryCore(coreTelemetryRoot);
+simulator.mountTelemetrySectors(sectorGraphRoot);
+simulator.mountTelemetrySectorBanner(sectorBannerRoot);
+simulator.mountTelemetryLapTimes(lapTimesRoot);
+simulator.mountTelemetrySectorTimes(sectorTimesRoot);
+simulator.mountRaceTelemetryDrawer(raceWorkbenchRoot, {
+  timingTowerVerticalFit: 'expand-race-view',
+  raceDataTelemetryDetail: true,
+});
 
 await simulator.start();
 ```
@@ -84,6 +106,8 @@ Standalone helper functions are also exported for host code that prefers functio
 
 ```js
 mountRaceControls(root, simulator);
+mountCameraControls(root, simulator);
+mountSafetyCarControl(root, simulator);
 mountTimingTower(root, simulator);
 mountRaceCanvas(root, simulator, {
   includeRaceDataPanel: true,
@@ -91,6 +115,15 @@ mountRaceCanvas(root, simulator, {
   timingTowerVerticalFit: 'scroll',
 });
 mountTelemetryPanel(root, simulator);
+mountTelemetryCore(root, simulator);
+mountTelemetrySectors(root, simulator);
+mountTelemetrySectorBanner(root, simulator);
+mountTelemetryLapTimes(root, simulator);
+mountTelemetrySectorTimes(root, simulator);
+mountRaceTelemetryDrawer(root, simulator, {
+  raceDataTelemetryDetail: true,
+});
+mountCarDriverOverview(root, simulator);
 mountRaceDataPanel(root, simulator);
 ```
 
@@ -103,8 +136,14 @@ Returned controller:
   mountCameraControls(root),
   mountSafetyCarControl(root),
   mountTimingTower(root),
-  mountRaceCanvas(root, { includeRaceDataPanel, includeTimingTower, timingTowerVerticalFit }),
+  mountRaceCanvas(root, { includeRaceDataPanel, includeTimingTower, includeTelemetrySectorBanner, timingTowerVerticalFit }),
   mountTelemetryPanel(root),
+  mountTelemetryCore(root),
+  mountTelemetrySectors(root),
+  mountTelemetrySectorBanner(root),
+  mountTelemetryLapTimes(root),
+  mountTelemetrySectorTimes(root),
+  mountRaceTelemetryDrawer(root, { timingTowerVerticalFit, drawerInitiallyOpen, raceDataTelemetryDetail }),
   mountRaceDataPanel(root),
   start(),
 
@@ -117,6 +156,7 @@ Returned controller:
   clearSafetyCar(),
   toggleSafetyCar(),
   getSnapshot(),
+  expert,
 }
 ```
 
@@ -131,29 +171,44 @@ Returned controller:
 - 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.
 - 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`.
+- `initialCameraMode` accepts `'overview'`, `'leader'`, `'selected'`, or `'show-all'`; invalid values fall back to `'leader'`.
 - Camera controls can be embedded in the race canvas, externally mounted, or omitted by `ui.cameraControls`.
-- Telemetry can include the car/driver overview directly or stay text-only through `ui.telemetryIncludesOverview` / `mountTelemetryPanel(root, { includeOverview: false })`.
+- 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 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, lower-third banner, safety-car control, and a right-side telemetry drawer. 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, and is inert/hidden to interaction when closed.
 - 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.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.
+- 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.
 - 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`.
+- 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.
 - 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.
+- 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 }`, advances only through `step(actions)`, and returns environment-loop JavaScript results with `observation`, `reward`, `terminated`, `truncated`, `done`, `events`, `state`, and `info`.
+- 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
 
@@ -169,7 +224,7 @@ Returned controller:
 - Safety car toggle.
 - External safety-car control through controller methods and optional mounted button.
 - Restart button.
-- Selected-car text telemetry.
+- Detached selected-car telemetry components for scalar readouts, sector progress graph, lap timing table, and sector timing table.
 - Car/driver overview panel with a center visual, linked stat cells, and a Car/Driver toggle.
 - Project/race data lower-third.
 - Intermittent project radio quotes.
@@ -182,7 +237,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 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.
 
 ## Verification
 
@@ -197,15 +253,14 @@ Expected:
 - All Vitest tests pass.
 - `npm pack --dry-run` succeeds and includes source files plus bundled assets.
 
-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.