wick-charts 0.7.0 → 0.9.0

package/README.md

@@ -19,6 +19,8 @@ npm install wick-charts
   - [Candle data](#candle-data)
   - [Line charts](#line-charts)
   - [Styling](#styling)
+  - [Customizing the hover legend text](#customizing-the-hover-legend-text)
+  - [High-DPI displays (devicePixelRatio)](#high-dpi-displays-devicepixelratio)
   - [Inverting the value axis](#inverting-the-value-axis)
   - [Reading chart state](#reading-chart-state)
   - [Setting the visible range](#setting-the-visible-range)
@@ -229,6 +231,83 @@ type-checks `style` against
 `CandlestickStyle`; the more general `new WickChart(canvas, { type: 'candlestick', style })`
 also works but doesn't — see "Series types" below for why, if you're curious.
 
+Every `px` value above (`font.axisSize`/`legendSize`, `axis.priceWidth`/`timeHeight`,
+`crosshair.labelPaddingX`/`labelPaddingY`, `legend.paddingX`/`paddingY`/`cursorGap`, and
+`LineStyle.lineWidth`) is authored in **CSS pixels** — the intuitive "how big should this look
+on screen" unit — regardless of the canvas's actual backing-store resolution. See the next
+section for what that means in practice.
+
+### Customizing the hover legend text
+
+`legend` above only styles the tooltip's box (colors, padding, offset) — the *text* inside it
+comes from the active series's `formatLegend`, which candlestick/line both ship with a fixed,
+English, OHLC-shaped default. An app that needs different text — localized labels, or a value
+computed from neighboring points, like percent change against the previous candle — overrides
+it per chart instance via `formatLegend`:
+
+```ts
+const chart = createCandlestickChart(canvas, {
+  formatLegend(candle, style, { index, allPoints }) {
+    const prev = allPoints[index - 1];
+    const change = prev ? (((candle.close - prev.close) / prev.close) * 100).toFixed(2) : null;
+    return [
+      `시가 ${candle.open.toLocaleString()}`,
+      `고가 ${candle.high.toLocaleString()}`,
+      `저가 ${candle.low.toLocaleString()}`,
+      `종가 ${candle.close.toLocaleString()}${change === null ? '' : ` (${change}%)`}`,
+    ];
+  },
+});
+```
+
+This replaces the series's `formatLegend` outright for this one chart instance — it doesn't
+merge with the built-in OHLC lines, so return every line you want shown. `allPoints` is every
+point currently loaded (not just visible), the same array a `ChartPlugin` reads through
+`PluginRenderApi.allPoints`; `index` is `candle`'s position in it, so `allPoints[index - 1]` is
+the previous point regardless of where the user has panned/zoomed to.
+
+`SeriesDefinition.formatLegend` (what candlestick/line ship with) is a shared default for every
+chart of that *type*; `WickChartOptions.formatLegend` is the per-*instance* override above it —
+reach for the latter for anything that varies by app, session, or locale rather than by chart
+type. `createCandlestickChart`/`createLineChart` type-check `formatLegend`'s `point`/`style`
+against the concrete series, the same way they type-check `style` itself.
+
+Return `[]` (or `undefined`) to suppress the built-in tooltip entirely — useful if you'd rather
+draw a completely custom tooltip layout yourself via a [`ChartPlugin`](#extending-plugins),
+using `chart.getHoveredPoint()` to know what's hovered.
+
+### High-DPI displays (devicePixelRatio)
+
+The [Quick start](#quick-start) resize snippet sizes the canvas's backing store
+(`canvas.width`/`height`) to `devicePixelRatio` times its CSS display size — the standard
+recipe for a crisp, non-blurry `<canvas>` on a Retina/high-DPI screen. wick-charts detects this
+itself, live, by comparing `canvas.width`/`height` against `canvas.getBoundingClientRect()` on
+every frame — there's no `devicePixelRatio` option to set, and nothing to recompute yourself on
+resize or on a browser zoom change; the chart just reads whatever the canvas's current backing
+store vs. CSS size actually is.
+
+Once detected, every CSS-pixel size option listed at the end of the previous section is scaled
+by that ratio before it's used — so `axisSize: 10` always looks like a 10px font on screen,
+whether the backing store is 1x or 3x the CSS size, and you never have to pre-multiply any
+option by `window.devicePixelRatio` yourself. (Colors and tick counts — `priceTickCount`,
+`timeMaxTicks` — aren't sizes and pass through unscaled.)
+
+This only reaches what the engine itself draws. A `ChartPlugin` or a custom `SeriesDefinition`
+sets its own canvas properties directly (`ctx.lineWidth`, a font size in `ctx.font`, a marker
+radius), and the engine has no way to know which of those are meant to be sizes — so both
+`PluginRenderApi` and `SeriesDrawContext` carry a `devicePixelRatio` field for exactly this:
+multiply your own literal pixel sizes by it before setting them on `ctx`, the same way the
+built-in line series scales `LineStyle.lineWidth`:
+
+```ts
+// inside a ChartPlugin's draw(api), or a custom SeriesDefinition's draw(context, style)
+ctx.lineWidth = 2 * api.devicePixelRatio; // always ~2 CSS px, not 2 backing-store px
+```
+
+If you never resize the canvas to a scaled backing store at all (`canvas.width` already equals
+its CSS display size, the default for an unstyled `<canvas>`), the ratio is exactly 1 and
+nothing here changes anything.
+
 ### Inverting the value axis
 
 `invertValueAxis` mirrors the value axis top-to-bottom — every pane's higher values render

package/dist/axisRenderer.d.ts

@@ -0,0 +1,39 @@
+import type { Scale } from './hybridScale.js';
+import type { ChartAxisOptions, ChartFontOptions } from './types.js';
+/**
+ * Draws the price/time axis chrome — boundary lines, grid lines, tick
+ * labels, and the separator between stacked panes. Split out of
+ * `ChartRenderer` because none of it needs anything beyond already-resolved
+ * style options and per-call geometry (a `Scale`, a pixel rect): no
+ * series-specific, plugin-specific, or pane-identity state crosses into
+ * this class — `ChartRenderer.render()` still owns deciding *what* to draw
+ * where (the main pane vs. each indicator pane, in what order), this only
+ * owns *how* one axis actually gets drawn once told where.
+ */
+export declare class AxisRenderer {
+    private ctx;
+    private axis;
+    private font;
+    constructor(ctx: CanvasRenderingContext2D, axis: Required<ChartAxisOptions>, font: Required<ChartFontOptions>);
+    private axisFont;
+    /** The decimal precision `formatPrice` should use for a given value
+     * range — shared by this class's own tick labels and
+     * `CrosshairRenderer`'s price label so both display the same value with
+     * the same rounding. */
+    priceStep(min: number, max: number): number;
+    /**
+     * Draws one pane's right-side value axis: boundary line, horizontal grid
+     * lines, and tick labels. Used for both the main price pane and every
+     * indicator pane — `topOffset` shifts everything down by that pane's own
+     * position in the stack (0 for the main pane, which sits at the top), so
+     * `yScale` only ever has to know about its own pane-local [0, chartHeight]
+     * range and never about where that pane lives in the full canvas.
+     */
+    renderPriceAxis(priceMin: number, priceMax: number, step: number, yScale: Scale, chartWidth: number, chartHeight: number, topOffset: number): void;
+    /** The horizontal rule separating an indicator pane from whatever sits
+     * above it (the main pane, or the previous indicator pane) — the same
+     * `axis.lineColor` boundary style `renderTimeAxis` already draws between
+     * the plotting area and the time-axis strip. */
+    renderPaneSeparator(top: number, chartWidth: number): void;
+    renderTimeAxis(times: number[], startIdx: number, visibleCount: number, chartHeight: number, chartWidth: number, xForIndex: (globalIndex: number) => number): void;
+}

package/dist/axisRenderer.js

@@ -0,0 +1,94 @@
+import { formatAxisLabel, pickTickIndices } from './axis.js';
+import { formatPrice, niceTicks } from './priceAxis.js';
+/**
+ * Draws the price/time axis chrome — boundary lines, grid lines, tick
+ * labels, and the separator between stacked panes. Split out of
+ * `ChartRenderer` because none of it needs anything beyond already-resolved
+ * style options and per-call geometry (a `Scale`, a pixel rect): no
+ * series-specific, plugin-specific, or pane-identity state crosses into
+ * this class — `ChartRenderer.render()` still owns deciding *what* to draw
+ * where (the main pane vs. each indicator pane, in what order), this only
+ * owns *how* one axis actually gets drawn once told where.
+ */
+export class AxisRenderer {
+    constructor(ctx, axis, font) {
+        this.ctx = ctx;
+        this.axis = axis;
+        this.font = font;
+    }
+    axisFont() {
+        return `${this.font.axisSize}px ${this.font.family}`;
+    }
+    /** The decimal precision `formatPrice` should use for a given value
+     * range — shared by this class's own tick labels and
+     * `CrosshairRenderer`'s price label so both display the same value with
+     * the same rounding. */
+    priceStep(min, max) {
+        const ticks = niceTicks(min, max, this.axis.priceTickCount);
+        return ticks.length > 1 ? ticks[1] - ticks[0] : 0;
+    }
+    /**
+     * Draws one pane's right-side value axis: boundary line, horizontal grid
+     * lines, and tick labels. Used for both the main price pane and every
+     * indicator pane — `topOffset` shifts everything down by that pane's own
+     * position in the stack (0 for the main pane, which sits at the top), so
+     * `yScale` only ever has to know about its own pane-local [0, chartHeight]
+     * range and never about where that pane lives in the full canvas.
+     */
+    renderPriceAxis(priceMin, priceMax, step, yScale, chartWidth, chartHeight, topOffset) {
+        const { ctx, axis } = this;
+        const ticks = niceTicks(priceMin, priceMax, axis.priceTickCount);
+        ctx.strokeStyle = axis.lineColor;
+        ctx.beginPath();
+        ctx.moveTo(chartWidth + 0.5, topOffset);
+        ctx.lineTo(chartWidth + 0.5, topOffset + chartHeight);
+        ctx.stroke();
+        ctx.font = this.axisFont();
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'middle';
+        for (const value of ticks) {
+            const localY = yScale.map(value);
+            if (localY < 0 || localY > chartHeight)
+                continue;
+            const y = topOffset + localY;
+            ctx.strokeStyle = axis.gridLineColor;
+            ctx.beginPath();
+            ctx.moveTo(0, y + 0.5);
+            ctx.lineTo(chartWidth, y + 0.5);
+            ctx.stroke();
+            ctx.fillStyle = axis.textColor;
+            ctx.fillText(formatPrice(value, step), chartWidth + 6, y);
+        }
+    }
+    /** The horizontal rule separating an indicator pane from whatever sits
+     * above it (the main pane, or the previous indicator pane) — the same
+     * `axis.lineColor` boundary style `renderTimeAxis` already draws between
+     * the plotting area and the time-axis strip. */
+    renderPaneSeparator(top, chartWidth) {
+        const { ctx, axis } = this;
+        ctx.strokeStyle = axis.lineColor;
+        ctx.beginPath();
+        ctx.moveTo(0, top + 0.5);
+        ctx.lineTo(chartWidth, top + 0.5);
+        ctx.stroke();
+    }
+    renderTimeAxis(times, startIdx, visibleCount, chartHeight, chartWidth, xForIndex) {
+        const { ctx, axis } = this;
+        const visibleTimes = times.slice(startIdx, startIdx + visibleCount);
+        const spanSeconds = visibleTimes[visibleTimes.length - 1] - visibleTimes[0];
+        ctx.strokeStyle = axis.lineColor;
+        ctx.beginPath();
+        ctx.moveTo(0, chartHeight + 0.5);
+        ctx.lineTo(chartWidth, chartHeight + 0.5);
+        ctx.stroke();
+        ctx.fillStyle = axis.textColor;
+        ctx.font = this.axisFont();
+        ctx.textAlign = 'center';
+        ctx.textBaseline = 'top';
+        for (const localIndex of pickTickIndices(visibleCount, axis.timeMaxTicks)) {
+            const x = xForIndex(startIdx + localIndex);
+            const label = formatAxisLabel(visibleTimes[localIndex], spanSeconds);
+            ctx.fillText(label, x, chartHeight + 6);
+        }
+    }
+}

package/dist/binarySearch.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Binary search over an ascending-sorted number array — extracted out of
+ * `WickChart` since it's pure array math with no dependency on chart state,
+ * used by `setVisibleTimeRange` to resolve a time to its index.
+ */
+/** First index in `values` (ascending) whose value is `>= target`, or
+ * `values.length` if every value is smaller — the standard binary
+ * lower-bound, O(log n) rather than a linear scan over what can be a
+ * multi-thousand-point loaded series. */
+export declare function lowerBound(values: number[], target: number): number;
+/** First index in `values` (ascending) whose value is `> target`, or
+ * `values.length` if none is — the exclusive end boundary for an inclusive
+ * upper bound, so a range `[lowerBound(from), upperBound(to))` includes
+ * every value in `[from, to]` inclusive on both ends. */
+export declare function upperBound(values: number[], target: number): number;

package/dist/binarySearch.js

@@ -0,0 +1,37 @@
+/**
+ * Binary search over an ascending-sorted number array — extracted out of
+ * `WickChart` since it's pure array math with no dependency on chart state,
+ * used by `setVisibleTimeRange` to resolve a time to its index.
+ */
+/** First index in `values` (ascending) whose value is `>= target`, or
+ * `values.length` if every value is smaller — the standard binary
+ * lower-bound, O(log n) rather than a linear scan over what can be a
+ * multi-thousand-point loaded series. */
+export function lowerBound(values, target) {
+    let lo = 0;
+    let hi = values.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (values[mid] < target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/** First index in `values` (ascending) whose value is `> target`, or
+ * `values.length` if none is — the exclusive end boundary for an inclusive
+ * upper bound, so a range `[lowerBound(from), upperBound(to))` includes
+ * every value in `[from, to]` inclusive on both ends. */
+export function upperBound(values, target) {
+    let lo = 0;
+    let hi = values.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (values[mid] <= target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}

package/dist/crosshairRenderer.d.ts

@@ -0,0 +1,60 @@
+import type { ChartCrosshairOptions, ChartFontOptions, ChartLegendOptions } from './types.js';
+/** Everything one frame's hover crosshair/legend needs — computed by
+ * `ChartRenderer.render()` (which owns the hovered point, the active
+ * series, and its style) and handed in as plain data so this class stays
+ * generic-free and series-agnostic. `legendParts` is already the result of
+ * `seriesDefinition.formatLegend?.(point, style)` — this class only lays
+ * out and draws whatever strings it's given. */
+export interface CrosshairRenderInput {
+    x: number;
+    timeSeconds: number;
+    hoverY: number | null;
+    valueMin: number;
+    valueMax: number;
+    priceStep: number;
+    chartWidth: number;
+    chartHeight: number;
+    /** Full pane-stack height — the dashed vertical line spans this, not
+     * just `chartHeight` (the main pane's own), so a hovered candle lines up
+     * across every indicator pane below it. */
+    stackHeight: number;
+    invertValueAxis: boolean;
+    legendParts: string[];
+    /** The canvas's own backing-store width — needed only to clamp the
+     * time-axis label chip so it never runs off the right edge. */
+    canvasWidth: number;
+}
+/**
+ * Draws the hover crosshair (dashed lines), its price/time label chips,
+ * and the OHLC-style legend tooltip. Split out of `ChartRenderer` for the
+ * same reason `AxisRenderer` was: everything it needs arrives as
+ * already-resolved style options plus one frame's worth of plain data
+ * (`CrosshairRenderInput`) — no series generic, no plugin state.
+ */
+export declare class CrosshairRenderer {
+    private ctx;
+    private crosshair;
+    private legend;
+    private font;
+    private priceAxisWidth;
+    constructor(ctx: CanvasRenderingContext2D, crosshair: Required<ChartCrosshairOptions>, legend: Required<ChartLegendOptions>, font: Required<ChartFontOptions>, priceAxisWidth: number);
+    private axisFont;
+    private legendFont;
+    render(input: CrosshairRenderInput): void;
+    /** The OHLC(+volume) tooltip — floats near the hovered pixel like a
+     * speech bubble, one line per part, rather than a fixed banner glued to
+     * a corner of the canvas. Offset up-and-right of the cursor/finger by
+     * `legend.cursorGap` and clamped to both chart edges so it never runs
+     * off-screen, including when there's no `hoverY` to anchor to (a series
+     * with no primary value still gets a legend, just pinned near the top
+     * at the hovered column). */
+    private renderHoverTooltip;
+    /** The highlighted price-axis label that follows the crosshair's
+     * horizontal line — drawn over `AxisRenderer`'s own tick labels so the
+     * hovered value reads clearly even where it lands between two ticks. */
+    private renderPriceLabelChip;
+    /** The highlighted time-axis label under the crosshair's vertical line.
+     * Clamped so its background chip stays fully on-screen even when the
+     * hovered point sits at the very first or last visible index. */
+    private renderTimeLabelChip;
+}

package/dist/crosshairRenderer.js

@@ -0,0 +1,121 @@
+import { formatHoverTime } from './axis.js';
+import { formatPrice } from './priceAxis.js';
+import { pixelToValue } from './valueAxis.js';
+/**
+ * Draws the hover crosshair (dashed lines), its price/time label chips,
+ * and the OHLC-style legend tooltip. Split out of `ChartRenderer` for the
+ * same reason `AxisRenderer` was: everything it needs arrives as
+ * already-resolved style options plus one frame's worth of plain data
+ * (`CrosshairRenderInput`) — no series generic, no plugin state.
+ */
+export class CrosshairRenderer {
+    constructor(ctx, crosshair, legend, font, priceAxisWidth) {
+        this.ctx = ctx;
+        this.crosshair = crosshair;
+        this.legend = legend;
+        this.font = font;
+        this.priceAxisWidth = priceAxisWidth;
+    }
+    axisFont() {
+        return `${this.font.axisSize}px ${this.font.family}`;
+    }
+    legendFont() {
+        return `${this.font.legendSize}px ${this.font.family}`;
+    }
+    render(input) {
+        const { x, timeSeconds, hoverY, valueMin, valueMax, priceStep, chartWidth, chartHeight, stackHeight, invertValueAxis, legendParts, canvasWidth, } = input;
+        const { ctx, crosshair } = this;
+        ctx.save();
+        ctx.strokeStyle = crosshair.lineColor;
+        ctx.setLineDash([4, 4]);
+        // Spans the whole pane stack (not just the main pane's own
+        // chartHeight) so hovering a candle lines up with the same column
+        // across every indicator pane below it — see `stackHeight`'s own doc
+        // comment for why the horizontal line/legend don't follow suit.
+        ctx.beginPath();
+        ctx.moveTo(x, 0);
+        ctx.lineTo(x, stackHeight);
+        ctx.stroke();
+        // The horizontal line follows the actual cursor/finger position, not
+        // any property of the hovered point — pinning it to (say) the candle's
+        // close would leave it motionless while the pointer moves anywhere
+        // within that same candle's column, which reads as broken/stuck rather
+        // than as a crosshair. Only drawn while the pointer is actually inside
+        // the chart's vertical extent, same as AxisRenderer's tick-skip logic.
+        const priceLineVisible = hoverY !== null && hoverY >= 0 && hoverY <= chartHeight;
+        if (priceLineVisible) {
+            ctx.beginPath();
+            ctx.moveTo(0, hoverY);
+            ctx.lineTo(chartWidth, hoverY);
+            ctx.stroke();
+        }
+        ctx.restore();
+        if (priceLineVisible) {
+            // Exact inverse of the value->y mapping createScale set up for this
+            // frame — same helper (and same invertValueAxis flag) as
+            // PluginRenderApi.valueForY, see src/valueAxis.ts.
+            const value = pixelToValue(hoverY, valueMin, valueMax, chartHeight, invertValueAxis);
+            this.renderPriceLabelChip(formatPrice(value, priceStep), hoverY, chartWidth);
+        }
+        this.renderTimeLabelChip(formatHoverTime(timeSeconds), x, chartHeight, canvasWidth);
+        if (legendParts.length === 0)
+            return;
+        this.renderHoverTooltip(legendParts, x, hoverY, chartWidth, chartHeight);
+    }
+    /** The OHLC(+volume) tooltip — floats near the hovered pixel like a
+     * speech bubble, one line per part, rather than a fixed banner glued to
+     * a corner of the canvas. Offset up-and-right of the cursor/finger by
+     * `legend.cursorGap` and clamped to both chart edges so it never runs
+     * off-screen, including when there's no `hoverY` to anchor to (a series
+     * with no primary value still gets a legend, just pinned near the top
+     * at the hovered column). */
+    renderHoverTooltip(lines, x, hoverY, chartWidth, chartHeight) {
+        const { ctx, font, legend } = this;
+        ctx.font = this.legendFont();
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'top';
+        const lineHeight = font.legendSize + 4;
+        const textWidth = Math.max(...lines.map((line) => ctx.measureText(line).width));
+        const boxWidth = textWidth + legend.paddingX * 2;
+        const boxHeight = lines.length * lineHeight + legend.paddingY * 2;
+        const anchorY = hoverY ?? 0;
+        const left = Math.min(Math.max(x + legend.cursorGap, 0), Math.max(0, chartWidth - boxWidth));
+        const top = Math.min(Math.max(anchorY - boxHeight - legend.cursorGap, 0), Math.max(0, chartHeight - boxHeight));
+        ctx.fillStyle = legend.background;
+        ctx.fillRect(left, top, boxWidth, boxHeight);
+        ctx.fillStyle = legend.textColor;
+        lines.forEach((line, i) => {
+            ctx.fillText(line, left + legend.paddingX, top + legend.paddingY + i * lineHeight);
+        });
+    }
+    /** The highlighted price-axis label that follows the crosshair's
+     * horizontal line — drawn over `AxisRenderer`'s own tick labels so the
+     * hovered value reads clearly even where it lands between two ticks. */
+    renderPriceLabelChip(text, y, chartWidth) {
+        const { ctx, font, crosshair } = this;
+        ctx.font = this.axisFont();
+        const chipHeight = font.axisSize + crosshair.labelPaddingY * 2;
+        ctx.fillStyle = crosshair.labelBackground;
+        ctx.fillRect(chartWidth, y - chipHeight / 2, this.priceAxisWidth, chipHeight);
+        ctx.fillStyle = crosshair.labelTextColor;
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'middle';
+        ctx.fillText(text, chartWidth + crosshair.labelPaddingX, y);
+    }
+    /** The highlighted time-axis label under the crosshair's vertical line.
+     * Clamped so its background chip stays fully on-screen even when the
+     * hovered point sits at the very first or last visible index. */
+    renderTimeLabelChip(text, x, chartHeight, canvasWidth) {
+        const { ctx, font, crosshair } = this;
+        ctx.font = this.axisFont();
+        const chipWidth = ctx.measureText(text).width + crosshair.labelPaddingX * 2;
+        const chipHeight = font.axisSize + crosshair.labelPaddingY * 2;
+        const chipLeft = Math.min(Math.max(x - chipWidth / 2, 0), canvasWidth - chipWidth);
+        ctx.fillStyle = crosshair.labelBackground;
+        ctx.fillRect(chipLeft, chartHeight, chipWidth, chipHeight);
+        ctx.fillStyle = crosshair.labelTextColor;
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'top';
+        ctx.fillText(text, chipLeft + crosshair.labelPaddingX, chartHeight + crosshair.labelPaddingY);
+    }
+}

package/dist/devicePixelRatio.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ratio between a canvas's backing-store size and its CSS display size —
+ * `canvas.width / rect.width` (or `.height`), the same signal
+ * `window.devicePixelRatio` gives once a canvas has actually been resized to
+ * match it (see the README's "High-DPI displays" section for the resize
+ * recipe this reads back). Read live off the canvas and its bounding rect
+ * rather than cached anywhere, so a change — a window dragged to a
+ * different-DPI monitor, a browser zoom level change, or simply an app
+ * resizing the canvas — is picked up on the very next call with no explicit
+ * resize notification needed, the same way `ChartRenderer.chartWidth`/
+ * `chartHeight` already track `canvas.width`/`height` live instead of
+ * caching them at construction.
+ *
+ * Returns 1 (no scaling) when the CSS size is 0 — an unattached or
+ * zero-size canvas — rather than dividing by zero.
+ */
+export declare function devicePixelRatio(canvas: HTMLCanvasElement, axis?: 'width' | 'height'): number;

package/dist/devicePixelRatio.js

@@ -0,0 +1,22 @@
+/**
+ * Ratio between a canvas's backing-store size and its CSS display size —
+ * `canvas.width / rect.width` (or `.height`), the same signal
+ * `window.devicePixelRatio` gives once a canvas has actually been resized to
+ * match it (see the README's "High-DPI displays" section for the resize
+ * recipe this reads back). Read live off the canvas and its bounding rect
+ * rather than cached anywhere, so a change — a window dragged to a
+ * different-DPI monitor, a browser zoom level change, or simply an app
+ * resizing the canvas — is picked up on the very next call with no explicit
+ * resize notification needed, the same way `ChartRenderer.chartWidth`/
+ * `chartHeight` already track `canvas.width`/`height` live instead of
+ * caching them at construction.
+ *
+ * Returns 1 (no scaling) when the CSS size is 0 — an unattached or
+ * zero-size canvas — rather than dividing by zero.
+ */
+export function devicePixelRatio(canvas, axis = 'width') {
+    const rect = canvas.getBoundingClientRect();
+    const cssSize = axis === 'width' ? rect.width : rect.height;
+    const deviceSize = axis === 'width' ? canvas.width : canvas.height;
+    return cssSize === 0 ? 1 : deviceSize / cssSize;
+}

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import type { DataLoader } from './dataSource.js';
 import type { ChartPlugin } from './plugins/types.js';
 import type { CandlestickStyle } from './series/candlestick.js';
 import type { LineStyle } from './series/line.js';
-import type { Candle, LinePoint, PaneOptions, WickChartOptions, SeriesPoint, ValueRange, WickTime } from './types.js';
-export type { BusinessDay, Candle, LinePoint, PaneOptions, WickChartOptions, WickTime, SeriesPoint, UnixMillis, ValueRange, } from './types.js';
+import type { Candle, LegendFormatContext, LinePoint, PaneOptions, WickChartOptions, SeriesPoint, ValueRange, WickTime } from './types.js';
+export type { BusinessDay, Candle, LegendFormatContext, LinePoint, PaneOptions, WickChartOptions, WickTime, SeriesPoint, UnixMillis, ValueRange, } from './types.js';
 export type { DataLoader, DataRequest } from './dataSource.js';
 export type { ChartPlugin, ChartPointerEvent, PluginRenderApi } from './plugins/types.js';
 export { distanceToSegment, hitTestPoint, hitTestSegment } from './hitTest.js';
@@ -326,8 +326,13 @@ export declare class WickChart<TPoint extends SeriesPoint = Candle> {
  * one) rather than widening `WickChartOptions` itself — that keeps every
  * series's style shape independent of every other's.
  */
-export declare function createCandlestickChart(canvas: HTMLCanvasElement, options?: Omit<WickChartOptions, 'type' | 'style'> & {
+export declare function createCandlestickChart(canvas: HTMLCanvasElement, options?: Omit<WickChartOptions, 'type' | 'style' | 'formatLegend'> & {
     style?: Partial<CandlestickStyle>;
+    /** Same override as `WickChartOptions.formatLegend`, with `point`/`style`/
+     * `context` narrowed to this series's own types instead of the general
+     * (unchecked) `SeriesPoint`/`unknown` shape `WickChartOptions` itself
+     * allows — see its doc comment for what this is for. */
+    formatLegend?(point: Candle, style: CandlestickStyle, context: LegendFormatContext<Candle>): string[];
 }): WickChart<Candle>;
 /**
  * The second series type's equivalent of `createCandlestickChart` above —
@@ -336,6 +341,9 @@ export declare function createCandlestickChart(canvas: HTMLCanvasElement, option
  * `Record<string, unknown>` `WickChartOptions.style` allows for `new
  * WickChart(canvas, { type: 'line', style })`.
  */
-export declare function createLineChart(canvas: HTMLCanvasElement, options?: Omit<WickChartOptions, 'type' | 'style'> & {
+export declare function createLineChart(canvas: HTMLCanvasElement, options?: Omit<WickChartOptions, 'type' | 'style' | 'formatLegend'> & {
     style?: Partial<LineStyle>;
+    /** Same override as `WickChartOptions.formatLegend`, narrowed to this
+     * series's own types — see `createCandlestickChart`'s equivalent. */
+    formatLegend?(point: LinePoint, style: LineStyle, context: LegendFormatContext<LinePoint>): string[];
 }): WickChart<LinePoint>;

package/dist/index.js

@@ -1,3 +1,5 @@
+import { lowerBound, upperBound } from './binarySearch.js';
+import { devicePixelRatio } from './devicePixelRatio.js';
 import { mergeSeriesPoints } from './mergeSeries.js';
 import { computePaneLayout } from './paneLayout.js';
 import { ChartRenderer } from './renderer.js';
@@ -45,39 +47,6 @@ const LONG_PRESS_MS = 350;
  * as a real drag, not a hold — cancels the pending long-press timer so a
  * fast pan gesture never flips into scrub mid-motion. */
 const LONG_PRESS_MOVE_TOLERANCE_PX = 10;
-/** First index in `times` (ascending) whose value is `>= target`, or
- * `times.length` if every value is smaller — the standard binary
- * lower-bound, O(log n) rather than a linear scan over what can be a
- * multi-thousand-point loaded series. Used by `setVisibleTimeRange` to
- * resolve a `from` time to its start index. */
-function lowerBound(times, target) {
-    let lo = 0;
-    let hi = times.length;
-    while (lo < hi) {
-        const mid = (lo + hi) >>> 1;
-        if (times[mid] < target)
-            lo = mid + 1;
-        else
-            hi = mid;
-    }
-    return lo;
-}
-/** First index in `times` (ascending) whose value is `> target`, or
- * `times.length` if none is — the exclusive end boundary for a `to` time,
- * so a range `[lowerBound(from), upperBound(to))` includes every point
- * with a time in `[from, to]` inclusive on both ends. */
-function upperBound(times, target) {
-    let lo = 0;
-    let hi = times.length;
-    while (lo < hi) {
-        const mid = (lo + hi) >>> 1;
-        if (times[mid] <= target)
-            lo = mid + 1;
-        else
-            hi = mid;
-    }
-    return lo;
-}
 /**
  * Interactive chart: drag to pan, wheel to zoom, drag the price-axis strip
  * to rescale it, hover a point for a legend. What gets plotted (candles
@@ -873,12 +842,10 @@ export class WickChart {
      * conversion `cursorPosition` applies to absolute coordinates, extracted
      * so pixel *deltas* (drag distance, wheel deltaX) can be converted too. */
     devicePixelScaleX() {
-        const rect = this.canvas.getBoundingClientRect();
-        return rect.width === 0 ? 1 : this.canvas.width / rect.width;
+        return devicePixelRatio(this.canvas, 'width');
     }
     devicePixelScaleY() {
-        const rect = this.canvas.getBoundingClientRect();
-        return rect.height === 0 ? 1 : this.canvas.height / rect.height;
+        return devicePixelRatio(this.canvas, 'height');
     }
 }
 /**

package/dist/plugins/types.d.ts

@@ -17,6 +17,15 @@ export interface PluginRenderApi<TPoint extends SeriesPoint = SeriesPoint> {
     ctx: CanvasRenderingContext2D;
     chartWidth: number;
     chartHeight: number;
+    /** Ratio between the canvas's backing-store size and its CSS display
+     * size — 1 on a standard-DPI display, 2 on a typical Retina one.
+     * `chartWidth`/`chartHeight` and everything `xForIndex`/`yForValue`
+     * return are already in backing-store pixels, but a plugin choosing its
+     * *own* literal pixel sizes (`ctx.lineWidth`, a font size in
+     * `ctx.font`, a marker radius) should multiply them by this first, the
+     * same way the built-in line series scales `LineStyle.lineWidth` — see
+     * "High-DPI displays" in the README. */
+    devicePixelRatio: number;
     /** Global (full sorted-array) index -> x pixel, same convention the
      * active series draws with. Valid only for the duration of this `draw()`
      * call — see the interface-level note on `PluginRenderApi`. */

package/dist/renderer.d.ts

@@ -12,8 +12,8 @@ export interface RenderInput<TPoint extends SeriesPoint> {
     hoverIndex: number | null;
     /** Device-pixel y of the pointer/finger that produced `hoverIndex`, or
      * null. Drives the crosshair's horizontal line directly — see
-     * `renderCrosshairAndLegend` for why that has to be the raw cursor
-     * position rather than any property of the hovered point itself. */
+     * `CrosshairRenderer` for why that has to be the raw cursor position
+     * rather than any property of the hovered point itself. */
     hoverY: number | null;
     plugins: ChartPlugin<TPoint>[];
     /** Indicator/oscillator panes declared via `WickChart.addPane`, resolved
@@ -23,20 +23,33 @@ export interface RenderInput<TPoint extends SeriesPoint> {
     panes: ResolvedPaneOptions[];
 }
 /**
- * The chart engine's renderer: canvas lifecycle, axes, crosshair, and
- * plugin drawing are all generic — none of it knows what kind of series is
- * on screen. The one series-specific seam is `seriesDefinition`, injected
- * at construction (see `src/series/types.ts`); everything above delegates
- * to it for value-range computation, point drawing, and legend text.
+ * The chart engine's renderer: owns the canvas lifecycle and orchestrates
+ * one frame — deciding what data is visible, computing scales, and calling
+ * out to collaborators for the actual pixel-pushing. None of it knows what
+ * kind of series is on screen: the one series-specific seam is
+ * `seriesDefinition`, injected at construction (see `src/series/types.ts`).
  * Stateless per call otherwise — all pan/zoom/hover state lives in
  * `Viewport` and `WickChart`; this class only turns a snapshot of that
  * state into pixels.
  *
+ * Axis chrome and the hover crosshair/legend are drawn by two collaborators
+ * (`AxisRenderer`, `CrosshairRenderer`) rather than methods on this class —
+ * both take only already-resolved style options and per-call geometry, no
+ * series generic or plugin state, so splitting them out keeps this file
+ * focused on orchestration (what gets drawn, in what order, with what
+ * scale) rather than mixing in how each individual chrome element paints.
+ *
  * Every visual constant below (fonts, axis sizing/coloring, crosshair
  * coloring/padding, legend color) is resolved once at construction from
  * `WickChartOptions.font`/`axis`/`crosshair`/`legend`, each merged field
  * by field over its own defaults — nothing here is a hardcoded module
- * constant a caller can't reach.
+ * constant a caller can't reach. Every *size* among them (font sizes, axis
+ * strip widths, padding, gaps) is specified in CSS pixels and scaled by the
+ * canvas's live devicePixelRatio (see `deviceRatio`) at the top of every
+ * `render()` call before use — colors and tick counts pass through
+ * unscaled. `AxisRenderer`/`CrosshairRenderer` themselves stay unaware of
+ * this: they're handed already-scaled options each frame, the same as they
+ * were handed unscaled ones before this existed.
  */
 export declare class ChartRenderer<TPoint extends SeriesPoint> {
     private canvas;
@@ -44,8 +57,15 @@ export declare class ChartRenderer<TPoint extends SeriesPoint> {
     private ctx;
     private background;
     private style;
-    private font;
+    /** Author-facing (CSS-pixel) style groups, resolved once at construction
+     * from `WickChartOptions.font`/`axis`/`crosshair`/`legend` — kept as
+     * fields so `render()` can rescale them fresh every frame against the
+     * canvas's current devicePixelRatio, which (a window dragged to a
+     * different-DPI monitor, a browser zoom change, or the app simply
+     * resizing the canvas) can change between frames. `axis` is additionally
+     * read directly by `chartWidth`/`chartHeight`/`priceAxisWidth` below. */
     private axis;
+    private font;
     private crosshair;
     private legend;
     /** Unlike the style groups above, mutable after construction — see
@@ -54,16 +74,26 @@ export declare class ChartRenderer<TPoint extends SeriesPoint> {
      * opposite way" view a user flips on and off), so it doesn't get the
      * "resolved once in the constructor" treatment those get. */
     private invertValueAxis;
+    /** Per-instance override of `seriesDefinition.formatLegend` — see
+     * `WickChartOptions.formatLegend`'s own doc comment for why this exists
+     * as a chart-instance option rather than only a series-type one. */
+    private formatLegendOverride?;
     constructor(canvas: HTMLCanvasElement, seriesDefinition: SeriesDefinition<TPoint, unknown>, options?: WickChartOptions);
     setInvertValueAxis(inverted: boolean): void;
+    /** Ratio between the canvas's backing-store size and its CSS display
+     * size — read live, not cached, for the same reason `chartWidth`/
+     * `chartHeight` below read `canvas.width`/`height` live: whatever it is
+     * *right now* is what this frame draws at. See `src/devicePixelRatio.ts`. */
+    private get deviceRatio();
     /** Pixel width of the point-plotting area — excludes the price-axis
      * strip on the right. Exposed so `WickChart` can convert cursor pixel
-     * positions to point indices / values for hit-testing and dragging. */
+     * positions to point indices / values for hit-testing and dragging.
+     * `priceAxisWidth` below is already devicePixelRatio-scaled, so this
+     * (and `chartHeight`) stay correct on a high-DPI canvas without
+     * `WickChart` having to know anything about DPR itself. */
     get chartWidth(): number;
     get chartHeight(): number;
     get priceAxisWidth(): number;
-    private axisFont;
-    private legendFont;
     render(input: RenderInput<TPoint>): void;
     /**
      * Builds the `PluginRenderApi` for one pane — the main price pane or a
@@ -73,40 +103,4 @@ export declare class ChartRenderer<TPoint extends SeriesPoint> {
      * frame-ended flag, for the whole stack; see `FrameGeometry`).
      */
     private buildPluginApi;
-    /** The decimal precision `formatPrice` should use for the current price
-     * range — shared by the axis ticks and the crosshair's price label so
-     * both display the same value with the same rounding. */
-    private currentPriceStep;
-    /**
-     * Draws one pane's right-side value axis: boundary line, horizontal grid
-     * lines, and tick labels. Used for both the main price pane and every
-     * indicator pane — `topOffset` shifts everything down by that pane's own
-     * position in the stack (0 for the main pane, which sits at the top), so
-     * `yScale` only ever has to know about its own pane-local [0, chartHeight]
-     * range and never about where that pane lives in the full canvas.
-     */
-    private renderPriceAxis;
-    /** The horizontal rule separating an indicator pane from whatever sits
-     * above it (the main pane, or the previous indicator pane) — the same
-     * `axis.lineColor` boundary style `renderTimeAxis` already draws between
-     * the plotting area and the time-axis strip. */
-    private renderPaneSeparator;
-    private renderTimeAxis;
-    private renderCrosshairAndLegend;
-    /** The OHLC(+volume) tooltip — floats near the hovered pixel like a
-     * speech bubble, one line per part, rather than a fixed banner glued to
-     * a corner of the canvas. Offset up-and-right of the cursor/finger by
-     * `legend.cursorGap` and clamped to both chart edges so it never runs
-     * off-screen, including when there's no `hoverY` to anchor to (a series
-     * with no primary value still gets a legend, just pinned near the top
-     * at the hovered column). */
-    private renderHoverTooltip;
-    /** The highlighted price-axis label that follows the crosshair's
-     * horizontal line — drawn over `renderPriceAxis`'s own tick labels so the
-     * hovered value reads clearly even where it lands between two ticks. */
-    private renderPriceLabelChip;
-    /** The highlighted time-axis label under the crosshair's vertical line.
-     * Clamped so its background chip stays fully on-screen even when the
-     * hovered point sits at the very first or last visible index. */
-    private renderTimeLabelChip;
 }

package/dist/renderer.js

@@ -1,7 +1,8 @@
-import { formatAxisLabel, formatHoverTime, pickTickIndices } from './axis.js';
+import { AxisRenderer } from './axisRenderer.js';
+import { CrosshairRenderer } from './crosshairRenderer.js';
+import { devicePixelRatio } from './devicePixelRatio.js';
 import { createScale } from './hybridScale.js';
 import { computePaneLayout } from './paneLayout.js';
-import { formatPrice, niceTicks } from './priceAxis.js';
 import { pixelToValue, valueAxisPixelRange } from './valueAxis.js';
 const DEFAULT_BACKGROUND = 'transparent';
 const DEFAULT_FONT = {
@@ -33,20 +34,33 @@ const DEFAULT_LEGEND = {
     cursorGap: 12,
 };
 /**
- * The chart engine's renderer: canvas lifecycle, axes, crosshair, and
- * plugin drawing are all generic — none of it knows what kind of series is
- * on screen. The one series-specific seam is `seriesDefinition`, injected
- * at construction (see `src/series/types.ts`); everything above delegates
- * to it for value-range computation, point drawing, and legend text.
+ * The chart engine's renderer: owns the canvas lifecycle and orchestrates
+ * one frame — deciding what data is visible, computing scales, and calling
+ * out to collaborators for the actual pixel-pushing. None of it knows what
+ * kind of series is on screen: the one series-specific seam is
+ * `seriesDefinition`, injected at construction (see `src/series/types.ts`).
  * Stateless per call otherwise — all pan/zoom/hover state lives in
  * `Viewport` and `WickChart`; this class only turns a snapshot of that
  * state into pixels.
  *
+ * Axis chrome and the hover crosshair/legend are drawn by two collaborators
+ * (`AxisRenderer`, `CrosshairRenderer`) rather than methods on this class —
+ * both take only already-resolved style options and per-call geometry, no
+ * series generic or plugin state, so splitting them out keeps this file
+ * focused on orchestration (what gets drawn, in what order, with what
+ * scale) rather than mixing in how each individual chrome element paints.
+ *
  * Every visual constant below (fonts, axis sizing/coloring, crosshair
  * coloring/padding, legend color) is resolved once at construction from
  * `WickChartOptions.font`/`axis`/`crosshair`/`legend`, each merged field
  * by field over its own defaults — nothing here is a hardcoded module
- * constant a caller can't reach.
+ * constant a caller can't reach. Every *size* among them (font sizes, axis
+ * strip widths, padding, gaps) is specified in CSS pixels and scaled by the
+ * canvas's live devicePixelRatio (see `deviceRatio`) at the top of every
+ * `render()` call before use — colors and tick counts pass through
+ * unscaled. `AxisRenderer`/`CrosshairRenderer` themselves stay unaware of
+ * this: they're handed already-scaled options each frame, the same as they
+ * were handed unscaled ones before this existed.
  */
 export class ChartRenderer {
     constructor(canvas, seriesDefinition, options = {}) {
@@ -58,45 +72,87 @@ export class ChartRenderer {
         this.ctx = ctx;
         this.background = options.background ?? DEFAULT_BACKGROUND;
         this.style = { ...seriesDefinition.defaultStyle, ...(options.style ?? {}) };
-        this.font = { ...DEFAULT_FONT, ...options.font };
         this.axis = { ...DEFAULT_AXIS, ...options.axis };
+        this.invertValueAxis = options.invertValueAxis ?? false;
+        this.formatLegendOverride = options.formatLegend;
+        this.font = { ...DEFAULT_FONT, ...options.font };
         this.crosshair = { ...DEFAULT_CROSSHAIR, ...options.crosshair };
         this.legend = { ...DEFAULT_LEGEND, ...options.legend };
-        this.invertValueAxis = options.invertValueAxis ?? false;
     }
     setInvertValueAxis(inverted) {
         this.invertValueAxis = inverted;
     }
+    /** Ratio between the canvas's backing-store size and its CSS display
+     * size — read live, not cached, for the same reason `chartWidth`/
+     * `chartHeight` below read `canvas.width`/`height` live: whatever it is
+     * *right now* is what this frame draws at. See `src/devicePixelRatio.ts`. */
+    get deviceRatio() {
+        return devicePixelRatio(this.canvas, 'width');
+    }
     /** Pixel width of the point-plotting area — excludes the price-axis
      * strip on the right. Exposed so `WickChart` can convert cursor pixel
-     * positions to point indices / values for hit-testing and dragging. */
+     * positions to point indices / values for hit-testing and dragging.
+     * `priceAxisWidth` below is already devicePixelRatio-scaled, so this
+     * (and `chartHeight`) stay correct on a high-DPI canvas without
+     * `WickChart` having to know anything about DPR itself. */
     get chartWidth() {
-        return Math.max(0, this.canvas.width - this.axis.priceWidth);
+        return Math.max(0, this.canvas.width - this.priceAxisWidth);
     }
     get chartHeight() {
-        return Math.max(0, this.canvas.height - this.axis.timeHeight);
+        return Math.max(0, this.canvas.height - this.axis.timeHeight * this.deviceRatio);
     }
     get priceAxisWidth() {
-        return this.axis.priceWidth;
-    }
-    axisFont() {
-        return `${this.font.axisSize}px ${this.font.family}`;
-    }
-    legendFont() {
-        return `${this.font.legendSize}px ${this.font.family}`;
+        return this.axis.priceWidth * this.deviceRatio;
     }
     render(input) {
         const { ctx, canvas, background, seriesDefinition, style } = this;
         const { sorted, times, viewport, hoverIndex, hoverY, plugins, panes } = input;
+        const ratio = this.deviceRatio;
+        // Scaled fresh every frame (see `deviceRatio`'s own doc comment for
+        // why this isn't done once at construction) — every *size* field gets
+        // multiplied by `ratio`, every color/count field passes through as-is.
+        // `AxisRenderer`/`CrosshairRenderer` are cheap POJO-ish collaborators
+        // with no state beyond these options, so rebuilding them here each
+        // frame is simpler than threading `ratio` through every one of their
+        // methods for what's otherwise the same "resolved options" shape they
+        // were built to take in the first place.
+        const scaledAxis = {
+            ...this.axis,
+            priceWidth: this.axis.priceWidth * ratio,
+            timeHeight: this.axis.timeHeight * ratio,
+        };
+        const scaledFont = {
+            ...this.font,
+            axisSize: this.font.axisSize * ratio,
+            legendSize: this.font.legendSize * ratio,
+        };
+        const scaledCrosshair = {
+            ...this.crosshair,
+            labelPaddingX: this.crosshair.labelPaddingX * ratio,
+            labelPaddingY: this.crosshair.labelPaddingY * ratio,
+        };
+        const scaledLegend = {
+            ...this.legend,
+            paddingX: this.legend.paddingX * ratio,
+            paddingY: this.legend.paddingY * ratio,
+            cursorGap: this.legend.cursorGap * ratio,
+        };
+        const axisRenderer = new AxisRenderer(ctx, scaledAxis, scaledFont);
+        const crosshairRenderer = new CrosshairRenderer(ctx, scaledCrosshair, scaledLegend, scaledFont, scaledAxis.priceWidth);
         const width = canvas.width;
         const height = canvas.height;
-        const chartWidth = this.chartWidth;
+        // Computed from `scaledAxis` (already built from `ratio` above) rather
+        // than by re-reading `this.chartWidth`/`chartHeight` — those getters
+        // recompute `deviceRatio`, which reads `getBoundingClientRect()` (a
+        // potential layout reflow in a real browser); doing that three times
+        // per frame instead of once matters at 60fps.
+        const chartWidth = Math.max(0, width - scaledAxis.priceWidth);
         // Full stack height: the main price pane plus every declared indicator
         // pane below it. `this.chartHeight` predates panes and named what's
         // now only true with zero of them — kept as the property name (public
         // API reads it through) but renamed locally here since most of this
         // method cares about one pane's height, not the stack's.
-        const stackHeight = this.chartHeight;
+        const stackHeight = Math.max(0, height - scaledAxis.timeHeight);
         ctx.clearRect(0, 0, width, height);
         if (background !== 'transparent') {
             ctx.fillStyle = background;
@@ -161,25 +217,44 @@ export class ChartRenderer {
             // grid lines, and the crosshair.
             ctx.save();
             try {
-                seriesDefinition.draw({ ctx, visible, startIndex: startIdx, xForIndex, slotWidth, yScale, chartHeight }, style);
+                seriesDefinition.draw({ ctx, visible, startIndex: startIdx, xForIndex, slotWidth, yScale, chartHeight, devicePixelRatio: ratio }, style);
             }
             finally {
                 ctx.restore();
             }
-            const priceStep = this.currentPriceStep(valueMin, valueMax);
-            this.renderPriceAxis(valueMin, valueMax, priceStep, yScale, chartWidth, chartHeight, mainRect.top);
+            const priceStep = axisRenderer.priceStep(valueMin, valueMax);
+            axisRenderer.renderPriceAxis(valueMin, valueMax, priceStep, yScale, chartWidth, chartHeight, mainRect.top);
             for (const { rect, min, max, scale } of paneScales) {
-                this.renderPaneSeparator(rect.top, chartWidth);
-                const step = this.currentPriceStep(min, max);
-                this.renderPriceAxis(min, max, step, scale, chartWidth, rect.height, rect.top);
+                axisRenderer.renderPaneSeparator(rect.top, chartWidth);
+                const step = axisRenderer.priceStep(min, max);
+                axisRenderer.renderPriceAxis(min, max, step, scale, chartWidth, rect.height, rect.top);
             }
-            this.renderTimeAxis(times, startIdx, visible.length, stackHeight, chartWidth, xForIndex);
+            axisRenderer.renderTimeAxis(times, startIdx, visible.length, stackHeight, chartWidth, xForIndex);
             if (hoverIndex !== null && hoverIndex >= startIdx && hoverIndex < endIdx) {
                 // The dashed vertical line spans the whole stack (every pane); the
                 // horizontal line, price-label chip, and OHLC legend stay scoped
                 // to the main pane only — an indicator pane's own hover readout,
                 // if it wants one, is the job of whatever plugin draws into it.
-                this.renderCrosshairAndLegend(sorted[hoverIndex], xForIndex(hoverIndex), times[hoverIndex], hoverY, valueMin, valueMax, priceStep, chartWidth, chartHeight, stackHeight);
+                // `formatLegendOverride`, when set, replaces the series's own
+                // formatLegend entirely for this chart instance rather than
+                // merging with it — see `WickChartOptions.formatLegend`.
+                const formatLegend = this.formatLegendOverride ?? seriesDefinition.formatLegend;
+                const legendContext = { index: hoverIndex, allPoints: sorted };
+                const legendParts = formatLegend?.(sorted[hoverIndex], style, legendContext) ?? [];
+                crosshairRenderer.render({
+                    x: xForIndex(hoverIndex),
+                    timeSeconds: times[hoverIndex],
+                    hoverY,
+                    valueMin,
+                    valueMax,
+                    priceStep,
+                    chartWidth,
+                    chartHeight,
+                    stackHeight,
+                    invertValueAxis: this.invertValueAxis,
+                    legendParts,
+                    canvasWidth: canvas.width,
+                });
             }
             if (plugins.length > 0) {
                 // Everything every pane's PluginRenderApi shares — only the pane's
@@ -196,10 +271,10 @@ export class ChartRenderer {
                     allPoints: sorted,
                     frameState,
                 };
-                const mainApi = this.buildPluginApi(mainRect, valueMin, valueMax, yScale, frameGeometry);
+                const mainApi = this.buildPluginApi(mainRect, valueMin, valueMax, yScale, frameGeometry, ratio);
                 const paneApiById = new Map();
                 for (const { pane, rect, min, max, scale } of paneScales) {
-                    paneApiById.set(pane.id, this.buildPluginApi(rect, min, max, scale, frameGeometry));
+                    paneApiById.set(pane.id, this.buildPluginApi(rect, min, max, scale, frameGeometry, ratio));
                 }
                 for (const plugin of plugins) {
                     if (plugin.visible === false)
@@ -240,12 +315,13 @@ export class ChartRenderer {
      * for this frame (shared because there is only one time axis, and one
      * frame-ended flag, for the whole stack; see `FrameGeometry`).
      */
-    buildPluginApi(rect, valueMin, valueMax, scale, geometry) {
+    buildPluginApi(rect, valueMin, valueMax, scale, geometry, devicePixelRatio) {
         const { chartWidth, xForIndex, indexForX, visibleStartIndex, visibleEndIndex, allPoints, frameState } = geometry;
         return {
             ctx: this.ctx,
             chartWidth,
             chartHeight: rect.height,
+            devicePixelRatio,
             xForIndex,
             yForValue: (value) => {
                 if (frameState.ended) {
@@ -267,172 +343,4 @@ export class ChartRenderer {
             allPoints,
         };
     }
-    /** The decimal precision `formatPrice` should use for the current price
-     * range — shared by the axis ticks and the crosshair's price label so
-     * both display the same value with the same rounding. */
-    currentPriceStep(priceMin, priceMax) {
-        const ticks = niceTicks(priceMin, priceMax, this.axis.priceTickCount);
-        return ticks.length > 1 ? ticks[1] - ticks[0] : 0;
-    }
-    /**
-     * Draws one pane's right-side value axis: boundary line, horizontal grid
-     * lines, and tick labels. Used for both the main price pane and every
-     * indicator pane — `topOffset` shifts everything down by that pane's own
-     * position in the stack (0 for the main pane, which sits at the top), so
-     * `yScale` only ever has to know about its own pane-local [0, chartHeight]
-     * range and never about where that pane lives in the full canvas.
-     */
-    renderPriceAxis(priceMin, priceMax, step, yScale, chartWidth, chartHeight, topOffset) {
-        const { ctx, axis } = this;
-        const ticks = niceTicks(priceMin, priceMax, axis.priceTickCount);
-        ctx.strokeStyle = axis.lineColor;
-        ctx.beginPath();
-        ctx.moveTo(chartWidth + 0.5, topOffset);
-        ctx.lineTo(chartWidth + 0.5, topOffset + chartHeight);
-        ctx.stroke();
-        ctx.font = this.axisFont();
-        ctx.textAlign = 'left';
-        ctx.textBaseline = 'middle';
-        for (const value of ticks) {
-            const localY = yScale.map(value);
-            if (localY < 0 || localY > chartHeight)
-                continue;
-            const y = topOffset + localY;
-            ctx.strokeStyle = axis.gridLineColor;
-            ctx.beginPath();
-            ctx.moveTo(0, y + 0.5);
-            ctx.lineTo(chartWidth, y + 0.5);
-            ctx.stroke();
-            ctx.fillStyle = axis.textColor;
-            ctx.fillText(formatPrice(value, step), chartWidth + 6, y);
-        }
-    }
-    /** The horizontal rule separating an indicator pane from whatever sits
-     * above it (the main pane, or the previous indicator pane) — the same
-     * `axis.lineColor` boundary style `renderTimeAxis` already draws between
-     * the plotting area and the time-axis strip. */
-    renderPaneSeparator(top, chartWidth) {
-        const { ctx, axis } = this;
-        ctx.strokeStyle = axis.lineColor;
-        ctx.beginPath();
-        ctx.moveTo(0, top + 0.5);
-        ctx.lineTo(chartWidth, top + 0.5);
-        ctx.stroke();
-    }
-    renderTimeAxis(times, startIdx, visibleCount, chartHeight, chartWidth, xForIndex) {
-        const { ctx, axis } = this;
-        const visibleTimes = times.slice(startIdx, startIdx + visibleCount);
-        const spanSeconds = visibleTimes[visibleTimes.length - 1] - visibleTimes[0];
-        ctx.strokeStyle = axis.lineColor;
-        ctx.beginPath();
-        ctx.moveTo(0, chartHeight + 0.5);
-        ctx.lineTo(chartWidth, chartHeight + 0.5);
-        ctx.stroke();
-        ctx.fillStyle = axis.textColor;
-        ctx.font = this.axisFont();
-        ctx.textAlign = 'center';
-        ctx.textBaseline = 'top';
-        for (const localIndex of pickTickIndices(visibleCount, axis.timeMaxTicks)) {
-            const x = xForIndex(startIdx + localIndex);
-            const label = formatAxisLabel(visibleTimes[localIndex], spanSeconds);
-            ctx.fillText(label, x, chartHeight + 6);
-        }
-    }
-    renderCrosshairAndLegend(point, x, timeSeconds, hoverY, valueMin, valueMax, priceStep, chartWidth, chartHeight, stackHeight) {
-        const { ctx, canvas, seriesDefinition, style, crosshair } = this;
-        ctx.save();
-        ctx.strokeStyle = crosshair.lineColor;
-        ctx.setLineDash([4, 4]);
-        // Spans the whole pane stack (not just the main pane's own
-        // chartHeight) so hovering a candle lines up with the same column
-        // across every indicator pane below it — see the call site's comment
-        // in `render()` for why the horizontal line/legend don't follow suit.
-        ctx.beginPath();
-        ctx.moveTo(x, 0);
-        ctx.lineTo(x, stackHeight);
-        ctx.stroke();
-        // The horizontal line follows the actual cursor/finger position, not
-        // any property of the hovered point — pinning it to (say) the candle's
-        // close would leave it motionless while the pointer moves anywhere
-        // within that same candle's column, which reads as broken/stuck rather
-        // than as a crosshair. Only drawn while the pointer is actually inside
-        // the chart's vertical extent, same as the price-axis tick-skip logic
-        // in renderPriceAxis.
-        const priceLineVisible = hoverY !== null && hoverY >= 0 && hoverY <= chartHeight;
-        if (priceLineVisible) {
-            ctx.beginPath();
-            ctx.moveTo(0, hoverY);
-            ctx.lineTo(chartWidth, hoverY);
-            ctx.stroke();
-        }
-        ctx.restore();
-        if (priceLineVisible) {
-            // Exact inverse of the value->y mapping createScale set up for this
-            // frame — same helper (and same invertValueAxis flag) as
-            // PluginRenderApi.valueForY, see src/valueAxis.ts.
-            const value = pixelToValue(hoverY, valueMin, valueMax, chartHeight, this.invertValueAxis);
-            this.renderPriceLabelChip(formatPrice(value, priceStep), hoverY, chartWidth);
-        }
-        this.renderTimeLabelChip(formatHoverTime(timeSeconds), x, chartHeight, canvas.width);
-        const parts = seriesDefinition.formatLegend?.(point, style) ?? [];
-        if (parts.length === 0)
-            return;
-        this.renderHoverTooltip(parts, x, hoverY, chartWidth, chartHeight);
-    }
-    /** The OHLC(+volume) tooltip — floats near the hovered pixel like a
-     * speech bubble, one line per part, rather than a fixed banner glued to
-     * a corner of the canvas. Offset up-and-right of the cursor/finger by
-     * `legend.cursorGap` and clamped to both chart edges so it never runs
-     * off-screen, including when there's no `hoverY` to anchor to (a series
-     * with no primary value still gets a legend, just pinned near the top
-     * at the hovered column). */
-    renderHoverTooltip(lines, x, hoverY, chartWidth, chartHeight) {
-        const { ctx, font, legend } = this;
-        ctx.font = this.legendFont();
-        ctx.textAlign = 'left';
-        ctx.textBaseline = 'top';
-        const lineHeight = font.legendSize + 4;
-        const textWidth = Math.max(...lines.map((line) => ctx.measureText(line).width));
-        const boxWidth = textWidth + legend.paddingX * 2;
-        const boxHeight = lines.length * lineHeight + legend.paddingY * 2;
-        const anchorY = hoverY ?? 0;
-        const left = Math.min(Math.max(x + legend.cursorGap, 0), Math.max(0, chartWidth - boxWidth));
-        const top = Math.min(Math.max(anchorY - boxHeight - legend.cursorGap, 0), Math.max(0, chartHeight - boxHeight));
-        ctx.fillStyle = legend.background;
-        ctx.fillRect(left, top, boxWidth, boxHeight);
-        ctx.fillStyle = legend.textColor;
-        lines.forEach((line, i) => {
-            ctx.fillText(line, left + legend.paddingX, top + legend.paddingY + i * lineHeight);
-        });
-    }
-    /** The highlighted price-axis label that follows the crosshair's
-     * horizontal line — drawn over `renderPriceAxis`'s own tick labels so the
-     * hovered value reads clearly even where it lands between two ticks. */
-    renderPriceLabelChip(text, y, chartWidth) {
-        const { ctx, font, crosshair } = this;
-        ctx.font = this.axisFont();
-        const chipHeight = font.axisSize + crosshair.labelPaddingY * 2;
-        ctx.fillStyle = crosshair.labelBackground;
-        ctx.fillRect(chartWidth, y - chipHeight / 2, this.priceAxisWidth, chipHeight);
-        ctx.fillStyle = crosshair.labelTextColor;
-        ctx.textAlign = 'left';
-        ctx.textBaseline = 'middle';
-        ctx.fillText(text, chartWidth + crosshair.labelPaddingX, y);
-    }
-    /** The highlighted time-axis label under the crosshair's vertical line.
-     * Clamped so its background chip stays fully on-screen even when the
-     * hovered point sits at the very first or last visible index. */
-    renderTimeLabelChip(text, x, chartHeight, canvasWidth) {
-        const { ctx, font, crosshair } = this;
-        ctx.font = this.axisFont();
-        const chipWidth = ctx.measureText(text).width + crosshair.labelPaddingX * 2;
-        const chipHeight = font.axisSize + crosshair.labelPaddingY * 2;
-        const chipLeft = Math.min(Math.max(x - chipWidth / 2, 0), canvasWidth - chipWidth);
-        ctx.fillStyle = crosshair.labelBackground;
-        ctx.fillRect(chipLeft, chartHeight, chipWidth, chipHeight);
-        ctx.fillStyle = crosshair.labelTextColor;
-        ctx.textAlign = 'left';
-        ctx.textBaseline = 'top';
-        ctx.fillText(text, chipLeft + crosshair.labelPaddingX, chartHeight + crosshair.labelPaddingY);
-    }
 }

package/dist/series/line.js

@@ -16,7 +16,7 @@ function getValueRange(visible, scaleFactor) {
     return fitRange(Math.min(...values), Math.max(...values), scaleFactor);
 }
 function draw(context, style) {
-    const { ctx, visible, startIndex, xForIndex, yScale } = context;
+    const { ctx, visible, startIndex, xForIndex, yScale, devicePixelRatio } = context;
     if (visible.length === 0)
         return;
     // Batched through mapMany (one call per array) rather than once per
@@ -26,7 +26,11 @@ function draw(context, style) {
     // filtered out first, so `ys[i]` still lines up with `visible[i]`.
     const ys = yScale.mapMany(visible.map((p) => p.value));
     ctx.strokeStyle = style.lineColor;
-    ctx.lineWidth = style.lineWidth;
+    // `lineWidth` is authored in CSS pixels, like every other size in
+    // `WickChartOptions` — scaled to backing-store pixels here so the stroke
+    // renders at its intended visual thickness on a high-DPI canvas instead
+    // of half that. See `SeriesDrawContext.devicePixelRatio`.
+    ctx.lineWidth = style.lineWidth * devicePixelRatio;
     ctx.beginPath();
     // `drawing` tracks whether the path is mid-segment — a non-finite value
     // (a gap in the data) breaks it, and the line resumes fresh at the next

package/dist/series/types.d.ts

@@ -1,5 +1,5 @@
 import type { Scale } from '../hybridScale.js';
-import type { SeriesPoint, ValueRange } from '../types.js';
+import type { LegendFormatContext, SeriesPoint, ValueRange } from '../types.js';
 export type { ValueRange } from '../types.js';
 /**
  * Everything a series's `draw` needs to turn its visible points into
@@ -23,6 +23,17 @@ export interface SeriesDrawContext<TPoint extends SeriesPoint> {
     /** Value (price) -> y pixel for the current frame's domain. */
     yScale: Scale;
     chartHeight: number;
+    /** Ratio between the canvas's backing-store size and its CSS display
+     * size — 1 on a standard-DPI display, 2 on a typical Retina one. Every
+     * geometric field above (`slotWidth`, `chartHeight`, the pixels `yScale`
+     * maps to) is already in backing-store pixels, but a *literal* pixel
+     * size in `style` (a stroke width, say — `LineStyle.lineWidth` is the
+     * built-in example) is normally authored in CSS pixels, the same
+     * intuitive unit `WickChartOptions.font`/`axis`/`crosshair`/`legend` use;
+     * multiply such a field by this before setting it on `ctx` so it renders
+     * at its intended visual size rather than half that on a 2x display. See
+     * "High-DPI displays" in the README. */
+    devicePixelRatio: number;
 }
 /**
  * The single seam a new chart type has to implement. `WickChart` and
@@ -51,6 +62,11 @@ export interface SeriesDefinition<TPoint extends SeriesPoint, TStyle> {
     draw(context: SeriesDrawContext<TPoint>, style: TStyle): void;
     /** Builds the hover/crosshair legend text for one point, one string per
      * segment (joined with spacing by the renderer). Omit to draw the
-     * crosshair line with no legend text. */
-    formatLegend?(point: TPoint, style: TStyle): string[];
+     * crosshair line with no legend text. `context` gives access to
+     * neighboring points (see `LegendFormatContext`) for anything the
+     * hovered point alone can't express, like a value compared against the
+     * previous point — this built-in series doesn't need it, but a custom
+     * one can. `WickChartOptions.formatLegend`, when set, overrides this per
+     * chart instance rather than per series type — see its own doc comment. */
+    formatLegend?(point: TPoint, style: TStyle, context: LegendFormatContext<TPoint>): string[];
 }

package/dist/types.d.ts

@@ -169,6 +169,22 @@ export interface ResolvedPaneOptions {
     heightRatio: number;
     getValueRange: () => ValueRange;
 }
+/**
+ * Context `SeriesDefinition.formatLegend` and `WickChartOptions.formatLegend`
+ * get alongside the hovered point and its style — everything needed to
+ * compute something derived from *neighboring* points (a percent change
+ * vs. the previous point, say), which the hovered point alone can't
+ * express. The same `allPoints`/index-into-it shape `SeriesDrawContext`
+ * already gives a series's own `draw()`, reused here so both call sites
+ * answer "what else is near this point" the same way.
+ */
+export interface LegendFormatContext<TPoint extends SeriesPoint = SeriesPoint> {
+    /** Global index of the hovered point in `allPoints`. */
+    index: number;
+    /** Every point currently loaded (not just visible), sorted ascending by
+     * time — the same array `SeriesDrawContext.allPoints` is. */
+    allPoints: readonly TPoint[];
+}
 export interface WickChartOptions {
     /**
      * Which registered series type to render this chart as (see
@@ -199,6 +215,30 @@ export interface WickChartOptions {
     crosshair?: ChartCrosshairOptions;
     /** Hover legend coloring. Merged over the built-in defaults field by field. */
     legend?: ChartLegendOptions;
+    /**
+     * Overrides the active series's own `formatLegend` (see
+     * `SeriesDefinition.formatLegend`) for this chart instance specifically —
+     * the hover legend's text, one string per line. `SeriesDefinition.formatLegend`
+     * is a shared default for every chart of that series *type* (registered
+     * once via `registerSeries`); this is a per-*instance* override for
+     * whatever varies by app/session instead of by chart type — localized
+     * labels, or a value derived from neighboring points via
+     * `context.allPoints`/`context.index` (a percent change vs. the previous
+     * point, say). Returning an empty array suppresses the built-in tooltip
+     * entirely, the same as a series with no `formatLegend` at all — draw
+     * your own via a `ChartPlugin` instead if you need a different layout,
+     * not just different text.
+     *
+     * Declared as a method (not an arrow-typed property) so, like
+     * `SeriesDefinition.formatLegend`, it type-checks bivariantly rather than
+     * contravariantly — the same tradeoff `style`'s untyped
+     * `Record<string, unknown>` already makes here: `new WickChart(canvas, {
+     * type, formatLegend })` doesn't verify `point`/`style` actually match
+     * `type`'s series, but `createCandlestickChart`/`createLineChart` narrow
+     * both to the concrete series's own types, the same way they narrow
+     * `style` — see their own doc comments.
+     */
+    formatLegend?(point: SeriesPoint, style: unknown, context: LegendFormatContext<SeriesPoint>): string[];
     /**
      * Mirrors the value axis top-to-bottom — every pane's higher values
      * render lower on screen instead of higher, with no change to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wick-charts",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "An open-source financial charting library — WASM (Rust) for compute, Canvas2D for rendering.",
   "license": "MIT",
   "author": "eatnows",