wick-charts 0.7.1 → 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/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,4 +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';
@@ -841,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

@@ -43,7 +43,13 @@ export interface RenderInput<TPoint extends SeriesPoint> {
  * 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;
@@ -51,24 +57,40 @@ export declare class ChartRenderer<TPoint extends SeriesPoint> {
     private ctx;
     private background;
     private style;
-    /** Kept as its own field (unlike font/crosshair/legend, which only
-     * `AxisRenderer`/`CrosshairRenderer` need after construction) because
-     * `chartWidth`/`chartHeight`/`priceAxisWidth` below read it directly on
-     * every call, not just once at construction. */
+    /** 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 axisRenderer;
-    private crosshairRenderer;
+    private font;
+    private crosshair;
+    private legend;
     /** Unlike the style groups above, mutable after construction — see
      * `setInvertValueAxis`. A live toggle, not a one-time style choice, is
      * the whole point of this option (a "what if this series moved the
      * 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;

package/dist/renderer.js

@@ -1,5 +1,6 @@
 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 { pixelToValue, valueAxisPixelRange } from './valueAxis.js';
@@ -53,7 +54,13 @@ const DEFAULT_LEGEND = {
  * 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 = {}) {
@@ -67,39 +74,85 @@ export class ChartRenderer {
         this.style = { ...seriesDefinition.defaultStyle, ...(options.style ?? {}) };
         this.axis = { ...DEFAULT_AXIS, ...options.axis };
         this.invertValueAxis = options.invertValueAxis ?? false;
-        const font = { ...DEFAULT_FONT, ...options.font };
-        const crosshair = { ...DEFAULT_CROSSHAIR, ...options.crosshair };
-        const legend = { ...DEFAULT_LEGEND, ...options.legend };
-        this.axisRenderer = new AxisRenderer(ctx, this.axis, font);
-        this.crosshairRenderer = new CrosshairRenderer(ctx, crosshair, legend, font, this.axis.priceWidth);
+        this.formatLegendOverride = options.formatLegend;
+        this.font = { ...DEFAULT_FONT, ...options.font };
+        this.crosshair = { ...DEFAULT_CROSSHAIR, ...options.crosshair };
+        this.legend = { ...DEFAULT_LEGEND, ...options.legend };
     }
     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;
+        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;
@@ -164,26 +217,31 @@ 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.axisRenderer.priceStep(valueMin, valueMax);
-            this.axisRenderer.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.axisRenderer.renderPaneSeparator(rect.top, chartWidth);
-                const step = this.axisRenderer.priceStep(min, max);
-                this.axisRenderer.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.axisRenderer.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.
-                const legendParts = seriesDefinition.formatLegend?.(sorted[hoverIndex], style) ?? [];
-                this.crosshairRenderer.render({
+                // `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,
@@ -213,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)
@@ -257,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) {

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.1",
+  "version": "0.9.0",
   "description": "An open-source financial charting library — WASM (Rust) for compute, Canvas2D for rendering.",
   "license": "MIT",
   "author": "eatnows",