hyperprop-charting-library 0.1.138 → 0.1.139

package/dist/index.js

@@ -2821,6 +2821,7 @@ var DEFAULT_OPTIONS = {
   doubleClickAction: "reset",
   keyboard: { enabled: true, panBars: 1, deleteSelectedDrawing: true },
   accessibility: { label: "Price chart", description: "", focusable: true },
+  downsampling: { enabled: true, thresholdPx: 1.5 },
   crosshair: DEFAULT_CROSSHAIR_OPTIONS,
   grid: DEFAULT_GRID_OPTIONS,
   watermark: DEFAULT_WATERMARK_OPTIONS,
@@ -2871,6 +2872,10 @@ var mergeChartOptions = (baseOptions, options = {}) => ({
     ...baseOptions.accessibility,
     ...options.accessibility ?? {}
   },
+  downsampling: {
+    ...baseOptions.downsampling,
+    ...options.downsampling ?? {}
+  },
   crosshair: {
     ...baseOptions.crosshair,
     ...options.crosshair ?? {}
@@ -3746,6 +3751,64 @@ function createChart(element, options = {}) {
     heikinAshiFingerprint = fingerprint;
     return result;
   };
+  let compareSeriesStates = [];
+  const prepareCompareSeries = (options2) => {
+    const rows = [];
+    for (const point of options2.data ?? []) {
+      const t = new Date(point.t).getTime();
+      const c = Number(point.c);
+      if (Number.isFinite(t) && Number.isFinite(c)) rows.push({ t, c });
+    }
+    rows.sort((a, b) => a.t - b.t);
+    return {
+      options: options2,
+      times: rows.map((row) => row.t),
+      closes: rows.map((row) => row.c),
+      aligned: null,
+      alignedFingerprint: ""
+    };
+  };
+  const mainDataFingerprint = () => {
+    const last = data[data.length - 1];
+    return last ? `${data.length}|${data[0].time.getTime()}|${last.time.getTime()}` : "empty";
+  };
+  const getAlignedCompareValues = (state) => {
+    const fingerprint = `${mainDataFingerprint()}|${state.times.length}|${state.times[state.times.length - 1] ?? 0}`;
+    if (state.aligned && state.alignedFingerprint === fingerprint) {
+      return state.aligned;
+    }
+    const aligned = new Float64Array(data.length).fill(Number.NaN);
+    let cursor = 0;
+    let lastValue = Number.NaN;
+    for (let i = 0; i < data.length; i += 1) {
+      const barTime = data[i].time.getTime();
+      while (cursor < state.times.length && state.times[cursor] <= barTime) {
+        lastValue = state.closes[cursor];
+        cursor += 1;
+      }
+      aligned[i] = lastValue;
+    }
+    state.aligned = aligned;
+    state.alignedFingerprint = fingerprint;
+    return aligned;
+  };
+  const visibleCompareSeries = () => compareSeriesStates.filter((state) => state.options.visible !== false && state.times.length > 0);
+  const setCompareSeries = (series) => {
+    compareSeriesStates = (series ?? []).filter((entry) => entry && entry.id).map(prepareCompareSeries);
+    scheduleDraw({ updateAutoScale: true });
+  };
+  const addCompareSeries = (series) => {
+    if (!series?.id) return;
+    compareSeriesStates = [...compareSeriesStates.filter((state) => state.options.id !== series.id), prepareCompareSeries(series)];
+    scheduleDraw({ updateAutoScale: true });
+  };
+  const removeCompareSeries = (id) => {
+    const next = compareSeriesStates.filter((state) => state.options.id !== id);
+    if (next.length === compareSeriesStates.length) return;
+    compareSeriesStates = next;
+    scheduleDraw({ updateAutoScale: true });
+  };
+  const getCompareSeries = () => compareSeriesStates.map((state) => state.options);
   const formatHoverTimeLabel = (time, mode) => {
     if (mode === "time") {
       return time.toLocaleTimeString(void 0, {
@@ -4351,6 +4414,31 @@ function createChart(element, options = {}) {
     const chartType = mergedOptions.chartType;
     const seriesData = chartType === "heikin-ashi" ? getHeikinAshiData() : data;
     const isLineStyleChart = chartType === "line" || chartType === "area" || chartType === "baseline";
+    const comparePlans = [];
+    for (const state of visibleCompareSeries()) {
+      const aligned = getAlignedCompareValues(state);
+      let anchorIndex = -1;
+      for (let index = startIndex; index <= endIndex; index += 1) {
+        if (Number.isFinite(aligned[index] ?? Number.NaN)) {
+          anchorIndex = index;
+          break;
+        }
+      }
+      if (anchorIndex < 0) continue;
+      const baseCompare = aligned[anchorIndex];
+      const baseMain = seriesData[anchorIndex]?.c ?? 0;
+      const usePercent = (state.options.scale ?? "percent") !== "price";
+      const toPrice = usePercent && baseCompare > 0 ? (value) => baseMain * value / baseCompare : (value) => value;
+      let lastNativeValue = Number.NaN;
+      for (let index = endIndex; index >= startIndex; index -= 1) {
+        const value = aligned[index];
+        if (value !== void 0 && Number.isFinite(value)) {
+          lastNativeValue = value;
+          break;
+        }
+      }
+      comparePlans.push({ state, aligned, toPrice, usePercent, baseCompare, lastNativeValue });
+    }
     const skipLatestIndex = mergedOptions.autoScaleIgnoreLatestCandle && data.length > 1 ? data.length - 1 : -1;
     const scanCandleRange = (from, to) => {
       let min = Number.POSITIVE_INFINITY;
@@ -4396,6 +4484,23 @@ function createChart(element, options = {}) {
         maxPrice = Math.max(maxPrice, weightedMax);
       }
     }
+    for (const plan of comparePlans) {
+      if (plan.state.options.includeInAutoScale === false) continue;
+      let compareMin = Number.POSITIVE_INFINITY;
+      let compareMax = Number.NEGATIVE_INFINITY;
+      for (let index = startIndex; index <= endIndex; index += 1) {
+        const value = plan.aligned[index];
+        if (value === void 0 || !Number.isFinite(value)) continue;
+        const price = plan.toPrice(value);
+        if (!Number.isFinite(price)) continue;
+        if (price < compareMin) compareMin = price;
+        if (price > compareMax) compareMax = price;
+      }
+      if (compareMin <= compareMax) {
+        minPrice = Math.min(minPrice, compareMin);
+        maxPrice = Math.max(maxPrice, compareMax);
+      }
+    }
     const priceRange = maxPrice - minPrice || 1;
     const autoMin = minPrice - priceRange * 0.08;
     const autoMax = maxPrice + priceRange * 0.08;
@@ -5507,7 +5612,106 @@ function createChart(element, options = {}) {
       }
       return data[index]?.v;
     };
-    if (isLineStyleChart) {
+    const downsamplingOptions = mergedOptions.downsampling ?? DEFAULT_OPTIONS.downsampling;
+    const downsampleThresholdPx = Math.max(0.2, downsamplingOptions?.thresholdPx ?? 1.5);
+    const shouldDownsample = (downsamplingOptions?.enabled ?? true) && candleSpacing < downsampleThresholdPx && endIndex - startIndex > 2;
+    const seriesColumns = [];
+    if (shouldDownsample) {
+      let current = null;
+      let currentColumn = Number.NaN;
+      for (let index = startIndex; index <= endIndex; index += 1) {
+        const point = seriesData[index];
+        if (!point) continue;
+        const column = Math.round(chartLeft + (index + 0.5 - xStart) / xSpan * chartWidth);
+        if (!current || column !== currentColumn) {
+          currentColumn = column;
+          current = {
+            x: column,
+            open: point.o,
+            high: point.h,
+            low: point.l,
+            close: point.c,
+            minClose: point.c,
+            maxClose: point.c,
+            minCloseIndex: index,
+            maxCloseIndex: index
+          };
+          seriesColumns.push(current);
+          continue;
+        }
+        if (point.h > current.high) current.high = point.h;
+        if (point.l < current.low) current.low = point.l;
+        current.close = point.c;
+        if (point.c < current.minClose) {
+          current.minClose = point.c;
+          current.minCloseIndex = index;
+        }
+        if (point.c > current.maxClose) {
+          current.maxClose = point.c;
+          current.maxCloseIndex = index;
+        }
+      }
+    }
+    if (shouldDownsample && !isLineStyleChart) {
+      const upColumns = new Path2D();
+      const downColumns = new Path2D();
+      for (const column of seriesColumns) {
+        const path = column.close >= column.open ? upColumns : downColumns;
+        const x = column.x + 0.5;
+        const top = crisp(yFromPrice(column.high));
+        const bottom = crisp(yFromPrice(column.low));
+        path.moveTo(x, top);
+        path.lineTo(x, bottom === top ? bottom + 1 : bottom);
+      }
+      ctx.lineWidth = 1;
+      ctx.strokeStyle = mergedOptions.upColor;
+      ctx.stroke(upColumns);
+      ctx.strokeStyle = mergedOptions.downColor;
+      ctx.stroke(downColumns);
+    } else if (shouldDownsample && isLineStyleChart) {
+      const seriesLineWidth = Math.max(1, mergedOptions.lineWidth);
+      const linePath = new Path2D();
+      let started = false;
+      let firstX = 0;
+      let lastX = 0;
+      for (const column of seriesColumns) {
+        const lowFirst = column.minCloseIndex <= column.maxCloseIndex;
+        const first = lowFirst ? column.minClose : column.maxClose;
+        const second = lowFirst ? column.maxClose : column.minClose;
+        const x = column.x;
+        if (!started) {
+          linePath.moveTo(x, yFromPrice(first));
+          firstX = x;
+          started = true;
+        } else {
+          linePath.lineTo(x, yFromPrice(first));
+        }
+        if (second !== first) {
+          linePath.lineTo(x, yFromPrice(second));
+        }
+        lastX = x;
+      }
+      if (started) {
+        if (chartType === "area" || chartType === "baseline") {
+          const baseY = chartType === "baseline" ? yFromPrice(mergedOptions.baselinePrice ?? (yMin + yMax) / 2) : chartBottom;
+          const fillPath = new Path2D(linePath);
+          fillPath.lineTo(lastX, baseY);
+          fillPath.lineTo(firstX, baseY);
+          fillPath.closePath();
+          ctx.save();
+          ctx.globalAlpha = Math.max(0, Math.min(1, mergedOptions.areaFillOpacity));
+          ctx.fillStyle = chartType === "baseline" ? mergedOptions.upColor : mergedOptions.lineColor;
+          ctx.fill(fillPath);
+          ctx.restore();
+        }
+        ctx.save();
+        ctx.strokeStyle = chartType === "baseline" ? mergedOptions.upColor : mergedOptions.lineColor;
+        ctx.lineWidth = seriesLineWidth;
+        ctx.lineJoin = "round";
+        ctx.stroke(linePath);
+        ctx.restore();
+      }
+    } else if (isLineStyleChart) {
       const seriesLineWidth = Math.max(1, mergedOptions.lineWidth);
       const linePath = new Path2D();
       let started = false;
@@ -5673,6 +5877,105 @@ function createChart(element, options = {}) {
         ctx.stroke(downHollowBodies);
       }
     }
+    const compareAxisTags = [];
+    for (const plan of comparePlans) {
+      const color = plan.state.options.color ?? "#f59e0b";
+      const lineWidth = Math.max(1, plan.state.options.lineWidth ?? 1.5);
+      const path = new Path2D();
+      let started = false;
+      let firstX = 0;
+      let lastX = 0;
+      let lastY = 0;
+      let lastPrice = Number.NaN;
+      const emit = (x, y) => {
+        if (!started) {
+          path.moveTo(x, y);
+          firstX = x;
+          started = true;
+        } else {
+          path.lineTo(x, y);
+        }
+        lastX = x;
+        lastY = y;
+      };
+      const xForIndex = (index) => chartLeft + (index + 0.5 - xStart) / xSpan * chartWidth;
+      if (shouldDownsample) {
+        let column = Number.NaN;
+        let minValue = 0;
+        let maxValue = 0;
+        let minIndex = 0;
+        let maxIndex = 0;
+        let hasColumn = false;
+        const flushColumn = () => {
+          if (!hasColumn) return;
+          const lowFirst = minIndex <= maxIndex;
+          const first = plan.toPrice(lowFirst ? minValue : maxValue);
+          const second = plan.toPrice(lowFirst ? maxValue : minValue);
+          if (Number.isFinite(first)) emit(column, yFromPrice(first));
+          if (Number.isFinite(second) && second !== first) emit(column, yFromPrice(second));
+          lastPrice = plan.toPrice(maxIndex >= minIndex ? maxValue : minValue);
+        };
+        for (let index = startIndex; index <= endIndex; index += 1) {
+          const value = plan.aligned[index];
+          if (value === void 0 || !Number.isFinite(value)) continue;
+          const nextColumn = Math.round(xForIndex(index));
+          if (!hasColumn || nextColumn !== column) {
+            flushColumn();
+            column = nextColumn;
+            minValue = value;
+            maxValue = value;
+            minIndex = index;
+            maxIndex = index;
+            hasColumn = true;
+            continue;
+          }
+          if (value < minValue) {
+            minValue = value;
+            minIndex = index;
+          }
+          if (value > maxValue) {
+            maxValue = value;
+            maxIndex = index;
+          }
+        }
+        flushColumn();
+      } else {
+        for (let index = startIndex; index <= endIndex; index += 1) {
+          const value = plan.aligned[index];
+          if (value === void 0 || !Number.isFinite(value)) continue;
+          const price = plan.toPrice(value);
+          if (!Number.isFinite(price)) continue;
+          lastPrice = price;
+          emit(xForIndex(index), yFromPrice(price));
+        }
+      }
+      if (!started) continue;
+      if (plan.state.options.style === "area") {
+        const fillPath = new Path2D(path);
+        fillPath.lineTo(lastX, chartBottom);
+        fillPath.lineTo(firstX, chartBottom);
+        fillPath.closePath();
+        ctx.save();
+        ctx.globalAlpha = Math.max(0, Math.min(1, mergedOptions.areaFillOpacity)) * 0.6;
+        ctx.fillStyle = color;
+        ctx.fill(fillPath);
+        ctx.restore();
+      }
+      ctx.save();
+      ctx.strokeStyle = color;
+      ctx.lineWidth = lineWidth;
+      ctx.lineJoin = "round";
+      ctx.stroke(path);
+      ctx.restore();
+      if (Number.isFinite(lastPrice)) {
+        const label = plan.state.options.label ?? plan.state.options.id;
+        const nativeLast = plan.lastNativeValue;
+        const usePercentTag = plan.usePercent && plan.baseCompare > 0 && Number.isFinite(nativeLast);
+        const changePct = usePercentTag ? (nativeLast / plan.baseCompare - 1) * 100 : 0;
+        const shortText = usePercentTag ? `${changePct >= 0 ? "+" : ""}${changePct.toFixed(2)}%` : formatPrice(nativeLast);
+        compareAxisTags.push({ y: lastY, text: `${label} ${shortText}`, shortText, color });
+      }
+    }
     const activeOverlayIndicators = indicators.filter((indicator) => indicator.visible).map((indicator) => ({ indicator, plugin: indicatorRegistry.get(indicator.type) })).filter(
       (value) => value.plugin !== void 0 && (value.indicator.pane ?? value.plugin.pane ?? "overlay") === "overlay"
     ).sort((a, b) => a.indicator.zIndex - b.indicator.zIndex);
@@ -6447,6 +6750,35 @@ function createChart(element, options = {}) {
       drawText(countdownText, chartRight + 6, (fullChartBottom + height) / 2, "left", "middle", xAxis.textColor);
       ctx.font = prevFont;
     }
+    if (compareAxisTags.length > 0 && width - chartRight > 0) {
+      const prevFont = ctx.font;
+      const tagFontSize = Math.max(9, (resolvedAxis.fontSize ?? 12) - 2);
+      ctx.font = `${tagFontSize}px ${mergedOptions.fontFamily}`;
+      ctx.textBaseline = "middle";
+      ctx.textAlign = "left";
+      const placed = [];
+      const tagHeight = tagFontSize + 6;
+      const gutterWidth = width - chartRight - 4;
+      for (const tag of [...compareAxisTags].sort((a, b) => a.y - b.y)) {
+        const text = measureTextWidth(tag.text) + 10 <= gutterWidth ? tag.text : tag.shortText;
+        const tagWidth = Math.min(gutterWidth, measureTextWidth(text) + 10);
+        if (tagWidth <= 0) continue;
+        let tagY = clamp(tag.y - tagHeight / 2, chartTop, chartBottom - tagHeight);
+        for (const slot of placed) {
+          if (tagY < slot.bottom + 2 && tagY + tagHeight > slot.top - 2) {
+            tagY = slot.bottom + 2;
+          }
+        }
+        placed.push({ top: tagY, bottom: tagY + tagHeight });
+        ctx.save();
+        ctx.fillStyle = tag.color;
+        fillRoundedRect(chartRight + 2, Math.round(tagY), Math.round(tagWidth), tagHeight, 3);
+        ctx.fillStyle = labelTextColorOn(tag.color, "#ffffff");
+        ctx.fillText(text, chartRight + 7, Math.round(tagY + tagHeight / 2));
+        ctx.restore();
+      }
+      ctx.font = prevFont;
+    }
     if (baseCtx) {
       if (baseCanvas.width !== canvas.width || baseCanvas.height !== canvas.height) {
         baseCanvas.width = canvas.width;
@@ -9548,6 +9880,10 @@ function createChart(element, options = {}) {
     getMagnetMode,
     setPriceScale,
     getPriceScale,
+    setCompareSeries,
+    addCompareSeries,
+    removeCompareSeries,
+    getCompareSeries,
     cancelDrawing,
     setTradeMarkers,
     setSelectedDrawing,

package/docs/API.md

@@ -568,6 +568,7 @@ an up measurement, red for down.
 - `cancelDrawing(): boolean` — abort an in-progress multi-click drawing (between the first click and the final point, e.g. a half-drawn trendline/ray/fib). Returns `true` if a draft was cancelled. Wire it to Escape.
 - Hold **Shift** while drawing or dragging an endpoint of a `trendline`/`ray`/`arrow` to constrain it to the nearest 0/45/90° angle (e.g. a perfectly horizontal line).
 - `setMagnetMode(mode): void` / `getMagnetMode()` — magnet/snap for all drawing tools. `"none"` off, `"weak"` snaps to a candle's OHLC only when the cursor is near a value, `"strong"` always snaps to the nearest OHLC of the bar under the cursor. Holding Cmd/Ctrl while drawing/dragging forces strong snapping regardless of the mode.
+- `setCompareSeries(series: CompareSeriesOptions[]): void` / `addCompareSeries(series)` / `removeCompareSeries(id)` / `getCompareSeries()` — overlay other instruments on the main pane; see "Compare overlays" below
 - `setPriceScale(options: { mode?: "linear" | "log" | "percent"; inverted?: boolean }): void` / `getPriceScale()` — price-scale modes for the main pane (TradingView-style). `"log"` maps prices through log10 (wide ranges get 1/2/5-per-decade axis marks). `"percent"` keeps the linear mapping but relabels the axis (ticks, last-price/PDC/H/L/bid/ask tags and the crosshair) as % change from the first visible bar's close, updating as you pan. `inverted: true` flips the axis top-to-bottom. All viewport state stays in plain price space, so switching modes never moves your zoom, and drawings/orders/indicators follow automatically. Indicator panes keep their own scales. Included in `saveState()` as `priceScale`.
 - `setActiveDrawingTool(tool: DrawingToolType | null): void` (`DrawingToolType` = `"horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement" | "fib-extension" | "long-position" | "short-position" | "price-range" | "rectangle" | "text" | "note" | "parallel-channel" | "ellipse" | "arrow" | "brush" | "callout" | "measure"`)
 - `getActiveDrawingTool(): DrawingToolType | null`
@@ -610,6 +611,56 @@ link.click();
 
 ---
 
+## Compare overlays (multi-series)
+
+Overlay other instruments on the main pane. The host owns the data (it already
+has a datafeed); the chart aligns each series to the main bars by timestamp and
+draws it.
+
+```ts
+chart.setCompareSeries([
+  { id: "NQ", label: "NQ1!", data: nqBars, color: "#22d3ee" },
+  { id: "BTC", label: "BTCUSD", data: btcBars, color: "#a855f7", style: "area" },
+]);
+```
+
+- **Alignment** is by timestamp, computed once per data change (a merge walk,
+  not a search per bar), so different session hours and holidays are fine — the
+  last known value carries forward across gaps, and bars before a compared
+  instrument starts are simply not drawn.
+- **`scale`** defaults to `"percent"`: both instruments are normalised to their
+  first visible bar, so a $180 index and a $60,000 coin can be compared by
+  shape. It re-anchors as you pan, exactly like TradingView. Use `"price"` to
+  plot raw values on the main scale (only sensible for related instruments).
+- **Autoscale** includes compare series unless `includeInAutoScale: false`.
+- Each series gets a colored tag in the price gutter showing its own % move
+  (or value in price mode); tags stack instead of overlapping, and drop the
+  label when the gutter is too narrow.
+- Compare data is **not** in `saveState()` — it can be megabytes and the host
+  re-fetches it anyway. Persist the symbol list yourself and re-supply data on
+  load.
+
+## Deep zoom-out (viewport downsampling)
+
+Once bars are narrower than `downsampling.thresholdPx` (default 1.5px), several
+bars share a pixel column, and drawing each one separately is wasted work. The
+chart aggregates each column into one min/max bucket, so path operations scale
+with the chart's width rather than the number of bars. Extremes are preserved
+exactly — a one-bar spike still reaches full height — because the bucket keeps
+the true high and low rather than sampling. Candle and bar styles converge to a
+single colored high-low column (the body is sub-pixel at that density anyway);
+line/area/baseline keep a min/max envelope so the shape of the move survives.
+
+Measured on the playground benchmark (50,000 bars, 120Hz display):
+
+| Scenario | Per-bar (before) | Downsampled |
+| --- | --- | --- |
+| zoom 100 ↔ 20k bars | 21.3ms avg, 49.8ms p95, 47fps, 53 slow frames | 8.3ms avg, 10.3ms p95, 120fps, 0 slow frames |
+| deep zoom-out, 50k bars | 52.7ms avg, 58.8ms p95, 19fps, 240 slow frames | 8.3ms avg, 10.2ms p95, 120fps, 0 slow frames |
+
+Turn it off with `downsampling: { enabled: false }`, or tune when it kicks in
+with `thresholdPx`.
+
 ## Context menus, selection toolbars and keyboard
 
 Three pieces of chrome that every host previously rebuilt by hand. The chart

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperprop-charting-library",
-  "version": "0.1.138",
+  "version": "0.1.139",
   "description": "Lightweight TypeScript charting core",
   "type": "module",
   "main": "./dist/hyperprop-charting-library.cjs",