@inventure71/paddockjs 0.2.0 → 0.3.0

package/docs/data_contract.md

@@ -54,7 +54,6 @@ const simulator = createPaddockSimulator({
 simulator.mountRaceCanvas(canvasRoot, {
   includeRaceDataPanel: true,
   includeTimingTower: true,
-  includeTelemetrySectorBanner: true,
   timingTowerVerticalFit: 'scroll',
 });
 await simulator.start();
@@ -75,11 +74,239 @@ 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:
@@ -109,9 +336,13 @@ Each `car.lapTelemetry` snapshot includes current/last/best lap and sector timin
 
 ## 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. Calling `restart({ trackSeed })` rebuilds the simulation on the deterministic circuit for that seed.
 
-`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.
+`initialCameraMode` is optional and accepts `'overview'`, `'leader'`, `'selected'`, or `'show-all'`. Invalid values fall back to `'leader'`.
 
 Each driver must have:
 
@@ -197,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
@@ -302,6 +533,7 @@ ui: {
     enabled: ['project', 'radio'],
   },
   raceDataBannerSize: 'custom',
+  raceDataTelemetryDetail: false,
   timingTowerVerticalFit: 'expand-race-view',
 }
 ```
@@ -316,6 +548,7 @@ ui: {
 - `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. 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.
@@ -401,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.
@@ -414,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.
@@ -428,13 +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()`.
+- `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 })`: renders a template that combines race canvas, embedded timing tower, lower-third banner, and a right-side telemetry drawer. The drawer uses the detached telemetry components and takes layout space from the race window when opened.
+- `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/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,
 });
 ```
 
@@ -73,7 +86,6 @@ simulator.mountTimingTower(timingRoot);
 simulator.mountRaceCanvas(canvasRoot, {
   includeRaceDataPanel: true,
   includeTimingTower: true,
-  includeTelemetrySectorBanner: true,
   timingTowerVerticalFit: 'scroll',
 });
 simulator.mountTelemetryPanel(telemetryRoot);
@@ -84,6 +96,7 @@ simulator.mountTelemetryLapTimes(lapTimesRoot);
 simulator.mountTelemetrySectorTimes(sectorTimesRoot);
 simulator.mountRaceTelemetryDrawer(raceWorkbenchRoot, {
   timingTowerVerticalFit: 'expand-race-view',
+  raceDataTelemetryDetail: true,
 });
 
 await simulator.start();
@@ -93,11 +106,12 @@ 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,
   includeTimingTower: true,
-  includeTelemetrySectorBanner: true,
   timingTowerVerticalFit: 'scroll',
 });
 mountTelemetryPanel(root, simulator);
@@ -106,7 +120,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 +143,7 @@ Returned controller:
   mountTelemetrySectorBanner(root),
   mountTelemetryLapTimes(root),
   mountTelemetrySectorTimes(root),
-  mountRaceTelemetryDrawer(root, { timingTowerVerticalFit, drawerInitiallyOpen }),
+  mountRaceTelemetryDrawer(root, { timingTowerVerticalFit, drawerInitiallyOpen, raceDataTelemetryDetail }),
   mountRaceDataPanel(root),
   start(),
 
@@ -139,6 +156,7 @@ Returned controller:
   clearSafetyCar(),
   toggleSafetyCar(),
   getSnapshot(),
+  expert,
 }
 ```
 
@@ -158,26 +176,39 @@ Returned controller:
 - 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 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.
+- 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. 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. 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
 
@@ -206,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
 
@@ -221,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.

package/docs/training.md

@@ -0,0 +1,104 @@
+# Bring Your Own Model
+
+PaddockJS does not train models for you. It provides a simulator environment contract so users can train with any toolchain, then run the resulting policy in the visual simulator.
+
+## Boundary
+
+PaddockJS owns:
+
+- deterministic simulator stepping
+- observations
+- normalized actions
+- events
+- optional reward callback hooks
+- browser expert stepping
+- sensor visualization
+
+Users own:
+
+- ML framework choice
+- training algorithm
+- model weights
+- model storage
+- model loading
+- reward design beyond optional starter helpers
+
+## Policy Shape
+
+Use this convention for browser playback:
+
+```js
+const policy = {
+  predict(observation) {
+    return {
+      steering: 0,
+      throttle: 1,
+      brake: 0,
+    };
+  },
+};
+```
+
+`predict()` receives one controlled driver's observation. It returns normalized controls:
+
+- `steering`: `-1` full left, `1` full right
+- `throttle`: `0` to `1`
+- `brake`: `0` to `1`
+
+## Headless Training Loop
+
+```js
+import { createPaddockEnvironment } from '@inventure71/paddockjs/environment';
+
+const env = createPaddockEnvironment({
+  drivers,
+  entries,
+  controlledDrivers: ['budget'],
+  frameSkip: 4,
+  reward: myReward,
+});
+
+let result = env.reset();
+while (!result.done) {
+  const observation = result.observation.budget;
+  const action = policy.predict(observation);
+  result = env.step({ budget: action });
+}
+```
+
+## Visual Playback Loop
+
+```js
+import { mountF1Simulator } from '@inventure71/paddockjs';
+
+const simulator = await mountF1Simulator(root, {
+  drivers,
+  entries,
+  expert: {
+    enabled: true,
+    controlledDrivers: ['budget'],
+    frameSkip: 4,
+    visualizeSensors: { rays: true },
+  },
+});
+
+function frame() {
+  const observation = simulator.expert.getObservation().budget;
+  const action = policy.predict(observation);
+  simulator.expert.step({ budget: action });
+  requestAnimationFrame(frame);
+}
+
+frame();
+```
+
+## Specs
+
+Use specs to connect external training code without guessing:
+
+```js
+const actionSpec = env.getActionSpec();
+const observationSpec = env.getObservationSpec();
+```
+
+These specs describe the action ranges, controlled drivers, ray layout, nearby-car limits, and vector schema.