Why Campos is the way it is

The built-in analytical ShotMap default now uses `colorScale="magma"` instead of `"turbo"`. Consumers who need the earlier output must pass `colorScale="turbo"` explicitly.

Markers are sorted by outcome before rendering: non-goals first, goals last. In dense penalty-area clusters, goal markers always sit on top of shot markers. Deterministic and unconditional — no API to override.

Marker radius is computed from xG via `r = √(minArea + t × (maxArea − minArea))`, not linearly. A 0.5 xG shot reads as ~71% the radius of a 1.0 xG shot, not 50% — which preserves perceptual equivalence because human vision reads circle area, not radius.

`preset="opta"` locks markers to circles with fill-vs-hollow encoding outcome (goal vs non-goal). `preset="statsbomb"` uses shapes keyed to context/body-part (hexagon foot, circle header, square set-piece) with fill colour driven by the xG colour ramp. The two presets intentionally produce different charts from the same data model.

Every event produced by an adapter is in canonical pitch coordinates before reaching a compute or render layer. x = 0 is the own goal, x = 100 is the opposition goal, y = 0 is attacker's right, y = 100 is attacker's left. No chart re-maps axes; all orientation is a render-time concern.

When `autoPitchLines: true` (default) and the colour ramp is dark (magma, inferno, viridis, or a custom dark gradient), pitch lines are forced to white — even if the user passed `pitchColors.lines="#333"`. Dark ramp + dark lines makes the pitch disappear; legibility wins over API consistency.

Zero-config Heatmap bins events into a fixed 12×8 grid. Adaptive schemes that vary bin count with data density were rejected because they break cross-match comparability — two heatmaps must be readable side by side without grid surprises.

`valueMode: "count" | "intensity" | "share"` only changes the scale-bar copy and tooltip phrasing. Cell fills are always driven by intensity (`count / maxCount`). Switching mode never repaints the surface — so two heatmaps in different modes remain visually comparable.

Every event produced by an adapter is in canonical pitch coordinates before reaching a compute or render layer. x = 0 is the own goal, x = 100 is the opposition goal, y = 0 is attacker's right, y = 100 is attacker's left. No chart re-maps axes; all orientation is a render-time concern.

When `autoPitchLines: true` (default) and the colour ramp is dark (magma, inferno, viridis, or a custom dark gradient), pitch lines are forced to white — even if the user passed `pitchColors.lines="#333"`. Dark ramp + dark lines makes the pitch disappear; legibility wins over API consistency.

Zero-config KDE uses Silverman's rule (`h = σ × n^(-1/6)`) independently on x and y. Silverman is designed for unimodal distributions, and multi-cluster football patterns (wing + centre + striker zones) over-smooth as a result. That's a known limitation, surfaced as a `[kde.low-confidence]` warning on sparse inputs.

KDE renders via a canvas-to-data-URL raster wrapped in an SVG `<image>`. Static export skips KDE entirely — it is not a member of the stable `ExportFrameSpec` union. Vector output is deferred until raster-vs-static parity rules are deliberately defined.

Every event produced by an adapter is in canonical pitch coordinates before reaching a compute or render layer. x = 0 is the own goal, x = 100 is the opposition goal, y = 0 is attacker's right, y = 100 is attacker's left. No chart re-maps axes; all orientation is a render-time concern.

Markers at data extremes no longer clip against axis frames. Scale range insets inward by 6px; axis lines stay at the frame edge. Opt out with `axisPadding: 0` or `false`.

`series[].hidden: true` suppresses rendering but keeps the series in domain inference, palette skipping, and envelope targetability. When a hidden series widens the domain, `[hidden.extends-x-domain]` / `[hidden.extends-y-domain]` always fires — consumers filter by warning code if the behaviour is intentional.

LineChart gains `bands` (shaded rectangles), `references` (horizontal / vertical / diagonal lines), and `envelopes` (signed-area fills between two bounds). Unlocks five editorial ideas from the cross-sport lab in one packet.

Warnings remain plain strings, but every warning starts with a bracket-prefixed code like `[envelope.no-overlap]`. Codes are public contract; prose may evolve. Consumers can grep codes reliably without a breaking type change.

Pass angles on `PassSonar` are always computed from canonical-frame start/end points (`atan2(endY - y, endX - x)`), so 0 rad always points toward the opposition goal. This is the "adjusted" convention some references call out. Heading-frame ("regular") sonars require tracking data and are deferred until a tracking adapter lands.

`PassSonar` exposes `colorBy: "completion" | "distance" | "none"` with `"completion"` as the default. `"completion"` keeps the current attempted/completed annular stack. `"distance"` matches Eliot McKinley's canonical reference — bar colour encodes mean pass distance on a sequential ramp.

`PassSonar` now defaults to `binCount: 24` (15° wedges), matching Eliot McKinley's canonical reference (`ref_code/PassSonar/`) and the convention adopted by mplsoccer / d3-soccer. Consumers that want the earlier 45° wedges must pass `binCount={8}` explicitly.

Each wedge's outer radius is `√(count / maxCount)`, not `count / maxCount`. A bin with four times the passes has twice the radius — matching how human vision reads wedge area. Aligns with `mplsoccer` and Eliot McKinley's canonical reference.

When `autoPitchLines: true` (default) and the colour ramp is dark (magma, inferno, viridis, or a custom dark gradient), pitch lines are forced to white — even if the user passed `pitchColors.lines="#333"`. Dark ramp + dark lines makes the pitch disappear; legibility wins over API consistency.

`Territory` accepts `grid="3x3"` or `"5x3"` (plus named tactical presets), never an arbitrary `gridX`. A deliberate break from Heatmap's flexibility: Territory is a broadcast-editorial view where thirds-by-thirds or fifths-by-thirds are semantically meaningful and any other resolution is noise.

Every event produced by an adapter is in canonical pitch coordinates before reaching a compute or render layer. x = 0 is the own goal, x = 100 is the opposition goal, y = 0 is attacker's right, y = 100 is attacker's left. No chart re-maps axes; all orientation is a render-time concern.

Markers at data extremes no longer clip against axis frames. Scale range insets inward by 6px; axis lines stay at the frame edge. Opt out with `axisPadding: 0` or `false`.

Shot annotations follow a three-tier policy. Tier 1 — goals — always annotate. Tier 2 — non-goals with xG ≥ 0.3, capped at 3 per 15-minute window. Tier 3 — everything else — surfaces only in the tooltip. Stops dense matches (30+ shots) becoming unreadable without losing the story.

Cumulative xG paths are SVG `M/H/V` step-after segments — no cubic Béziers, no linear interpolation between shots. Smooth curves imply continuous chance generation, which is a lie. A step function says "this xG value held until the next shot", which is what actually happened.

Markers at data extremes no longer clip against axis frames. Scale range insets inward by 6px; axis lines stay at the frame edge. Opt out with `axisPadding: 0` or `false`.

`BumpChart` expects a `rank` field that is already a discrete 1..N ordinal. It never derives rank from `points` / `goals` / `xG` internally. Tie-breaking (dense vs min vs max) is a narrative choice and lives upstream; the chart refuses to own it.

Markers at data extremes no longer clip against axis frames. Scale range insets inward by 6px; axis lines stay at the frame edge. Opt out with `axisPadding: 0` or `false`.

The trail narrows as it recedes into the past. The marker and label live at the most recent timepoint. Consumers reading left-to-right intuit the story as "how we got to here" — not "where we started".

The marker glyph holds only the jersey number, initials, or position code. Full names render in a rounded pill below the marker when `showNames: true`. This keeps markers legible across long or multilingual names without clipping, and preserves a readable glyph even when the name pill is off.

Every event produced by an adapter is in canonical pitch coordinates before reaching a compute or render layer. x = 0 is the own goal, x = 100 is the opposition goal, y = 0 is attacker's right, y = 100 is attacker's left. No chart re-maps axes; all orientation is a render-time concern.

Bins whose mean resultant length R (circular concentration) < 0.3 render a neutral glyph (hollow circle by default) instead of an arrow. A zone where passes go in every direction has no honest mean — drawing an arrow would invent a direction the data doesn't support.

Every event produced by an adapter is in canonical pitch coordinates before reaching a compute or render layer. x = 0 is the own goal, x = 100 is the opposition goal, y = 0 is attacker's right, y = 100 is attacker's left. No chart re-maps axes; all orientation is a render-time concern.

Passes with null / missing `endX` or `endY` render as a dot at the origin, not as an omitted pass and not as an inferred trajectory. Header counts include both arrows and dots so the completion denominator stays honest.

Every event produced by an adapter is in canonical pitch coordinates before reaching a compute or render layer. x = 0 is the own goal, x = 100 is the opposition goal, y = 0 is attacker's right, y = 100 is attacker's left. No chart re-maps axes; all orientation is a render-time concern.

When the input contains `A→B` (10 passes) and `B→A` (8 passes), the default render collapses them into a single undirected edge with weight 18. `directed: true` keeps the pair distinct with arrowheads, at the cost of dense-network readability.

Every event produced by an adapter is in canonical pitch coordinates before reaching a compute or render layer. x = 0 is the own goal, x = 100 is the opposition goal, y = 0 is attacker's right, y = 100 is attacker's left. No chart re-maps axes; all orientation is a render-time concern.

Markers at data extremes no longer clip against axis frames. Scale range insets inward by 6px; axis lines stay at the frame edge. Opt out with `axisPadding: 0` or `false`.

Every event produced by an adapter is in canonical pitch coordinates before reaching a compute or render layer. x = 0 is the own goal, x = 100 is the opposition goal, y = 0 is attacker's right, y = 100 is attacker's left. No chart re-maps axes; all orientation is a render-time concern.

The bar geometry never inverts. A metric with `percentile: 15, originalDirection: "lower"` renders a 15% bar plus a "lower is better" badge — not an 85% bar. The chart owns rendering; the caller owns statistical correctness.

Slice radius reads as percentile against the declared cohort. Raw metric values (xG, progressive passes, tackles) pass through to tooltips and labels but never set the wedge geometry. Consumers who need raw-scale polar charts pick a different primitive.

Markers at data extremes no longer clip against axis frames. Scale range insets inward by 6px; axis lines stay at the frame edge. Opt out with `axisPadding: 0` or `false`.

`renderCell(datum, index, view)` receives a third `SmallMultiplesView` argument carrying `pitchOrientation`, `pitchCrop`, and `sharedScale`. Consumers opt-in per chart by forwarding `view` into children. Implicit React context was rejected — it breaks SSR, static export, and agent-readability.