react-native-vroom-chart 0.15.0 → 0.17.0

package/src/useChartCore.ts

@@ -3,15 +3,24 @@ import type { MutableRefObject } from 'react';
 
 import NativeVroomChart from './NativeVroomChart';
 import type { DataTransition } from './dataTransitions';
-import { classifyTransition, inferStepMs, timeframeWindow } from './dataTransitions';
+import {
+  classifyStream,
+  classifyTransition,
+  inferStepMs,
+  isPinnedToLatest,
+  timeframeWindow,
+} from './dataTransitions';
 import { ease } from './easing';
 import type { ChartFrame, ChartHandle } from './jsi.d';
 import { packCandles } from './packCandles';
 import { applyTheme, parseColor, FLOAT_LINE_TIP_PULSE } from './theme';
 import type {
   BollingerBandsConfig,
+  ATRConfig,
   Candle,
   ChartType,
+  FairValueGapsConfig,
+  IchimokuConfig,
   MACDConfig,
   MovingAverageOverlay,
   PriceLine,
@@ -21,6 +30,7 @@ import type {
   RSIConfig,
   TransitionEasing,
   IntervalTransition,
+  StreamTransition,
   VisibleRange,
   VolumeConfig,
   VroomTheme,
@@ -38,6 +48,9 @@ const MA_SOURCES = [
   'ohlc4',
 ] as const;
 
+// Mirrors vroom::atr::Smoothing order in packages/core/src/atr.h.
+const ATR_SMOOTHINGS = ['rma', 'sma', 'ema'] as const;
+
 // An unset style color marshals as the core's transparent inherit sentinel.
 const inheritColor = (v: string | number | undefined): number =>
   (v != null ? parseColor(v) : null) ?? 0;
@@ -69,6 +82,7 @@ function rsiToSpec(cfg: RSIConfig | undefined) {
     maWidth: cfg?.maWidth ?? -1,
     bandColor: inheritColor(cfg?.bandColor),
     bandsVisible: cfg?.bandsVisible ?? true,
+    extremeFill: cfg?.extremeFill ?? true,
   };
 }
 
@@ -110,6 +124,89 @@ function bollingerToSpec(cfg: BollingerBandsConfig | undefined) {
   };
 }
 
+// Ichimoku defaults. Green and red do double duty: they color span A and kijun,
+// and tint the cloud for whichever span is on top.
+const DEFAULT_ICH_GREEN = 0xff26a69a;
+const DEFAULT_ICH_RED = 0xffef5350;
+const DEFAULT_ICH_BLUE = 0xff2962ff;
+const DEFAULT_ICH_ORANGE = 0xffff6d00;
+const DEFAULT_ICH_TEAL = 0xff00bcd4;
+
+function ichimokuToSpec(cfg: IchimokuConfig | undefined) {
+  const color = (v: string | number | undefined, fallback: number) =>
+    (v != null ? parseColor(v) : null) ?? fallback;
+  return {
+    enabled: cfg?.enabled ?? false,
+    tenkanPeriod: cfg?.tenkanPeriod ?? 9,
+    kijunPeriod: cfg?.kijunPeriod ?? 26,
+    senkouBPeriod: cfg?.senkouBPeriod ?? 52,
+    displacement: cfg?.displacement ?? 26,
+    tenkanColor: color(cfg?.tenkanColor, DEFAULT_ICH_BLUE),
+    tenkanWidth: cfg?.tenkanWidth ?? 1,
+    tenkanEnabled: cfg?.tenkanVisible ?? true,
+    kijunColor: color(cfg?.kijunColor, DEFAULT_ICH_RED),
+    kijunWidth: cfg?.kijunWidth ?? 1,
+    kijunEnabled: cfg?.kijunVisible ?? true,
+    senkouAColor: color(cfg?.senkouAColor, DEFAULT_ICH_GREEN),
+    senkouAWidth: cfg?.senkouAWidth ?? 1,
+    senkouAEnabled: cfg?.senkouAVisible ?? true,
+    senkouBColor: color(cfg?.senkouBColor, DEFAULT_ICH_ORANGE),
+    senkouBWidth: cfg?.senkouBWidth ?? 1,
+    senkouBEnabled: cfg?.senkouBVisible ?? true,
+    chikouColor: color(cfg?.chikouColor, DEFAULT_ICH_TEAL),
+    chikouWidth: cfg?.chikouWidth ?? 1,
+    chikouEnabled: cfg?.chikouVisible ?? true,
+    cloudEnabled: cfg?.cloudVisible ?? true,
+    bullishCloudColor: color(cfg?.bullishCloudColor, DEFAULT_ICH_GREEN),
+    bearishCloudColor: color(cfg?.bearishCloudColor, DEFAULT_ICH_RED),
+    cloudOpacity: cfg?.cloudOpacity ?? 0.15,
+  };
+}
+
+// Fair Value Gap defaults. The border colors fall back to the fill color, so a
+// config that only restyles the fill keeps its outline in the same hue.
+const DEFAULT_FVG_GREEN = 0xff26a69a;
+const DEFAULT_FVG_RED = 0xffef5350;
+const FVG_FILL_TYPES = ['close', 'wick'] as const;
+const FVG_BORDER_STYLES = ['solid', 'dotted', 'dashed'] as const;
+
+function fvgToSpec(cfg: FairValueGapsConfig | undefined) {
+  const color = (v: string | number | undefined, fallback: number) =>
+    (v != null ? parseColor(v) : null) ?? fallback;
+  const bullish = color(cfg?.bullishColor, DEFAULT_FVG_GREEN);
+  const bearish = color(cfg?.bearishColor, DEFAULT_FVG_RED);
+  return {
+    enabled: cfg?.enabled ?? false,
+    maxBarsBack: cfg?.maxBarsBack ?? 300,
+    waitForClose: cfg?.waitForClose ?? false,
+    fillType: Math.max(0, FVG_FILL_TYPES.indexOf(cfg?.fillType ?? 'close')),
+    deleteAfterFill: cfg?.deleteAfterFill ?? true,
+    extendBoxes: cfg?.extendBoxes ?? false,
+    boxLength: cfg?.boxLength ?? 20,
+    bullishColor: bullish,
+    bearishColor: bearish,
+    opacity: cfg?.opacity ?? 0.15,
+    borderEnabled: cfg?.borderVisible ?? true,
+    borderStyle: Math.max(
+      0,
+      FVG_BORDER_STYLES.indexOf(cfg?.borderStyle ?? 'solid'),
+    ),
+    borderWidth: cfg?.borderWidth ?? 1,
+    bullishBorderColor: color(cfg?.bullishBorderColor, bullish),
+    bearishBorderColor: color(cfg?.bearishBorderColor, bearish),
+    labelsEnabled: cfg?.showLabels ?? true,
+    label: cfg?.label ?? 'FVG',
+    labelDistance: cfg?.labelDistance ?? 10,
+    // Alpha 0 is the core's "inherit the border color" sentinel.
+    labelColor: color(cfg?.labelColor, 0),
+    labelFontSize: cfg?.labelFontSize ?? 0,
+    showInverse: cfg?.showInverse ?? false,
+    inverseBullishColor: color(cfg?.inverseBullishColor, bullish),
+    inverseBearishColor: color(cfg?.inverseBearishColor, bearish),
+    inverseLabel: cfg?.inverseLabel ?? 'iFVG',
+  };
+}
+
 function macdToSpec(cfg: MACDConfig | undefined) {
   const srcIdx = cfg?.source ? MA_SOURCES.indexOf(cfg.source) : 0;
   return {
@@ -136,6 +233,16 @@ function macdToSpec(cfg: MACDConfig | undefined) {
   };
 }
 
+function atrToSpec(cfg: ATRConfig | undefined) {
+  return {
+    enabled: cfg?.enabled ?? false,
+    period: cfg?.period ?? 14,
+    smoothing: Math.max(0, ATR_SMOOTHINGS.indexOf(cfg?.smoothing ?? 'rma')),
+    lineColor: inheritColor(cfg?.lineColor),
+    lineWidth: cfg?.lineWidth ?? -1,
+  };
+}
+
 // Unset style fields go down as the core's inherit sentinels (negative float,
 // transparent color) rather than as literal defaults, so the theme keys stay in
 // charge of anything the consumer didn't set.
@@ -273,6 +380,10 @@ export type TransitionOptions = {
   transitionEasing?: TransitionEasing;
   /** `'transform'` (default) slot-lerps; `'fade'` fades out then in. */
   intervalTransition?: IntervalTransition;
+  /** `'transform'` eases live updates; `'none'` (default) snaps them. */
+  streamTransition?: StreamTransition;
+  /** Duration of the stream animation in ms. 0 snaps. Default 150. */
+  streamTransitionMs?: number;
   /** OS reduced-motion preference: skips the capture and snaps. */
   reduceMotion?: boolean;
   /** Receives every morph frame. Without one, data swaps snap. */
@@ -304,13 +415,19 @@ export function useChartCore(
   theme?: VroomTheme,
   rsi?: RSIConfig,
   macd?: MACDConfig,
+  atr?: ATRConfig,
   movingAverages?: MovingAverageOverlay[],
   vwap?: VWAPConfig,
   bollingerBands?: BollingerBandsConfig,
+  ichimoku?: IchimokuConfig,
+  fairValueGaps?: FairValueGapsConfig,
   volume?: VolumeConfig,
   priceLines?: PriceLinesProp,
   footprints?: FootprintsProp,
   transition?: TransitionOptions,
+  // Trails the config params because it's data state, not configuration: it
+  // pairs with `candles` above (see showLoadingLine below).
+  loading?: boolean,
 ): ChartCoreState {
   const handleRef = useRef<ChartHandle | null>(null);
   // Push setDefaultCandleWidth only once (first load): setCandles re-runs on
@@ -326,6 +443,13 @@ export function useChartCore(
     seriesKey?: string;
   } | null>(null);
   const intervalMorphRaf = useRef<number | null>(null);
+  const streamRaf = useRef<number | null>(null);
+  // Where an in-flight stream shift is headed, so cancelling it can land there
+  // rather than stranding the view mid-slide.
+  const streamWindowRef = useRef<VisibleRange | null>(null);
+  // Whether that loop is the one driving the morph scalar, so settling it never
+  // cuts short a timeframe switch that happens to overlap.
+  const streamMorphRef = useRef(false);
   const [picture, setPicture] = useState<ChartFrame | null>(null);
 
   if (!handleRef.current && size.width > 0 && size.height > 0) {
@@ -341,33 +465,63 @@ export function useChartCore(
     easing: TransitionEasing | undefined;
     reduceMotion: boolean;
     interval: IntervalTransition;
-  }>({ ms: 300, easing: undefined, reduceMotion: false, interval: 'transform' });
+    stream: StreamTransition;
+    streamMs: number;
+  }>({
+    ms: 300,
+    easing: undefined,
+    reduceMotion: false,
+    interval: 'transform',
+    stream: 'none',
+    streamMs: 150,
+  });
   animRef.current = {
     ms: Math.max(0, transition?.transitionMs ?? 300),
     easing: transition?.transitionEasing,
     reduceMotion: transition?.reduceMotion ?? false,
     interval: transition?.intervalTransition === 'fade' ? 'fade' : 'transform',
+    stream: transition?.streamTransition === 'transform' ? 'transform' : 'none',
+    // Shorter than transitionMs by default: ticks can land faster than a 300ms
+    // curve, and every one that does interrupts the last.
+    streamMs: Math.max(0, transition?.streamTransitionMs ?? 150),
   };
   const onFrameRef = useRef(transition?.onFrame);
   onFrameRef.current = transition?.onFrame;
   const seriesKey = transition?.seriesKey;
 
+  // Set only while the loading hand-off is in its *first* stage, which is the
+  // one an interruption can't simply land: stage one leaves `loading` set in
+  // the core, and only stage two releases it.
+  const loadingHandoffRef = useRef(false);
+
   // Stop an in-flight interval morph and land the core on the new candles.
   const endIntervalMorph = useCallback(() => {
     if (intervalMorphRaf.current != null) {
       cancelAnimationFrame(intervalMorphRaf.current);
       intervalMorphRaf.current = null;
     }
-    handleRef.current?.setIntervalMorph(1);
+    const h = handleRef.current;
+    // Walk a half-finished hand-off through the rest of its stages rather than
+    // just stopping the clock, or the core would be left drawing the loading
+    // line over the data it was supposed to hand off to.
+    if (loadingHandoffRef.current) {
+      loadingHandoffRef.current = false;
+      h?.setLoadingMorph(1);
+      h?.beginLoadingReveal();
+    }
+    h?.setIntervalMorph(1);
   }, []);
 
   // Runs the interval morph clock. The core holds the pre-swap geometry (see
   // beginIntervalMorph) and reshapes each candle slot toward its new counterpart.
-  const startIntervalMorph = useCallback((h: ChartHandle) => {
+  // `durationMs` overrides transitionMs for the loading hand-off, which splits
+  // it across two stages.
+  const startIntervalMorph = useCallback((h: ChartHandle, durationMs?: number) => {
     const { ms, easing } = animRef.current;
+    const dur = durationMs ?? ms;
     const start = performance.now();
     const step = (now: number) => {
-      const p = Math.min(1, (now - start) / ms);
+      const p = Math.min(1, (now - start) / dur);
       h.setIntervalMorph(p < 1 ? ease(easing, p) : 1);
       const pic = h.render();
       if (pic) onFrameRef.current?.(pic);
@@ -376,12 +530,129 @@ export function useChartCore(
     intervalMorphRaf.current = requestAnimationFrame(step);
   }, []);
 
+  // Hands the loading line over to the data that just landed, in two stages:
+  // the line reshapes into the series' silhouette, then the candles grow out of
+  // it while it fades.
+  //
+  // Sequential rather than overlapped — the shape has to read as the data
+  // before the bars start emerging from it — so the two split transitionMs and
+  // the whole hand-off costs what any other transition costs.
+  const startLoadingHandoff = useCallback(
+    (h: ChartHandle) => {
+      const { ms, easing } = animRef.current;
+      const half = ms / 2;
+      loadingHandoffRef.current = true;
+      h.beginLoadingMorph();
+      const start = performance.now();
+      const step = (now: number) => {
+        const p = Math.min(1, (now - start) / half);
+        h.setLoadingMorph(p < 1 ? ease(easing, p) : 1);
+        const pic = h.render();
+        if (pic) onFrameRef.current?.(pic);
+        if (p < 1) {
+          intervalMorphRaf.current = requestAnimationFrame(step);
+          return;
+        }
+        intervalMorphRaf.current = null;
+        // Past here an interruption is an ordinary interval morph again: the
+        // core has left the loading state, so landing the clock is enough.
+        loadingHandoffRef.current = false;
+        // Stage two rides the interval-morph clock, which also carries the
+        // line's fade-out — so the bars' growth and the line's exit finish
+        // together instead of one outlasting the other.
+        h.beginLoadingReveal();
+        startIntervalMorph(h, half);
+      };
+      intervalMorphRaf.current = requestAnimationFrame(step);
+    },
+    [startIntervalMorph],
+  );
+
+  // Stops an in-flight stream animation and puts the chart somewhere coherent.
+  //
+  // A pending window shift always lands on its target: abandoned mid-slide it
+  // would strand the view between two bars, half a candle off the grid.
+  //
+  // `keepMorph` is for a tick restarting on top of one already running —
+  // beginStreamMorph blends out of the geometry currently on screen, so landing
+  // that geometry first would throw away the very thing it resumes from.
+  const settleStream = useCallback((keepMorph = false) => {
+    if (streamRaf.current != null) {
+      cancelAnimationFrame(streamRaf.current);
+      streamRaf.current = null;
+    }
+    const h = handleRef.current;
+    const target = streamWindowRef.current;
+    streamWindowRef.current = null;
+    if (target) h?.setVisibleRange(target.startMs, target.endMs);
+    if (streamMorphRef.current && !keepMorph) {
+      streamMorphRef.current = false;
+      h?.setIntervalMorph(1);
+    }
+  }, []);
+
+  // Runs the clock for a live update. One loop drives both halves so they land
+  // on the same frame.
+  //
+  // `window` is null for a plain tick; for an append it is where the view has to
+  // end up. The slide is measured from wherever the window is *now*, so a shift
+  // interrupting another continues from the current position instead of
+  // snapping back to the start of the last one.
+  const startStreamAnim = useCallback(
+    (h: ChartHandle, morphing: boolean, window: VisibleRange | null) => {
+      const { streamMs, easing } = animRef.current;
+      let from = window ? h.getVisibleRange() : null;
+      // What the previous frame left the window at. Anything else — a pan, a
+      // pinch — lands somewhere different, which is how the slide notices it is
+      // no longer the only thing moving the view and gets out of the way.
+      // Cheaper than teaching every gesture to cancel it, and it can't miss one.
+      let applied: VisibleRange | null = null;
+      streamWindowRef.current = window;
+      streamMorphRef.current = morphing;
+      const start = performance.now();
+      const step = (now: number) => {
+        if (from && applied) {
+          const now_w = h.getVisibleRange();
+          if (now_w.startMs !== applied.startMs || now_w.endMs !== applied.endMs) {
+            from = null;
+            streamWindowRef.current = null;
+          }
+        }
+        const p = Math.min(1, (now - start) / streamMs);
+        const e = p < 1 ? ease(easing, p) : 1;
+        if (morphing) h.setIntervalMorph(e);
+        if (from && window) {
+          applied = {
+            startMs: Math.round(from.startMs + (window.startMs - from.startMs) * e),
+            endMs: Math.round(from.endMs + (window.endMs - from.endMs) * e),
+          };
+          h.setVisibleRange(applied.startMs, applied.endMs);
+        }
+        const pic = h.render();
+        if (pic) onFrameRef.current?.(pic);
+        if (p < 1) {
+          streamRaf.current = requestAnimationFrame(step);
+        } else {
+          streamRaf.current = null;
+          streamWindowRef.current = null;
+          streamMorphRef.current = false;
+        }
+      };
+      streamRaf.current = requestAnimationFrame(step);
+    },
+    [],
+  );
+
   useEffect(() => {
     return () => {
       if (intervalMorphRaf.current != null) {
         cancelAnimationFrame(intervalMorphRaf.current);
         intervalMorphRaf.current = null;
       }
+      if (streamRaf.current != null) {
+        cancelAnimationFrame(streamRaf.current);
+        streamRaf.current = null;
+      }
     };
   }, []);
 
@@ -393,14 +664,28 @@ export function useChartCore(
   const startMs = visibleRange?.startMs ?? 0;
   const endMs = visibleRange?.endMs ?? 0;
 
+  // The core trusts `setLoading` outright, so the "and no data yet" half of the
+  // condition is decided here. Both halves matter: without `loading` a chart
+  // that legitimately has no bars would wave a placeholder forever, and without
+  // the emptiness check a background refresh of a loaded series would blank the
+  // chart the user is already reading.
+  const showLoadingLine = loading === true && candles.length === 0;
+  // Tracks whether the *core* is currently showing the line, which is what
+  // decides if the next data push is a hand-off. Distinct from `showLoadingLine`:
+  // that is this render's intent, this is what's on screen.
+  const lineUpRef = useRef(false);
+
   // Stable deps so inline `theme={{...}}` / `rsi={{...}}` literals don't re-run
   // the effect every render — only when the actual values change.
   const themeKey = theme ? JSON.stringify(theme) : '';
   const rsiKey = rsi ? JSON.stringify(rsi) : '';
   const macdKey = macd ? JSON.stringify(macd) : '';
+  const atrKey = atr ? JSON.stringify(atr) : '';
   const maKey = movingAverages ? JSON.stringify(movingAverages) : '';
   const vwapKey = vwap ? JSON.stringify(vwap) : '';
   const bollingerKey = bollingerBands ? JSON.stringify(bollingerBands) : '';
+  const ichimokuKey = ichimoku ? JSON.stringify(ichimoku) : '';
+  const fvgKey = fairValueGaps ? JSON.stringify(fairValueGaps) : '';
   const volumeKey = volume ? JSON.stringify(volume) : '';
   const priceLinesKey = priceLines ? JSON.stringify(priceLines) : '';
   const footprintsKey = footprints ? JSON.stringify(footprints) : '';
@@ -409,6 +694,10 @@ export function useChartCore(
     const h = handleRef.current;
     if (!h) return;
     h.setSize(size.width, size.height, size.pxRatio ?? 1);
+    // Ahead of setCandles, like setDefaultCandleWidth below: the default framing
+    // runs inside setCandles and reserves room past the newest candle for
+    // Ichimoku's leading spans, so it has to already know they're coming.
+    h.setIchimoku(ichimokuToSpec(ichimoku));
     // Drive the initial zoom from a target candle width. Pushed once, before the
     // first setCandles (while the core window is still 0/0), and only when the
     // caller isn't explicitly controlling the range.
@@ -425,6 +714,31 @@ export function useChartCore(
     // the viewport: a stream leaves it alone, a timeframe switch re-anchors and
     // morphs into it, a different asset resets it.
     let morphing = false;
+
+    if (showLoadingLine) {
+      // Clear the core's buffer, which the `candles.length > 0` gate below
+      // otherwise never does: pushing an empty array is treated as "hold the
+      // last frame" everywhere else, so a chart switching assets would still be
+      // holding the previous one's bars underneath the line — and would
+      // classify the incoming series as a timeframe switch rather than a fresh
+      // load. Scoped to the loading case so that hold-the-last-frame behavior
+      // is untouched for every other empty push.
+      if (!lineUpRef.current) {
+        endIntervalMorph();
+        settleStream();
+        h.setCandles(packCandles([]));
+        prevDataRef.current = null;
+      }
+      h.setLoading(true, !animRef.current.reduceMotion);
+      lineUpRef.current = true;
+    } else if (lineUpRef.current && candles.length === 0) {
+      // Loading resolved to nothing — an empty result, or an error the consumer
+      // handled. There's no geometry to morph into, so drop the line rather
+      // than leaving it waving at data that isn't coming.
+      h.setLoading(false, true);
+      lineUpRef.current = false;
+    }
+
     if (candles.length > 0) {
       const prev = prevDataRef.current;
       const freshHandle = prev == null || prev.handle !== h;
@@ -447,6 +761,60 @@ export function useChartCore(
         } | null = null;
         // The pre-swap candle envelope, used to scale-lock the y-axis below.
         let prevEnvelope: { low: number; high: number } | null = null;
+        // Set when this push is the loading line's hand-off to real data.
+        let handOff = false;
+        // Set for an animated live update: whether the last bar reshapes, and
+        // the window an appended bar should pull the view to.
+        let stream: { morph: boolean; window: VisibleRange | null } | null = null;
+        if (transitionKind === 'stream' && prev != null && !explicit) {
+          const { stream: mode, streamMs, reduceMotion } = animRef.current;
+          const stepMs = inferStepMs(candles);
+          if (
+            mode === 'transform' &&
+            streamMs > 0 &&
+            stepMs != null &&
+            !reduceMotion &&
+            onFrameRef.current != null
+          ) {
+            const lastMs = candles[candles.length - 1].timeMs;
+            const prevLastMs = prev.candles[prev.candles.length - 1].timeMs;
+            if (classifyStream(prev.candles, candles) === 'append') {
+              // Pull the window along by exactly what the data advanced, so the
+              // series translates a whole slot and the newest bar holds its
+              // place on screen. Only for a view still following the newest bar
+              // — someone reading history keeps their window.
+              //
+              // No capture here: slots pair from the right edge, so the new bar
+              // would take the previous one's geometry and drag every candle
+              // onto its neighbour. Translating the window moves them by their
+              // own timestamps instead.
+              const w = h.getVisibleRange();
+              const prevStepMs = inferStepMs(prev.candles) ?? stepMs;
+              if (isPinnedToLatest(w, prevLastMs, prevStepMs)) {
+                const by = lastMs - prevLastMs;
+                stream = {
+                  morph: false,
+                  window: { startMs: w.startMs + by, endMs: w.endMs + by },
+                };
+              }
+            } else {
+              stream = { morph: true, window: null };
+            }
+          }
+          if (stream?.morph) {
+            // Keep the geometry on screen for beginStreamMorph to resume from:
+            // at any real tick rate most ticks interrupt the previous one, and
+            // that continuity is what keeps the bar from stuttering.
+            settleStream(true);
+            h.beginStreamMorph();
+          } else {
+            // An append has no use for a capture — it would pair the new bar
+            // with the old one's geometry and drag the whole series along.
+            settleStream();
+          }
+        } else if (transitionKind === 'stream') {
+          settleStream();
+        }
         if (transitionKind === 'timeframe' && prev != null) {
           const oldWindow = h.getVisibleRange();
           const oldStepMs = inferStepMs(prev.candles);
@@ -475,6 +843,22 @@ export function useChartCore(
           endIntervalMorph();
         }
 
+        // The loading line's data has landed, so it hands over to the series
+        // instead of the chart cutting to it. Always classified 'initial' (the
+        // loading branch above cleared prevDataRef), so this runs after that
+        // branch's endIntervalMorph.
+        if (lineUpRef.current) {
+          lineUpRef.current = false;
+          handOff =
+            animRef.current.ms > 0 &&
+            !animRef.current.reduceMotion &&
+            onFrameRef.current != null;
+          // Snap path only. The hand-off itself starts after setCandles and the
+          // framing below: both its stages aim at where the candles will
+          // actually sit, so neither can be set up until they're there.
+          if (!handOff) h.setLoading(false, true);
+        }
+
         h.setCandles(packCandles(candles));
 
         if (transitionKind === 'timeframe') {
@@ -499,9 +883,16 @@ export function useChartCore(
           // Started after the new bounds are in place: the snapshot is in band
           // fractions, so frame 0 still matches the pre-switch pixels exactly.
           if (morphing) startIntervalMorph(h);
+        } else if (stream) {
+          // After setCandles, so the capture (and the window it slides from) is
+          // measured against the data the animation is heading toward.
+          startStreamAnim(h, stream.morph, stream.window);
         } else if (transitionKind === 'reset') {
           h.resetView();
         }
+        // After setCandles and the framing above, so the line aims at — and the
+        // candles grow from — the geometry each bar will actually occupy.
+        if (handOff) startLoadingHandoff(h);
         prevDataRef.current = { handle: h, candles, seriesKey };
       }
     }
@@ -522,9 +913,11 @@ export function useChartCore(
     }
     h.setRSI(rsiToSpec(rsi));
     h.setMACD(macdToSpec(macd));
+    h.setATR(atrToSpec(atr));
     h.setOverlays((movingAverages ?? []).map(overlayToNumeric));
     h.setVWAP(vwapToSpec(vwap));
     h.setBollinger(bollingerToSpec(bollingerBands));
+    h.setFairValueGaps(fvgToSpec(fairValueGaps));
     h.setVolume(volumeToSpec(volume));
     // setVolume snaps the collapse scalar to its `enabled`, which would cut a
     // toggle animation short whenever this effect re-runs (a streaming candle, a
@@ -545,10 +938,11 @@ export function useChartCore(
     // frame 0 is pixel-identical to what's on screen, so there's nothing to show
     // in the meantime anyway.
     if (!morphing) setPicture(h.render());
-    // theme/rsi/macd/movingAverages/vwap/bollingerBands/volume/priceLines/
-    // footprints are represented by their *Key deps.
+    // theme/rsi/macd/atr/movingAverages/vwap/bollingerBands/ichimoku/
+    // fairValueGaps/volume/priceLines/footprints are represented by their *Key
+    // deps.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [candles, seriesKey, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, maKey, vwapKey, bollingerKey, volumeKey, priceLinesKey, footprintsKey, startIntervalMorph, endIntervalMorph]);
+  }, [candles, showLoadingLine, seriesKey, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, atrKey, maKey, vwapKey, bollingerKey, ichimokuKey, fvgKey, volumeKey, priceLinesKey, footprintsKey, startIntervalMorph, startLoadingHandoff, endIntervalMorph, startStreamAnim, settleStream]);
 
   return { handle: handleRef.current, picture, volumeCollapseRef };
 }