wick-charts 0.3.0

package/dist/mergeSeries.d.ts

@@ -0,0 +1,14 @@
+import type { SeriesPoint } from './types.js';
+/**
+ * Merges `incoming` into `existing`, de-duplicating by normalized time
+ * (incoming wins on conflict — it's the freshly-fetched source of truth)
+ * and returns a fully re-sorted ascending array. Generic over any point
+ * shape with a `time` field, not just `Candle` — a future series type
+ * reuses this unchanged.
+ *
+ * Overlap is expected, not an edge case: a loader asked for "everything
+ * before time T" may reasonably return a batch that laps back over points
+ * the chart already has, and the caller shouldn't have to worry about
+ * trimming it exactly.
+ */
+export declare function mergeSeriesPoints<TPoint extends SeriesPoint>(existing: TPoint[], incoming: TPoint[]): TPoint[];

package/dist/mergeSeries.js

@@ -0,0 +1,21 @@
+import { toUnixSeconds } from './time.js';
+/**
+ * Merges `incoming` into `existing`, de-duplicating by normalized time
+ * (incoming wins on conflict — it's the freshly-fetched source of truth)
+ * and returns a fully re-sorted ascending array. Generic over any point
+ * shape with a `time` field, not just `Candle` — a future series type
+ * reuses this unchanged.
+ *
+ * Overlap is expected, not an edge case: a loader asked for "everything
+ * before time T" may reasonably return a batch that laps back over points
+ * the chart already has, and the caller shouldn't have to worry about
+ * trimming it exactly.
+ */
+export function mergeSeriesPoints(existing, incoming) {
+    const byTime = new Map();
+    for (const p of existing)
+        byTime.set(toUnixSeconds(p.time), p);
+    for (const p of incoming)
+        byTime.set(toUnixSeconds(p.time), p);
+    return Array.from(byTime.values()).sort((a, b) => toUnixSeconds(a.time) - toUnixSeconds(b.time));
+}

package/dist/plugins/types.d.ts

@@ -0,0 +1,140 @@
+import type { SeriesPoint } from '../types.js';
+/**
+ * What a plugin gets to draw with, rebuilt fresh by `ChartRenderer` every
+ * frame from that frame's own geometry — a plugin never caches this across
+ * renders, since panning/zooming changes every value here.
+ *
+ * Stronger than "don't cache it": `xForIndex` and `yForValue` must only be
+ * called *synchronously*, inside the `draw()` call that received this
+ * object. `yForValue` closes over the frame's `Scale`, which for a
+ * large-enough series is WASM-backed and gets its backing memory freed the
+ * moment `draw()` returns (see `ChartRenderer.render`'s `finally` block) —
+ * stashing this object for a `setTimeout`, a promise callback, or the next
+ * frame and calling `yForValue` from there is a use-after-free, not just a
+ * staleness bug.
+ */
+export interface PluginRenderApi<TPoint extends SeriesPoint = SeriesPoint> {
+    ctx: CanvasRenderingContext2D;
+    chartWidth: number;
+    chartHeight: 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`. */
+    xForIndex: (globalIndex: number) => number;
+    /** Value in the current frame's y-domain -> y pixel. Valid only for the
+     * duration of this `draw()` call — see the interface-level note on
+     * `PluginRenderApi`. */
+    yForValue: (value: number) => number;
+    /** x pixel -> global (possibly fractional) index — the exact inverse of
+     * `xForIndex`, i.e. `xForIndex(indexForX(x)) === x`. For placing or
+     * hit-testing something at a pixel position instead of a known index. */
+    indexForX: (x: number) => number;
+    /** y pixel -> value in the current frame's y-domain — the exact inverse
+     * of `yForValue`. */
+    valueForY: (y: number) => number;
+    /** Index range currently visible, global (sorted-array) indices. */
+    visibleStartIndex: number;
+    visibleEndIndex: number;
+    /**
+     * Every point currently loaded (not just visible), sorted ascending by
+     * time — the same array the active series slices its own `visible` from.
+     * A plugin that needs data outside the visible window (a moving average
+     * needs `period - 1` points of "warm-up" history before the first
+     * visible bar to be accurate there) reads from here rather than being
+     * limited to `visibleStartIndex..visibleEndIndex`.
+     */
+    allPoints: readonly TPoint[];
+}
+/**
+ * A pointer (mouse, or single-finger touch) position, given to a plugin's
+ * `onPointerDown`/`onPointerMove`/`onPointerUp`. `x`/`y` are canvas
+ * backing-store pixels — the same convention `PluginRenderApi`'s
+ * `xForIndex`/`yForValue` use. `index` and `value` are that position
+ * already converted to data space (the chart's own inverse-coordinate
+ * math, so a plugin never has to duplicate it): `index` is a possibly
+ * fractional global (sorted-array) index, and `value` is the value under
+ * the pointer in the current frame's y-domain — `null` if there's no data
+ * or no usable chart area to compute one against.
+ *
+ * `xForIndex`/`yForValue` are the forward direction — for converting a
+ * shape a plugin is storing in data space (so it survives pan/zoom) back
+ * to pixels at the moment of this event, to compare against `x`/`y` with
+ * `hitTestSegment`/`hitTestPoint` (see `src/hitTest.ts`). Same caveat as
+ * `PluginRenderApi`'s mapping functions: valid for this dispatch only —
+ * the mapping shifts on the next pan/zoom/frame, so call them
+ * synchronously inside the handler that received this event, never stash
+ * them for later.
+ */
+export interface ChartPointerEvent {
+    x: number;
+    y: number;
+    index: number;
+    value: number | null;
+    xForIndex: (index: number) => number;
+    yForValue: (value: number) => number | null;
+}
+/**
+ * The extension point for anything that draws *on top of* a chart without
+ * being the chart itself — price/event markers, alert lines, drawing
+ * tools, annotations, indicator overlays. Register instances via
+ * `WickChart.addPlugin`; `ChartRenderer` calls `draw` once per frame,
+ * after the active series and axes, so plugin output always sits above the
+ * plotted data.
+ *
+ * This is deliberately a single narrow interface rather than a family of
+ * marker/annotation/tool base classes — a plugin author owns their own
+ * styling and reads whatever data it needs (candle fields, indicator
+ * state, ...) off `allPoints`, and just needs pixel-space geometry for the
+ * current frame, which `PluginRenderApi` provides. Generic over the same
+ * `TPoint` the chart itself is generic over, so a candlestick chart's
+ * plugins see `Candle`-shaped points without a cast.
+ *
+ * The optional `onPointer*` hooks are what an *interactive* plugin (a
+ * trend line, a drawing tool — anything placed or edited by the user,
+ * rather than purely computed from data like an indicator) needs beyond
+ * `draw`: a way to see raw pointer gestures on the chart, which
+ * `WickChart` would otherwise consume entirely for its own panning.
+ */
+export interface ChartPlugin<TPoint extends SeriesPoint = SeriesPoint> {
+    /**
+     * Stable identifier for this plugin instance, opaque to the chart —
+     * only used to look a plugin back up via `WickChart.setPluginVisible`
+     * once an app is managing a growing list of indicators/drawing tools and
+     * no longer wants to hold onto every instance it created. Not required:
+     * a plugin with no `id` can still be added/removed by reference via
+     * `addPlugin`/`removePlugin`, it just can't be targeted by
+     * `setPluginVisible`. Uniqueness across the chart's plugins is the
+     * caller's responsibility — the chart doesn't enforce it.
+     */
+    id?: string;
+    /**
+     * Whether this plugin currently draws and can claim pointer gestures.
+     * Defaults to `true` (a plugin with no `visible` field behaves exactly
+     * as before this field existed). Set to `false` to hide a plugin
+     * without losing its state by removing it — e.g. an indicator or
+     * drawing tool a user toggled off in a management UI but might turn
+     * back on. Toggle it via `WickChart.setPluginVisible`, or mutate it
+     * directly and call `chart.render()`.
+     */
+    visible?: boolean;
+    draw(api: PluginRenderApi<TPoint>): void;
+    /**
+     * Called on pointer down inside the chart's plotting area (not the
+     * price-axis strip). Return `true` to *claim* the gesture: `WickChart`
+     * then suppresses its own panning/hover for this pointer until it's
+     * released, and routes `onPointerMove`/`onPointerUp` to this plugin and
+     * no other. Return `false`/`undefined` (the default, if omitted) to
+     * leave the gesture to the chart's own panning — a plugin should only
+     * claim a gesture while actively placing or editing something of its
+     * own, not on every pointer down.
+     *
+     * Checked in reverse-registration order (the most recently added plugin
+     * gets first refusal), and the first plugin to claim a gesture wins —
+     * at most one plugin owns a given pointer down-to-up sequence.
+     */
+    onPointerDown?(event: ChartPointerEvent): boolean | void;
+    /** Only called for a gesture this plugin's `onPointerDown` claimed. */
+    onPointerMove?(event: ChartPointerEvent): void;
+    /** Only called for a gesture this plugin's `onPointerDown` claimed. */
+    onPointerUp?(event: ChartPointerEvent): void;
+}

package/dist/plugins/types.js

@@ -0,0 +1 @@
+export {};

package/dist/priceAxis.d.ts

@@ -0,0 +1,7 @@
+/** Generates ~`targetCount` evenly-spaced, human-friendly tick values
+ * covering [min, max] — e.g. 71000, 71500, 72000 rather than the raw
+ * fractional steps a naive linear split would produce. */
+export declare function niceTicks(min: number, max: number, targetCount: number): number[];
+/** Formats a price with a decimal count inferred from the tick step, so
+ * 0.5-step ticks show "71000.5" and 100-step ticks show "71000". */
+export declare function formatPrice(value: number, step: number): string;

package/dist/priceAxis.js

@@ -0,0 +1,49 @@
+/** Rounds `range` to a "nice" 1/2/5×10^n value — the classic Heckbert
+ * nice-numbers step used by every axis-tick generator (d3 included). */
+function niceNumber(range, round) {
+    const exponent = Math.floor(Math.log10(range));
+    const fraction = range / 10 ** exponent;
+    let niceFraction;
+    if (round) {
+        if (fraction < 1.5)
+            niceFraction = 1;
+        else if (fraction < 3)
+            niceFraction = 2;
+        else if (fraction < 7)
+            niceFraction = 5;
+        else
+            niceFraction = 10;
+    }
+    else {
+        if (fraction <= 1)
+            niceFraction = 1;
+        else if (fraction <= 2)
+            niceFraction = 2;
+        else if (fraction <= 5)
+            niceFraction = 5;
+        else
+            niceFraction = 10;
+    }
+    return niceFraction * 10 ** exponent;
+}
+/** Generates ~`targetCount` evenly-spaced, human-friendly tick values
+ * covering [min, max] — e.g. 71000, 71500, 72000 rather than the raw
+ * fractional steps a naive linear split would produce. */
+export function niceTicks(min, max, targetCount) {
+    if (min === max)
+        return [min];
+    const step = niceNumber((max - min) / Math.max(1, targetCount - 1), true);
+    const niceMin = Math.floor(min / step) * step;
+    const niceMax = Math.ceil(max / step) * step;
+    const ticks = [];
+    for (let v = niceMin; v <= niceMax + step * 0.5; v += step) {
+        ticks.push(Math.round(v * 1e8) / 1e8); // strip float noise
+    }
+    return ticks;
+}
+/** Formats a price with a decimal count inferred from the tick step, so
+ * 0.5-step ticks show "71000.5" and 100-step ticks show "71000". */
+export function formatPrice(value, step) {
+    const decimals = step > 0 && step < 1 ? Math.max(0, -Math.floor(Math.log10(step))) : 0;
+    return value.toLocaleString('en-US', { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+}

package/dist/priceRange.d.ts

@@ -0,0 +1,12 @@
+import type { ValueRange } from './types.js';
+/**
+ * Widens/narrows a raw [min, max] domain around its center by
+ * `scaleFactor`, with a floor so a flat or single-point series still gets
+ * a visible span instead of collapsing to zero height. This is the shared
+ * "auto-fit + manual zoom" math every series's `getValueRange` needs —
+ * only how a series derives its own raw min/max (candlestick: high/low
+ * across visible candles; a future line series: min/max of `.value`)
+ * differs between series types, so that part lives in each series
+ * definition instead of here. See `src/series/candlestick.ts` for a caller.
+ */
+export declare function fitRange(rawMin: number, rawMax: number, scaleFactor: number): ValueRange;

package/dist/priceRange.js

@@ -0,0 +1,16 @@
+/**
+ * Widens/narrows a raw [min, max] domain around its center by
+ * `scaleFactor`, with a floor so a flat or single-point series still gets
+ * a visible span instead of collapsing to zero height. This is the shared
+ * "auto-fit + manual zoom" math every series's `getValueRange` needs —
+ * only how a series derives its own raw min/max (candlestick: high/low
+ * across visible candles; a future line series: min/max of `.value`)
+ * differs between series types, so that part lives in each series
+ * definition instead of here. See `src/series/candlestick.ts` for a caller.
+ */
+export function fitRange(rawMin, rawMax, scaleFactor) {
+    const mid = (rawMin + rawMax) / 2;
+    const rawHalfSpan = (rawMax - rawMin) / 2 || Math.abs(mid) * 0.01 || 1;
+    const halfSpan = rawHalfSpan * scaleFactor;
+    return { min: mid - halfSpan, max: mid + halfSpan };
+}

package/dist/renderer.d.ts

@@ -0,0 +1,79 @@
+import type { ChartPlugin } from './plugins/types.js';
+import type { SeriesDefinition } from './series/types.js';
+import type { WickChartOptions, SeriesPoint } from './types.js';
+import type { Viewport } from './viewport.js';
+export interface RenderInput<TPoint extends SeriesPoint> {
+    /** Every point, sorted ascending by normalized time. */
+    sorted: TPoint[];
+    /** Parallel to `sorted` — each already run through `toUnixSeconds`. */
+    times: number[];
+    viewport: Viewport;
+    /** Index into `sorted` (not viewport-local) of the hovered point, or null. */
+    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. */
+    hoverY: number | null;
+    plugins: ChartPlugin<TPoint>[];
+}
+/**
+ * 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.
+ * 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.
+ *
+ * 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.
+ */
+export declare class ChartRenderer<TPoint extends SeriesPoint> {
+    private canvas;
+    private seriesDefinition;
+    private ctx;
+    private background;
+    private style;
+    private font;
+    private axis;
+    private crosshair;
+    private legend;
+    constructor(canvas: HTMLCanvasElement, seriesDefinition: SeriesDefinition<TPoint, unknown>, options?: WickChartOptions);
+    /** 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. */
+    get chartWidth(): number;
+    get chartHeight(): number;
+    get priceAxisWidth(): number;
+    private axisFont;
+    private legendFont;
+    render(input: RenderInput<TPoint>): void;
+    /** 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;
+    private renderPriceAxis;
+    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

@@ -0,0 +1,318 @@
+import { formatAxisLabel, formatHoverTime, pickTickIndices } from './axis.js';
+import { createScale } from './hybridScale.js';
+import { formatPrice, niceTicks } from './priceAxis.js';
+const DEFAULT_BACKGROUND = 'transparent';
+const DEFAULT_FONT = {
+    family: 'sans-serif',
+    axisSize: 10,
+    legendSize: 11,
+};
+const DEFAULT_AXIS = {
+    priceWidth: 64,
+    timeHeight: 24,
+    priceTickCount: 5,
+    timeMaxTicks: 6,
+    textColor: '#787878',
+    lineColor: '#33333333',
+    gridLineColor: '#2a2a2a55',
+};
+const DEFAULT_CROSSHAIR = {
+    lineColor: '#9090904d',
+    labelBackground: '#3a3a3a',
+    labelTextColor: '#f0f0f0',
+    labelPaddingX: 4,
+    labelPaddingY: 3,
+};
+const DEFAULT_LEGEND = {
+    textColor: '#f0f0f0',
+    background: '#3a3a3a',
+    paddingX: 8,
+    paddingY: 6,
+    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.
+ * 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.
+ *
+ * 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.
+ */
+export class ChartRenderer {
+    constructor(canvas, seriesDefinition, options = {}) {
+        this.canvas = canvas;
+        this.seriesDefinition = seriesDefinition;
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            throw new Error('wick-charts: canvas 2d context unavailable');
+        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.crosshair = { ...DEFAULT_CROSSHAIR, ...options.crosshair };
+        this.legend = { ...DEFAULT_LEGEND, ...options.legend };
+    }
+    /** 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. */
+    get chartWidth() {
+        return Math.max(0, this.canvas.width - this.axis.priceWidth);
+    }
+    get chartHeight() {
+        return Math.max(0, this.canvas.height - this.axis.timeHeight);
+    }
+    get priceAxisWidth() {
+        return this.axis.priceWidth;
+    }
+    axisFont() {
+        return `${this.font.axisSize}px ${this.font.family}`;
+    }
+    legendFont() {
+        return `${this.font.legendSize}px ${this.font.family}`;
+    }
+    render(input) {
+        const { ctx, canvas, background, seriesDefinition, style } = this;
+        const { sorted, times, viewport, hoverIndex, hoverY, plugins } = input;
+        const width = canvas.width;
+        const height = canvas.height;
+        const chartWidth = this.chartWidth;
+        const chartHeight = this.chartHeight;
+        ctx.clearRect(0, 0, width, height);
+        if (background !== 'transparent') {
+            ctx.fillStyle = background;
+            ctx.fillRect(0, 0, width, height);
+        }
+        if (sorted.length === 0 || chartWidth <= 0 || chartHeight <= 0)
+            return;
+        const startIdx = Math.max(0, Math.floor(viewport.startIndex));
+        const endIdx = Math.min(sorted.length, Math.ceil(viewport.endIndex));
+        const visible = sorted.slice(startIdx, endIdx);
+        if (visible.length === 0)
+            return;
+        // Manual mode (user has dragged/scaled the price axis) wins once set;
+        // otherwise fit to whatever points are currently visible.
+        const { min: valueMin, max: valueMax } = viewport.valueRangeOverride ?? seriesDefinition.getValueRange(visible, viewport.valueScaleFactor);
+        // JS below a few hundred points, WASM above — see hybridScale.ts.
+        // Whichever it picks, `dispose()` must run once we're done reading
+        // from it (a no-op on the JS path, a real WASM memory free otherwise).
+        const { scale: yScale, dispose: disposeYScale } = createScale(valueMin, valueMax, chartHeight, 0, visible.length);
+        // Flipped in `finally`, right before `disposeYScale()` frees the WASM
+        // scale's backing memory (a no-op on the JS path). Guards `yForValue`
+        // below so a plugin that stashes it and calls it later gets a clear
+        // thrown error instead of touching freed WASM memory — see the
+        // interface-level warning on `PluginRenderApi`.
+        let frameEnded = false;
+        try {
+            const slotWidth = chartWidth / viewport.visibleCount;
+            // x position for a *global* sorted-array index — honors the (possibly
+            // fractional) viewport.startIndex so panning is pixel-smooth, not
+            // stepped a whole point at a time.
+            const xForIndex = (globalIndex) => (globalIndex - viewport.startIndex) * slotWidth + slotWidth / 2;
+            seriesDefinition.draw({ ctx, visible, startIndex: startIdx, xForIndex, slotWidth, yScale, chartHeight }, style);
+            const priceStep = this.currentPriceStep(valueMin, valueMax);
+            this.renderPriceAxis(valueMin, valueMax, priceStep, yScale, chartWidth, chartHeight);
+            this.renderTimeAxis(times, startIdx, visible.length, chartHeight, chartWidth, xForIndex);
+            if (hoverIndex !== null && hoverIndex >= startIdx && hoverIndex < endIdx) {
+                this.renderCrosshairAndLegend(sorted[hoverIndex], xForIndex(hoverIndex), times[hoverIndex], hoverY, valueMin, valueMax, priceStep, chartWidth, chartHeight);
+            }
+            if (plugins.length > 0) {
+                const api = {
+                    ctx,
+                    chartWidth,
+                    chartHeight,
+                    xForIndex,
+                    yForValue: (value) => {
+                        if (frameEnded) {
+                            throw new Error('wick-charts: PluginRenderApi.yForValue called after its frame ended — ' +
+                                'only call it synchronously inside ChartPlugin.draw()');
+                        }
+                        return yScale.map(value);
+                    },
+                    // Exact inverse of xForIndex above — solving
+                    // `x = (index - viewport.startIndex) * slotWidth + slotWidth / 2` for `index`.
+                    indexForX: (x) => viewport.startIndex + (x - slotWidth / 2) / slotWidth,
+                    // Exact inverse of the value->y mapping createScale set up for this
+                    // frame (domain [valueMin, valueMax] -> range [chartHeight, 0]).
+                    valueForY: (y) => valueMin + (1 - y / chartHeight) * (valueMax - valueMin),
+                    visibleStartIndex: startIdx,
+                    visibleEndIndex: endIdx,
+                    allPoints: sorted,
+                };
+                for (const plugin of plugins) {
+                    if (plugin.visible === false)
+                        continue;
+                    // save/restore isolates each plugin's canvas state (strokeStyle,
+                    // lineDash, ...) from the next one — a plugin that forgets to
+                    // clean up after itself can't bleed style into whatever draws
+                    // after it. try/catch isolates failures the same way: one
+                    // plugin throwing shouldn't blank out the rest of the chart.
+                    ctx.save();
+                    try {
+                        plugin.draw(api);
+                    }
+                    catch (error) {
+                        console.error('wick-charts: a plugin threw during draw()', error);
+                    }
+                    finally {
+                        ctx.restore();
+                    }
+                }
+            }
+        }
+        finally {
+            frameEnded = true;
+            disposeYScale();
+        }
+    }
+    /** 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;
+    }
+    renderPriceAxis(priceMin, priceMax, step, yScale, chartWidth, chartHeight) {
+        const { ctx, axis } = this;
+        const ticks = niceTicks(priceMin, priceMax, axis.priceTickCount);
+        ctx.strokeStyle = axis.lineColor;
+        ctx.beginPath();
+        ctx.moveTo(chartWidth + 0.5, 0);
+        ctx.lineTo(chartWidth + 0.5, chartHeight);
+        ctx.stroke();
+        ctx.font = this.axisFont();
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'middle';
+        for (const value of ticks) {
+            const y = yScale.map(value);
+            if (y < 0 || y > chartHeight)
+                continue;
+            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);
+        }
+    }
+    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) {
+        const { ctx, canvas, seriesDefinition, style, crosshair } = this;
+        ctx.save();
+        ctx.strokeStyle = crosshair.lineColor;
+        ctx.setLineDash([4, 4]);
+        ctx.beginPath();
+        ctx.moveTo(x, 0);
+        ctx.lineTo(x, chartHeight);
+        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 formula as PluginRenderApi.valueForY.
+            const value = valueMin + (1 - hoverY / chartHeight) * (valueMax - valueMin);
+            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);
+    }
+}