@inventure71/paddockjs 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- eabe042: Prepare the major 0.3.0 feature release with published-package docs, runtime restart hardening, and the first expert environment API. Public install docs now target npm consumption, package dry-run contents exclude repo-agent files and unexported standalone code, lockfiles are synchronized to the package version, host driver/entry validation rejects duplicate IDs, invalid lap counts normalize to one-lap races, restart can rebuild deterministic tracks from a new `trackSeed`, asset URL changes are explicitly remount-only, and rerender paths destroy replaced PixiJS display children. The release also adds a browser-free JavaScript environment contract through the `@inventure71/paddockjs/environment` subpath and an opt-in browser expert wrapper that reuses the visual simulator's race state, including opt-in in-canvas ray sensor visualization for controlled expert drivers, center-origin geometry-based ray detection for track exit/re-entry transitions and car footprints, a starter `createProgressReward()` callback, and a dependency-free headless training/evaluation example. It also documents the bring-your-own-model boundary, adds environment action/observation specs, and includes a visual policy-runner example that demonstrates `policy.predict(observation)` driving browser expert mode without adding ML dependencies or model persistence.
+
+## 0.2.0
+
+### Minor Changes
+
+- 846f388: Add detached telemetry surfaces, sector timing status colors, a broadcast sector banner, and a race telemetry drawer template with embedded timing tower, safety-car control, and lower-third race data.
+
+### Patch Changes
+
+- 21cf4e5: Document the official release workflow and switch automated publishing to npm trusted publishing through GitHub Actions.
+
 All notable changes to this project will be documented in this file.
 
 The npm release workflow updates this changelog from committed Changesets.

package/INSTALL_AND_UPDATE.md

@@ -0,0 +1,163 @@
+# PaddockJS Install and Update Guide
+
+This guide explains how host websites consume the published PaddockJS npm package.
+
+## Install
+
+Install the package from npm:
+
+```bash
+npm install @inventure71/paddockjs
+```
+
+The host website imports PaddockJS by package name:
+
+```js
+import { mountF1Simulator } from '@inventure71/paddockjs';
+```
+
+Host applications should not copy simulator assets into their own source tree. PaddockJS owns its bundled car, safety-car, logo, panel, and track texture assets.
+
+## Host Website Setup
+
+Create a host entry file in the consuming website:
+
+```js
+import {
+  CHAMPIONSHIP_ENTRY_BLUEPRINTS,
+  DEMO_PROJECT_DRIVERS,
+  mountF1Simulator,
+} from '@inventure71/paddockjs';
+
+const root = document.getElementById('f1-simulator-root');
+
+if (root) {
+  await mountF1Simulator(root, {
+    drivers: DEMO_PROJECT_DRIVERS,
+    entries: CHAMPIONSHIP_ENTRY_BLUEPRINTS,
+    title: 'F1 Simulator Lab',
+    kicker: 'Race Control',
+    backLinkHref: '/projects',
+    backLinkLabel: 'Projects',
+    onDriverOpen(driver) {
+      if (driver.link) window.location.href = driver.link;
+    },
+  });
+}
+```
+
+The host page needs a root element and the bundled JavaScript/CSS produced by the host build:
+
+```html
+<div id="f1-simulator-root"></div>
+<script type="module" src="/dist/f1-simulator.js"></script>
+```
+
+If the host bundler does not extract package CSS automatically, import the stylesheet explicitly:
+
+```js
+import '@inventure71/paddockjs/styles.css';
+```
+
+## Build Setup
+
+Use a browser bundler that understands JavaScript module imports, CSS imports, and image imports. Vite, Rollup, Webpack, and similar bundlers are valid fits.
+
+Use Node `20.19.0` or newer for local package development, showcase builds, and host builds based on the current Vite toolchain.
+
+Example Vite entry config:
+
+```js
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  build: {
+    outDir: 'dist',
+    rollupOptions: {
+      input: 'src/paddockjs-entry.js',
+      output: {
+        entryFileNames: 'f1-simulator.js',
+        chunkFileNames: 'chunks/[name]-[hash].js',
+        assetFileNames: 'assets/[name]-[hash][extname]',
+      },
+    },
+  },
+});
+```
+
+Run the host's normal install and build checks:
+
+```bash
+npm install
+npm run check
+```
+
+Do not use raw Node as the main import test:
+
+```bash
+node -e "import('@inventure71/paddockjs')"
+```
+
+That can fail because PaddockJS imports CSS and image assets. Verify through a browser-oriented host build instead.
+
+## Updating The Package
+
+Install the latest published version:
+
+```bash
+npm install @inventure71/paddockjs@latest
+npm run check
+```
+
+Install a specific version when the host needs a controlled upgrade:
+
+```bash
+npm install @inventure71/paddockjs@0.2.0
+npm run check
+```
+
+After updating, smoke-test the page that mounts the simulator. Browser behavior changes should be checked in the consuming host, because host CSS, container size, and route handling are outside the package.
+
+## Package Release Workflow
+
+The package repo owns its release process:
+
+- `npm run check` runs runtime tests, public type verification, dry-pack verification, and the tracked showcase build.
+- `npm run changeset` records the next version bump and changelog note.
+- `npm run version-packages` applies pending Changesets locally.
+- `.github/workflows/ci.yml` verifies the package on push and pull request.
+- `.github/workflows/release.yml` opens a release PR from Changesets and publishes to npm after merge through npm trusted publishing.
+
+For trusted publishing on npm, configure the package settings to trust:
+
+- organization or user: `Inventure71`
+- repository: `PaddockJS`
+- workflow filename: `release.yml`
+
+No long-lived `NPM_TOKEN` secret is required once trusted publishing is enabled.
+
+The release PR must include synchronized `package.json`, `package-lock.json`, `CHANGELOG.md`, and Changesets output for the version being published.
+
+## When Something Breaks
+
+If the host cannot resolve the package, reinstall from npm:
+
+```bash
+npm install @inventure71/paddockjs@latest
+```
+
+If the host bundler cannot resolve an asset, verify the package contents from the package repo:
+
+```bash
+npm run pack:dry
+```
+
+Check that the asset is listed in the dry-pack output.
+
+If simulator tests fail after a package change:
+
+```bash
+npm test
+```
+
+Fix the package first, then update and rebuild the host.

package/README.md

@@ -1,6 +1,6 @@
 # PaddockJS
 
-This folder is the extractable F1 simulator component. It owns the simulator source, bundled simulator assets, CSS, demo data, and the public mount API.
+PaddockJS is an installable F1-style simulator component for browser host websites. It owns the simulator source, bundled simulator assets, CSS, demo data, and public mount API.
 
 ## Install
 
@@ -10,24 +10,19 @@ From npm:
 npm install @inventure71/paddockjs
 ```
 
-For local sibling-repo development:
-
-```bash
-npm install ../PaddockJS
-```
-
 ## Documentation
 
 Start with [docs/index.md](docs/index.md) for system specs, rules, concepts, data contracts, and architecture notes.
 
 ## Package Workflow
 
-The repo now includes the full package-release boundary:
+The repo includes the full package-release boundary:
 
 - a tracked showcase host in `local-preview/`
 - public TypeScript declarations in `src/index.d.ts`
 - GitHub Actions CI in `.github/workflows/ci.yml`
 - Changesets release automation in `.github/workflows/release.yml`
+- npm trusted publishing support through GitHub Actions OIDC
 
 Useful commands:
 
@@ -40,6 +35,67 @@ npm run changeset
 
 `npm run check` verifies the runtime tests, public declaration file, dry package contents, and showcase build.
 
+Local development and showcase builds require Node `20.19.0` or newer. CI currently runs the package check on Node 22 and releases on Node 24.
+
+## Expert Environment API
+
+Headless training code imports the environment subpath:
+
+```js
+import { createPaddockEnvironment, createProgressReward } from '@inventure71/paddockjs/environment';
+```
+
+The package root remains the browser component API. The environment subpath is intentionally browser-free and does not import DOM, PixiJS, or package CSS.
+PaddockJS is a bring-your-own-model environment. It does not choose an ML framework, store model weights, or ship a trained driver. See [Bring Your Own Model](docs/training.md) for the policy shape and visual playback loop.
+
+```js
+const env = createPaddockEnvironment({
+  drivers,
+  entries,
+  controlledDrivers: ['budget'],
+  frameSkip: 2,
+  reward: createProgressReward(),
+});
+
+let result = env.reset();
+result = env.step({
+  budget: { steering: 0, throttle: 1, brake: 0 },
+});
+```
+
+The repository includes a dependency-free starter training loop that uses the same environment contract:
+
+```bash
+node examples/train-basic-policy.mjs --generations=4 --candidates=5 --episodes=1 --steps=240
+```
+
+Each ray reports track-transition distance and car distance. A track hit uses `kind: 'exit'` when the ray leaves the road and `kind: 'entry'` when an off-track ray points back to the road.
+
+External training code can inspect the environment contract without guessing field ranges:
+
+```js
+const actionSpec = env.getActionSpec();
+const observationSpec = env.getObservationSpec();
+```
+
+Browser expert mode is opt-in through the normal mount API. When enabled, the visual simulator advances only when host code calls `simulator.expert.step(actions)`. Expert mode is a mount-time boundary; changing `expert` through `restart(nextOptions)` is rejected so ticker ownership cannot silently change under a mounted simulator.
+Set `expert.visualizeSensors` to draw expert sensor rays inside the actual race canvas for visual debugging:
+
+```js
+const simulator = await mountF1Simulator(root, {
+  drivers,
+  entries,
+  expert: {
+    enabled: true,
+    controlledDrivers: ['budget'],
+    frameSkip: 4,
+    visualizeSensors: {
+      rays: true,
+    },
+  },
+});
+```
+
 ## API
 
 All-in-one mount:
@@ -67,12 +123,14 @@ const simulator = await mountF1Simulator(document.getElementById('sim-root'), {
       vehicle: { id: 'budget-bb01', name: 'BB-01 Ledger', power: 48, braking: 72, aero: 55, dragEfficiency: 66, mechanicalGrip: 63, weightControl: 58, tireCare: 82 },
     },
   ],
+  initialCameraMode: 'show-all',
+  expert: {
+    enabled: true,
+    controlledDrivers: ['budget'],
+  },
   onDriverOpen(driver) {
     window.location.href = driver.link;
   },
-  onRaceFinish({ winner, classification }) {
-    console.log('Race winner:', winner.name, classification);
-  },
 });
 ```
 
@@ -96,7 +154,11 @@ simulator.mountTimingTower(document.getElementById('sim-timing'));
 simulator.mountRaceCanvas(document.getElementById('sim-race'), {
   includeRaceDataPanel: true,
 });
-simulator.mountTelemetryPanel(document.getElementById('sim-telemetry'));
+simulator.mountTelemetryCore(document.getElementById('sim-telemetry-core'));
+simulator.mountTelemetrySectors(document.getElementById('sim-telemetry-sectors'));
+simulator.mountTelemetrySectorBanner(document.getElementById('sim-telemetry-sector-banner'));
+simulator.mountTelemetryLapTimes(document.getElementById('sim-telemetry-laps'));
+simulator.mountTelemetrySectorTimes(document.getElementById('sim-telemetry-sector-times'));
 simulator.mountCarDriverOverview(document.getElementById('sim-overview'));
 
 await simulator.start();
@@ -112,18 +174,28 @@ simulator.mountRaceCanvas(document.getElementById('sim-race'), {
 });
 ```
 
+For a packaged race-window template with a right-side telemetry drawer:
+
+```js
+simulator.mountRaceTelemetryDrawer(document.getElementById('sim-race-workbench'), {
+  timingTowerVerticalFit: 'expand-race-view',
+  raceDataTelemetryDetail: true,
+});
+```
+
 `drivers` is the host-owned project/pilot list. `entries` is the optional driver/car/team pairing sheet. The car/driver overview uses the existing driver and vehicle rating components from each entry. Driver and vehicle entries can also include `customFields` as extra label/value metadata. Entries can include `team: { id, name, color, icon }`; the timing tower uses the team icon and defaults team color to the car color when omitted. Assets, including the default car image and generic driver helmet, are bundled by default, so the host website does not need to provide simulator images or textures.
 
 The returned object supports:
 
 - `destroy()`
-- `restart(nextOptions)`
+- `restart(nextOptions)` for non-asset, non-expert race/data/seed changes
 - `selectDriver(driverId)`
 - `setSafetyCarDeployed(deployed)`
 - `callSafetyCar()`
 - `clearSafetyCar()`
 - `toggleSafetyCar()`
 - `getSnapshot()`
+- `expert` when explicitly enabled, otherwise `null`
 
 Useful UI options:
 
@@ -139,26 +211,34 @@ ui: {
   cameraControls: 'external',
   showFps: false,
   telemetryIncludesOverview: false,
+  telemetryModules: ['core', 'sectors', 'lapTimes', 'sectorTimes'],
   raceDataBanners: {
     initial: 'project',
     enabled: ['project', 'radio'],
   },
   raceDataBannerSize: 'auto',
+  raceDataTelemetryDetail: true,
   timingTowerVerticalFit: 'expand-race-view',
 }
 ```
 
 `preset` is resolved before explicit host options. Available presets are `dashboard`, `timing-overlay`, `compact-race`, and `full-dashboard`; hosts can start from a preset and override any `ui` or `theme` field. `theme` maps to package CSS variables for the stable sizing/color contract: `accentColor`, `greenColor`, `yellowColor`, `timingTowerMaxWidth`, and `raceViewMinHeight`.
 
-If `trackSeed` is omitted, each mounted browser simulator creates a fresh procedural circuit. Passing `trackSeed` makes the track deterministic so multiple embeds can share the same generated circuit; repeated procedural seeds are cached within the page runtime.
+If `trackSeed` is omitted, each mounted browser simulator creates a fresh procedural circuit. Passing `trackSeed` makes the track deterministic so multiple embeds can share the same generated circuit; repeated procedural seeds are cached within the page runtime. `restart({ trackSeed })` rebuilds the race on the deterministic circuit for the new seed. Asset URL changes are not restartable; destroy and mount a new simulator when changing assets.
+
+`initialCameraMode` accepts `'overview'`, `'leader'`, `'selected'`, or `'show-all'`; invalid values fall back to `'leader'`. `layoutPreset: 'left-tower-overlay'` creates a left broadcast gutter inside the race view, frames the camera around the remaining race area, and places the timing tower in that gutter without covering camera controls. The project/radio lower-third stays inside the race window and can intentionally render over the timing sidebar instead of shrinking around it. Composable hosts should pass `{ includeRaceDataPanel: true }` to `mountRaceCanvas()` when they want that lower-third clipped and layered by the race window; `mountRaceDataPanel()` remains available for hosts that intentionally want the banner as a standalone surface. `raceDataTelemetryDetail: true` makes the project lower-third include a compact S1/S2/S3 sector strip; radio mode stays the same and the standalone `mountTelemetrySectorBanner()` surface remains available only when a host explicitly mounts it. `includeTimingTower: true` embeds the timing tower directly inside the race canvas and reserves camera space from the measured tower gutter when the tower is a side overlay. In narrow mobile hosts, package CSS stacks the embedded timing tower full-width and the camera stops reserving a fake left gutter. `mountRaceTelemetryDrawer()` is a higher-level template that mounts the race canvas, embedded timing tower, lower-third, safety-car control, and a right telemetry drawer together; pass `{ raceDataTelemetryDetail: true }` when the drawer lower-third should include compact sector detail. Opening the drawer reduces the race area instead of overlaying it, and closing it removes the drawer from interaction. `raceDataBanners.initial` selects the starting banner state (`'project'`, `'radio'`, or `'hidden'`), while `raceDataBanners.enabled` chooses which banner types may appear. `raceDataBannerSize: 'auto'` uses the race space to the right of the timing board when it is wide enough and falls back to the full lower-third overlap when it is not; `'custom'` preserves the default CSS-variable-driven lower-third size for hosts that want to tune their own banner geometry. `timingTowerVerticalFit: 'expand-race-view'` lets the race window grow tall enough for the tower; `'scroll'` keeps the race window height and scrolls the timing list inside the cropped tower. The same fit values can be passed to `mountRaceCanvas()` when `includeTimingTower` is enabled. Standalone timing towers are capped by `--timing-board-max-width` and fill their mount root height; placing the root in a fixed-height container makes only the timing entries scroll. Timing entries always stack from the top as fixed rows, so P1/P2 occupy the same vertical positions whether the race has 2 cars or 20. The timing tower includes an `Int`/`Gap` broadcast switch: `Int` shows the interval to the car ahead, while `Gap` shows total gap to the leader. `cameraControls: 'external'` moves view controls out of the canvas so hosts can mount them with `mountCameraControls()`. `showFps: false` hides the FPS readout. `telemetryIncludesOverview: false` keeps the car/driver overview out of the telemetry stack so hosts can mount `mountCarDriverOverview()` separately. `telemetryModules` controls optional package-owned telemetry surfaces: `core`, `sectors`, `lapTimes`, and `sectorTimes`; those same surfaces are also available as fully detached mount methods.
+
+### Composable overlay layout contract
+
+`ui.layoutPreset: 'left-tower-overlay'` is package-owned. Hosts should not recreate or depend on internal shell classes such as `.sim-shell--left-tower-overlay` or `.sim-grid` as their public integration contract.
 
-`layoutPreset: 'left-tower-overlay'` creates a left broadcast gutter inside the race view, frames the camera around the remaining race area, and places the timing tower in that gutter without covering camera controls. The project/radio lower-third stays inside the race window and can intentionally render over the timing sidebar instead of shrinking around it. Composable hosts should pass `{ includeRaceDataPanel: true }` to `mountRaceCanvas()` when they want that lower-third clipped and layered by the race window; `mountRaceDataPanel()` remains available for hosts that intentionally want the banner as a standalone surface. `includeTimingTower: true` embeds the timing tower directly inside the race canvas and reserves camera space from the measured tower gutter. `raceDataBanners.initial` selects the starting banner state (`'project'`, `'radio'`, or `'hidden'`), while `raceDataBanners.enabled` chooses which banner types may appear. `raceDataBannerSize: 'auto'` uses the race space to the right of the timing board when it is wide enough and falls back to the full lower-third overlap when it is not; `'custom'` preserves the default CSS-variable-driven lower-third size for hosts that want to tune their own banner geometry. `timingTowerVerticalFit: 'expand-race-view'` lets the race window grow tall enough for the tower; `'scroll'` keeps the race window height and scrolls the timing list inside the cropped tower. The same fit values can be passed to `mountRaceCanvas()` when `includeTimingTower` is enabled. Standalone timing towers are capped by `--timing-board-max-width` and fill their mount root height; placing the root in a fixed-height container makes only the timing entries scroll. Timing entries always stack from the top as fixed rows, so P1/P2 occupy the same vertical positions whether the race has 2 cars or 20. The timing tower includes an `Int`/`Gap` broadcast switch: `Int` shows the interval to the car ahead, while `Gap` shows total gap to the leader. `cameraControls: 'external'` moves view controls out of the canvas so hosts can mount them with `mountCameraControls()`. `showFps: false` hides the FPS readout. `telemetryIncludesOverview: false` keeps telemetry text-only so hosts can mount `mountCarDriverOverview()` separately.
+For the all-in-one simulator, call `mountF1Simulator()` and let PaddockJS generate the shell. For composable layouts, hosts should provide mount roots and call package mount methods such as `mountRaceCanvas(root, { includeTimingTower: true, includeRaceDataPanel: true })` or `mountRaceTelemetryDrawer(root)`. Host CSS may size the outer container, but timing-tower placement, gutter measurement, camera safe area, and narrow-screen stacking are owned by PaddockJS.
 
 Mounted package surfaces include a lightweight red start-light loading overlay. The runtime removes each overlay after PixiJS, assets, controls, and the initial readouts are ready.
 
 The runtime also pauses its render ticker when the race canvas is offscreen or the browser tab is hidden. This keeps pages with multiple PaddockJS embeds responsive without requiring host code to manually start and stop each simulator.
 
-Lifecycle callbacks are optional and host-owned. PaddockJS emits `onLoadingChange`, `onReady`, `onError`, `onDriverSelect`, `onRaceEvent`, `onLapChange`, and `onRaceFinish`; callback errors are routed to `onError` when provided and do not stop the simulator loop. Race snapshots include per-car interval timing, leader-gap timing, calibrated `speedKph`, finish state, `raceControl.winner` after the first finisher, and final `raceControl.classification` only after the whole field finishes. The field then circulates in safety-car mode and the race canvas shows a package-owned winner banner.
+Lifecycle callbacks are optional and host-owned. PaddockJS emits `onLoadingChange`, `onReady`, `onError`, `onDriverSelect`, `onRaceEvent`, `onLapChange`, and `onRaceFinish`; callback errors are routed to `onError` when provided and do not stop the simulator loop. Race snapshots include per-car interval timing, leader-gap timing, calibrated `speedKph`, automatic `track.sectors`, per-car `lapTelemetry`, finish state, `raceControl.winner` after the first finisher, and final `raceControl.classification` only after the whole field finishes. The field then circulates in safety-car mode and the race canvas shows a package-owned winner banner.
 
 ## License
 

package/docs/architecture.md

@@ -48,13 +48,36 @@ host page
   -> simulator.mountSafetyCarControl(safetyCarRoot)
   -> simulator.mountTimingTower(timingRoot)
   -> simulator.mountRaceCanvas(canvasRoot, { includeRaceDataPanel })
-  -> simulator.mountTelemetryPanel(telemetryRoot)
+  -> simulator.mountTelemetryCore(coreTelemetryRoot)
+  -> simulator.mountTelemetrySectors(sectorGraphRoot)
+  -> simulator.mountTelemetrySectorBanner(sectorBannerRoot)
+  -> simulator.mountTelemetryLapTimes(lapTimesRoot)
+  -> simulator.mountTelemetrySectorTimes(sectorTimesRoot)
+  -> simulator.mountRaceTelemetryDrawer(raceWorkbenchRoot) [optional template alternative]
   -> simulator.mountRaceDataPanel(raceDataRoot) [optional standalone alternative]
   -> simulator.start()
   -> new F1SimulatorApp(compositeRoot, resolvedOptions)
   -> PixiJS render loop + DOM readout updates
 ```
 
+Headless environment flow:
+
+```txt
+training script
+  -> import from @inventure71/paddockjs/environment
+  -> createPaddockEnvironment(options)
+  -> resolveEnvironmentOptions(options)
+  -> createRaceSimulation(...)
+  -> env.reset()
+  -> env.step(actions)
+  -> resolveActionMap(actions)
+  -> RaceSimulation.step(...) repeated by frameSkip
+  -> buildEnvironmentObservation(...)
+  -> optional reward(context)
+```
+
+Browser expert mode reuses the same environment runtime around the visual app's existing `RaceSimulation` instance. When `expert.enabled` is true, the visual ticker does not advance simulation time automatically; `simulator.expert.reset()` and `simulator.expert.step(actions)` are the only simulation-advance entry points.
+
 ## Public Entry
 
 `src/index.js` is the public package entry.
@@ -70,6 +93,18 @@ Responsibilities:
 - Return the controller methods.
 - Re-export the composable mount API.
 
+`src/index.js` does not export the headless environment API. Training and automation code imports `@inventure71/paddockjs/environment`, which resolves to `src/environment/index.js`.
+
+`src/environment/` owns the browser-free expert environment:
+
+- `index.js` and `index.d.ts` expose the public subpath API.
+- `runtime.js` owns environment-loop `reset()`, `step(actions)`, `getObservation()`, and `getState()` around an injected race-simulation host.
+- `options.js` validates `controlledDrivers`, scenario participants, frame skip, action policy, sensor config, and episode limits.
+- `actions.js` maps normalized public controls onto simulator steering/throttle/brake controls.
+- `observations.js`, `sensors.js`, and `events.js` build sensor-style observations, fixed-schema vectors, ray/nearby-car readings, and global/per-driver events.
+
+The environment subpath must not import `src/index.js`, package CSS, PixiJS, `F1SimulatorApp`, or DOM-specific code.
+
 `src/api/PaddockSimulatorController.js` owns composable mounting.
 
 Responsibilities:
@@ -99,8 +134,12 @@ Responsibilities:
 - Race data panel rendering.
 - Safety car button.
 - Multiple package-rendered safety-car buttons bound to one simulation state.
-- Restart behavior.
-- Lifecycle cleanup.
+- Restart behavior for race data, seed, and track changes. Asset URL changes and browser expert mode changes are intentionally outside restart because texture loading and ticker ownership are part of initialization.
+- Lifecycle cleanup, including partial-init failure cleanup and destruction of replaced PixiJS display children without destroying shared textures.
+
+When `options.expert.enabled` is true, `F1SimulatorApp` creates a narrow browser expert adapter around its existing `this.sim` race simulation. The adapter uses the same shared environment runtime as the headless API, but it must not create a second race simulation for the visual mount. Expert browser mounts disable automatic ticker-driven simulation advancement; the canvas updates only after `simulator.expert.reset()` or `simulator.expert.step(actions)` renders the new snapshot. Expert mode is a mount-time boundary; runtime restart rejects `expert` changes instead of attempting to rewire ticker ownership in place.
+
+Expert sensor visualization belongs to the browser app layer, not the headless environment. The environment result owns the observation contract; `BrowserExpertAdapter` passes that observation into `F1SimulatorApp.renderExpertFrame()`, and `F1SimulatorApp` draws opt-in sensor rays in a Pixi world layer so they share the same camera transform as the track and cars.
 
 This file is still large. When changing it substantially, prefer extracting cohesive modules rather than adding unrelated responsibilities.
 
@@ -118,6 +157,7 @@ Responsibilities:
 - Car creation.
 - Race ordering.
 - Lap calculation.
+- Per-car lap and sector telemetry.
 - Timing history.
 - DRS eligibility.
 - Collision response.
@@ -127,13 +167,13 @@ Responsibilities:
 
 `src/simulation/vehiclePhysics.js` owns vehicle integration and surface physics.
 
-`src/simulation/trackModel.js` owns track construction, procedural track generation, DRS zones, and nearest-track queries. Browser mounts generate a fresh procedural seed when `trackSeed` is omitted; explicit procedural track seeds are cached so repeated mounts with the same seed do not regenerate or rebuild the same model.
+`src/simulation/trackModel.js` owns track construction, procedural track generation, automatic three-sector metadata, DRS zones, and nearest-track queries. Browser mounts generate a fresh procedural seed when `trackSeed` is omitted; explicit procedural track seeds are cached so repeated mounts with the same seed do not regenerate or rebuild the same model.
 
 `src/simulation/units.js` owns conversion between simulator units and public meter/km/h display values. Physics stays in simulator units; snapshots expose calibrated display fields such as `speedKph`, `distanceMeters`, and `gapMeters`.
 
 `src/rendering/renderSnapshot.js` owns interpolation for rendering.
 
-The app runtime pauses its PixiJS ticker when the race canvas is outside the viewport or the document is hidden, then resets the frame clock before resuming. This prevents host pages with several simulator embeds from running every race while only one is visible, and avoids a large simulation catch-up step when the canvas re-enters view. Camera safe-area layout measurements are cached and invalidated by resize observation so the 60 FPS render path does not force repeated DOM geometry reads. Long project-radio delays are also treated as stale schedule state instead of replaying every missed lower-third transition.
+The app runtime pauses its PixiJS ticker when the race canvas is outside the viewport or the document is hidden, then resets the frame clock before resuming. This prevents host pages with several simulator embeds from running every race while only one is visible, and avoids a large simulation catch-up step when the canvas re-enters view. Camera safe-area layout measurements are cached and invalidated by resize observation so the 60 FPS render path does not force repeated DOM geometry reads. Runtime readouts avoid redundant DOM writes for unchanged text, timing markup, finish classification, and static selected-car overview data. Long project-radio delays are also treated as stale schedule state instead of replaying every missed lower-third transition.
 
 ## Data Layer
 
@@ -141,9 +181,9 @@ The app runtime pauses its PixiJS ticker when the race canvas is outside the vie
 
 `src/data/vehicleData.js` converts vehicle rating sheets into physical setup values.
 
-`src/data/championship.js` pairs drivers with entries and generates timing codes, numbers, team metadata, and converted constructor data.
+`src/data/championship.js` pairs drivers with entries and generates timing codes, numbers, team metadata, and converted constructor data. It rejects duplicate entry driver IDs, ignores omitted driver numbers during uniqueness checks, and falls back to stable grid-order numbers when host entries do not provide numbers.
 
-`src/data/normalizeDrivers.js` validates host driver data and invokes championship pairing.
+`src/data/normalizeDrivers.js` validates host driver data, rejects duplicate driver IDs before runtime maps are created, and invokes championship pairing.
 
 `src/data/demoDrivers.js` is demo/portfolio-flavored sample data. It should not become the only supported data path.
 
@@ -156,13 +196,16 @@ The app runtime pauses its PixiJS ticker when the race canvas is outside the vie
 - Safety-car control.
 - Timing tower.
 - Race canvas.
-- Race-data panel.
-- Telemetry panel.
+- Race-data panel, including the optional project telemetry detail variant.
+- Telemetry stack template.
+- Detached telemetry core, sector graph, lap-time table, and sector-time table.
+- Broadcast sector banner.
+- Race telemetry drawer template.
 - Car/driver overview panel.
 
-`src/ui/shellTemplate.js` composes those component templates into the default all-in-one simulator DOM and package-owned layout presets such as `left-tower-overlay`. The telemetry panel can embed the car/driver overview, but the overview is also a separately mountable package-owned component. The left-tower overlay preset is responsible for internal component placement and package-owned proportions; the project/radio lower-third remains owned by the race canvas so it can either use the race space beside the timing tower in `auto` sizing mode or overlap the tower when space is constrained. Composable hosts can also ask the race-canvas template to embed the timing tower directly with `includeTimingTower`, using the same expand-vs-scroll vertical fit contract. `F1SimulatorApp` measures the resulting timing-tower gutter when framing the PixiJS camera, whether the tower comes from the prebuilt shell or from an embedded composable race canvas. Hosts should not provide the internal simulator markup or tune preset internals with raw sizing options.
+`src/ui/shellTemplate.js` composes those component templates into the default all-in-one simulator DOM and package-owned layout presets such as `left-tower-overlay`. Telemetry graph/table surfaces are independent package-owned components controlled by `ui.telemetryModules` when used through stack/drawer templates; the app renders them from `car.lapTelemetry` without requiring host-owned DOM. The telemetry stack can embed the car/driver overview, but the overview is also a separately mountable package-owned component. The broadcast sector banner is a separate lower-third-style sector graph that can be mounted standalone or embedded inside the race canvas only when a host explicitly asks for that independent popup; `F1SimulatorApp` binds the selected car name/code/color to it through the same readout path as the other telemetry surfaces. The race telemetry drawer template composes a race canvas with embedded timing tower, project/radio lower-third, safety-car control, and detached telemetry components in a right drawer. Its open/close state is owned by `F1SimulatorApp`; the safety-car control remains available while telemetry is open. The drawer reserves final race-view space with a stable margin while the sidebar itself animates with a compositor transform, avoiding grid-template reflow during the slide. The drawer race area inherits the workbench height so host embeds do not leave unused black space below the simulation. The left-tower overlay preset is responsible for internal component placement and package-owned proportions; the project/radio lower-third remains owned by the race canvas so it can either use the race space beside the timing tower in `auto` sizing mode or overlap the tower when space is constrained. Composable hosts can also ask the race-canvas template to embed the timing tower directly with `includeTimingTower`, using the same expand-vs-scroll vertical fit contract. `F1SimulatorApp` measures the resulting timing-tower gutter when framing the PixiJS camera, whether the tower comes from the prebuilt shell or from an embedded composable race canvas. On narrow hosts, CSS stacks timing boards full-width and the camera safe-area measurement treats those boards as stacked content instead of side gutters. Hosts should not provide the internal simulator markup or tune preset internals with raw sizing options.
 
-`src/config/defaultOptions.js` owns preset resolution and the public theme contract. Presets are merged before host options; theme fields are applied as package CSS variables by the all-in-one app and composable controller. This keeps sizing/color customization explicit without turning internal layout ratios into public API.
+`src/config/defaultOptions.js` owns preset resolution, telemetry module normalization, and the public theme contract. Presets are merged before host options; theme fields are applied as package CSS variables by the all-in-one app and composable controller. This keeps sizing/color customization explicit without turning internal layout ratios into public API.
 
 Race completion is owned by `src/simulation/raceSimulation.js`. The app layer reads `raceControl.finished`, `winner`, and `classification` from snapshots, renders the winner banner, and emits lifecycle callbacks. UI code must not infer finish state from lap text or timing rows.
 
@@ -191,6 +234,7 @@ Current coverage includes:
 - Championship metadata.
 - Component API and callback behavior.
 - Driver controller behavior.
+- Expert environment actions, observations, rewards, events, and browser adapter behavior.
 - Procedural track rendering helpers.
 - Race simulation rules.
 - Render interpolation.

package/docs/concepts.md

@@ -131,6 +131,10 @@ Progress is the wrapped distance around the current lap.
 
 Race distance is cumulative and can increase beyond one lap. Ranking uses race distance, not wrapped progress.
 
+## Sectors
+
+Every built track is divided into three equal sectors, published as `track.sectors`. Sector timing is derived from cumulative race distance crossing those sector boundaries, not from UI state.
+
 ## Snapshot
 
 A snapshot is the read-only state returned by the race simulation and exposed through `getSnapshot()`.
@@ -146,7 +150,7 @@ Snapshots include:
 - Events from the last step.
 - Ordered cars with telemetry and setup data.
 
-Per-car timing exposes both interval to the car ahead and cumulative gap to the leader. Per-car speed and distance display fields are calibrated through the simulator unit conversion helpers instead of treating rendered world units as meters.
+Per-car timing exposes both interval to the car ahead and cumulative gap to the leader. Per-car `lapTelemetry` exposes current lap, current sector, current/last/best lap times, current/last/best sector times, sector progress, and sector performance status. Sector performance status marks completed sector times as `overall-best`, `personal-best`, or `slower`, which drives the purple/green/yellow timing colors in sector graphs and tables. Per-car speed and distance display fields are calibrated through the simulator unit conversion helpers instead of treating rendered world units as meters.
 
 ## Render Snapshot