@pond-ts/charts 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
 them all. Pre-1.0: minor bumps may include new features and type-level changes;
 patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.39.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.41.0...HEAD
+[0.41.0]: https://github.com/pjm17971/pond-ts/compare/v0.40.0...v0.41.0
+[0.40.0]: https://github.com/pjm17971/pond-ts/compare/v0.39.0...v0.40.0
 [0.39.0]: https://github.com/pjm17971/pond-ts/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/pjm17971/pond-ts/compare/v0.37.0...v0.38.0
 [0.37.0]: https://github.com/pjm17971/pond-ts/compare/v0.36.0...v0.37.0
@@ -37,21 +39,61 @@ patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.41.0] — 2026-07-06
+
+### Added
+
+- **`@pond-ts/charts`: `<Candlestick>` — a first-class OHLC mark** (Phase 1 of
+  the financial-charts RFC, Tidal-driven). `open`/`high`/`low`/`close` props
+  default to the conventional names (`<Candlestick series={s} />` for a standard
+  OHLCV series); draws-only (body extents derived per-mark); **point- or
+  interval-keyed** so raw daily OHLCV feeds straight in (no `aggregate`), while a
+  weekly/monthly rollup is the identical call. `variant: 'candle' | 'bar' |
+'hollow'`, `colorBy: 'direction' | 'series'`, `gap`, and `showOHLC` (four-pill
+  O/H/L/C hover readout; default is a single `close` pill keyed on `as`).
+  Participates in the crosshair x-snap (unlike `BoxPlot`). Supersedes `BoxPlot
+shape='solid'` for OHLC data.
+- **`@pond-ts/charts`: `ohlcFromTimeSeries`** + the `OhlcSeries` / `OhlcColumns`
+  types — read four price columns into a chart-ready columnar view (exported
+  alongside the existing `*FromTimeSeries` builders).
+
+### Changed
+
+- **`@pond-ts/charts`: `ChartTheme` gains a required `candle` slot** (a
+  `CandleStyle`: `rising`/`falling`/`neutral` body+wick pairs, `bodyWidth`,
+  `wickWidth`). `defaultTheme` and `estelaTheme` ship neutral, **unbranded**
+  up/down pairs — market green/red is a `cssVarTheme` overlay, not a library
+  default. **Breaking (type-level):** a hand-built `ChartTheme` that doesn't
+  derive from a shipped theme must add a `candle` slot to compile.
+
+## [0.40.0] — 2026-07-05
+
+A **core + charts** release from the estela `DataChart`-port friction wave.
+`@pond-ts/react` and `@pond-ts/fit` carry no code changes — republished in
+lock-step (peer ranges widen to `^0.40.0`).
+
+### Added
+
+- `pond-ts`: **`TimeSeries.fromColumns({ sort })`** — an opt-in `sort?: boolean`
+  (default `false`) that stable-sorts a columnar payload by key before
+  construction, the columnar counterpart of `fromJSON`'s `sort`. The default path
+  is unchanged: a decreasing key still throws (a backwards key on the trusted fast
+  door is a corruption signal, not silently accepted), and the `Float64Array`
+  zero-copy adoption is preserved when `sort` is unset. (#344)
+- `@pond-ts/charts`: **controlled bar hover** — `<ChartContainer hovered
+onHover>`, the transient-hover analog of the existing `selected` / `onSelect`
+  pair, keyed by the same `SelectInfo`. Pin a lit `<BarChart>` bar from a legend
+  or list row (`hovered`), or mirror a bar-originated hover out-of-band
+  (`onHover`); omit both for today's uncontrolled behavior. (#343)
+
 ### Fixed
 
-- **Charts — click-to-select an annotation now works while `panZoom` is on.** A
-  _selectable but non-editable_ `<Region>` / `<Marker>` (one with no `onChange`)
-  lets its press bubble to the plot so a drag can pan _through_ it. The plot
-  captured the pointer on press to start the pan, and the browser then retargeted
-  the resulting `click` onto the plot (Pointer Events spec: a captured pointer's
-  compatibility mouse events fire on the capture target) — silently dropping the
-  mark's `onSelectAnnotation`. The plot now **defers** its pan pointer-capture
-  until the pointer actually moves past the drag slop, so a click (no drag) leaves
-  the pointer on the mark and its select fires, while a press-drag still pans
-  through and the tracker still hides once the pan commits. Resolves the
-  browser-dependent finding deferred from #308; adds
-  `e2e/annotations-panzoom.spec.ts`, the first real-pointer-event behavior e2e for
-  the annotation layer. (#309)
+- `@pond-ts/charts`: **axis and layer registration are value-equality-guarded** —
+  a fresh-but-value-equal `ticks` / `format` / `byValue()`-projected `series`
+  reference no longer re-registers the axis/layer, fixing a "Maximum update depth
+  exceeded" loop on frequently re-rendering (scrub-driven) charts. The layer and
+  axis docs gain a memoize note for `format` / `series` (an inline `format`
+  closure still must be hoisted — a closure can't be value-compared). (#342)
 
 ## [0.39.0] — 2026-07-03
 
@@ -89,6 +131,19 @@ carry no code changes — republished in lock-step (peer ranges widen to `^0.39.
 
 - `@pond-ts/charts`: the crosshair x-axis pill and marker pills read the axis's
   own formatter (a value-axis / off-boundary time no longer shows a raw number).
+- **Charts — click-to-select an annotation now works while `panZoom` is on.** A
+  _selectable but non-editable_ `<Region>` / `<Marker>` (one with no `onChange`)
+  lets its press bubble to the plot so a drag can pan _through_ it. The plot
+  captured the pointer on press to start the pan, and the browser then retargeted
+  the resulting `click` onto the plot (Pointer Events spec: a captured pointer's
+  compatibility mouse events fire on the capture target) — silently dropping the
+  mark's `onSelectAnnotation`. The plot now **defers** its pan pointer-capture
+  until the pointer actually moves past the drag slop, so a click (no drag) leaves
+  the pointer on the mark and its select fires, while a press-drag still pans
+  through and the tracker still hides once the pan commits. Resolves the
+  browser-dependent finding deferred from #308; adds
+  `e2e/annotations-panzoom.spec.ts`, the first real-pointer-event behavior e2e for
+  the annotation layer. (#309)
 
 ## [0.38.0] — 2026-07-03
 

package/dist/AreaChart.d.ts

@@ -8,6 +8,10 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * `ValueSeries` (`series.byValue('dist')`) against its value axis — the
      * container infers which from the data, no axis-type prop (mirrors
      * `<LineChart>`). Either way `column` names the numeric value to fill from.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
+     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column to fill from. */

package/dist/BandChart.d.ts

@@ -8,6 +8,10 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * container infers which from the data, no axis-type prop (mirrors
      * `<LineChart>` / `<AreaChart>`). Either way `lower`/`upper` name the numeric
      * edge columns.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
+     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric column for the band's lower edge (e.g. `p25`). */

package/dist/BarChart.d.ts

@@ -10,6 +10,10 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * the same neighbour-spacing span applies (see {@link barsFromValueSeries}); the
      * container infers the x-kind from the data, no axis-type prop (mirrors the
      * other layers).
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
+     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column for the bar height. */
@@ -63,6 +67,12 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
  * readout reads the same bar you click, even across a wide bucket (they differ
  * only by the `gap` inset, where the pixel rect is narrower than the span).
  *
+ * Both channels are also **controllable from outside** the chart via the
+ * container: `selected`/`onSelect` (committed) and `hovered`/`onHover` (transient)
+ * — pass either to pin the lit/selected bar from a legend or list row, and read
+ * the callback to mirror a bar-originated hover/click out-of-band. Symmetric pair,
+ * keyed by the same {@link SelectInfo} identity.
+ *
  * **Value axis** — bars also scale on a value axis when fed a `ValueSeries`
  * (`series.byValue('dist')`): estela's distance-domain splits/laps, one bar per
  * segment over a monotonic axis. A `ValueSeries` is point-keyed, so the span is

package/dist/BarChart.js

@@ -26,6 +26,12 @@ import { useSlotKey } from './use-slot-key.js';
  * readout reads the same bar you click, even across a wide bucket (they differ
  * only by the `gap` inset, where the pixel rect is narrower than the span).
  *
+ * Both channels are also **controllable from outside** the chart via the
+ * container: `selected`/`onSelect` (committed) and `hovered`/`onHover` (transient)
+ * — pass either to pin the lit/selected bar from a legend or list row, and read
+ * the callback to mirror a bar-originated hover/click out-of-band. Symmetric pair,
+ * keyed by the same {@link SelectInfo} identity.
+ *
  * **Value axis** — bars also scale on a value axis when fed a `ValueSeries`
  * (`series.byValue('dist')`): estela's distance-domain splits/laps, one bar per
  * segment over a monotonic axis. A `ValueSeries` is point-keyed, so the span is

package/dist/Candlestick.d.ts

@@ -0,0 +1,93 @@
+import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { type CandleVariant, type ColorBy } from './ohlc.js';
+export interface CandlestickProps<S extends SeriesSchema> {
+    /**
+     * The source series. **Point-keyed** (`time`) raw OHLCV feeds straight in —
+     * each candle's slot is derived from neighbour spacing (see
+     * {@link ohlcFromTimeSeries}), no `aggregate` pass needed. An **interval /
+     * timeRange**-keyed series (an `aggregate` rollup — weekly / monthly bars) uses
+     * the key's own `[begin, end)` as the slot. The chart infers the x-kind from
+     * the data; there's no axis-type prop.
+     */
+    series: TimeSeries<S>;
+    /** Opening-price column. **Omitted ⇒ `'open'`.** */
+    open?: string;
+    /** Session-high column. **Omitted ⇒ `'high'`.** */
+    high?: string;
+    /** Session-low column. **Omitted ⇒ `'low'`.** */
+    low?: string;
+    /** Closing-price column. **Omitted ⇒ `'close'`.** */
+    close?: string;
+    /**
+     * The series' semantic identifier — what the data _is_ (e.g. a ticker). The
+     * theme maps it to a {@link CandleStyle} (`theme.candle[as] ??
+     * theme.candle.default`). **Omitted ⇒ the `default` candle style.** It's also
+     * the tracker/readout label for the series (the primary `close` pill keys on
+     * `as`, not the raw column name).
+     */
+    as?: string;
+    /**
+     * Which `<YAxis>` (by its `id`) this candle scales against — the *scale*, where
+     * `as` picks the *style*. **Omitted ⇒ the row's default axis.**
+     */
+    axis?: string;
+    /**
+     * How each mark renders — `'candle'` (default; filled body + wick), `'bar'`
+     * (OHLC tick bar), or `'hollow'` (rising hollow / falling filled). See
+     * {@link CandleVariant}.
+     */
+    variant?: CandleVariant;
+    /**
+     * What drives the colour — `'direction'` (default; rising / falling / doji off
+     * open vs close, the market convention) or `'series'` (one colour off the `as`
+     * role, no green/red). See {@link ColorBy}.
+     */
+    colorBy?: ColorBy;
+    /**
+     * Total horizontal inset between adjacent candles in px (half each side), so
+     * they breathe — see `barSpanPx`. **Omitted ⇒ `0`** (the body already insets to
+     * `style.bodyWidth` of the slot). A candle narrower than 1px after the inset
+     * collapses to a 1px mark, so a thin slot stays visible.
+     */
+    gap?: number;
+    /**
+     * Fan the **full O/H/L/C** to the tracker readout (four value pills) instead of
+     * the default single `close` pill. **Omitted ⇒ `false`** — close is "the price"
+     * for a compact legend; the full quote is opt-in for a dense hover readout.
+     */
+    showOHLC?: boolean;
+    /**
+     * @internal Declaration position among the `<Layers>` children, injected by
+     * `Layers` so z-order follows JSX order. Do not set.
+     */
+    index?: number;
+}
+/**
+ * A first-class OHLC **candlestick** draw layer — the financial sibling of
+ * {@link BoxPlot}. Reads four price columns (`open`/`high`/`low`/`close`) of
+ * `series` into an {@link OhlcSeries} and draws one candle per key: the
+ * `open→close` body (direction-coloured) and the `high–low` wick, over the key's
+ * slot x-span. Derives the body extents itself (`min`/`max` of open/close) — the
+ * consumer never runs a `withColumn` precompute. Registers into the enclosing
+ * {@link Layers}; renders nothing to the DOM — the row draws it. Gap-aware (a key
+ * missing any price draws nothing).
+ *
+ * **Draws only** — windowing stays upstream: raw daily OHLCV is a point-keyed
+ * `TimeSeries` fed straight in, and a weekly / monthly bar is the identical call
+ * on an `aggregate(Sequence.calendar('week'), …)` rollup (interval-keyed). This
+ * 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
+ * `showOHLC` for the full four-pill quote.
+ *
+ * ```tsx
+ * <Layers>
+ *   <Candlestick series={daily} as="AAPL" />
+ * </Layers>
+ * ```
+ */
+export declare function Candlestick<S extends SeriesSchema>({ series, open, high, low, close, as: semantic, axis, variant, colorBy, gap, showOHLC, index, }: CandlestickProps<S>): null;
+//# sourceMappingURL=Candlestick.d.ts.map

package/dist/Candlestick.js

@@ -0,0 +1,102 @@
+import { useContext, useEffect, useMemo } from 'react';
+import { ohlcFromTimeSeries } from './data.js';
+import { drawCandles, isFiniteOhlc, ohlcExtent, ohlcIndexAtTime, resolveCandleStyle, } from './ohlc.js';
+import { ContainerContext, LayersContext, } from './context.js';
+import { useSlotKey } from './use-slot-key.js';
+/**
+ * A first-class OHLC **candlestick** draw layer — the financial sibling of
+ * {@link BoxPlot}. Reads four price columns (`open`/`high`/`low`/`close`) of
+ * `series` into an {@link OhlcSeries} and draws one candle per key: the
+ * `open→close` body (direction-coloured) and the `high–low` wick, over the key's
+ * slot x-span. Derives the body extents itself (`min`/`max` of open/close) — the
+ * consumer never runs a `withColumn` precompute. Registers into the enclosing
+ * {@link Layers}; renders nothing to the DOM — the row draws it. Gap-aware (a key
+ * missing any price draws nothing).
+ *
+ * **Draws only** — windowing stays upstream: raw daily OHLCV is a point-keyed
+ * `TimeSeries` fed straight in, and a weekly / monthly bar is the identical call
+ * on an `aggregate(Sequence.calendar('week'), …)` rollup (interval-keyed). This
+ * 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
+ * `showOHLC` for the full four-pill quote.
+ *
+ * ```tsx
+ * <Layers>
+ *   <Candlestick series={daily} as="AAPL" />
+ * </Layers>
+ * ```
+ */
+export function Candlestick({ series, open = 'open', high = 'high', low = 'low', close = 'close', as: semantic, axis, variant = 'candle', colorBy = 'direction', gap = 0, showOHLC = false, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<Candlestick> must be rendered inside a <ChartContainer>');
+    }
+    const layers = useContext(LayersContext);
+    if (layers === null) {
+        throw new Error('<Candlestick> must be rendered inside a <Layers>');
+    }
+    const ohlc = useMemo(() => ohlcFromTimeSeries(series, { open, high, low, close }), [series, open, high, low, close]);
+    // Styling: semantic identifier → theme candle style. The single styling channel.
+    const { candle } = container.theme;
+    const style = (semantic !== undefined ? candle[semantic] : undefined) ?? candle.default;
+    // Series identity for the readout (the `as` role, else the close column name) —
+    // the primary `close` pill keys on this, like every other layer.
+    const label = semantic ?? close;
+    const entry = useMemo(() => ({
+        layer: {
+            yExtent: () => ohlcExtent(ohlc),
+            xKind: 'time',
+            xExtent: () => ohlc.length === 0 ? null : [ohlc.x[0], ohlc.xEnd[ohlc.length - 1]],
+            sampleAt: (time) => {
+                // 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).
+                if (ohlc.length === 0)
+                    return [];
+                const i = ohlcIndexAtTime(ohlc, time);
+                if (i < 0 || !isFiniteOhlc(ohlc, i))
+                    return [];
+                const at = (ohlc.x[i] + ohlc.xEnd[i]) / 2;
+                const { body, wick } = resolveCandleStyle(style, ohlc.open[i], ohlc.close[i], colorBy);
+                if (!showOHLC) {
+                    // Default: `close` is "the price", keyed on the series id.
+                    return [{ x: at, value: ohlc.close[i], color: body, label }];
+                }
+                // Opt-in full quote: four value pills (body colour for open/close, wick
+                // colour for the high/low extremes). Each is a value-only axis pill.
+                const samples = [
+                    { x: at, value: ohlc.high[i], color: wick, label: 'high' },
+                    { x: at, value: ohlc.open[i], color: body, label: 'open' },
+                    { x: at, value: ohlc.close[i], color: body, label: 'close' },
+                    { x: at, value: ohlc.low[i], color: wick, label: 'low' },
+                ];
+                return samples;
+            },
+            draw: (ctx, xScale, yScale) => drawCandles(ctx, ohlc, xScale, yScale, style, variant, colorBy, gap),
+        },
+        axisId: axis,
+        index,
+    }), [ohlc, style, label, variant, colorBy, gap, showOHLC, axis, index]);
+    // Stable per-instance slot (see useSlotKey): keeps this candle layer's
+    // z-position + identity across prop updates; the injected index drives the sort.
+    const slot = useSlotKey();
+    useEffect(() => () => layers.unregisterLayer(slot), [layers, slot]);
+    useEffect(() => {
+        layers.registerLayer(slot, entry);
+    }, [layers, slot, entry]);
+    // Also a tracker source: the container fans in this series' OHLC at the cursor
+    // for the (outside-the-chart) readout.
+    const { registerTrackerSource, unregisterTrackerSource } = container;
+    useEffect(() => () => unregisterTrackerSource(slot), [unregisterTrackerSource, slot]);
+    useEffect(() => {
+        registerTrackerSource(slot, entry.layer);
+    }, [registerTrackerSource, slot, entry.layer]);
+    return null;
+}
+//# sourceMappingURL=Candlestick.js.map

package/dist/ChartContainer.d.ts

@@ -57,6 +57,31 @@ export interface ChartContainerProps {
      * works in both controlled and uncontrolled mode.
      */
     onSelect?: (hit: SelectInfo | null) => void;
+    /**
+     * Controlled hover-highlight — the transiently lit mark (echo the `onHover` arg
+     * back), or `null`. **Omitted ⇒ uncontrolled** (the pointer over a selectable
+     * layer manages it internally). The hover analog of {@link selected}: pass it to
+     * **pin** a lit mark from outside the chart (e.g. hovering a legend / list row
+     * lights the matching {@link BarChart} bar). Only layers with a hover-highlight
+     * (currently `BarChart`) render it; keyed by the same {@link SelectInfo} identity
+     * as selection.
+     */
+    hovered?: SelectInfo | null;
+    /**
+     * Fires when the pointer enters a selectable layer's mark (the hit mark) or
+     * leaves every mark (`null`) — the hover analog of {@link onSelect}. Notification
+     * only (works controlled or uncontrolled), and **deduped**: it fires on a mark
+     * transition, not on every pointer move. Wire it to mirror hover out-of-band
+     * (e.g. a list row ↔ the bar), pairing with {@link hovered} to sync both ways.
+     * (The annotation counterpart is {@link onHoverAnnotation}.)
+     *
+     * **Dedup key:** by the mark's `key` + `label` only (not `value`/`color`). So on
+     * a live chart where a bar's value changes while the cursor stays on it, this
+     * won't re-fire — read the current value from your series, not the last
+     * `onHover` payload. (Matches the internal hover-highlight, which repaints on
+     * key transitions.)
+     */
+    onHover?: (hit: SelectInfo | null) => void;
     /**
      * Enable pan/zoom: drag the plot to pan the time range, wheel to zoom around
      * the cursor. **Default off** — so it doesn't capture drag/scroll unless asked.
@@ -155,5 +180,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map

package/dist/ChartContainer.js

@@ -31,7 +31,7 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, children, }) {
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, children, }) {
     // The explicit base domain from `range` (a tuple or a TimeRange). `undefined`
     // ⇒ auto-fit (resolved from the layers below). Pan/zoom seeds from it; `seed`
     // is the placeholder while auto-fitting.
@@ -175,18 +175,36 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             setInternalSelected(hit);
     }, []);
     // Hover-highlight: the transient mark under the pointer (distinct from the
-    // committed selection). Deduped by key+label so the data canvas repaints only
-    // when the hovered mark changes — not on every pointer move (the move itself
-    // just slides the SVG cursor, which never touches the data canvas).
-    const [hovered, setHoveredState] = useState(null);
+    // committed selection). Controlled (`hovered` prop) or uncontrolled (internal),
+    // mirroring selection; `onHover` notifies in both modes. Deduped by key+label
+    // so it fires — and the data canvas repaints — only when the hovered mark
+    // changes, not on every pointer move (the move itself just slides the SVG
+    // cursor, which never touches the data canvas).
+    const [internalHovered, setInternalHovered] = useState(null);
+    const controlledHover = hovered !== undefined;
+    const hoveredValue = controlledHover ? (hovered ?? null) : internalHovered;
+    const onHoverRef = useRef(onHover);
+    const controlledHoverRef = useRef(controlledHover);
+    // The last mark we reported — so the callback dedups across pointer moves even
+    // in controlled mode, where there's no internal state to compare against.
+    const lastHoverRef = useRef(null);
+    useLayoutEffect(() => {
+        onHoverRef.current = onHover;
+        controlledHoverRef.current = controlledHover;
+    });
     const setHovered = useCallback((hit) => {
-        setHoveredState((prev) => prev === hit ||
+        const prev = lastHoverRef.current;
+        const same = prev === hit ||
             (prev !== null &&
                 hit !== null &&
                 prev.key === hit.key &&
-                prev.label === hit.label)
-            ? prev
-            : hit);
+                prev.label === hit.label);
+        if (same)
+            return;
+        lastHoverRef.current = hit;
+        onHoverRef.current?.(hit);
+        if (!controlledHoverRef.current)
+            setInternalHovered(hit);
     }, []);
     // Rows report their per-slot gutter widths; we reserve each slot's max.
     const [gutters, setGutters] = useState([]);
@@ -284,7 +302,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         setDragging,
         selected: selectedValue,
         select,
-        hovered,
+        hovered: hoveredValue,
         setHovered,
         cursor,
         cursorTime,
@@ -329,7 +347,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         setDragging,
         selectedValue,
         select,
-        hovered,
+        hoveredValue,
         setHovered,
         cursor,
         cursorTime,

package/dist/ChartRow.js

@@ -9,6 +9,62 @@ import { YAxis } from './YAxis.js';
 import { ContainerContext, RowContext, } from './context.js';
 /** Sentinel id for the implicit axis a row gets when no `<YAxis>` is declared. */
 const IMPLICIT_AXIS_ID = '__default__';
+/** Element-wise compare of two optional number arrays (an axis's tick values) —
+ *  so a *fresh* `ticks={[…]}` array whose contents are unchanged doesn't count as
+ *  a new spec (see {@link axisSpecEqual}). */
+function numberArraysEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1)
+        if (!Object.is(a[i], b[i]))
+            return false;
+    return true;
+}
+/**
+ * Value-equality for two {@link AxisSpec}s — the registration guard's compare
+ * (see `registerAxis`). Every field is a plain value except `format`, which may
+ * be a `(value) => string` closure: those are compared by **reference**
+ * (`Object.is`), so a stable/hoisted formatter (or a string specifier) is equal
+ * across renders but a *fresh inline function* is not — the one case a structural
+ * guard provably can't collapse, hence the `<YAxis format>` memoize note. A
+ * fresh-but-value-equal `ticks` array (the common live-chart footgun) compares
+ * equal element-wise and no-ops.
+ */
+function axisSpecEqual(a, b) {
+    return (a.id === b.id &&
+        a.side === b.side &&
+        a.width === b.width &&
+        // Object.is (not ===) so a degenerate NaN bound compares equal to itself and
+        // doesn't re-register every render.
+        Object.is(a.min, b.min) &&
+        Object.is(a.max, b.max) &&
+        a.pad === b.pad &&
+        a.labelPlacement === b.labelPlacement &&
+        a.index === b.index &&
+        Object.is(a.format, b.format) &&
+        numberArraysEqual(a.tickValues, b.tickValues));
+}
+/**
+ * Value-equality for two {@link LayerEntry}s — **defensive, not load-bearing.**
+ * The axis guard (`axisSpecEqual`) is what breaks the update-depth loop; this is
+ * belt-and-suspenders for the layer setter. Note that under the current draw-layer
+ * structure it *won't* actually fire: every layer builds `layer` inside the same
+ * `useMemo` as `entry`, so the register effect only runs when `entry` is fresh —
+ * and a fresh `entry` always carries a fresh `layer`, so `a.layer === b.layer` is
+ * never true when the guard runs (it falls through to a normal register). It would
+ * only bite if a future layer memoized `layer` separately from `entry` (or the
+ * `Layers` registry ref changed under a stable entry). A fresh `series` projection
+ * (`byValue()` mints one each call) rebuilds the memo → a new `layer` and
+ * legitimately re-registers; that's a consumer-side memoize (see the `series` note
+ * on the draw-layer components), not something the setter can value-compare.
+ */
+function layerEntryEqual(a, b) {
+    return a.layer === b.layer && a.axisId === b.axisId && a.index === b.index;
+}
 /** Axis tick count for the per-axis formatter — matches `<YAxis>`'s tick count
  *  so the readout formatter is calibrated exactly as the labels are. */
 const AXIS_TICK_COUNT = 5;
@@ -52,8 +108,19 @@ export function ChartRow({ height, cursor, children }) {
     // min/max or series change silently rebind axes / reorder the z-stack.)
     const [axes, setAxes] = useState(() => new Map());
     const [layers, setLayers] = useState(() => new Map());
+    // Registration is idempotent under value-equality: a `<YAxis>` re-fires its
+    // register effect whenever its `spec` memo yields a fresh object — which an
+    // inline `ticks={[]}` / `format` or a re-rendered parent does every render. If
+    // the spec is *value*-equal to the stored one, skip the `setState` entirely so
+    // it can't spin `register → setState → re-render → register` into React's
+    // "Maximum update depth exceeded" on a scrub-heavy chart (F-charts-axis-reregister).
     const registerAxis = useCallback((key, spec) => {
-        setAxes((m) => new Map(m).set(key, spec));
+        setAxes((m) => {
+            const prev = m.get(key);
+            if (prev !== undefined && axisSpecEqual(prev, spec))
+                return m;
+            return new Map(m).set(key, spec);
+        });
     }, []);
     const unregisterAxis = useCallback((key) => {
         setAxes((m) => {
@@ -64,8 +131,17 @@ export function ChartRow({ height, cursor, children }) {
             return next;
         });
     }, []);
+    // Same value-equality guard as `registerAxis`: a re-register carrying the same
+    // `layer` object (stable while the draw layer's inputs are) + `axisId`/`index`
+    // no-ops rather than churning state. (A fresh `series` projection rebuilds the
+    // layer and legitimately re-registers — see `layerEntryEqual`.)
     const registerLayer = useCallback((key, entry) => {
-        setLayers((m) => new Map(m).set(key, entry));
+        setLayers((m) => {
+            const prev = m.get(key);
+            if (prev !== undefined && layerEntryEqual(prev, entry))
+                return m;
+            return new Map(m).set(key, entry);
+        });
     }, []);
     const unregisterLayer = useCallback((key) => {
         setLayers((m) => {

package/dist/LineChart.d.ts

@@ -8,6 +8,11 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * `ValueSeries` (`series.byValue('cumDist')`) against its value axis — the
      * container infers which from the data, no axis-type prop. Either way the key
      * / axis column supplies x and `column` supplies y.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * passing `series={s.byValue('dist')}` inline re-registers this layer every
+     * render — on a frequently re-rendering (e.g. scrub-driven) chart, memoize the
+     * projection (`useMemo`) so the layer isn't rebuilt each frame.
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column to plot. */

package/dist/YAxis.d.ts

@@ -36,6 +36,12 @@ export interface YAxisProps {
      * function. Omit for the scale's d3 default — which is calibrated to the tick
      * step, so a between-ticks readout rounds to tick precision; pass a specifier
      * (e.g. `',.2f'`) when you want finer readout precision. See {@link AxisFormat}.
+     *
+     * **Live charts:** a string specifier is value-compared, so an inline
+     * `format='.0%'` is safe every render. An inline `format={(v) => …}` **function**
+     * is a fresh reference each render — the one axis prop a structural guard can't
+     * value-compare — so on a frequently re-rendering (e.g. scrub-driven) chart,
+     * hoist it or wrap it in `useCallback`, or it re-registers the axis each frame.
      */
     format?: AxisFormat;
     /**
@@ -45,9 +51,10 @@ export interface YAxisProps {
      * lever for a non-uniform axis like pace, where the caller chooses round-pace
      * positions and their own `m:ss` labels (`{ at: -300, label: '5:00' }`). `at`
      * values outside `[min, max]` extrapolate off-plot (the scale does not clamp).
-     * Pass `[]` to draw none. For a live / animating chart, **memoize the array** —
-     * an inline `ticks={[…]}` is a fresh reference each render and re-registers the
-     * axis (like `format`; harmless for a static chart).
+     * Pass `[]` to draw none. The array is **value-compared on registration**, so an
+     * inline `ticks={[…]}` (or `ticks={[]}`) with unchanged contents no longer
+     * re-registers the axis — only genuinely changed tick positions do. (An inline
+     * `format` *function* still needs hoisting; see `format`.)
      */
     ticks?: ReadonlyArray<{
         readonly at: number;

package/dist/data.d.ts

@@ -53,6 +53,32 @@ export interface BoxSeries {
     readonly upper: Float64Array;
     readonly length: number;
 }
+/**
+ * A chart-ready view of an OHLC series ({@link Candlestick}): the candle's
+ * horizontal slot (`x` = left edge, `xEnd` = right edge) plus the four price
+ * channels per mark — `open`/`high`/`low`/`close`. The chart derives the body
+ * extents (`min`/`max` of open/close) itself at draw time; only the four raw
+ * columns are read here.
+ *
+ * A mark is drawn only where **all four** prices are finite; any one `NaN` is a
+ * gap (the candle draws nothing — same gap contract as {@link BoxSeries}).
+ *
+ * Unlike {@link BoxSeries} (interval-keyed only), the OHLC view supports **both**
+ * key shapes, like {@link BarSeries}: an **interval**-keyed series (an
+ * `aggregate` rollup — weekly/monthly bars) uses the key's own `[begin, end)` as
+ * the slot; a **point**-keyed series (raw daily OHLCV) derives the slot from
+ * neighbour spacing (see {@link ohlcFromTimeSeries}), so it feeds straight in
+ * with no `aggregate` pass.
+ */
+export interface OhlcSeries {
+    readonly x: Float64Array;
+    readonly xEnd: Float64Array;
+    readonly open: Float64Array;
+    readonly high: Float64Array;
+    readonly low: Float64Array;
+    readonly close: Float64Array;
+    readonly length: number;
+}
 /**
  * A chart-ready view of an interval-keyed series for bars: each mark spans
  * `[begin[i], end[i]]` (the key's range) with height `y[i]`. Unlike
@@ -83,6 +109,17 @@ export interface BoxColumns {
     /** Upper whisker end (e.g. `p95` / `max`). */
     readonly upper: string;
 }
+/** The four OHLC column names {@link ohlcFromTimeSeries} reads. */
+export interface OhlcColumns {
+    /** Opening price column. */
+    readonly open: string;
+    /** Session high column. */
+    readonly high: string;
+    /** Session low column. */
+    readonly low: string;
+    /** Closing price column. */
+    readonly close: string;
+}
 /**
  * Build a {@link ChartSeries} from a pond `TimeSeries` by reading its columnar
  * buffers directly — no per-event materialization. `column` names a numeric
@@ -143,6 +180,26 @@ export declare function bandFromValueSeries<VS extends ValueSeriesSchema>(series
  * @throws TypeError if any quantile column is not a numeric column.
  */
 export declare function boxFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, columns: BoxColumns): BoxSeries;
+/**
+ * Build an {@link OhlcSeries} from a pond `TimeSeries` — four numeric price
+ * columns (`open`/`high`/`low`/`close`) plus the candle's horizontal slot.
+ *
+ * **Key-shape aware, like {@link barsFromTimeSeries}.** An **interval /
+ * timeRange**-keyed series (an `aggregate` rollup — weekly / monthly bars) uses
+ * the key's own `[begin, end)` as the slot. A **point**-keyed (`time`) series —
+ * raw daily OHLCV — has `begin === end` (zero width), so the slot is derived from
+ * neighbour spacing (each candle centred on its timestamp, reaching halfway to
+ * each neighbour; see {@link neighbourSpans}). This is the ergonomic win over the
+ * interval-only {@link boxFromTimeSeries}: raw OHLC feeds straight in with no
+ * `aggregate` pass.
+ *
+ * A key with any of the four prices missing reads as a gap (the candle draws
+ * nothing). Detected by `keyColumn().kind === 'time'`.
+ *
+ * @throws RangeError if any price column does not exist.
+ * @throws TypeError if any price column is not a numeric column.
+ */
+export declare function ohlcFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, columns: OhlcColumns): OhlcSeries;
 /**
  * Build a {@link BarSeries} from a pond `TimeSeries` — one bar per event, the
  * key's `[begin, end]` as the x-span and `column` as the height.

package/dist/data.js

@@ -170,6 +170,41 @@ export function boxFromTimeSeries(series, columns) {
         length: series.length,
     };
 }
+/**
+ * Build an {@link OhlcSeries} from a pond `TimeSeries` — four numeric price
+ * columns (`open`/`high`/`low`/`close`) plus the candle's horizontal slot.
+ *
+ * **Key-shape aware, like {@link barsFromTimeSeries}.** An **interval /
+ * timeRange**-keyed series (an `aggregate` rollup — weekly / monthly bars) uses
+ * the key's own `[begin, end)` as the slot. A **point**-keyed (`time`) series —
+ * raw daily OHLCV — has `begin === end` (zero width), so the slot is derived from
+ * neighbour spacing (each candle centred on its timestamp, reaching halfway to
+ * each neighbour; see {@link neighbourSpans}). This is the ergonomic win over the
+ * interval-only {@link boxFromTimeSeries}: raw OHLC feeds straight in with no
+ * `aggregate` pass.
+ *
+ * A key with any of the four prices missing reads as a gap (the candle draws
+ * nothing). Detected by `keyColumn().kind === 'time'`.
+ *
+ * @throws RangeError if any price column does not exist.
+ * @throws TypeError if any price column is not a numeric column.
+ */
+export function ohlcFromTimeSeries(series, columns) {
+    const open = readNumericColumn(series, columns.open);
+    const high = readNumericColumn(series, columns.high);
+    const low = readNumericColumn(series, columns.low);
+    const close = readNumericColumn(series, columns.close);
+    const n = series.length;
+    if (series.keyColumn().kind !== 'time') {
+        // Interval / timeRange: the key's own endpoints are the candle slot.
+        const { begin, end } = keyBeginEnd(series);
+        return { x: begin, xEnd: end, open, high, low, close, length: n };
+    }
+    // Point key (begin === end): synthesize the slot from neighbour spacing so raw
+    // daily OHLCV renders as contiguous candles without a pre-key to intervals.
+    const { begin, end } = neighbourSpans(series.keyColumn().begin, n);
+    return { x: begin, xEnd: end, open, high, low, close, length: n };
+}
 /**
  * Per-row begin/end buffers for the key column, each aligned to the logical
  * length (zero-copy views). For an interval / timeRange key these are the key's
@@ -184,6 +219,30 @@ function keyBeginEnd(series) {
     // (point-in-time), which the caller's point-key fallback replaces.
     return { begin: key.begin.subarray(0, n), end: key.end.subarray(0, n) };
 }
+/**
+ * Synthesize per-point `[begin, end]` spans from a monotonic axis buffer by
+ * **neighbour spacing**: each point is centred on its own value and reaches
+ * halfway to each neighbour (a Voronoi cell on the axis). The first / last points
+ * mirror their single adjacent gap so the end cells match their interior width; a
+ * lone point (length 1) keeps zero width (the renderer's `minWidth` floor takes
+ * over). Shared by the point-keyed `TimeSeries` bars, the `ValueSeries` bars, and
+ * the point-keyed OHLC reader. `axis` is a zero-copy key buffer (must not be
+ * mutated) — fresh output buffers are allocated.
+ */
+function neighbourSpans(axis, n) {
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        const x = axis[i];
+        // Half-gap to the previous neighbour (mirror the next gap at the left edge).
+        const prevGap = i > 0 ? x - axis[i - 1] : i + 1 < n ? axis[i + 1] - x : 0;
+        // Half-gap to the next neighbour (mirror the previous gap at the right edge).
+        const nextGap = i + 1 < n ? axis[i + 1] - x : i > 0 ? x - axis[i - 1] : 0;
+        begin[i] = x - prevGap / 2;
+        end[i] = x + nextGap / 2;
+    }
+    return { begin, end };
+}
 /**
  * Build a {@link BarSeries} from a pond `TimeSeries` — one bar per event, the
  * key's `[begin, end]` as the x-span and `column` as the height.
@@ -215,20 +274,8 @@ export function barsFromTimeSeries(series, column) {
         return { begin, end, y, length: n };
     }
     // Point key (begin === end): synthesize a span from neighbour spacing so the
-    // bars have width. Copy into fresh buffers — the key's begin buffer is shared
-    // (zero-copy) and must not be mutated.
-    const src = series.keyColumn().begin;
-    const begin = new Float64Array(n);
-    const end = new Float64Array(n);
-    for (let i = 0; i < n; i += 1) {
-        const t = src[i];
-        // Half-gap to the previous point (mirror the next gap at the left edge).
-        const prevGap = i > 0 ? t - src[i - 1] : i + 1 < n ? src[i + 1] - t : 0;
-        // Half-gap to the next point (mirror the previous gap at the right edge).
-        const nextGap = i + 1 < n ? src[i + 1] - t : i > 0 ? t - src[i - 1] : 0;
-        begin[i] = t - prevGap / 2;
-        end[i] = t + nextGap / 2;
-    }
+    // bars have width (see neighbourSpans).
+    const { begin, end } = neighbourSpans(series.keyColumn().begin, n);
     return { begin, end, y, length: n };
 }
 /**
@@ -253,20 +300,9 @@ export function barsFromTimeSeries(series, column) {
 export function barsFromValueSeries(series, column) {
     const y = readValueColumn(series, column);
     const n = series.length;
-    // axisValues() is the monotonic key buffer (zero-copy) — must not be mutated,
-    // so synthesise the spans into fresh buffers.
-    const ax = series.axisValues();
-    const begin = new Float64Array(n);
-    const end = new Float64Array(n);
-    for (let i = 0; i < n; i += 1) {
-        const x = ax[i];
-        // Half-gap to the previous neighbour (mirror the next gap at the left edge).
-        const prevGap = i > 0 ? x - ax[i - 1] : i + 1 < n ? ax[i + 1] - x : 0;
-        // Half-gap to the next neighbour (mirror the previous gap at the right edge).
-        const nextGap = i + 1 < n ? ax[i + 1] - x : i > 0 ? x - ax[i - 1] : 0;
-        begin[i] = x - prevGap / 2;
-        end[i] = x + nextGap / 2;
-    }
+    // axisValues() is the monotonic key buffer (zero-copy); neighbourSpans reads it
+    // and allocates fresh span buffers (never mutates the source).
+    const { begin, end } = neighbourSpans(series.axisValues(), n);
     return { begin, end, y, length: n };
 }
 //# sourceMappingURL=data.js.map

package/dist/index.d.ts

@@ -42,18 +42,21 @@ export { BoxPlot } from './BoxPlot.js';
 export type { BoxPlotProps } from './BoxPlot.js';
 export { BarChart } from './BarChart.js';
 export type { BarChartProps } from './BarChart.js';
+export { Candlestick } from './Candlestick.js';
+export type { CandlestickProps } from './Candlestick.js';
+export type { CandleVariant, ColorBy } from './ohlc.js';
 export { Region, Baseline, Marker } from './annotations.js';
 export type { RegionProps, BaselineProps, MarkerProps } from './annotations.js';
 export type { AnnotationKind, CreateSpec } from './context.js';
 export { YAxisIndicator, createLiveValue } from './indicators.js';
 export type { YAxisIndicatorProps, LiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, } from './data.js';
-export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, } from './data.js';
+export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, } from './data.js';
+export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, } from './data.js';
 export type { RadiusEncoding, ColorEncoding } from './encoding.js';
 export type { Curve } from './curve.js';
 export type { GapMode } from './gaps.js';
 export { defaultTheme, estelaTheme } from './theme.js';
-export type { ChartTheme, LineStyle, BandStyle, AreaStyle, ScatterStyle, BoxStyle, BarStyle, } from './theme.js';
+export type { ChartTheme, LineStyle, BandStyle, AreaStyle, ScatterStyle, BoxStyle, CandleStyle, BarStyle, } from './theme.js';
 export { cssVarTheme } from './css-theme.js';
 export type { ChartThemeOverrides, VarReader } from './css-theme.js';
 export { useChartTheme } from './useChartTheme.js';

package/dist/index.js

@@ -29,13 +29,14 @@ export { AreaChart } from './AreaChart.js';
 export { ScatterChart } from './ScatterChart.js';
 export { BoxPlot } from './BoxPlot.js';
 export { BarChart } from './BarChart.js';
+export { Candlestick } from './Candlestick.js';
 // Annotations — user-authored marks in the turquoise register (distinct from the
 // data): a shaded span, a horizontal value line, a vertical x line.
 export { Region, Baseline, Marker } from './annotations.js';
 // Axis indicators — a value pill pinned to an axis edge (the ChartIQ live tag).
 // `createLiveValue` is the high-frequency, isolated-repaint update path.
 export { YAxisIndicator, createLiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, } from './data.js';
+export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, } from './data.js';
 export { defaultTheme, estelaTheme } from './theme.js';
 // CSS-custom-property → ChartTheme bridge: build a theme from a design system's
 // tokens (`cssVarTheme`), and a hook that re-resolves it on a `data-theme`

package/dist/ohlc.d.ts

@@ -0,0 +1,81 @@
+import type { OhlcSeries } from './data.js';
+import type { Scale } from './line.js';
+import type { CandleStyle } from './theme.js';
+/**
+ * How an OHLC mark renders (pjm17971's fork 2 — bundled as one component, like
+ * {@link BoxShape}, not split into a separate `<OHLCBar>`):
+ *
+ * - **`candle`** (default) — a filled `open→close` body with a `high–low` wick.
+ * - **`bar`** — an OHLC tick bar: a `high–low` stem with a left tick at `open`
+ *   and a right tick at `close`, no body.
+ * - **`hollow`** — like `candle`, but a **rising** candle (close > open) draws a
+ *   *hollow* (outlined) body and a **falling / doji** one a filled body.
+ */
+export type CandleVariant = 'candle' | 'bar' | 'hollow';
+/**
+ * What drives a candle's colour:
+ *
+ * - **`direction`** (default, market convention) — `rising` when close > open,
+ *   `falling` when close < open, `neutral` when equal (a doji).
+ * - **`series`** — one colour off the `as` role (the style's `rising` pair),
+ *   *no* green/red. Keeps "colour = series" when a candle sits beside coloured
+ *   lines and the up/down split would read as a second, conflicting encoding.
+ */
+export type ColorBy = 'direction' | 'series';
+/**
+ * The `[min, max]` vertical extent of the **drawn** candles — the lowest `low`
+ * and highest `high` over keys where **all four** prices are finite — or `null`
+ * if none are. Gap keys (any price `NaN`) are excluded, matching what
+ * {@link drawCandles} draws, so they don't drag the y-domain.
+ *
+ * Only `low`/`high` bound the extent: they are the outermost reach of a candle,
+ * so `open`/`close` lie within `[low, high]` for any well-formed OHLC row and
+ * never widen it. (A malformed row where, say, `close > high` would clip — an
+ * upstream data error, not the chart's to paper over.)
+ */
+export declare function ohlcExtent(ohlc: OhlcSeries): [number, number] | null;
+/**
+ * The index of the candle whose slot `[x, xEnd]` contains `time` — the candle
+ * **under the cursor** — or `-1` if `time` is in no slot. Containment (the box
+ * analog {@link boxIndexAtTime}), not nearest-by-`begin` (which flips to the next
+ * candle past a wide one's midpoint). Candles are sorted by `x`; at a shared edge
+ * the left candle wins. A gap candle (some price non-finite) still owns its span
+ * here; the caller drops it on the finiteness check. O(N) over the candles
+ * (view-scale).
+ */
+export declare function ohlcIndexAtTime(ohlc: OhlcSeries, time: number): number;
+/** All four prices finite at `i` — i.e. this candle is drawn. */
+export declare function isFiniteOhlc(ohlc: OhlcSeries, i: number): boolean;
+/**
+ * Resolve the `{ body, wick }` colours for one candle from its `open`/`close`
+ * and the {@link ColorBy} mode. `direction` picks `rising` (close > open) /
+ * `falling` (close < open) / `neutral` (equal — a doji, falling back to `rising`
+ * when the style omits it); `series` always returns `rising` (one colour, no
+ * up/down split). The single source of the colour decision, shared by
+ * {@link drawCandles} and `<Candlestick>`'s tracker readouts so the pill colour
+ * matches the mark.
+ */
+export declare function resolveCandleStyle(style: CandleStyle, open: number, close: number, colorBy: ColorBy): {
+    body: string;
+    wick: string;
+};
+/**
+ * Draw one candle per key of `ohlc`, mapping data→pixels through
+ * `xScale`/`yScale`. The OHLC sibling of {@link drawBox}: each key gets its own
+ * mark over its slot x-span (`barSpanPx`, inset by `gapPx` so adjacent candles
+ * breathe), in the chosen {@link CandleVariant}, coloured per {@link ColorBy}.
+ *
+ * The body extents are derived here (`min`/`max` of open/close) — the consumer
+ * never precomputes them. A doji (open === close) draws a {@link MIN_BODY_HEIGHT_PX}
+ * body so it stays visible. The body is a fraction (`style.bodyWidth`, default
+ * {@link DEFAULT_BODY_WIDTH}) of the slot, centred; the wick / OHLC-bar stem sits
+ * at the slot centre.
+ *
+ * **Gap-aware**: a key with any price non-finite is skipped entirely (no partial
+ * candle) — the same contract as a box / band gap.
+ *
+ * O(N) over the keys, a fixed number of path ops each — no per-key allocation
+ * beyond the `barSpanPx` tuple.
+ */
+export declare function drawCandles(ctx: CanvasRenderingContext2D, ohlc: OhlcSeries, xScale: Scale, yScale: Scale, style: CandleStyle, variant?: CandleVariant, colorBy?: ColorBy, gapPx?: number, minWidthPx?: number): void;
+//# sourceMappingURL=ohlc.d.ts.map

package/dist/ohlc.js

@@ -0,0 +1,153 @@
+import { barSpanPx } from './range.js';
+/** Default body width as a fraction of the candle slot when the style omits one. */
+const DEFAULT_BODY_WIDTH = 0.8;
+/** Minimum body height in px so a doji (open === close) still shows a mark. */
+const MIN_BODY_HEIGHT_PX = 1;
+/**
+ * The `[min, max]` vertical extent of the **drawn** candles — the lowest `low`
+ * and highest `high` over keys where **all four** prices are finite — or `null`
+ * if none are. Gap keys (any price `NaN`) are excluded, matching what
+ * {@link drawCandles} draws, so they don't drag the y-domain.
+ *
+ * Only `low`/`high` bound the extent: they are the outermost reach of a candle,
+ * so `open`/`close` lie within `[low, high]` for any well-formed OHLC row and
+ * never widen it. (A malformed row where, say, `close > high` would clip — an
+ * upstream data error, not the chart's to paper over.)
+ */
+export function ohlcExtent(ohlc) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < ohlc.length; i += 1) {
+        if (!isFiniteOhlc(ohlc, i))
+            continue;
+        const lo = ohlc.low[i];
+        const hi = ohlc.high[i];
+        if (lo < min)
+            min = lo;
+        if (hi > max)
+            max = hi;
+    }
+    return min === Infinity ? null : [min, max];
+}
+/**
+ * The index of the candle whose slot `[x, xEnd]` contains `time` — the candle
+ * **under the cursor** — or `-1` if `time` is in no slot. Containment (the box
+ * analog {@link boxIndexAtTime}), not nearest-by-`begin` (which flips to the next
+ * candle past a wide one's midpoint). Candles are sorted by `x`; at a shared edge
+ * the left candle wins. A gap candle (some price non-finite) still owns its span
+ * here; the caller drops it on the finiteness check. O(N) over the candles
+ * (view-scale).
+ */
+export function ohlcIndexAtTime(ohlc, time) {
+    for (let i = 0; i < ohlc.length; i += 1) {
+        if (time >= ohlc.x[i] && time <= ohlc.xEnd[i])
+            return i;
+    }
+    return -1;
+}
+/** All four prices finite at `i` — i.e. this candle is drawn. */
+export function isFiniteOhlc(ohlc, i) {
+    return (Number.isFinite(ohlc.open[i]) &&
+        Number.isFinite(ohlc.high[i]) &&
+        Number.isFinite(ohlc.low[i]) &&
+        Number.isFinite(ohlc.close[i]));
+}
+/**
+ * Resolve the `{ body, wick }` colours for one candle from its `open`/`close`
+ * and the {@link ColorBy} mode. `direction` picks `rising` (close > open) /
+ * `falling` (close < open) / `neutral` (equal — a doji, falling back to `rising`
+ * when the style omits it); `series` always returns `rising` (one colour, no
+ * up/down split). The single source of the colour decision, shared by
+ * {@link drawCandles} and `<Candlestick>`'s tracker readouts so the pill colour
+ * matches the mark.
+ */
+export function resolveCandleStyle(style, open, close, colorBy) {
+    if (colorBy === 'series')
+        return style.rising;
+    if (close > open)
+        return style.rising;
+    if (close < open)
+        return style.falling;
+    return style.neutral ?? style.rising;
+}
+/**
+ * Draw one candle per key of `ohlc`, mapping data→pixels through
+ * `xScale`/`yScale`. The OHLC sibling of {@link drawBox}: each key gets its own
+ * mark over its slot x-span (`barSpanPx`, inset by `gapPx` so adjacent candles
+ * breathe), in the chosen {@link CandleVariant}, coloured per {@link ColorBy}.
+ *
+ * The body extents are derived here (`min`/`max` of open/close) — the consumer
+ * never precomputes them. A doji (open === close) draws a {@link MIN_BODY_HEIGHT_PX}
+ * body so it stays visible. The body is a fraction (`style.bodyWidth`, default
+ * {@link DEFAULT_BODY_WIDTH}) of the slot, centred; the wick / OHLC-bar stem sits
+ * at the slot centre.
+ *
+ * **Gap-aware**: a key with any price non-finite is skipped entirely (no partial
+ * candle) — the same contract as a box / band gap.
+ *
+ * O(N) over the keys, a fixed number of path ops each — no per-key allocation
+ * beyond the `barSpanPx` tuple.
+ */
+export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle', colorBy = 'direction', gapPx = 0, minWidthPx = 1) {
+    const bodyFraction = style.bodyWidth ?? DEFAULT_BODY_WIDTH;
+    for (let i = 0; i < ohlc.length; i += 1) {
+        if (!isFiniteOhlc(ohlc, i))
+            continue;
+        const open = ohlc.open[i];
+        const close = ohlc.close[i];
+        const [x0, x1] = barSpanPx(ohlc.x[i], ohlc.xEnd[i], xScale, gapPx, minWidthPx);
+        const mid = (x0 + x1) / 2;
+        const bodyHalf = ((x1 - x0) * bodyFraction) / 2;
+        const bx0 = mid - bodyHalf;
+        const bodyW = bodyHalf * 2;
+        const yOpen = yScale(open);
+        const yHigh = yScale(ohlc.high[i]);
+        const yLow = yScale(ohlc.low[i]);
+        const yClose = yScale(close);
+        const { body, wick } = resolveCandleStyle(style, open, close, colorBy);
+        if (variant === 'bar') {
+            // OHLC bar: a high–low stem, a left tick at open, a right tick at close —
+            // all one colour (the `body` role), no filled body.
+            ctx.strokeStyle = body;
+            ctx.lineWidth = style.wickWidth;
+            ctx.beginPath();
+            ctx.moveTo(mid, yHigh); // stem
+            ctx.lineTo(mid, yLow);
+            ctx.moveTo(bx0, yOpen); // open tick (points left)
+            ctx.lineTo(mid, yOpen);
+            ctx.moveTo(mid, yClose); // close tick (points right)
+            ctx.lineTo(mid + bodyHalf, yClose);
+            ctx.stroke();
+            continue;
+        }
+        // candle / hollow: the high–low wick first (so the body overlaps it), then
+        // the open→close body.
+        ctx.strokeStyle = wick;
+        ctx.lineWidth = style.wickWidth;
+        ctx.beginPath();
+        ctx.moveTo(mid, yHigh);
+        ctx.lineTo(mid, yLow);
+        ctx.stroke();
+        // Body extents, with a doji floor so open === close still shows a mark.
+        let top = Math.min(yOpen, yClose);
+        let h = Math.abs(yClose - yOpen);
+        if (h < MIN_BODY_HEIGHT_PX) {
+            top -= (MIN_BODY_HEIGHT_PX - h) / 2;
+            h = MIN_BODY_HEIGHT_PX;
+        }
+        // `hollow`: a rising candle is outlined (hollow), a falling / doji one filled
+        // — the same strict-`>` boundary resolveCandleStyle uses (equality → neutral),
+        // so a doji's fill and its colour agree.
+        const hollow = variant === 'hollow' && close > open;
+        if (hollow) {
+            ctx.strokeStyle = body;
+            ctx.lineWidth = style.wickWidth;
+            ctx.strokeRect(bx0, top, bodyW, h);
+        }
+        else {
+            ctx.fillStyle = body;
+            ctx.fillRect(bx0, top, bodyW, h);
+        }
+    }
+}
+//# sourceMappingURL=ohlc.js.map

package/dist/theme.d.ts

@@ -73,6 +73,22 @@ export interface ChartTheme {
         readonly default: BoxStyle;
         readonly [semantic: string]: BoxStyle;
     };
+    /**
+     * Map from a candle's semantic identifier to its style — a first-class OHLC
+     * mark ({@link Candlestick}), the financial sibling of the box. Unlike the
+     * other slots a {@link CandleStyle} carries a *pair* (`rising`/`falling`, plus
+     * an optional `neutral` doji): direction colouring is intrinsic to the mark, so
+     * one colour can't express it. `default` is the fallback; a chart tags each
+     * series with a role (`<Candlestick as="AAPL" />`) resolving `candle[semantic]
+     * ?? candle.default`. The default pair is **neutral / unbranded** (a
+     * distinguishable up/down, *not* market green/red) — a consumer supplies its
+     * own palette via `cssVarTheme`; the library owns the type + a renderable
+     * default, never a brand.
+     */
+    readonly candle: {
+        readonly default: CandleStyle;
+        readonly [semantic: string]: CandleStyle;
+    };
     /**
      * Map from a bar's semantic identifier to its style — the fill, the
      * selected-bar highlight, and the slot gap / minimum width ({@link BarChart}).
@@ -204,6 +220,42 @@ export interface BoxStyle {
     readonly whisker: string;
     readonly whiskerWidth: number;
 }
+/**
+ * A resolved candlestick style ({@link Candlestick}). A candle is unreadable in
+ * one colour — rising vs falling *must* differ to mean anything — so the style
+ * is a **pair**: `rising` (close > open) and `falling` (close < open), each a
+ * `body` (the open→close rectangle / the OHLC bar) and a `wick` (the high–low
+ * line / the bar's stem). `neutral` styles a **doji** (open === close); it falls
+ * back to `rising` when unset. `bodyWidth` is the body's fraction of the candle
+ * slot (0–1; the wick always sits at the slot centre) — omitted ⇒ `0.8`.
+ * `wickWidth` is the wick / bar stroke width in px.
+ *
+ * With `colorBy='series'` the direction split is bypassed and every candle draws
+ * in the `rising` colours (one colour = one series, for a candle sitting beside
+ * coloured lines).
+ */
+export interface CandleStyle {
+    /** Rising candle (close > open) — body + wick colours. Also the single colour
+     *  under `colorBy='series'`. */
+    readonly rising: {
+        readonly body: string;
+        readonly wick: string;
+    };
+    /** Falling candle (close < open) — body + wick colours. */
+    readonly falling: {
+        readonly body: string;
+        readonly wick: string;
+    };
+    /** Doji (open === close) — body + wick colours; falls back to `rising` if unset. */
+    readonly neutral?: {
+        readonly body: string;
+        readonly wick: string;
+    };
+    /** Body width as a fraction of the candle slot (0–1). Omitted ⇒ `0.8`. */
+    readonly bodyWidth?: number;
+    /** Wick / OHLC-bar stroke width in px. */
+    readonly wickWidth: number;
+}
 /**
  * A resolved area style: an outline stroke plus a graded fill. `color`/`width`
  * stroke the value line on top; `fill` is the gradient base colour, opaque

package/dist/theme.js

@@ -75,6 +75,18 @@ export const defaultTheme = {
             whiskerWidth: 1,
         },
     },
+    candle: {
+        // Neutral / unbranded up-down pair — *not* market green/red (a consumer
+        // supplies that via cssVarTheme). Rising reuses the brand blue; falling the
+        // warm secondary accent — distinguishable at a glance on the light ground.
+        default: {
+            rising: { body: '#2563eb', wick: '#1e3a8a' },
+            falling: { body: '#e8836b', wick: '#b4442a' },
+            neutral: { body: '#94a3b8', wick: '#64748b' },
+            bodyWidth: 0.7,
+            wickWidth: 1,
+        },
+    },
     bar: {
         // Flat blue fill; the selected bar brightens + outlines. `secondary` reuses
         // the line's warm accent for a second series.
@@ -202,6 +214,18 @@ export const estelaTheme = {
             whiskerWidth: 1.5,
         },
     },
+    candle: {
+        // On the dark ground: brand teal rising, warm filament falling — the estela
+        // palette's own up/down, still *not* literal green/red (a financial consumer
+        // like Tidal overlays its market palette via cssVarTheme).
+        default: {
+            rising: { body: '#15B3A6', wick: '#0E7D74' }, // --es-estela
+            falling: { body: '#E0B36A', wick: '#B4863F' }, // --es-filament
+            neutral: { body: '#4E6B6B', wick: '#DBEAE8' }, // --es-slate / --es-mist
+            bodyWidth: 0.7,
+            wickWidth: 1.5,
+        },
+    },
     bar: {
         // Brand-teal fill on the dark ground; the selected bar lifts to the bright
         // reef + an outline. `secondary` is the warm filament accent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.39.0",
-    "pond-ts": "^0.39.0",
+    "@pond-ts/react": "^0.41.0",
+    "pond-ts": "^0.41.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {