@inventure71/paddockjs 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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/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.
+This folder is the extractable F1 simulator component. It owns the simulator source, bundled simulator assets, CSS, demo data, and the public mount API. 
 
 ## Install
 
@@ -28,6 +28,7 @@ The repo now includes the full package-release boundary:
 - 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:
 
@@ -95,8 +96,13 @@ simulator.mountSafetyCarControl(document.getElementById('sim-safety-car'));
 simulator.mountTimingTower(document.getElementById('sim-timing'));
 simulator.mountRaceCanvas(document.getElementById('sim-race'), {
   includeRaceDataPanel: true,
+  includeTelemetrySectorBanner: 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();
@@ -108,10 +114,19 @@ The race canvas can also own the timing tower when a host wants a single reusabl
 simulator.mountRaceCanvas(document.getElementById('sim-race'), {
   includeTimingTower: true,
   includeRaceDataPanel: true,
+  includeTelemetrySectorBanner: true,
   timingTowerVerticalFit: 'scroll',
 });
 ```
 
+For a packaged race-window template with a right-side telemetry drawer:
+
+```js
+simulator.mountRaceTelemetryDrawer(document.getElementById('sim-race-workbench'), {
+  timingTowerVerticalFit: 'expand-race-view',
+});
+```
+
 `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:
@@ -139,6 +154,7 @@ ui: {
   cameraControls: 'external',
   showFps: false,
   telemetryIncludesOverview: false,
+  telemetryModules: ['core', 'sectors', 'lapTimes', 'sectorTimes'],
   raceDataBanners: {
     initial: 'project',
     enabled: ['project', 'radio'],
@@ -152,13 +168,13 @@ ui: {
 
 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.
 
-`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.
+`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 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, safety-car control, lower-third, and a right telemetry drawer together; 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.
 
 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,7 +48,12 @@ 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)
@@ -118,6 +123,7 @@ Responsibilities:
 - Car creation.
 - Race ordering.
 - Lap calculation.
+- Per-car lap and sector telemetry.
 - Timing history.
 - DRS eligibility.
 - Collision response.
@@ -127,13 +133,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
 
@@ -157,12 +163,15 @@ The app runtime pauses its PixiJS ticker when the race canvas is outside the vie
 - Timing tower.
 - Race canvas.
 - Race-data panel.
-- Telemetry panel.
+- 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; `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, safety-car control, lower-third, sector banner, and detached telemetry components in a right drawer; the drawer's open/close state and safety-car button are owned by `F1SimulatorApp`. 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.
 

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
 

package/docs/data_contract.md

@@ -54,6 +54,7 @@ const simulator = createPaddockSimulator({
 simulator.mountRaceCanvas(canvasRoot, {
   includeRaceDataPanel: true,
   includeTimingTower: true,
+  includeTelemetrySectorBanner: true,
   timingTowerVerticalFit: 'scroll',
 });
 await simulator.start();
@@ -67,10 +68,45 @@ 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',
+});
 simulator.mountCarDriverOverview(overviewRoot);
 simulator.mountRaceDataPanel(raceDataRoot);
 ```
 
+## 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.
@@ -253,6 +289,13 @@ ui: {
   showFps: true,
   showTimingTower: true,
   showTelemetry: true,
+  telemetryIncludesOverview: true,
+  telemetryModules: {
+    core: true,
+    sectors: true,
+    lapTimes: true,
+    sectorTimes: true,
+  },
   showRaceDataPanel: true,
   raceDataBanners: {
     initial: 'project',
@@ -268,12 +311,14 @@ 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.
 - `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 +360,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
 
@@ -352,7 +429,12 @@ Composable controllers additionally expose:
 - `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`.
+- `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.
 - `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/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

@@ -73,9 +73,18 @@ simulator.mountTimingTower(timingRoot);
 simulator.mountRaceCanvas(canvasRoot, {
   includeRaceDataPanel: true,
   includeTimingTower: true,
+  includeTelemetrySectorBanner: true,
   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',
+});
 
 await simulator.start();
 ```
@@ -88,9 +97,16 @@ mountTimingTower(root, simulator);
 mountRaceCanvas(root, simulator, {
   includeRaceDataPanel: true,
   includeTimingTower: true,
+  includeTelemetrySectorBanner: true,
   timingTowerVerticalFit: 'scroll',
 });
 mountTelemetryPanel(root, simulator);
+mountTelemetryCore(root, simulator);
+mountTelemetrySectors(root, simulator);
+mountTelemetrySectorBanner(root, simulator);
+mountTelemetryLapTimes(root, simulator);
+mountTelemetrySectorTimes(root, simulator);
+mountRaceTelemetryDrawer(root, simulator);
 mountRaceDataPanel(root, simulator);
 ```
 
@@ -103,8 +119,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 }),
   mountRaceDataPanel(root),
   start(),
 
@@ -131,18 +153,20 @@ 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`.
 - 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. `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.
 - 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.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.
 - `onDriverOpen(driver)` is the navigation boundary.
@@ -153,7 +177,7 @@ Returned controller:
 - 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.
 
 ## Current Visible Features
 
@@ -169,7 +193,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "A data-driven browser F1 simulator component for project portfolios.",
   "license": "Apache-2.0",

package/src/api/PaddockSimulatorController.js

@@ -5,8 +5,14 @@ import {
   createRaceCanvasMarkup,
   createRaceControlsMarkup,
   createRaceDataPanelMarkup,
+  createRaceTelemetryDrawerMarkup,
   createSafetyCarControlMarkup,
+  createTelemetryCoreMarkup,
+  createTelemetryLapTimesMarkup,
   createTelemetryPanelMarkup,
+  createTelemetrySectorBannerMarkup,
+  createTelemetrySectorTimesMarkup,
+  createTelemetrySectorsMarkup,
   createTimingTowerMarkup,
 } from '../ui/componentTemplates.js';
 import { applyPaddockThemeCssVariables, resolveF1SimulatorOptions } from '../config/defaultOptions.js';
@@ -117,18 +123,44 @@ export class PaddockSimulatorController {
   mountRaceCanvas(root, {
     includeRaceDataPanel = false,
     includeTimingTower = false,
+    includeTelemetrySectorBanner = false,
     timingTowerVerticalFit,
   } = {}) {
     return this.mountComponent(root, 'race-canvas', createRaceCanvasMarkup({
       ...this.options,
       includeRaceDataPanel,
       includeTimingTower,
+      includeTelemetrySectorBanner,
       timingTowerVerticalFit,
     }));
   }
 
   mountTelemetryPanel(root, { includeOverview } = {}) {
-    return this.mountComponent(root, 'telemetry-panel', createTelemetryPanelMarkup(this.options, { includeOverview }));
+    return this.mountComponent(root, 'telemetry-stack', createTelemetryPanelMarkup(this.options, { includeOverview }));
+  }
+
+  mountTelemetryCore(root) {
+    return this.mountComponent(root, 'telemetry-core', createTelemetryCoreMarkup(this.options));
+  }
+
+  mountTelemetrySectors(root) {
+    return this.mountComponent(root, 'telemetry-sectors', createTelemetrySectorsMarkup(this.options));
+  }
+
+  mountTelemetryLapTimes(root) {
+    return this.mountComponent(root, 'telemetry-lap-times', createTelemetryLapTimesMarkup(this.options));
+  }
+
+  mountTelemetrySectorTimes(root) {
+    return this.mountComponent(root, 'telemetry-sector-times', createTelemetrySectorTimesMarkup(this.options));
+  }
+
+  mountTelemetrySectorBanner(root) {
+    return this.mountComponent(root, 'telemetry-sector-banner', createTelemetrySectorBannerMarkup(this.options));
+  }
+
+  mountRaceTelemetryDrawer(root, options = {}) {
+    return this.mountComponent(root, 'race-telemetry-drawer', createRaceTelemetryDrawerMarkup(this.options, options));
   }
 
   mountCarDriverOverview(root) {
@@ -228,6 +260,30 @@ export function mountTelemetryPanel(root, simulator, options) {
   return simulator.mountTelemetryPanel(root, options);
 }
 
+export function mountTelemetryCore(root, simulator) {
+  return simulator.mountTelemetryCore(root);
+}
+
+export function mountTelemetrySectors(root, simulator) {
+  return simulator.mountTelemetrySectors(root);
+}
+
+export function mountTelemetryLapTimes(root, simulator) {
+  return simulator.mountTelemetryLapTimes(root);
+}
+
+export function mountTelemetrySectorTimes(root, simulator) {
+  return simulator.mountTelemetrySectorTimes(root);
+}
+
+export function mountTelemetrySectorBanner(root, simulator) {
+  return simulator.mountTelemetrySectorBanner(root);
+}
+
+export function mountRaceTelemetryDrawer(root, simulator, options) {
+  return simulator.mountRaceTelemetryDrawer(root, options);
+}
+
 export function mountRaceDataPanel(root, simulator) {
   return simulator.mountRaceDataPanel(root);
 }