wick-charts 0.7.1 → 0.10.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)
@@ -206,6 +208,8 @@ const chart = createCandlestickChart(canvas, {
   },
   crosshair: {
     lineColor: '#9090904d',
+    lineWidth: 1,
+    lineDash: [4, 4], // [] for a solid line — same convention as ctx.setLineDash
     labelBackground: '#3a3a3a',
     labelTextColor: '#f0f0f0',
     labelPaddingX: 4,
@@ -229,6 +233,103 @@ 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 : null;
+    return [
+      `시가 ${candle.open.toLocaleString()}`,
+      `고가 ${candle.high.toLocaleString()}`,
+      `저가 ${candle.low.toLocaleString()}`,
+      `종가 ${candle.close.toLocaleString()}`,
+      // A line can be a plain string (drawn in legend.textColor, like the
+      // four above) or { text, color } for one that needs its own color —
+      // see "Coloring individual legend lines" just below.
+      change === null
+        ? '등락 —'
+        : { text: `등락 ${change >= 0 ? '+' : ''}${change.toFixed(2)}%`, color: change >= 0 ? '#22c55e' : '#ef4444' },
+    ];
+  },
+});
+```
+
+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.
+
+#### Coloring individual legend lines
+
+Every line returned by `formatLegend` is a `LegendLine` — either a plain `string`, drawn in
+`legend.textColor` like every line before this existed, or `{ text, color }` for one line that
+needs its own color independent of the rest (the `change` line above: green when positive, red
+when negative, regardless of `legend.textColor`). Mixing both shapes in one returned array, as
+above, is the normal case — only the lines that actually need a distinct color use the object
+form. There's no chart-wide "green means up" setting for this: which color means "up" is a
+convention that varies by market (green-up in most markets, red-up in South Korea and a few
+others) and isn't something the library should hardcode, so `formatLegend` decides it per line
+the same way it decides everything else about the legend's text. This is separate from
+`CandlestickStyle.upColor`/`downColor`, which is the *candle's own* body/wick color, a
+chart-wide setting rather than something recomputed per hovered point.
+
+`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
@@ -513,6 +614,62 @@ the price pane — an indicator pane's own hover readout, if you want one, is so
 plugin draws (it has the same `xForIndex`/`yForValue` a price-pane plugin does, just mapped
 against that pane's own value domain and pixel rect).
 
+### Splitting volume into its own pane
+
+The candlestick series' default volume bars are a translucent backdrop *inside* the price
+pane (`CandlestickStyle.volumeAreaHeightRatio`, `0.2` of the chart height by default) — fine
+for a compact chart, but on a tall one, or whenever a candle's own range dips into that bottom
+margin, the bars visually collide with the candles drawn over them. The same `addPane` +
+`ChartPlugin.paneId` mechanism the previous section uses for RSI/MACD works just as well for
+volume — it just reads `Candle.volume` instead of computing an indicator:
+
+```ts
+// PaneOptions.getValueRange takes no arguments, so — same as the MACD pane above needing its
+// own auto-fit range — it closes over the chart's current data itself rather than reading it
+// from an argument. `allData` is whatever you last passed to `chart.setData()`.
+let allData: Candle[] = [];
+
+const chart = createCandlestickChart(canvas, {
+  style: { volumeAreaHeightRatio: 0 }, // suppress the in-pane backdrop — see below for why
+});
+
+chart.addPane({
+  id: 'volume',
+  heightRatio: 0.15,
+  getValueRange: () => {
+    const { startIndex, endIndex } = chart.getVisibleRange();
+    let max = 0;
+    for (let i = startIndex; i < endIndex; i++) max = Math.max(max, allData[i]?.volume ?? 0);
+    return { min: 0, max: max || 1 };
+  },
+});
+
+chart.addPlugin({
+  paneId: 'volume',
+  draw({ ctx, allPoints, visibleStartIndex, visibleEndIndex, xForIndex, yForValue }) {
+    const zeroY = yForValue(0);
+    const barWidth = (xForIndex(visibleStartIndex + 1) - xForIndex(visibleStartIndex)) * 0.6;
+    for (let i = visibleStartIndex; i < visibleEndIndex; i++) {
+      const c = allPoints[i];
+      if (c.volume === undefined) continue;
+      ctx.fillStyle = c.close >= c.open ? '#26a69a' : '#ef5350';
+      const y = yForValue(c.volume);
+      ctx.fillRect(xForIndex(i) - barWidth / 2, y, barWidth, zeroY - y);
+    }
+  },
+});
+
+chart.setData(candles);
+allData = candles; // keep in sync on every later setData() call too
+```
+
+Setting `volumeAreaHeightRatio: 0` on the style matters — leaving the default `0.2` active
+alongside a dedicated volume pane double-draws the bars (once as the in-pane backdrop, once in
+the new pane). Unlike an indicator pane's `getValueRange`, volume's domain is naturally
+`[0, max]` rather than something auto-fit around a signed value the way MACD's is — the
+example above recomputes `max` from the currently visible candles each frame, the same way
+`computeMacdValueRange` does in the "Multi-pane indicators" example above.
+
 ### Cleanup
 
 Call `chart.destroy()` when you're done with a chart (component unmount, etc.) — it removes a

package/dist/crosshairRenderer.d.ts

@@ -1,4 +1,4 @@
-import type { ChartCrosshairOptions, ChartFontOptions, ChartLegendOptions } from './types.js';
+import type { ChartCrosshairOptions, ChartFontOptions, ChartLegendOptions, LegendLine } 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
@@ -19,7 +19,7 @@ export interface CrosshairRenderInput {
      * across every indicator pane below it. */
     stackHeight: number;
     invertValueAxis: boolean;
-    legendParts: string[];
+    legendParts: LegendLine[];
     /** 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;

package/dist/crosshairRenderer.js

@@ -27,7 +27,8 @@ export class CrosshairRenderer {
         const { ctx, crosshair } = this;
         ctx.save();
         ctx.strokeStyle = crosshair.lineColor;
-        ctx.setLineDash([4, 4]);
+        ctx.lineWidth = crosshair.lineWidth;
+        ctx.setLineDash(crosshair.lineDash);
         // 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
@@ -74,8 +75,12 @@ export class CrosshairRenderer {
         ctx.font = this.legendFont();
         ctx.textAlign = 'left';
         ctx.textBaseline = 'top';
+        // Each line is either a plain string or { text, color } — normalize to
+        // its text once up front for sizing, and read its own color (falling
+        // back to legend.textColor) only when actually drawing it below.
+        const texts = lines.map((line) => (typeof line === 'string' ? line : line.text));
         const lineHeight = font.legendSize + 4;
-        const textWidth = Math.max(...lines.map((line) => ctx.measureText(line).width));
+        const textWidth = Math.max(...texts.map((text) => ctx.measureText(text).width));
         const boxWidth = textWidth + legend.paddingX * 2;
         const boxHeight = lines.length * lineHeight + legend.paddingY * 2;
         const anchorY = hoverY ?? 0;
@@ -83,9 +88,9 @@ export class CrosshairRenderer {
         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);
+            ctx.fillStyle = typeof line === 'string' ? legend.textColor : (line.color ?? legend.textColor);
+            ctx.fillText(texts[i], left + legend.paddingX, top + legend.paddingY + i * lineHeight);
         });
     }
     /** The highlighted price-axis label that follows the crosshair's

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, LegendLine, LinePoint, PaneOptions, WickChartOptions, SeriesPoint, ValueRange, WickTime } from './types.js';
+export type { BusinessDay, Candle, LegendFormatContext, LegendLine, 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>): LegendLine[];
 }): 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>): LegendLine[];
 }): 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';
@@ -20,6 +21,8 @@ const DEFAULT_AXIS = {
 };
 const DEFAULT_CROSSHAIR = {
     lineColor: '#9090904d',
+    lineWidth: 1,
+    lineDash: [4, 4],
     labelBackground: '#3a3a3a',
     labelTextColor: '#f0f0f0',
     labelPaddingX: 4,
@@ -53,7 +56,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 +76,87 @@ 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,
+            lineWidth: this.crosshair.lineWidth * ratio,
+            lineDash: this.crosshair.lineDash.map((segment) => segment * ratio),
+            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,40 +221,19 @@ 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);
-            }
-            this.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({
-                    x: xForIndex(hoverIndex),
-                    timeSeconds: times[hoverIndex],
-                    hoverY,
-                    valueMin,
-                    valueMax,
-                    priceStep,
-                    chartWidth,
-                    chartHeight,
-                    stackHeight,
-                    invertValueAxis: this.invertValueAxis,
-                    legendParts,
-                    canvasWidth: canvas.width,
-                });
+                axisRenderer.renderPaneSeparator(rect.top, chartWidth);
+                const step = axisRenderer.priceStep(min, max);
+                axisRenderer.renderPriceAxis(min, max, step, scale, chartWidth, rect.height, rect.top);
             }
+            axisRenderer.renderTimeAxis(times, startIdx, visible.length, stackHeight, chartWidth, xForIndex);
             if (plugins.length > 0) {
                 // Everything every pane's PluginRenderApi shares — only the pane's
                 // own rect/value-domain/scale differ between `buildPluginApi`
@@ -213,10 +249,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)
@@ -242,6 +278,37 @@ export class ChartRenderer {
                     }
                 }
             }
+            // Drawn last, after every plugin (including paneId'd ones and main-pane
+            // overlays like trade markers) rather than right after the axes, so the
+            // hover legend/crosshair always sits on top of everything else instead
+            // of being covered by a plugin's own output — the crosshair is the most
+            // "active"/topmost thing on the chart at the moment it's shown.
+            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.
+                // `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,
+                });
+            }
         }
         finally {
             frameState.ended = true;
@@ -257,12 +324,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/candlestick.d.ts

@@ -11,7 +11,12 @@ export interface CandlestickStyle {
     /** Fraction of the chart's full height that volume bars occupy, measured
      * up from the bottom. Candles still use the full height for their own
      * price scale regardless of this value — the bars sit in this bottom
-     * margin, layered underneath. Defaults to 0.2. */
+     * margin, layered underneath (and can visually collide with a candle
+     * whose range dips into that margin). Defaults to 0.2. Set to 0 to
+     * suppress this in-pane backdrop entirely — do this when drawing volume
+     * in its own pane instead via `WickChart.addPane` + a `ChartPlugin`
+     * reading `Candle.volume` off `allPoints` (see "Splitting volume into
+     * its own pane" in the README), so the two don't double-draw. */
     volumeAreaHeightRatio: number;
     /** Opacity (0-1) of the volume bars, so they read as a backdrop rather
      * than competing with the candles drawn over them. Defaults to 0.5. */

package/dist/series/candlestick.js

@@ -18,6 +18,13 @@ function getValueRange(visible, scaleFactor) {
  * OHLC-only data look exactly as they did before this existed. */
 function drawVolumeBars(context, style) {
     const { ctx, visible, startIndex, xForIndex, slotWidth, chartHeight } = context;
+    // A caller drawing volume in its own pane via WickChart.addPane (see
+    // "Splitting volume into its own pane" in the README) sets this to 0 to
+    // fully suppress this in-pane backdrop — without this guard, the
+    // Math.max(1, ...) floor below still drew a 1px sliver per candle even
+    // at ratio 0.
+    if (style.volumeAreaHeightRatio <= 0)
+        return;
     const maxVolume = visible.reduce((max, c) => (c.volume !== undefined ? Math.max(max, c.volume) : max), 0);
     if (maxVolume <= 0)
         return;

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, LegendLine, 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>): LegendLine[];
 }

package/dist/types.d.ts

@@ -103,8 +103,16 @@ export interface ChartAxisOptions {
 /** Coloring and padding for the hover crosshair's lines and its two
  * highlighted axis-label chips. */
 export interface ChartCrosshairOptions {
-    /** Dashed crosshair line color. Defaults to `'#9090904d'`. */
+    /** Crosshair line color. Defaults to `'#9090904d'`. */
     lineColor?: string;
+    /** Crosshair line thickness, in CSS px (scaled by `devicePixelRatio`
+     * like every other size field here). Defaults to `1`. */
+    lineWidth?: number;
+    /** `CanvasRenderingContext2D.setLineDash` pattern, in CSS px (scaled by
+     * `devicePixelRatio` like every other size field here). Defaults to
+     * `[4, 4]`. Pass `[]` for a solid line — the same canvas convention
+     * `setLineDash` itself uses, so this needs no separate on/off flag. */
+    lineDash?: number[];
     /** Background fill of the price/time label chips. Defaults to `'#3a3a3a'`. */
     labelBackground?: string;
     /** Text color inside the label chips. Defaults to `'#f0f0f0'`. */
@@ -169,6 +177,34 @@ 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[];
+}
+/**
+ * One line of the hover legend — a plain `string` (drawn in the legend's
+ * configured `textColor`, same as every version of this library before
+ * per-line color existed) or `{ text, color }` for a line that needs its
+ * own color independent of the rest — a percent-change line that should
+ * read green/red by sign, say. Mixing both in the same `formatLegend`
+ * return array is fine: each line is colored independently.
+ */
+export type LegendLine = string | {
+    text: string;
+    color?: string;
+};
 export interface WickChartOptions {
     /**
      * Which registered series type to render this chart as (see
@@ -199,6 +235,32 @@ 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 `LegendLine` per line (a plain string, or
+     * `{ text, color }` for a line that needs its own color — see
+     * `LegendLine`). `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>): LegendLine[];
     /**
      * 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.10.0",
   "description": "An open-source financial charting library — WASM (Rust) for compute, Canvas2D for rendering.",
   "license": "MIT",
   "author": "eatnows",