Docs: add polar, radar, radial bar, pie, and wind rose guides

CHANGELOG.md

@@ -28,6 +28,14 @@ in the README).
   silently leave a stale row in the CodSpeed dashboard.
 
 ### Fixed
+- Polar customization now stays consistent across the browser, SVG, and native
+  raster renderers: point-anchored annotations use the joint `(theta, r)`
+  projection, explicit chart padding survives the polar layout pass, gradient
+  fills reach native raster wedges, and annular sectors honor rounded corners
+  and strokes.
+- `radar_chart(fill=False)` now renders area children as styled outlines,
+  translating their line color, width, opacity, curve, and dash props instead
+  of passing incompatible area props to the line renderer.
 - Repeated data updates no longer leak GPU buffers. Trace teardown walked a
   hand-kept list of geometry buffer names, so every rebuilt trace — each
   state-driven update, each append that could not patch in place, each animated
@@ -96,6 +104,16 @@ in the README).
   stay uniform.
 
 ### Changed
+- Default tooltips now lead with the hovered series name, and the radial row of
+  a polar readout is labelled `r` rather than presented as a Cartesian `y`. The
+  numeric angle row is gone from polar readouts: on most polar charts the angle
+  is where layout put the mark and the cursor is already on it, so it answered a
+  question nobody asked. Two things survive because they are not numeric angles
+  — an authored spoke label (a radar category reads `power`) and any row named
+  explicitly through `labels={"x": ...}`, which opts the angle back in formatted
+  through the theta axis's own text function. Compositions whose bearing *is*
+  data say so themselves: a wind rose band still reads its direction, and a pie
+  slice reads its category and value.
 - Polar wedge subdivision is span-proportional: `segments(span) =
   clamp(ceil(96 · |span| / turn), 2, 96)` in every renderer, over the *authored*
   angular width. Sagitta is quadratic in the per-segment angle, so this holds the

README.md

@@ -296,7 +296,9 @@ next, no dates implied:
 - **Categorical distributions:** strip, swarm, beeswarm, boxen, rug
 - **Regression diagnostics:** trendline, residual, QQ, PP
 - **Scatter matrix and joint plots:** SPLOM, pair grid, marginal histograms
-- **Pie / donut:** in `xy.pyplot` today, promoting to `xy.pie_chart(xy.pie(...))`
+- **Pie / donut:** `xy.pie_chart(labels, values, hole=...)` ships over
+  unequal-width core polar bars, with Matplotlib-shaped helpers in `xy.pyplot`;
+  nested donuts and variable-radius composition remain
 - **Candlestick / OHLC and finance overlays:** SMA, VWAP, Bollinger, RSI, MACD; prototyped, awaiting a fresh landing
 - **Waterfall and funnel**
 - **Treemap, sunburst, and icicle**

docs/api-reference/changelog.md

@@ -37,6 +37,20 @@ density families, facets, live `Chart.append()`/`pick()`/`select_range()`,
 browser-free native PNG, pure SVG export, CSS-compiled mark styling, and the
 experimental `xy.pyplot` compatibility layer.
 
+The Unreleased polar expansion adds heatmap, contour, and error-bar marks;
+partial sectors, holes/data-space origins, categorical theta, log/symlog
+radius, and polygonal grids; and matching pyplot theta/r-origin controls.
+Protocol v12 prevents an older client from silently interpreting that geometry
+as the previous full-circle surface.
+
+Outlined radar charts now render reliably: `radar_chart(fill=False)` translates
+area stroke settings into the corresponding line props, including color, width,
+opacity, curve, and dash.
+
+Default tooltips now lead with a named series and speak polar coordinates on
+polar charts: θ values reuse authored tick labels or the axis unit, and radial
+values are labeled r instead of appearing as Cartesian x/y rows.
+
 Read [Chart methods](/docs/xy/api-reference/figure-methods/),
 [Customize Each Part](/docs/xy/styling/customize/#fill,-stroke,-opacity,-and-gradients), and
 [Limitations and alpha status](/docs/xy/api-reference/limitations-and-alpha-status/)

docs/api-reference/chart-factories.md

@@ -6,9 +6,10 @@ description: Reference XY chart containers, shared props, and facet construction
 # Chart Factories
 
 Chart factories compose marks, axes, annotations, and chrome into a public
-`Chart`. The generated inventory below follows the same taxonomy as the
-[Chart Gallery](/docs/xy/overview/gallery/). Its names, signatures, and
-defaults come directly from XY's public Python callables.
+`Chart`. The generated inventory below is organized by chart family; use the
+[Chart Gallery](/docs/xy/overview/gallery/) when visual browsing is more
+helpful. Its names, signatures, and defaults come directly from XY's public
+Python callables.
 
 Use `chart()` when different mark kinds share a panel. A family container is
 usually clearer when the children represent one chart family.

docs/api-reference/limitations-and-alpha-status.md

@@ -28,6 +28,10 @@ pre-1.0 releases can make breaking changes with migration notes.
   new visible-window representation.
 - Density is native-binned and GPU-rendered. It is not an all-GPU ingest and
   aggregation pipeline.
+- Polar traces do not use Cartesian decimation, density, or refined-view
+  tiers. `line`, `scatter`, and `area` render directly and reject more than
+  200,000 points per trace. Heatmap and contour grids are not governed by that
+  point ceiling.
 - Arrow ingest is zero-copy only for compatible, null-free primitive layouts.
   Chunking, nulls, dtype conversion, and datetime conversion can copy.
 - Disk-backed/out-of-core residency is not a shipped public tier.
@@ -46,6 +50,18 @@ and [Benchmarks](/docs/xy/overview/benchmarks/) for scoped evidence.
 - Linked views synchronize viewport axes, not selections or cross-filtering.
 - Facets support display/export and shared domains but not `Chart` append,
   pick, or Python-side range-selection methods.
+- Polar interaction currently consists of hover, radial zoom about a fixed
+  radial minimum, and reset. Authored sectors are supported; theta pan/rotation,
+  interactive sector zoom, box zoom, selection, brushing, and crosshairs are
+  disabled.
+- Point-anchored `text`, `label`, `marker`, `arrow`, and `callout` annotations
+  use the joint `(theta, r)` projection consistently on polar charts in the
+  browser, SVG, and native raster output. Polar rules and bands remain deferred
+  because they require spoke/ring and sector/annulus geometry, and raise at
+  payload build instead of using Cartesian geometry.
+- Polar histograms, box plots, hexbin/density, generic segments, and meshes
+  remain outside the mark allowlist. Polar LOD, facets/animation, and angular
+  navigation/selection are also deferred.
 - Browser context limits matter on large dashboards. XY's context governor
   defaults to 12 live contexts and reacquires off-screen charts as they return;
   more than that many simultaneously visible charts is not an unbounded

docs/app/scripts/check_html_routes.py

@@ -12,7 +12,7 @@
 ROUTES_ROOT = APP_ROOT / ".web" / "app" / "routes"
 LIVE_PREVIEW_MARKERS = ("python demo exec", "python demo-only exec")
 INLINE_SVG_PREVIEW_ROUTES = {"/overview/gallery/"}
-INLINE_SVG_PREVIEW_COUNT = 29
+INLINE_SVG_PREVIEW_COUNT = 34
 XY_PAYLOAD_PATTERN = re.compile(r'["\'](?P<url>/docs/xy/xy/[a-f0-9]+\.xyf)["\']')
 XY_PAYLOAD_MAGIC = b"XYBF"
 LLMS_DIRECTIVE = "For AI agents: the complete XY documentation index is at"