react-native-livechart 4.24.1 → 4.26.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,12 +16,14 @@ 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,
   CandlePoint,
   LiveChartFrameStats,
   LiveChartPoint,
+  RangeAnimationConfig,
   SeriesConfig,
 } from "../types";
 import {
@@ -30,11 +32,23 @@ 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;
   smoothing: number;
+  rangeAnimation?: RangeAnimationConfig;
   /** Extra catch-up speed added to `smoothing` when the live value lags. */
   adaptiveSpeedBoost?: number;
   exaggerate?: boolean;
@@ -96,6 +110,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 +205,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 +233,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>;
@@ -219,6 +246,7 @@ export interface EngineFrameRefs {
   timestamp: SharedValue<number>;
   timeWindow: SharedValue<number>;
   smoothing: SharedValue<number>;
+  rangeAnimationSV?: SharedValue<RangeAnimationConfig | undefined>;
   adaptiveSpeedBoostSV?: SharedValue<number | undefined>;
   exaggerateSV: SharedValue<boolean>;
   referenceValue: SharedValue<number | undefined>;
@@ -268,6 +296,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 +304,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,
@@ -361,6 +391,7 @@ export function applyLiveChartEngineFrame(
   input.canvasHeight = sv.canvasHeight.value;
   input.timeWindow = sv.timeWindow.value;
   input.smoothing = sv.smoothing.value;
+  input.rangeAnimation = sv.rangeAnimationSV?.value;
   input.adaptiveSpeedBoost = sv.adaptiveSpeedBoostSV?.value;
   input.exaggerate = sv.exaggerateSV.value;
   input.referenceValue = sv.referenceValue.value;
@@ -375,7 +406,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 +418,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,19 +443,26 @@ 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,
+    rangeAnimation,
     adaptiveSpeedBoost,
     exaggerate,
     referenceValue: configuredReferenceValue,
@@ -442,9 +483,13 @@ export function useLiveChartEngine(
     static: isStatic,
     isFrameLoopActive,
     debugFrameStats,
+    autoSleep = false,
+    keepAwake,
+    wakeSignal,
     snapKey,
     mode,
     candles,
+    candlesChangeSource = candles,
     liveCandle,
     candleGaps,
     candleGapBridgeNoTrades,
@@ -472,9 +517,8 @@ 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 rangeAnimationSV = useDerivedValue(() => rangeAnimation);
   const adaptiveSpeedBoostSV = useDerivedValue(() => adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => exaggerate ?? false);
   const referenceValue = useDerivedValue(() => configuredReferenceValue);
@@ -597,8 +641,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,
@@ -610,6 +660,7 @@ export function useLiveChartEngine(
       canvasHeight,
       timeWindow,
       smoothing,
+      rangeAnimationSV,
       adaptiveSpeedBoostSV,
       exaggerateSV,
       referenceValue,
@@ -644,6 +695,8 @@ export function useLiveChartEngine(
       extremaMaxTime,
     }),
     [
+      pointHistory,
+      candleHistory,
       adaptiveSpeedBoostSV,
       allowFutureViewEndSV,
       candleGapBridgeNoTradesSV,
@@ -676,6 +729,7 @@ export function useLiveChartEngine(
       returnFrom,
       returnT,
       smoothing,
+      rangeAnimationSV,
       snapSV,
       thresholdRangeExtendToNow,
       thresholdRangeExtendToStart,
@@ -696,41 +750,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(), rangeAnimationSV.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, rangeAnimationSV,
+    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 +860,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 +899,7 @@ export function useLiveChartEngine(
   );
 
   return {
+    wake,
     data,
     value,
     displayValue,

package/src/core/useLiveChartSeriesEngine.ts

@@ -10,7 +10,7 @@ import {
   type SharedValue,
 } from "react-native-reanimated";
 import { MS_PER_FRAME_60FPS, RETURN_TO_LIVE_MS } from "../constants";
-import type { LiveChartPoint, SeriesConfig } from "../types";
+import type { LiveChartPoint, RangeAnimationConfig, SeriesConfig } from "../types";
 import {
   tickLiveChartSeriesEngineFrame,
   type MultiEngineTickInput,
@@ -22,6 +22,7 @@ export interface MultiSeriesEngineConfig {
   series: SharedValue<SeriesConfig[]>;
   timeWindow: number;
   smoothing: number;
+  rangeAnimation?: RangeAnimationConfig;
   /** Extra catch-up speed added to `smoothing` when a series tip lags. */
   adaptiveSpeedBoost?: number;
   exaggerate?: boolean;
@@ -64,6 +65,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>;
@@ -74,6 +77,7 @@ export interface MultiEngineFrameRefs {
   canvasHeight: SharedValue<number>;
   timeWindow: SharedValue<number>;
   smoothing: SharedValue<number>;
+  rangeAnimationSV?: SharedValue<RangeAnimationConfig | undefined>;
   adaptiveSpeedBoostSV?: SharedValue<number | undefined>;
   exaggerateSV: SharedValue<boolean>;
   referenceValue: SharedValue<number | undefined>;
@@ -238,6 +242,7 @@ export function applyLiveChartSeriesEngineFrame(
   input.canvasHeight = sv.canvasHeight.value;
   input.timeWindow = sv.timeWindow.value;
   input.smoothing = sv.smoothing.value;
+  input.rangeAnimation = sv.rangeAnimationSV?.value;
   input.adaptiveSpeedBoost = sv.adaptiveSpeedBoostSV?.value;
   input.exaggerate = sv.exaggerateSV.value;
   input.referenceValue = sv.referenceValue.value;
@@ -268,6 +273,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.
@@ -288,6 +304,7 @@ export function useLiveChartSeriesEngine(
   const viewWindow = useSharedValue<number | null>(null);
   const timeWindow = useDerivedValue(() => viewWindow.value ?? config.timeWindow);
   const smoothing = useDerivedValue(() => config.smoothing);
+  const rangeAnimationSV = useDerivedValue(() => config.rangeAnimation);
   const adaptiveSpeedBoostSV = useDerivedValue(() => config.adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
   const referenceValue = useDerivedValue(() => config.referenceValue);
@@ -328,6 +345,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 +381,7 @@ export function useLiveChartSeriesEngine(
 
   const frameRefs: MultiEngineFrameRefs = {
     series,
+    renderedSeries,
     displaySeriesValues,
     seriesOpacities,
     displayMin,
@@ -373,6 +392,7 @@ export function useLiveChartSeriesEngine(
     canvasHeight,
     timeWindow,
     smoothing,
+    rangeAnimationSV,
     adaptiveSpeedBoostSV,
     exaggerateSV,
     referenceValue,
@@ -448,7 +468,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();
+    }
+  }
+}