@pond-ts/charts 0.70.0 → 0.71.0

package/AGENTS.md

@@ -159,6 +159,7 @@ import {
   Layers,
   LineChart,
   YAxis,
+  CrosshairCursor,
 } from '@pond-ts/charts';
 
 const [live, snap] = useLiveSeries({
@@ -167,7 +168,8 @@ const [live, snap] = useLiveSeries({
   retention: { maxAge: '10m' },
 });
 
-<ChartContainer width={800} cursor="crosshair" panZoom>
+<ChartContainer width={800} panZoom>
+  <CrosshairCursor />
   <ChartRow height={240}>
     <YAxis id="ms" />
     <Layers>

package/API.md

@@ -251,17 +251,17 @@ Types: `UseSnapshotOptions`, `SnapshotSource` (structural — covers
 
 ### Components — layout & axes
 
-| Component                   | Key props                                                                                                                                                                                     | Purpose                                                                                                                                                               | Source                                                 |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| `ChartContainer`            | `width`, `range?`, `theme?`, `cursor?`, `panZoom?`, `xScale?`, `bounds?`, `showAxis?`, `calendar?`, `timeZone?`, `origin?`, `maxBandWidth?`/`bandAlign?`, `onTrackerChanged?`, `onDrawStats?` | Root: shared x-scale, interactions, annotations; `timeZone` renders the time axis in an IANA zone (default: viewer-local; a `calendar.timeZone` supplies the default) | `packages/charts/src/ChartContainer.tsx`               |
-| `ChartRow`                  | `height`, `cursor?` (deprecated — mount a cursor in the row)                                                                                                                                  | One stacked plot band; owns its y-axes                                                                                                                                | `packages/charts/src/ChartRow.tsx`                     |
-| `Layers`                    | children                                                                                                                                                                                      | Mandatory z-stack inside a row (back-to-front)                                                                                                                        | `packages/charts/src/Layers.tsx`                       |
-| `YAxis`                     | `id` (req), `side?`, `scale?` (`'linear'` \| `'log'` \| `'symlog'`), `linearWindow?`, `min?`/`max?`, `format?`, `width?`, `hide?`                                                             | Y-axis gutter; layers bind via their `axis` prop                                                                                                                      | `packages/charts/src/YAxis.tsx`                        |
-| `XAxis`                     | `side?`, `label?`, `format?`, `ticks?`, `transform?`, `dateStyle?`, `timeZone?` (this strip in another IANA zone)                                                                             | Placeable x-axis strip; kind inferred from data                                                                                                                       | `packages/charts/src/XAxis.tsx`                        |
-| `TimeAxis` / `CategoryAxis` | (XAxis props)                                                                                                                                                                                 | Thin `XAxis` presets                                                                                                                                                  | `packages/charts/src/TimeAxis.tsx`, `CategoryAxis.tsx` |
-| `Canvas`                    | `width`, `height`, `draw`                                                                                                                                                                     | Low-level DPR-aware canvas primitive                                                                                                                                  | `packages/charts/src/Canvas.tsx`                       |
-| `Selector`                  | `enabled?` (default `true`), `selected?` (mark \| set), `hovered?`, `onSelect?`, `onHover?`, `children?`                                                                                      | Wraps its scope; mounting enables click-select and owns the state it drives (RFC A10)                                                                                 | `packages/charts/src/selectors.tsx`                    |
-| `MultiSelector`             | `enabled?`, `selected?`, `hovered?`, `sequence?`, `onSelect?`, `onHover?`, `children?`                                                                                                        | Sweep-select superset of `Selector`: drag sweeps marks, release reports `(hits, modifiers, spans)` — plural, one per swept layer (RFC A5.2)                           | `packages/charts/src/selectors.tsx`                    |
+| Component                   | Key props                                                                                                                                                                          | Purpose                                                                                                                                                               | Source                                                 |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `ChartContainer`            | `width`, `range?`, `theme?`, `panZoom?`, `xScale?`, `bounds?`, `showAxis?`, `calendar?`, `timeZone?`, `origin?`, `maxBandWidth?`/`bandAlign?`, `onTrackerChanged?`, `onDrawStats?` | Root: shared x-scale, interactions, annotations; `timeZone` renders the time axis in an IANA zone (default: viewer-local; a `calendar.timeZone` supplies the default) | `packages/charts/src/ChartContainer.tsx`               |
+| `ChartRow`                  | `height`                                                                                                                                                                           | One stacked plot band; owns its y-axes                                                                                                                                | `packages/charts/src/ChartRow.tsx`                     |
+| `Layers`                    | children                                                                                                                                                                           | Mandatory z-stack inside a row (back-to-front)                                                                                                                        | `packages/charts/src/Layers.tsx`                       |
+| `YAxis`                     | `id` (req), `side?`, `scale?` (`'linear'` \| `'log'` \| `'symlog'`), `linearWindow?`, `min?`/`max?`, `format?`, `width?`, `hide?`                                                  | Y-axis gutter; layers bind via their `axis` prop                                                                                                                      | `packages/charts/src/YAxis.tsx`                        |
+| `XAxis`                     | `side?`, `label?`, `format?`, `ticks?`, `transform?`, `dateStyle?`, `timeZone?` (this strip in another IANA zone)                                                                  | Placeable x-axis strip; kind inferred from data                                                                                                                       | `packages/charts/src/XAxis.tsx`                        |
+| `TimeAxis` / `CategoryAxis` | (XAxis props)                                                                                                                                                                      | Thin `XAxis` presets                                                                                                                                                  | `packages/charts/src/TimeAxis.tsx`, `CategoryAxis.tsx` |
+| `Canvas`                    | `width`, `height`, `draw`                                                                                                                                                          | Low-level DPR-aware canvas primitive                                                                                                                                  | `packages/charts/src/Canvas.tsx`                       |
+| `Selector`                  | `enabled?` (default `true`), `selected?` (mark \| set), `hovered?`, `onSelect?`, `onHover?`, `children?`                                                                           | Wraps its scope; mounting enables click-select and owns the state it drives (RFC A10)                                                                                 | `packages/charts/src/selectors.tsx`                    |
+| `MultiSelector`             | `enabled?`, `selected?`, `hovered?`, `sequence?`, `onSelect?`, `onHover?`, `children?`                                                                                             | Sweep-select superset of `Selector`: drag sweeps marks, release reports `(hits, modifiers, spans)` — plural, one per swept layer (RFC A5.2)                           | `packages/charts/src/selectors.tsx`                    |
 
 ### Components — draw layers
 
@@ -303,25 +303,24 @@ schema columns). Because the union splits per series _kind_, a value typed as
 
 ### Components — cursors (mounted presets)
 
-The `cursor` string modes as components (interaction RFC §4/A4.1) — mount one
-as a child of `<ChartContainer>` (the default for every row) or inside a
-`<ChartRow>` (the per-row override). Render-only presets stack; one
-gesture-owning cursor (`Crosshair`/`Range`) per scope. The `cursor` /
-`cursorTime` / `crosshairSnap` / `cursorFormat` / `cursorSequence` /
-`onRegionSelect` / `regionSelectModifier` props (and `<ChartRow cursor>`) are
-**deprecated** — they keep working for one minor via an internal shim. The
-underlying `CursorSpec` contract stays unpublished (Q3); every drag claim on
-the plot (annotation-create, the range drag, pan) is arbitrated by one brush
-recognizer with a documented precedence (`src/brush.tsx`, RFC A1.5/A2.7).
-
-| Component         | Key props                                                     | Purpose                                                                                                                       | Source                            |
-| ----------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| `LineCursor`      | `showTime?`                                                   | The synced vertical line (`cursor="line"`, the legacy default)                                                                | `packages/charts/src/cursors.tsx` |
-| `PointCursor`     | `showTime?`                                                   | A dot on each series at the cursor (`"point"`)                                                                                | `packages/charts/src/cursors.tsx` |
-| `InlineCursor`    | `showTime?`                                                   | Dots + a value chip beside each (`"inline"`)                                                                                  | `packages/charts/src/cursors.tsx` |
-| `FlagCursor`      | `showTime?`                                                   | Dots + staffed value flags stacked at the top (`"flag"`)                                                                      | `packages/charts/src/cursors.tsx` |
-| `CrosshairCursor` | `snap?`, `showTime?`, `format?`                               | The inspection reticle: dashed cross, y value pill, x time pill (`"crosshair"`)                                               | `packages/charts/src/cursors.tsx` |
-| `RangeCursor`     | `sequence?`, `onDragRelease?`, `enableDrag?`, `dragModifier?` | The hover-time band + the drag: release fires once with a `RangeSpan`, then reverts (`"region"` + `onRegionSelect` successor) | `packages/charts/src/cursors.tsx` |
+Cursor presets (interaction RFC §4/A4.1). **A chart shows a cursor only when
+one is mounted** — mount one as a child of `<ChartContainer>` (the default for
+every row) or inside a `<ChartRow>` (the per-row override). Render-only
+presets stack; one gesture-owning cursor (`Crosshair`/`Range`) per scope. The
+first mounted cursor that sets `format` shapes the chart's readout channel.
+The underlying `CursorSpec` contract stays unpublished (Q3); every drag claim
+on the plot (annotation-create, the range drag, pan) is arbitrated by one
+brush recognizer with a documented precedence (`src/brush.tsx`, RFC
+A1.5/A2.7).
+
+| Component         | Key props                                                     | Purpose                                                                                                                                                | Source                            |
+| ----------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
+| `LineCursor`      | `showTime?`, `format?`                                        | The synced vertical line                                                                                                                               | `packages/charts/src/cursors.tsx` |
+| `PointCursor`     | `showTime?`, `format?`                                        | A dot on each series at the cursor                                                                                                                     | `packages/charts/src/cursors.tsx` |
+| `InlineCursor`    | `showTime?`, `format?`                                        | Dots + a value chip beside each                                                                                                                        | `packages/charts/src/cursors.tsx` |
+| `FlagCursor`      | `showTime?`, `format?`                                        | Dots + staffed value flags stacked at the top                                                                                                          | `packages/charts/src/cursors.tsx` |
+| `CrosshairCursor` | `snap?`, `showTime?`, `format?`, `onSnap?`                    | The inspection reticle: dashed cross, centre dot in the snapped series' colour, y value pill, x time pill; `onSnap` reports the snapped series + point | `packages/charts/src/cursors.tsx` |
+| `RangeCursor`     | `sequence?`, `onDragRelease?`, `enableDrag?`, `dragModifier?` | The hover-time band + the drag: release fires once with a `RangeSpan`, then reverts; on a category axis the band shades the slot and the drag is off   | `packages/charts/src/cursors.tsx` |
 
 ### Components — standalone row lists (DOM tables, no `<ChartContainer>`)
 
@@ -398,8 +397,8 @@ Series shapes (same file): `ChartSeries`, `BandSeries`, `BoxSeries`,
 | `scaleBand` / `ScaleBand`                  | Ordinal slot scale for the category axis                                                                                                                                                                                             | `packages/charts/src/bandScale.ts`        |
 | `GapMode`                                  | `'none' \| 'empty' \| 'dashed' \| 'step' \| 'fade'` (Line/Area `gaps` prop)                                                                                                                                                          | `packages/charts/src/gaps.ts`             |
 | `DecimateOption`                           | `<LineChart decimate>` — M4 viewport decimation (`bool \| { threshold }`)                                                                                                                                                            | `packages/charts/src/decimate.ts`         |
-| `CursorMode`                               | `'none' \| 'line' \| 'point' \| 'inline' \| 'flag' \| 'crosshair' \| 'region'`                                                                                                                                                       | `packages/charts/src/context.ts`          |
 | `TrackerInfo` / `TrackerSample`            | Hover readout payload (`onTrackerChanged`)                                                                                                                                                                                           | `packages/charts/src/context.ts`          |
+| `CursorSnap`                               | The point a `<CrosshairCursor>` snapped to (`onSnap`): a `TrackerSample` + `axisId` + `formatted`                                                                                                                                    | `packages/charts/src/context.ts`          |
 | `AnnotationKind` / `CreateSpec`            | Annotation identity + draw-gesture payload (`onCreate`)                                                                                                                                                                              | `packages/charts/src/context.ts`          |
 | `SelectInfo`                               | Selection/hover payload (`Selector`/`MultiSelector` `onSelect`/`onHover`)                                                                                                                                                            | `packages/charts/src/context.ts`          |
 | `SelectModifiers`                          | Keyboard modifiers on a click, 2nd arg to `onSelect`                                                                                                                                                                                 | `packages/charts/src/context.ts`          |

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.70.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.71.0...HEAD
+[0.71.0]: https://github.com/pond-ts/pond/compare/v0.70.0...v0.71.0
 [0.70.0]: https://github.com/pond-ts/pond/compare/v0.69.0...v0.70.0
 [0.69.0]: https://github.com/pond-ts/pond/compare/v0.68.0...v0.69.0
 [0.68.0]: https://github.com/pond-ts/pond/compare/v0.67.0...v0.68.0
@@ -73,6 +74,115 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.71.0] — 2026-09-24
+
+### Added
+
+- `@pond-ts/charts`: **`format` on `<LineCursor>`, `<PointCursor>`,
+  `<InlineCursor>` and `<FlagCursor>`** — the readout format that used to be
+  the container's `cursorFormat`, now on whichever cursor you mount (it was
+  already on `<CrosshairCursor>`). The chart still has one readout channel:
+  the first mounted cursor that sets `format` shapes it.
+
+- `@pond-ts/charts`: **`<CrosshairCursor onSnap>`** — tells you what the
+  crosshair is snapped to: the series (`label`, `color`, `axisId`) and the
+  point (`x`, `value`, `formatted`, plus `readout` when the layer has one), as
+  a new exported **`CursorSnap`** type. Fires only when the snapped point
+  changes, and with `null` when the pointer leaves. With `snap={false}` the
+  reticle follows the pointer rather than a series, so it stays `null`; a
+  reticle drawn by a controlled `trackerPosition` with no pointer on the chart
+  also reports `null`. Story `Cursors/Crosshair / SnapReadout`.
+
+- `@pond-ts/charts`: **`<CrosshairCursor>` snaps to box plots.** Its vertical
+  line lands on the centre of the box under the pointer and its horizontal
+  line on the quantile nearest the pointer (`upper` / `q3` / `median` / `q1` /
+  `lower`), with that value on the y-axis pill and reported by `onSnap`. A box
+  used to be skipped by the crosshair entirely: the line sat wherever the
+  pointer was and there was no value to read. The flag cursor still shows the
+  box's one consolidated flag, and the point / inline / flag cursors still draw
+  no per-quantile dots on a box. In a row with a box and a line, the vertical
+  line snaps to whichever of the two is drawn on top, the same rule as for two
+  lines. Story `Cursors/Crosshair / BoxPlot`.
+
+### Changed
+
+- `@pond-ts/charts`: the **crosshair's centre dot is drawn in the snapped
+  series' colour** rather than the cursor ink, so the reticle shows which line
+  it is reading. The free reticle (`snap={false}`) has no series under it and
+  keeps the cursor ink.
+
+- **charts:** **`<AreaChart>` fills to zero by default.** An omitted `baseline`
+  used to rest the fill on the bottom of the plot, which on auto-fit data sits
+  just under the lowest value — so a series running 50–90 drew 60 as a sliver
+  and 90 as a slab several times its size, and the fill's height said nothing
+  about the value. The default is now `0`: zero is pulled into the auto-fit
+  domain and each fill is as tall as its value, the usual reading of an area.
+  A number still sets another reference level. The old look is one prop away:
+  **`baseline="floor"`** rests the fill on the bottom of the plot and adds
+  nothing to the domain — for a price or an elevation profile, where starting
+  at zero would flatten the shape. **Migration:** an `<AreaChart>` with no
+  `baseline` whose data sits far from zero will now show zero on its axis; add
+  `baseline="floor"` to keep the previous rendering. Charts that already wrote
+  `baseline={0}`, or whose axis already started at zero, are unchanged. On a
+  log axis nothing changes: zero has no position there, so it rests on the
+  floor and is not pulled into the domain. On an axis pinned above zero
+  (`<YAxis min={40}>`) the baseline is clamped to the axis floor, as a bar's is,
+  so the fill's fade stays on the plot.
+
+### Removed
+
+- `@pond-ts/charts` (**breaking**): **the old cursor props are gone — a chart
+  shows a cursor only when you mount one.** Removed: `<ChartContainer>`'s
+  `cursor`, `cursorTime`, `crosshairSnap`, `cursorFormat`, `cursorSequence`,
+  `onRegionSelect` and `regionSelectModifier`, `<ChartRow cursor>`, and the
+  `CursorMode` type. They were deprecated in 0.58.0. The behaviour change that
+  matters most: a chart with no cursor component used to get a vertical line
+  cursor anyway; it now gets **no cursor** (hover still reports through
+  `onTrackerChanged`). Closes
+  [#647](https://github.com/pond-ts/pond/issues/647). **Migration:**
+
+  | Before                                           | After                                                                        |
+  | ------------------------------------------------ | ---------------------------------------------------------------------------- |
+  | no `cursor` prop (the implicit line)             | `<LineCursor />` (not on a `<MultiSelector>` row — see below)                |
+  | `cursor="line" \| "point" \| "inline" \| "flag"` | `<LineCursor />` / `<PointCursor />` / `<InlineCursor />` / `<FlagCursor />` |
+  | `cursor="crosshair"` + `crosshairSnap={false}`   | `<CrosshairCursor snap={false} />`                                           |
+  | `cursorTime`                                     | `showTime` on the cursor                                                     |
+  | `cursorFormat="…"`                               | `format="…"` on the cursor                                                   |
+  | `cursor="region"` + `cursorSequence={seq}`       | `<RangeCursor sequence={seq} />`                                             |
+  | `onRegionSelect={([a, b]) => …}`                 | `<RangeCursor onDragRelease={({ x: [a, b] }) => …} />`                       |
+  | `regionSelectModifier="shift"`                   | `<RangeCursor dragModifier="shift" />`                                       |
+  | `cursor="none"`                                  | mount nothing                                                                |
+  | `<ChartRow cursor="…">`                          | mount the cursor inside that `<ChartRow>`                                    |
+
+  Mount the cursor as a child of `<ChartContainer>` for every row, or inside
+  one `<ChartRow>` for that row only. A row that should have no cursor while
+  its siblings have one: mount the cursors per row instead of at the
+  container. **Don't add `<LineCursor />` to a row with a `<MultiSelector>`**:
+  there the selector's resting band is the cursor (as it already was under the
+  implicit line), and any mounted cursor replaces the band.
+
+### Fixed
+
+- `@pond-ts/charts`: **`<RangeCursor>` on a category axis now shades the bar
+  under the pointer.** It used to draw nothing there, so mounting one left the
+  row with no cursor at all. The band covers the whole slot, the way a
+  bucketed band covers a bucket on a time axis. The drag stays off on a
+  category axis (`onDragRelease` never fires there, and the chart now warns
+  in development when it is wired); dragging across bars to get them back is
+  what `<MultiSelector>` does. Story `Cursors/Range / CategoryAxis`.
+
+- **charts:** **A selectable `<AreaChart>` on a log axis with `baseline={0}`
+  counted every point over its x span as a hit.** Zero maps to `NaN` on a log
+  scale; the draw already fell back to the axis floor, but the hit test used
+  the `NaN` pixel, and a `NaN` bound fails neither range check. It now resolves
+  the baseline the same way the draw does.
+- **charts:** **`<AreaChart baseline={0}>` on an auto-fit log axis clipped
+  most of its series.** The zero baseline was pulled into the extent, which
+  left the log fit with no positive low end, so the domain collapsed around the
+  largest value (data from 10 to 1e5 fitted `[1e4, 1e6]`). A baseline at or
+  below zero is now left out of a log axis's fit. A layer's `yExtent` receives
+  the axis's scale kind for this.
+
 ## [0.70.0] — 2026-09-18
 
 ### Added

package/dist/AreaChart.d.ts

@@ -31,21 +31,27 @@ export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      */
     axis?: string;
     /**
-     * The value the fill rests on — the flat edge opposite the value line. Two
-     * forms:
+     * The value the fill rests on — the flat edge opposite the value line.
      *
-     * - **Omitted ⇒ the axis's lower bound** (the bottom of the plot): the
-     *   elevation form — fill from the line down to the floor, shade grading down.
-     * - **A number (e.g. `0`) ⇒ a fixed baseline**: the above/below-axis form —
-     *   values above it fill up, below it fill down, each side's shade fading
-     *   toward the baseline. For the esnet two-colour traffic look, compose two
-     *   `<AreaChart>`s (an "in" column and an "out" column, distinct `as` roles).
+     * - **Omitted ⇒ `0`**: an area measures size from zero, so values above zero
+     *   fill up and values below it fill down, each side's shade fading toward
+     *   the zero line. Zero is pulled into the auto-fit domain, so the axis always
+     *   shows where the fill starts.
+     * - **Another number ⇒ that reference level**, with the same behaviour (e.g.
+     *   `baseline={100}` for an index that fills above and below 100). For the
+     *   esnet two-colour traffic look, compose two `<AreaChart>`s (an "in" column
+     *   and an "out" column, distinct `as` roles).
+     * - **`'floor'` ⇒ the axis's lower bound** (the bottom of the plot): the fill
+     *   rests on whatever the axis starts at, and nothing is added to the domain.
+     *   For a series that never nears zero where zero would flatten the shape — a
+     *   price, an elevation profile.
      *
-     * A fixed baseline is pulled into the auto-fit domain so the baseline line is
-     * always visible (an above/below area with `baseline={0}` shows the zero
-     * axis).
+     * On a **log** axis zero has no position, so a baseline at or below zero
+     * falls back to the axis floor and is not pulled into the domain. On an axis
+     * pinned so that it excludes the baseline, the fill rests on the nearest
+     * edge (the baseline is clamped into the domain, as a bar's is).
      */
-    baseline?: number;
+    baseline?: number | 'floor';
     /**
      * Render-time path interpolation for the outline + fill edge — a view concern
      * (denoise the data with pond's `smooth()` upstream). **Omitted ⇒ `'linear'`**
@@ -95,8 +101,9 @@ export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      * (`theme.area[as] ?? theme.area.default`), overridden by {@link bandColors}.
      * Breakpoints are data and live here; colour stays in the theme — the same
      * split `<BarChart thresholds>` uses ([PND-BANDBAR2]), and the same
-     * magnitude-mirrored reading: values below zero (an above/below-axis area
-     * with `baseline={0}`) walk the same ±ladder without negative breakpoints.
+     * magnitude-mirrored reading: values below zero (which fill downward from
+     * the default zero baseline) walk the same ±ladder without negative
+     * breakpoints.
      *
      * **A banded area is still one area.** One hit region, one legend row, one
      * readout identity; hover / selection strengthen the fill and keep the band
@@ -171,8 +178,9 @@ export type AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extends Val
  *  it to the call signature, so this reads the bound through a localized,
  *  documented shape rather than widening `drawArea`'s contract to d3-scale. */
 /**
- * The area's baseline in **data** units: the caller's `baseline` when it has a
- * finite position on this axis, else the axis floor.
+ * The area's baseline in **data** units: the caller's `baseline`, clamped into
+ * the axis domain, when it has a finite position on this axis; else the axis
+ * floor.
  *
  * The fallback is not defensive padding — it's the log case. `baseline={0}` is
  * the natural thing to write and is correct on a linear axis; on a log axis
@@ -191,15 +199,15 @@ export declare function resolveAreaBaseline(baseline: number | undefined, yScale
  * against its `axis`), and renders nothing to the DOM — the row draws it. The
  * fill + outline break at gaps rather than spanning them.
  *
- * Two forms via `baseline` (see {@link AreaChartProps.baseline}): omit it for
- * the **elevation** form (rest on the axis floor) or pass `0` for the
- * **above/below-axis** form (positive up, negative down). The esnet two-colour
- * traffic look composes two layers, each with its own `as` role:
+ * The fill rests on `baseline` (see {@link AreaChartProps.baseline}): **`0`
+ * by default** (positive up, negative down), any other number for a different
+ * reference level, or `'floor'` for the bottom of the plot. The esnet
+ * two-colour traffic look composes two layers, each with its own `as` role:
  *
  * ```tsx
  * <Layers>
- *   <AreaChart series={s} column="in"  baseline={0} as="in" />
- *   <AreaChart series={s} column="out" baseline={0} as="out" />
+ *   <AreaChart series={s} column="in"  as="in" />
+ *   <AreaChart series={s} column="out" as="out" />
  * </Layers>
  * ```
  */

package/dist/AreaChart.js

@@ -16,8 +16,9 @@ import { useBandLadder } from './use-band-ladder.js';
  *  it to the call signature, so this reads the bound through a localized,
  *  documented shape rather than widening `drawArea`'s contract to d3-scale. */
 /**
- * The area's baseline in **data** units: the caller's `baseline` when it has a
- * finite position on this axis, else the axis floor.
+ * The area's baseline in **data** units: the caller's `baseline`, clamped into
+ * the axis domain, when it has a finite position on this axis; else the axis
+ * floor.
  *
  * The fallback is not defensive padding — it's the log case. `baseline={0}` is
  * the natural thing to write and is correct on a linear axis; on a log axis
@@ -28,14 +29,20 @@ import { useBandLadder } from './use-band-ladder.js';
  * layer's meaning ("fill from the bottom") on both scale kinds.
  */
 export function resolveAreaBaseline(baseline, yScale) {
-    const floor = domainFloor(yScale);
+    const d = yScale.domain?.();
+    const floor = d && d.length > 0 ? d[0] : 0;
     if (baseline === undefined)
         return floor;
-    return Number.isFinite(yScale(baseline)) ? baseline : floor;
-}
-function domainFloor(yScale) {
-    const d = yScale.domain?.();
-    return d && d.length > 0 ? d[0] : 0;
+    if (!Number.isFinite(yScale(baseline)))
+        return floor;
+    if (!d || d.length === 0)
+        return baseline;
+    // Clamped into the domain, as a bar's baseline is: under an explicit
+    // `<YAxis min={40}>` the default 0 is off the plot, and a fill resting
+    // there would anchor its fade (and a gap's `'fade'` connector) off-plot.
+    const lo = Math.min(d[0], d[d.length - 1]);
+    const hi = Math.max(d[0], d[d.length - 1]);
+    return Math.min(hi, Math.max(lo, baseline));
 }
 /**
  * An area draw layer: fills between a value `column` and a `baseline`, with a
@@ -45,15 +52,15 @@ function domainFloor(yScale) {
  * against its `axis`), and renders nothing to the DOM — the row draws it. The
  * fill + outline break at gaps rather than spanning them.
  *
- * Two forms via `baseline` (see {@link AreaChartProps.baseline}): omit it for
- * the **elevation** form (rest on the axis floor) or pass `0` for the
- * **above/below-axis** form (positive up, negative down). The esnet two-colour
- * traffic look composes two layers, each with its own `as` role:
+ * The fill rests on `baseline` (see {@link AreaChartProps.baseline}): **`0`
+ * by default** (positive up, negative down), any other number for a different
+ * reference level, or `'floor'` for the bottom of the plot. The esnet
+ * two-colour traffic look composes two layers, each with its own `as` role:
  *
  * ```tsx
  * <Layers>
- *   <AreaChart series={s} column="in"  baseline={0} as="in" />
- *   <AreaChart series={s} column="out" baseline={0} as="out" />
+ *   <AreaChart series={s} column="in"  as="in" />
+ *   <AreaChart series={s} column="out" as="out" />
  * </Layers>
  * ```
  */
@@ -66,6 +73,8 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
     if (layers === null) {
         throw new Error('<AreaChart> must be rendered inside a <Layers>');
     }
+    // `undefined` below means "the axis floor" — the internal helpers' spelling.
+    const baseValue = baseline === 'floor' ? undefined : (baseline ?? 0);
     const cs = useMemo(() => series instanceof ValueSeries
         ? fromValueSeries(series, column)
         : fromTimeSeries(series, column), [series, column]);
@@ -141,7 +150,13 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
     const entry = useMemo(() => ({
         layer: {
             as: semantic,
-            yExtent: () => areaExtent(cs, baseline),
+            // A baseline with no position on a log axis (zero, the default) is
+            // left out of the fit: the draw rests it on the floor anyway, and an
+            // extent of `[0, max]` gives the log fit no positive low end, so it
+            // would collapse the domain onto the max and clip the series.
+            yExtent: (scale) => areaExtent(cs, scale === 'log' && baseValue !== undefined && baseValue <= 0
+                ? undefined
+                : baseValue),
             // The container infers the shared x scale's kind from its layers — a
             // ValueSeries plots on a value axis, a TimeSeries on time.
             xKind: series instanceof ValueSeries ? 'value' : 'time',
@@ -155,7 +170,7 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
                     sweepAxis: 'x',
                     sweepSpanOnly: true,
                     hitTest: (px, py, xScale, yScale) => {
-                        const i = areaHitIndex(cs, baseline, px, py, xScale, yScale);
+                        const i = areaHitIndex(cs, baseValue, px, py, xScale, yScale);
                         if (i === null)
                             return null;
                         return {
@@ -266,15 +281,15 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
                     : { ...inStyle, color: style.spanColor, fill: style.spanColor }, 1), true, 0, plotExtentOf(ctx, xScale, yScale).width);
                 function drawAreaWith(st) {
                     return drawArea(ctx, cs, xScale, yScale, st, 
-                    // Omitted baseline rests on the axis floor (resolved late from the
-                    // scale, so it tracks the auto-fit domain); a fixed baseline is used
-                    // verbatim.
+                    // `'floor'` rests on the axis floor (resolved late from the
+                    // scale, so it tracks the auto-fit domain); a number (default 0)
+                    // is used verbatim.
                     // A log axis has no position for zero — or anything at or below
                     // it — so an explicit out-of-domain `baseline` would scale to
                     // `NaN` and poison every coordinate in the fill path. Fall back
-                    // to the axis floor, which is exactly what an omitted baseline
+                    // to the axis floor, which is exactly what `'floor'`
                     // already resolves to.
-                    resolveAreaBaseline(baseline, yScale), curveFactory, gaps, gapConnectorOpacity, decimate, bandLadder);
+                    resolveAreaBaseline(baseValue, yScale), curveFactory, gaps, gapConnectorOpacity, decimate, bandLadder);
                 }
             },
         },
@@ -288,7 +303,7 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
         readoutY,
         style,
         label,
-        baseline,
+        baseValue,
         curveFactory,
         gaps,
         gapConnectorOpacity,

package/dist/BoxPlot.js

@@ -139,9 +139,11 @@ export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, ax
                 // The readout reads the box **under the cursor** (boxIndexAtTime — span
                 // containment, not nearest-by-begin which flips past a wide box's
                 // midpoint), anchored at the box **centre** `(x + xEnd) / 2`. Outside
-                // every box → no readout. Off-chart fan-in only; the in-chart flag is
-                // `cursorFlag`. `push` skips a non-finite quantile, so an absent
-                // (range-only) q1/q3/median simply doesn't read out.
+                // every box → no readout. Feeds the off-chart readout and the
+                // crosshair (its x-snap lands mid-box, its y-snap on the nearest
+                // quantile); the in-chart flag is `cursorFlag`. `push` skips a
+                // non-finite quantile, so an absent (range-only) q1/q3/median simply
+                // doesn't read out.
                 if (bx.length === 0)
                     return [];
                 const i = boxIndexAtTime(bx, x);

package/dist/Candlestick.d.ts

@@ -111,9 +111,9 @@ export interface CandlestickProps<S extends SeriesSchema> {
  * supersedes `BoxPlot shape='solid'` for OHLC (which needed a quantile remap, a
  * body precompute, two overlaid layers for green/red, and a column-name tracker).
  *
- * **Cursor.** Unlike `BoxPlot`, a candle **participates in the crosshair x-snap**
- * (it exposes plain `sampleAt`, not a consolidated `cursorFlag`), so the reticle
- * lands on candles. The readout keys on `as` and shows `close` by default; pass
+ * **Cursor.** A candle **participates in the crosshair snap** (as a box plot
+ * does), so the reticle lands on candles; unlike a box plot it has no
+ * consolidated `cursorFlag`, so the flag cursor shows a chip per value. The readout keys on `as` and shows `close` by default; pass
  * `showOHLC` for the full four-pill quote.
  *
  * ```tsx

package/dist/Candlestick.js

@@ -37,9 +37,9 @@ import { spansForLayer } from './span.js';
  * supersedes `BoxPlot shape='solid'` for OHLC (which needed a quantile remap, a
  * body precompute, two overlaid layers for green/red, and a column-name tracker).
  *
- * **Cursor.** Unlike `BoxPlot`, a candle **participates in the crosshair x-snap**
- * (it exposes plain `sampleAt`, not a consolidated `cursorFlag`), so the reticle
- * lands on candles. The readout keys on `as` and shows `close` by default; pass
+ * **Cursor.** A candle **participates in the crosshair snap** (as a box plot
+ * does), so the reticle lands on candles; unlike a box plot it has no
+ * consolidated `cursorFlag`, so the flag cursor shows a chip per value. The readout keys on `as` and shows `close` by default; pass
  * `showOHLC` for the full four-pill quote.
  *
  * ```tsx
@@ -94,8 +94,8 @@ export function Candlestick({ series, open = 'open', high = 'high', low = 'low',
                 // The readout reads the candle **under the cursor** (containment span,
                 // not nearest-by-begin), anchored at the slot centre. Outside every
                 // candle → no readout. No `cursorFlag`: the samples flow through the
-                // normal per-series tracker path, which is also what keeps the candle
-                // in the crosshair x-snap (BoxPlot's cursorFlag opts out of both).
+                // normal per-series tracker path (BoxPlot's cursorFlag takes its
+                // values out of the per-series dots and chips).
                 if (ohlc.length === 0)
                     return [];
                 const i = ohlcIndexAtTime(ohlc, time);