> ## Documentation Index
> Fetch the complete documentation index at: https://playbook.smedleygroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Race History

> The classic whole-field gap-to-leader-average trace over the race, race sessions only.

## Overview

Race History plots every driver's running gap to a moving, period-aware leader baseline across the whole race distance. It is the widget for reading how the field's pace spread out over a race, including how a safety car compressed or scattered it.

> [!NOTE]
>
> Race-only. Outside a race, or before the session type resolves, this widget shows an explicit notice instead of an in-race empty state.

***

## What It Shows

![Race History mid-race with GPS-style driver tags on every trace (Singapore 2026 Race, lap 40)](https://mintcdn.com/smedley_group/1sk8-0h-JRH4PrIf/images/watchparty/race-history.png?fit=max\&auto=format\&n=1sk8-0h-JRH4PrIf\&q=85\&s=c74970358c90413300328e05e4ad7a2e)

One line per driver with at least one completed timed lap, in team colour (dashed for the second of two team-mates). The x-axis is fixed to the full race length in laps, with a major gridline every five laps and a minor one at every lap, so it never rescales as the race unfolds. The y-axis, "Gap to leader average \[s]", is drawn inverted, so a driver running ahead of the leader's own average pace reads upward.

| Element | Meaning |
| - | - |
| Driver tag | A GPS-callout-style chip (car number and driver code) pinned to the end of each trace, so the running order reads at a glance without tracing back to the legend |
| Translucent boxes | Safety car, virtual safety car, and red-flag periods, drawn behind the traces |

![Race History zoomed to laps 23 to 40 with a right-drag box (Singapore 2026 Race)](https://mintcdn.com/smedley_group/1sk8-0h-JRH4PrIf/images/watchparty/race-history-zoom.png?fit=max\&auto=format\&n=1sk8-0h-JRH4PrIf\&q=85\&s=afdd11bd1abe2aca4c06fc203f137cbf)

**Zooming.** Right-drag across the plot to draw a box, and on release the chart zooms both axes to it, as above. The drag carries on if the pointer leaves the plot or the chart, and the zoom lands at the last point inside the plot when you let go. A right-click without moving opens a small menu with **Reset zoom**, which returns the chart to the whole race. Left-drag is unchanged and there are no zoom sliders. While zoomed, each driver tag moves to the last lap still in view, so everyone on screen stays labelled.

**Baseline**: each lap's contribution is that lap's time minus the leader's own mean lap time within the current period, not one flat race-wide average, so the field reads condensed during a neutralisation instead of drifting away from a stale pre-neutralisation baseline. The leader's own trace therefore averages to roughly zero within every period.

**Sub-races.** A red flag, and a virtual safety car lasting two or more of the leader's laps, each become their own sub-race: they split the green periods either side of them and take the leader's own lap time as a **per-lap** reference rather than one period-wide mean. A short VSC does not split; its box is still drawn behind the traces, it simply stays inside the surrounding period's mean. The red-flag box spans every affected lap, including the restart procedure, and the box and the maths read the same periods, so they can never disagree about which laps were affected.

The current leader is whichever driver the tower's own race ordering currently has out front, not a fixed driver for the session.

> [!WARNING]
>
> This widget always plots raw lap times. It has no fuel-corrected toggle, unlike Lap Times and the Laps table.

***

## Data Behind It

Race History is built entirely client-side (`buildRaceHistoryOption`) from lap rows already hydrated through the `laps` REST endpoint and the `laps`/`timing` WebSocket channels, plus `race_control` for the safety-car/VSC/red-flag period boxes. It consumes no dedicated insight of its own.

***

## States

| State | Behaviour |
| - | - |
| Not a race | Shows "Session is not a race." |
| No completed lap yet | Shows "No completed laps yet." |
| Lap-time coverage incomplete | Shows "Laptimes missing" for the **whole** widget |
| Live vs replay | Wire-identical; the widget never branches on envelope source |

> [!WARNING]
>
> The lap-time coverage rule is deliberately strict: because each driver's y-value is a running cumulative sum, a single missing lap time before that driver's last timed lap would silently corrupt every later point on their line. If any plotted driver has a gap in their own timed-lap sequence up to their own last timed lap, the whole widget shows "Laptimes missing" rather than a partially wrong chart.

***

## Next Steps

> **[Timing Tower](/software/internal/watchparty/widgets/timing-tower)**
>
> The running order this chart's leader baseline is drawn from.

> **[Lap Times](/software/internal/watchparty/widgets/lap-times)**
>
> Compare a chosen few drivers' pace directly, with a fuel-corrected toggle.

> **[Predicted Race History](/software/internal/watchparty/strategy/predicted-race-history)**
>
> The strategy engine's forward-looking counterpart, re-baselined into the same gap frame.

> **[Data Journey](/software/internal/watchparty/concepts/data-journey)**
>
> How live and replay laps reach the browser identically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.