> ## 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.

# Pit Window

> A live 60-second gap bar centred on a reference driver, for judging a pit stop against the cars around them right now.

## Overview

The Pit Window widget (registry id `pitwindow`, built by `PitWindowBar`) is a horizontal bar centred on a reference driver you choose in the widget itself. It plots every car within 30 seconds of that driver's on-track gap, so an engineer can read at a glance who a pit stop would drop the reference driver behind, or who it might jump.

> [!NOTE]
>
> This is a live gap picture, not a forecast. For a modelled prediction of when and where a stop should happen, see [Predicted Pit Window and SC](/software/internal/watchparty/strategy/predicted-pit-window) in the Strategy suite, a separate widget built on the strategy engine.

***

## Choosing the reference driver

The reference driver comes from the **Reference** dropdown in the widget's own header, and from nothing else. It opens on the race leader as of the playhead and lists every car in the timing tower's running order, so the list reads the way the tower does.

The timing tower's own selection does not feed this widget. Selecting a driver in the tower changes the comparison chart and the other selection-driven widgets, and leaves the pit window exactly where you put it. The choice clears when you change session, so a car number cannot leak from one weekend into another, and the dropdown stays reachable in the empty state, so a reference driver with no measurable position is never a dead end.

***

## What It Shows

![The Pit Window bar centred on VER in P1, with every other car to the left of the reference line and the pit-loss bands either side (Singapore 2026, lap 42)](https://mintcdn.com/smedley_group/mBbZR7MlEHu8vHdi/images/watchparty/pit-window.png?fit=max\&auto=format\&n=mBbZR7MlEHu8vHdi\&q=85\&s=e65f1b92b723f3acb267410ff877482e)

The bar spans 60 seconds, the reference driver fixed at the centre (0s).

| Element | Encoding |
| - | - |
| Direction | The higher a car's track position, the further **right** it sits. Ahead (negative) draws to the right of the reference and behind (positive) to the left, so with P1 as the reference every other car is on the left. The axis reads +30 at the left edge to −30 at the right |
| Reference driver | A thin white vertical line at 0s, which is what every other car is read against |
| Every car | A TLA chip in the GPS map's callout style: near-black, a team-coloured border, white mono text. No car carries a coloured rule of its own |
| Tyre and stops | A disc on the chip's top-left corner, filled with the car's current compound, carrying the number of stops it has already made |
| Chip position | Resting on the axis by default, raised a lane only when it would otherwise overprint a neighbour |
| Stalks | A thin leader down to the axis, drawn only under a chip that had to be raised |
| Major ticks | Every 5 seconds, taller, with the axis's only labels |
| Minor ticks | Every 1 second, short, unlabelled |
| Pit-loss reference lines | Up to three dashed pairs, GREEN, SC and VSC, marking where the reference driver would rejoin if they pitted under each condition; each carries a ±0.5 second uncertainty band |

Only cars within the 30-second window either side of the reference are drawn; anything further away is simply not on the bar.

### Reading the chips

The chips are the cars. Since there are no per-driver rules, a car's gap is read from where its chip sits against the axis, measured from the white line at 0s.

Two rules keep that honest when the field is tight or a car is at the very edge of the window:

* **A chip only leaves the axis to avoid a collision.** Labels are assigned to lanes, and a chip climbs only as far as it must to clear the ones already placed. When it does climb, it takes a stalk down to the axis, which is what keeps it attributable to its own gap. A car with room around it always sits flat on the axis with no stalk.
* **A chip at the edge slides inward rather than being clipped.** A car at ±30 seconds sits at the very end of the bar, where a centred chip would hang half its width off the widget. The chip slides just far enough to stay whole. Only the label moves; the gap it reports is unchanged.

### The tyre disc

The disc is centred on the chip's top-left corner, so three quarters of it sits outside the box. Its fill is the compound the car is currently running, using the same tyre colour tokens as every other widget, and the number printed on it is how many stops that driver has already made. The digit's colour is a per-compound token paired to the fill, so it stays legible in both the dark and the light theme.

A compound that the source has not resolved yet gets the neutral fill and **still shows its number**. The stop count is known and true whether or not the tyre is, so this case is never a "?".

Both values come from the same sources the rest of the app uses, never re-derived here: the compound from the driver's latest as-of lap through the shared `compoundForLap`, which means a manual compound override wins here exactly as it does in the timing tower, and the stop count from the Pit Stops table's own `buildStopsTable`.

### The pit-loss reference lines

**The reference lines are strategy-sourced.** They come from the as-of strategy snapshot's own resolved `pit_loss` block, so they are the round's real modelled pit losses rather than a hard-coded constant. The SC and VSC pairs use the app's usual safety-car colour tokens.

The widget captions exactly what it has:

| Situation | Caption |
| - | - |
| No strategy snapshot at this lap yet | "Pit loss: no prediction at this lap yet", no lines drawn |
| A snapshot that predates the strategy wrapper b1.6.0 | "Pit loss: not in this snapshot (strategy b1.6.0+)", no lines drawn |
| A snapshot with no VSC pair for the round | GREEN and SC pairs drawn, plus "VSC loss: not supplied for this round" |
| A resolved value beyond the bar's own ±30 second span | That pair is left off the bar and reported in its own out-of-range caption, never silently dropped |

***

## Data Behind It

The bar itself is client-derived; its reference lines are not. `screens/derive.ts`'s `buildPitWindowData` is a pure function of the hydrated race state, the drivers map, the reference driver, the playhead cutoff, the as-of pit-loss block and the shared compound-override index:

* Each car's gap is the timing tower's own gap to the leader, taken from the tower's entries as they stand, so the two widgets always show the same numbers, live or in replay. The leader (P1) is pinned to 0s. A car's relative gap to the reference is the difference of the two gaps-to-leader. A lapped car, a car showing OUT and a car with no time are left off the bar.
* The sign convention is unchanged and independent of the drawing: positive means behind the reference, negative means ahead. Which side of the bar each sign draws on is the component's business, and since 20 October 2026 ahead draws on the right, so the better a car's position the further right it sits.
* The pit-loss lines come from the strategy snapshot as of the playhead, resolved by `strategyDerive.pitLossAsOf`. The widget therefore reads `strategy_snapshot` while, and only while, a pit loss is actually drawn on the bar.
* The constants `PIT_WINDOW_HALF_SPAN_S` (30) and `PIT_WINDOW_PIT_UNCERTAINTY_S` (0.5) live in `screens/derive.ts`. The uncertainty band is a fixed display affordance, not a parameter.
* The axis is generated from `PIT_WINDOW_HALF_SPAN_S` rather than written out, so it cannot end up describing a window the bar no longer draws.
* The underlying laps, stints and pit rows hydrate the same way as the timing tower: `GET /v1/sessions/{session_key}/laps` on enter/seek/reconnect, kept current by the `laps` and `timing` WS channels. Live and replay envelopes are wire-identical.

***

## States

| State | Behaviour |
| - | - |
| Reference driver has no measurable on-track position yet | "No pit window for this driver yet." empty state, with the dropdown still reachable so another driver can be picked |
| Session is not a race | "Session is not a race." notice: this is a race-only widget |
| A car outside ±30 seconds of the reference | Not drawn; it reappears once inside the window |
| A compound not yet reported | Neutral disc, real stop count, no "?" |
| Live vs replay | Identical rendering |

***

## FAQ

> **How is this different from Predicted Pit Window and SC?**
>
> This widget shows where cars are RIGHT NOW relative to the reference driver, with the round's modelled pit losses drawn on as reference bands. The Strategy suite's Predicted Pit Window and SC is a forecast of when a stop should happen, built on the strategy engine, a separate system.

> **Why has the pit-loss line moved since last round?**
>
> Because it is not a constant. Each pair is the round's own resolved pit loss from the as-of strategy snapshot, so it changes circuit to circuit and can change within a session as the snapshot updates.

> **Why is the whole field on the left when P1 is the reference?**
>
> Because position runs left to right: the better a car's track position, the further right it sits. The leader has nobody ahead, so with P1 selected every other car is behind, which is the left half of the bar. Pick a midfield reference and the cars ahead appear on the right.

> **Why is one driver's TLA higher than the others?**
>
> It would have overprinted a neighbour on the axis. A chip climbs only as far as it needs to stay readable, and takes a stalk down to the axis so you can still see which gap it belongs to.

> **Why does the timing tower selection not move this widget any more?**
>
> By design. The reference driver is the widget's own choice, so the pit window stays put while you use the tower's selection for the charts and the other selection-driven widgets.

***

## Next Steps

> **[Timing Tower](/software/internal/watchparty/widgets/timing-tower)**
>
> The running order this widget's reference dropdown lists.

> **[Predicted Pit Window and SC](/software/internal/watchparty/strategy/predicted-pit-window)**
>
> The strategy engine's modelled forecast, as opposed to this live picture.

> **[Pit Stops](/software/internal/watchparty/widgets/pit-stops)**
>
> The stop counts the tyre discs carry, with each stop's pit lane time.

> **[Race History](/software/internal/watchparty/widgets/race-history)**
>
> How the gaps this bar reads have evolved over the race.


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