react-native-livechart 4.24.0 → 4.25.0

package/src/core/useLiveChartEngine.ts

@@ -5,7 +5,7 @@
  *
  * @see https://github.com/benjitaylor/liveline
  */
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import {
   cancelAnimation,
   Easing,
@@ -16,6 +16,7 @@ import {
   withTiming,
   type SharedValue,
 } from "react-native-reanimated";
+import { useDemandFrameLoop } from "../hooks/useDemandFrameLoop";
 import { MS_PER_FRAME_60FPS, RETURN_TO_LIVE_MS } from "../constants";
 import type {
   CandleGap,
@@ -30,7 +31,18 @@ import {
   type EngineTickMutable,
 } from "./liveChartEngineTick";
 
+import {
+  makeHistoryRangeCache,
+  type HistoryRangeCache,
+  type HistoryRevision,
+} from "./historyRangeCache";
+
+import { useHistoryRevision } from "./useHistoryRevision";
+
 export interface EngineConfig {
+  /** Original inputs before a reveal/stash bridge that may suppress same-array notifications. */
+  dataChangeSource?: SharedValue<LiveChartPoint[]>;
+  candlesChangeSource?: SharedValue<CandlePoint[]>;
   data: SharedValue<LiveChartPoint[]>;
   value: SharedValue<number>;
   timeWindow: number;
@@ -96,6 +108,12 @@ export interface EngineConfig {
   static?: boolean;
   /** Runtime gate for the frame loop. Gestures and configuration stay mounted. */
   isFrameLoopActive?: SharedValue<boolean>;
+  /** Experimental automatic idle scheduling, single-series only. */
+  autoSleep?: boolean;
+  /** Effects that require continuous engine work. */
+  keepAwake?: SharedValue<boolean>;
+  /** Appearance/reveal changes that should wake a settled engine. */
+  wakeSignal?: SharedValue<unknown>;
   /** Optional development-only frame publication counters. */
   debugFrameStats?: SharedValue<LiveChartFrameStats>;
   /**
@@ -185,16 +203,21 @@ export interface ChartEngineEdge {
   edgeValue: SharedValue<number>;
 }
 
-export interface SingleEngineState extends ChartEngineLayout, ChartEngineExtrema {
+export interface SingleEngineState
+  extends ChartEngineLayout,
+    ChartEngineExtrema {
   data: SharedValue<LiveChartPoint[]>;
   value: SharedValue<number>;
   displayValue: SharedValue<number>;
 }
 
-export interface MultiEngineState extends ChartEngineLayout, ChartEngineExtrema {
+export interface MultiEngineState
+  extends ChartEngineLayout,
+    ChartEngineExtrema {
   data: SharedValue<LiveChartPoint[]>;
   value: SharedValue<number>;
   displayValue: SharedValue<number>;
+  /** Entries captured by the last measured engine frame; history arrays remain shared. */
   series: SharedValue<SeriesConfig[]>;
   displaySeriesValues: SharedValue<number[]>;
   seriesOpacities: SharedValue<number[]>;
@@ -208,6 +231,8 @@ export type ChartEngineWithLiveValue = ChartEngineLayout & {
 };
 
 export interface EngineFrameRefs {
+  pointHistory?: SharedValue<HistoryRevision<LiveChartPoint> | undefined>;
+  candleHistory?: SharedValue<HistoryRevision<CandlePoint> | undefined>;
   data: SharedValue<LiveChartPoint[]>;
   value: SharedValue<number>;
   displayValue: SharedValue<number>;
@@ -268,6 +293,7 @@ export interface EngineFrameRefs {
 
 /** Stable state/input containers reused by the UI-thread frame callback. */
 export interface EngineFrameScratch {
+  historyCache: HistoryRangeCache;
   state: EngineTickMutable;
   input: EngineTickInput;
 }
@@ -275,6 +301,7 @@ export interface EngineFrameScratch {
 /** Allocate one single-series frame scratch. Call once per engine instance. */
 export function makeEngineFrameScratch(): EngineFrameScratch {
   return {
+    historyCache: makeHistoryRangeCache(),
     state: {
       displayValue: 0,
       displayMin: 0,
@@ -375,7 +402,9 @@ export function applyLiveChartEngineFrame(
   input.nowOverride = sv.nowOverrideSV?.value;
   input.windowBuffer = sv.windowBufferSV?.value ?? 0;
   input.targetValue = sv.value.value;
-  input.points = sv.data.value;
+  const pointHistory = sv.pointHistory?.value;
+  const candleHistory = sv.candleHistory?.value;
+  input.points = pointHistory?.data ?? sv.data.value;
   input.nowSeconds = Date.now() / 1000;
   input.paused = sv.pausedSV.value;
   input.snap = snap;
@@ -385,15 +414,16 @@ export function applyLiveChartEngineFrame(
   input.returnFrom = sv.returnFromSV?.value;
   input.viewWindow = sv.viewWindowSV?.value;
   input.mode = sv.modeSV.value;
-  input.candles = sv.candles?.value;
+  input.candles = candleHistory?.data ?? sv.candles?.value;
+  input.historyRevision =
+    input.mode === "candle" ? candleHistory : pointHistory;
   input.liveCandle = sv.liveCandle?.value;
   input.candleGaps = sv.candleGapsSV?.value;
-  input.candleGapBridgeNoTrades =
-    sv.candleGapBridgeNoTradesSV?.value ?? false;
+  input.candleGapBridgeNoTrades = sv.candleGapBridgeNoTradesSV?.value ?? false;
   input.candleGapBridgeUnavailable =
     sv.candleGapBridgeUnavailableSV?.value ?? false;
   input.candleGapBridgeUnknown = sv.candleGapBridgeUnknownSV?.value ?? false;
-  tickLiveChartEngineFrame(state, input);
+  tickLiveChartEngineFrame(state, input, scratch?.historyCache);
   sv.displayValue.value = state.displayValue;
   sv.displayMin.value = state.displayMin;
   sv.displayMax.value = state.displayMax;
@@ -409,16 +439,22 @@ export function applyLiveChartEngineFrame(
   // once a real (measured) frame consumed it. The tick early-returns on a
   // zero-size canvas (before applying the snap), so keep the flag pending until
   // the canvas has laid out, or a snap arriving pre-layout would be dropped.
-  if (snap && sv.snapSV && sv.canvasWidth.value !== 0 && sv.canvasHeight.value !== 0) {
+  if (
+    snap &&
+    sv.snapSV &&
+    sv.canvasWidth.value !== 0 &&
+    sv.canvasHeight.value !== 0
+  ) {
     sv.snapSV.value = false;
   }
 }
 
 export function useLiveChartEngine(
   config: EngineConfig,
-): SingleEngineState & ChartEngineScroll & ChartEngineEdge {
+): SingleEngineState & ChartEngineScroll & ChartEngineEdge & { wake: () => void } {
   const {
     data,
+    dataChangeSource = data,
     value,
     timeWindow: configuredTimeWindow,
     smoothing: configuredSmoothing,
@@ -442,9 +478,13 @@ export function useLiveChartEngine(
     static: isStatic,
     isFrameLoopActive,
     debugFrameStats,
+    autoSleep = false,
+    keepAwake,
+    wakeSignal,
     snapKey,
     mode,
     candles,
+    candlesChangeSource = candles,
     liveCandle,
     candleGaps,
     candleGapBridgeNoTrades,
@@ -472,9 +512,7 @@ export function useLiveChartEngine(
   );
   // Static charts snap to their target in one tick (smoothing=1), so the single
   // settle reaction below produces the final state with no per-frame easing.
-  const smoothing = useDerivedValue(() =>
-    isStatic ? 1 : configuredSmoothing,
-  );
+  const smoothing = useDerivedValue(() => (isStatic ? 1 : configuredSmoothing));
   const adaptiveSpeedBoostSV = useDerivedValue(() => adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => exaggerate ?? false);
   const referenceValue = useDerivedValue(() => configuredReferenceValue);
@@ -597,8 +635,14 @@ export function useLiveChartEngine(
   // React renders: Reanimated uses captured closure values as implicit reaction
   // dependencies, and rebuilding this object would unregister/re-register the
   // static settle mapper behind its path consumers. See #329.
+  // Observe original feeds as well as reveal bridges: same-array assignments
+  // may suppress bridge notifications. Live candle changes stay uncached.
+  const pointHistory = useHistoryRevision(data, dataChangeSource);
+  const candleHistory = useHistoryRevision(candles, candlesChangeSource);
   const frameRefs = useMemo<EngineFrameRefs>(
     () => ({
+      pointHistory,
+      candleHistory,
       data,
       value,
       displayValue,
@@ -644,6 +688,8 @@ export function useLiveChartEngine(
       extremaMaxTime,
     }),
     [
+      pointHistory,
+      candleHistory,
       adaptiveSpeedBoostSV,
       allowFutureViewEndSV,
       candleGapBridgeNoTradesSV,
@@ -696,41 +742,78 @@ export function useLiveChartEngine(
     frameScratchRef.current = makeEngineFrameScratch();
   }
 
-  // `autostart=false` registers the frame callback without running it — the live
-  // loop is fully inert in static mode (the invariant that makes this worth it).
-  const engineFrameCallback = useFrameCallback((frameInfo) => {
+  const tickFrame = useCallback((dt: number): boolean => {
     "worklet";
-    if (isFrameLoopActive?.get() === false) return;
-    const beforeValue = debugFrameStats ? displayValue.get() : 0;
-    const beforeMin = debugFrameStats ? displayMin.get() : 0;
-    const beforeMax = debugFrameStats ? displayMax.get() : 0;
-    const beforeWindow = debugFrameStats ? displayWindow.get() : 0;
-    const beforeTimestamp = debugFrameStats ? timestamp.get() : 0;
-    const beforeLiveEdge = debugFrameStats ? liveEdge.get() : 0;
-    const beforeEdgeValue = debugFrameStats ? edgeValue.get() : 0;
-    applyLiveChartEngineFrame(frameInfo, frameRefs, frameScratchRef.current!);
+    if (isFrameLoopActive?.get() === false) return false;
+    if (!autoSleep && !debugFrameStats) {
+      applyLiveChartEngineFrame({ timeSincePreviousFrame: dt }, frameRefs, frameScratchRef.current!);
+      return true;
+    }
+    const beforeValue = displayValue.get();
+    const beforeMin = displayMin.get();
+    const beforeMax = displayMax.get();
+    const beforeWindow = displayWindow.get();
+    const beforeTimestamp = timestamp.get();
+    const beforeLiveEdge = liveEdge.get();
+    const beforeEdgeValue = edgeValue.get();
+    applyLiveChartEngineFrame({ timeSincePreviousFrame: dt }, frameRefs, frameScratchRef.current!);
+    const changed = beforeValue !== displayValue.get() || beforeMin !== displayMin.get() ||
+      beforeMax !== displayMax.get() || beforeWindow !== displayWindow.get() ||
+      beforeTimestamp !== timestamp.get() || beforeEdgeValue !== edgeValue.get();
     if (debugFrameStats) {
-      const didPublish =
-        beforeValue !== displayValue.get() ||
-        beforeMin !== displayMin.get() ||
-        beforeMax !== displayMax.get() ||
-        beforeWindow !== displayWindow.get() ||
-        beforeTimestamp !== timestamp.get() ||
-        beforeLiveEdge !== liveEdge.get() ||
-        beforeEdgeValue !== edgeValue.get();
+      const didPublish = changed || beforeLiveEdge !== liveEdge.get();
       const previous = debugFrameStats.get();
-      debugFrameStats.set({
-        frames: previous.frames + 1,
-        published: previous.published + (didPublish ? 1 : 0),
-        skipped: previous.skipped + (didPublish ? 0 : 1),
-      });
+      debugFrameStats.set({ frames: previous.frames + 1, published: previous.published + (didPublish ? 1 : 0), skipped: previous.skipped + (didPublish ? 0 : 1) });
+    }
+    // The liveEdge clock alone is not a visible animation while parked/paused.
+    // Do not sleep if a stranded viewEnd actually fell back to following live.
+    const parked = viewEnd.get() !== null && timestamp.get() === viewEnd.get();
+    const clockMoves = nowOverrideSV.get() === undefined && !pausedSV.get() && !parked;
+    return changed || clockMoves || keepAwake?.get() === true || returnT.get() < 1;
+  }, [autoSleep, isFrameLoopActive, displayValue, displayMin, displayMax, displayWindow, timestamp,
+    liveEdge, edgeValue, frameRefs, frameScratchRef, debugFrameStats, viewEnd, nowOverrideSV, pausedSV, keepAwake, returnT]);
+
+  const prepareWake = useCallback(() => {
+    "worklet";
+    // Read the arrays themselves, not a length/endpoints fingerprint: modify()
+    // can change an interior value without changing any of those quantities.
+    // History revisions also notify when a reveal bridge suppresses a same-array
+    // source update. A sleeping engine must wake to consume that invalidation.
+    return [pointHistory.get(), candleHistory.get(), data.get(), value.get(), candles?.get(), liveCandle?.get(), canvasWidth.get(),
+      canvasHeight.get(), timeWindow.get(), smoothing.get(), adaptiveSpeedBoostSV.get(),
+      exaggerateSV.get(), referenceValue.get(), referenceValues.get(), thresholdRangePoints.get(),
+      thresholdRangeExtendToStart.get(), thresholdRangeExtendToNow.get(), nonNegativeSV.get(),
+      maxValueSV.get(), yRangeScale?.get(), nowOverrideSV.get(), windowBufferSV.get(), pausedSV.get(),
+      viewEnd.get(), viewWindow.get(), allowFutureViewEndSV.get(), returnT.get(), returnFrom.get(),
+      snapSV.get(), modeSV.get(), candleGapsSV.get(), candleGapBridgeNoTradesSV.get(),
+      candleGapBridgeUnavailableSV.get(), candleGapBridgeUnknownSV.get(), isFrameLoopActive?.get(),
+      keepAwake?.get(), wakeSignal?.get()];
+  }, [pointHistory, candleHistory, data, value, candles, liveCandle, canvasWidth, canvasHeight, timeWindow, smoothing,
+    adaptiveSpeedBoostSV, exaggerateSV, referenceValue, referenceValues, thresholdRangePoints,
+    thresholdRangeExtendToStart, thresholdRangeExtendToNow, nonNegativeSV, maxValueSV, yRangeScale,
+    nowOverrideSV, windowBufferSV, pausedSV, viewEnd, viewWindow, allowFutureViewEndSV, returnT,
+    returnFrom, snapSV, modeSV, candleGapsSV, candleGapBridgeNoTradesSV, candleGapBridgeUnavailableSV,
+    candleGapBridgeUnknownSV, isFrameLoopActive, keepAwake, wakeSignal]);
+
+  const wakeLoop = useDemandFrameLoop(autoSleep && !isStatic, prepareWake, tickFrame);
+  const wake = useCallback(() => {
+    "worklet";
+    if (!autoSleep || isStatic) return;
+    // Gestures need a fresh live boundary BEFORE clamping their first delta.
+    if (isFrameLoopActive?.get() !== false) {
+      liveEdge.set((nowOverrideSV.get() ?? Date.now() / 1000) + windowBufferSV.get() * timeWindow.get());
     }
-  }, !isStatic);
+    wakeLoop();
+  }, [autoSleep, isStatic, isFrameLoopActive, liveEdge, nowOverrideSV, windowBufferSV, timeWindow, wakeLoop]);
+
+  const legacyActive = !isStatic && !autoSleep;
+  const engineFrameCallback = useFrameCallback((frameInfo) => {
+    "worklet";
+    tickFrame(frameInfo.timeSincePreviousFrame ?? MS_PER_FRAME_60FPS);
+  }, legacyActive);
   useEffect(() => {
-    // Reanimated only seeds `isActive` from `autostart` on mount. Keep the
-    // imperative state aligned when a chart switches between static and live.
-    engineFrameCallback.setActive(!isStatic);
-  }, [isStatic, engineFrameCallback]);
+    engineFrameCallback.setActive(legacyActive);
+  }, [legacyActive, engineFrameCallback]);
 
   // When time-scroll is disabled while scrolled back, return the window to the
   // live edge. With a positive duration this glides: snapshot the frozen edge into
@@ -769,29 +852,32 @@ export function useLiveChartEngine(
   // constant so it never fires.
   useAnimatedReaction(
     () => {
-      if (!isStaticSV.get()) return 0; // inert when not static — never changes
-      const d = data.get();
-      const n = d.length;
-      return [
-        n,
-        n ? d[0].time : 0,
-        n ? d[0].value : 0,
-        n ? d[n - 1].time : 0,
-        n ? d[n - 1].value : 0,
-        value.get(),
-        canvasWidth.get(),
-        canvasHeight.get(),
-        timeWindow.get(),
-        // Range props can arrive after the data shared value. Re-settle when
-        // those bounds change too, rather than retaining the previous scale
-        // until another data/layout update (static charts have no frame loop).
-        maxValueSV.get(),
-        referenceValue.get(),
-        ...(referenceValues.get() ?? []),
-      ].join(",");
+      if (!isStaticSV.get()) return null; // inert when not static
+      return {
+        revision:
+          modeSV.get() === "candle" ? candleHistory.get() : pointHistory.get(),
+        fingerprint: [
+          value.get(),
+          canvasWidth.get(),
+          canvasHeight.get(),
+          timeWindow.get(),
+          // Range props can arrive after the data shared value. Re-settle when
+          // those bounds change too, rather than retaining the previous scale
+          // until another data/layout update (static charts have no frame loop).
+          maxValueSV.get(),
+          referenceValue.get(),
+          ...(referenceValues.get() ?? []),
+        ].join(","),
+      };
     },
     (curr, prev) => {
-      if (!isStaticSV.get() || curr === prev) return;
+      if (
+        !isStaticSV.get() ||
+        curr === null ||
+        (curr.revision === prev?.revision &&
+          curr.fingerprint === prev?.fingerprint)
+      )
+        return;
       applyLiveChartEngineFrame(
         { timeSincePreviousFrame: MS_PER_FRAME_60FPS },
         frameRefs,
@@ -805,6 +891,7 @@ export function useLiveChartEngine(
   );
 
   return {
+    wake,
     data,
     value,
     displayValue,

package/src/core/useLiveChartSeriesEngine.ts

@@ -64,6 +64,8 @@ export interface MultiSeriesEngineConfig {
 
 export interface MultiEngineFrameRefs {
   series: SharedValue<SeriesConfig[]>;
+  /** Drawing input published with this frame's range/tips. Optional for standalone callers. */
+  renderedSeries?: SharedValue<SeriesConfig[]>;
   displaySeriesValues: SharedValue<number[]>;
   seriesOpacities: SharedValue<number[]>;
   displayMin: SharedValue<number>;
@@ -268,6 +270,17 @@ export function applyLiveChartSeriesEngineFrame(
   sv.extremaMaxValue.value = state.extremaMaxValue;
   sv.extremaMinTime.value = state.extremaMinTime;
   sv.extremaMaxTime.value = state.extremaMaxTime;
+  // Drawing must not react to replacement histories before the engine has
+  // calculated their range and tips. Publish from the same measured frame and
+  // the same input read above. Copy entries because producers can mutate live
+  // values in place; retain history arrays to avoid copying every point per frame.
+  if (sv.renderedSeries && input.canvasWidth !== 0 && input.canvasHeight !== 0) {
+    const rendered: SeriesConfig[] = [];
+    for (let i = 0; i < seriesSnap.length; i++) {
+      rendered.push({ ...seriesSnap[i] });
+    }
+    sv.renderedSeries.value = rendered;
+  }
   // Clear the one-shot snap so the next frame eases normally again — but only
   // once a real (measured) frame consumed it (the tick early-returns on a
   // zero-size canvas before applying the snap). See applyLiveChartEngineFrame.
@@ -328,6 +341,7 @@ export function useLiveChartSeriesEngine(
 
   const displaySeriesValues = useSharedValue<number[]>([]);
   const seriesOpacities = useSharedValue<number[]>([]);
+  const renderedSeries = useSharedValue<SeriesConfig[]>([]);
 
   // Live data extrema (value + time of the visible high / low across series).
   const extremaMinValue = useSharedValue(NaN);
@@ -363,6 +377,7 @@ export function useLiveChartSeriesEngine(
 
   const frameRefs: MultiEngineFrameRefs = {
     series,
+    renderedSeries,
     displaySeriesValues,
     seriesOpacities,
     displayMin,
@@ -448,7 +463,7 @@ export function useLiveChartSeriesEngine(
     viewEnd,
     viewWindow,
     liveEdge,
-    series,
+    series: renderedSeries,
     displaySeriesValues,
     seriesOpacities,
     extremaMinValue,

package/src/draw/candleBodyPath.ts

@@ -0,0 +1,38 @@
+import type { SkPathBuilder } from "@shopify/react-native-skia";
+import type { CandleRect } from "./candle";
+
+/**
+ * Build one color's candle-body or volume-bar batch. Skia copies addRect's coordinates synchronously,
+ * so one plain rectangle can serve every sharp body in this rebuild. Keep it
+ * local to the worklet invocation: derived initializers also run on React's
+ * runtime, where mutating a previously serialized scratch object is unsafe.
+ */
+export function buildCandleBodyPath(
+  builder: SkPathBuilder,
+  bodies: CandleRect[],
+  up: boolean,
+  radius: number,
+) {
+  "worklet";
+  const rect = { x: 0, y: 0, width: 0, height: 0 };
+  for (let i = 0; i < bodies.length; i++) {
+    const body = bodies[i];
+    if (body.up !== up) continue;
+    const rr = radius > 0 ? Math.min(radius, body.w / 2, body.h / 2) : 0;
+    if (rr > 0) {
+      builder.addRRect({
+        rect: { x: body.x, y: body.y, width: body.w, height: body.h },
+        rx: rr,
+        ry: rr,
+      });
+    } else {
+      rect.x = body.x;
+      rect.y = body.y;
+      rect.width = body.w;
+      rect.height = body.h;
+      builder.addRect(rect);
+    }
+  }
+  // A fresh immutable path both resets the builder and notifies subscribers.
+  return builder.detach();
+}

package/src/draw/lineFillPaths.ts

@@ -0,0 +1,63 @@
+import type { SkPathBuilder } from "@shopify/react-native-skia";
+import { drawSpline, type SplineScratch } from "../math/spline";
+import { sampleThresholdYAt } from "../math/threshold";
+
+/** Emit each segment's curve math once into the line, fill and optional band.
+ * Builders remain separate so gaps and independent fill closures are preserved.
+ * Finalization is left to the caller; no extra intermediate native paths.
+ */
+export function buildLineFillPaths(
+  line: SkPathBuilder,
+  fill: SkPathBuilder,
+  band: SkPathBuilder | undefined,
+  pts: number[],
+  ranges: number[],
+  scratch: SplineScratch,
+  linear: boolean,
+  bottom: number,
+  thresholdY: number,
+  samples: number[] | undefined,
+  x0: number,
+  x1: number,
+  /** A threshold-only update can retain the existing line and fill paths. */
+  bandOnly = false,
+) {
+  "worklet";
+  for (let range = 0; range < ranges.length; range += 2) {
+    const start = ranges[range],
+      end = ranges[range + 1];
+    const first = start * 2,
+      last = (end - 1) * 2;
+    const left = pts[first],
+      right = pts[last];
+    if (!bandOnly) {
+      line.moveTo(left, pts[first + 1]);
+      fill.moveTo(left, pts[first + 1]);
+    }
+    band?.moveTo(left, pts[first + 1]);
+    if (bandOnly) {
+      if (band) drawSpline(band, pts, scratch, linear, start, end);
+    } else {
+      drawSpline(line, pts, scratch, linear, start, end, fill, band);
+      fill.lineTo(right, bottom);
+      fill.lineTo(left, bottom);
+      fill.close();
+    }
+    if (band) {
+      if (samples && samples.length >= 2) {
+        const count = samples.length,
+          step = (x1 - x0) / (count - 1);
+        band.lineTo(right, sampleThresholdYAt(samples, x0, x1, right));
+        for (let i = count - 1; i >= 0; i--) {
+          const x = x0 + step * i;
+          if (x > left && x < right) band.lineTo(x, samples[i]);
+        }
+        band.lineTo(left, sampleThresholdYAt(samples, x0, x1, left));
+      } else {
+        band.lineTo(right, thresholdY);
+        band.lineTo(left, thresholdY);
+      }
+      band.close();
+    }
+  }
+}

package/src/draw/volume.ts

@@ -1,3 +1,9 @@
+import {
+  volumeStartIndex,
+  volumeEndIndex,
+  visibleMaxVolume,
+  type VolumeRange,
+} from "./volumeRange";
 import { CANDLE_METRICS_DEFAULTS } from "../constants";
 import type { CandleMetrics, CandlePoint } from "../types";
 import type { ChartPadding } from "./line";
@@ -105,6 +111,8 @@ export function buildVolumeGeometry(
   bandHeight: number,
   candleWidthSecs: number,
   metrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
+  /** Internal cached history range. Live volume is always folded in below. */
+  history?: VolumeRange,
 ): VolumeGeometry {
   "worklet";
   const chartW = canvasW - padding.left - padding.right;
@@ -126,25 +134,14 @@ export function buildVolumeGeometry(
   const padLeft = padding.left;
   const baseline = canvasH - padding.bottom + bandHeight;
 
-  // Binary search for the first candle overlapping the window (same as candles).
-  let lo = 0;
-  let hi = candles.length;
-  while (lo < hi) {
-    const mid = (lo + hi) >> 1;
-    if (candles[mid].time + candleWidthSecs < winStart) lo = mid + 1;
-    else hi = mid;
-  }
-
-  // Pass 1 — largest visible volume (the bar that fills the band). The live
-  // candle counts too so a tall in-progress bar doesn't overflow the band.
-  let maxVol = 0;
-  for (let i = lo; i < candles.length; i++) {
-    /* istanbul ignore next -- past visible window */
-    if (candles[i].time > winEnd) break;
-    const v = candles[i].volume ?? 0;
-    if (v > maxVol) maxVol = v;
-  }
-  if (liveCandle && candleVisible(liveCandle, winStart, winEnd, candleWidthSecs)) {
+  const lo =
+    history?.start ?? volumeStartIndex(candles, winStart, candleWidthSecs);
+  const end = history?.end ?? volumeEndIndex(candles, winEnd);
+  let maxVol = history?.max ?? visibleMaxVolume(candles, lo, end);
+  if (
+    liveCandle &&
+    candleVisible(liveCandle, winStart, winEnd, candleWidthSecs)
+  ) {
     const v = liveCandle.volume ?? 0;
     if (v > maxVol) maxVol = v;
   }
@@ -153,9 +150,7 @@ export function buildVolumeGeometry(
 
   // Pass 2 — build the bars normalized to maxVol.
   const bars: VolumeBar[] = [];
-  for (let i = lo; i < candles.length; i++) {
-    /* istanbul ignore next -- past visible window */
-    if (candles[i].time > winEnd) break;
+  for (let i = lo; i < end; i++) {
     appendVolumeBar(
       candles[i],
       winStart,
@@ -172,7 +167,10 @@ export function buildVolumeGeometry(
       bars,
     );
   }
-  if (liveCandle && candleVisible(liveCandle, winStart, winEnd, candleWidthSecs)) {
+  if (
+    liveCandle &&
+    candleVisible(liveCandle, winStart, winEnd, candleWidthSecs)
+  ) {
     appendVolumeBar(
       liveCandle,
       winStart,

package/src/draw/volumeRange.ts

@@ -0,0 +1,51 @@
+import type { CandlePoint } from "../types";
+
+/** First bucket touching the left edge (inclusive). */
+export function volumeStartIndex(
+  candles: CandlePoint[],
+  start: number,
+  width: number,
+): number {
+  "worklet";
+  let lo = 0,
+    hi = candles.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (candles[mid].time + width < start) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/** First bucket beyond the right edge (exclusive). */
+export function volumeEndIndex(candles: CandlePoint[], end: number): number {
+  "worklet";
+  let lo = 0,
+    hi = candles.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (candles[mid].time <= end) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+export function visibleMaxVolume(
+  candles: CandlePoint[],
+  start: number,
+  end: number,
+): number {
+  "worklet";
+  let max = 0;
+  for (let i = start; i < end; i++) {
+    const volume = candles[i].volume ?? 0;
+    if (volume > max) max = volume;
+  }
+  return max;
+}
+
+export interface VolumeRange {
+  start: number;
+  end: number;
+  max: number;
+}