react-native-vroom-chart 0.15.0 → 0.17.0

package/cpp/VroomChartHostObject.cpp

@@ -57,6 +57,11 @@ std::vector<jsi::PropNameID> ChartHostObject::getPropertyNames(
   out.push_back(jsi::PropNameID::forAscii(rt, "getVisiblePriceEnvelope"));
   out.push_back(jsi::PropNameID::forAscii(rt, "preservePriceEnvelope"));
   out.push_back(jsi::PropNameID::forAscii(rt, "beginIntervalMorph"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "beginStreamMorph"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setLoading"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "beginLoadingMorph"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setLoadingMorph"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "beginLoadingReveal"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setIntervalMorph"));
   out.push_back(jsi::PropNameID::forAscii(rt, "pan"));
   out.push_back(jsi::PropNameID::forAscii(rt, "translate"));
@@ -71,9 +76,12 @@ std::vector<jsi::PropNameID> ChartHostObject::getPropertyNames(
   out.push_back(jsi::PropNameID::forAscii(rt, "getCrosshairInfo"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setRSI"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setMACD"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setATR"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setOverlays"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setVWAP"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setBollinger"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setIchimoku"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setFairValueGaps"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setVolume"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setVolumeCollapse"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setAxisCollapse"));
@@ -510,6 +518,101 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
         });
   }
 
+  if (name == "beginStreamMorph") {
+    // beginStreamMorph() — capture the visible geometry so the next setCandles
+    // can ease a live tick into place. Leaves the axes alone, and continues
+    // from the shape on screen when one is still animating. Call before
+    // setCandles.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "beginStreamMorph"),
+        0,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* /*args*/,
+               size_t /*count*/) -> jsi::Value {
+          vroom_chart_begin_stream_morph(chart_);
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "setLoading") {
+    // setLoading(on, animate?) — show or hide the loading line. `on` must mean
+    // "loading *and* holding no data"; the core takes it at face value.
+    // `animate` defaults to true; pass false for reduced motion.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setLoading"),
+        2,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 1) return jsi::Value::undefined();
+          const bool on = args[0].isBool() ? args[0].getBool()
+                                           : args[0].asNumber() != 0;
+          bool animate = true;
+          if (count >= 2 && !args[1].isUndefined() && !args[1].isNull()) {
+            animate = args[1].isBool() ? args[1].getBool()
+                                       : args[1].asNumber() != 0;
+          }
+          vroom_chart_set_loading(chart_, on ? 1 : 0, animate ? 1 : 0);
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "beginLoadingMorph") {
+    // beginLoadingMorph() — hand-off stage one: aim the loading line at the
+    // centres of the candles that just landed. Call *after* setCandles, then
+    // drive setLoadingMorph from 0 to 1.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "beginLoadingMorph"),
+        0,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* /*args*/,
+               size_t /*count*/) -> jsi::Value {
+          vroom_chart_begin_loading_morph(chart_);
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "setLoadingMorph") {
+    // setLoadingMorph(t) — advance stage one. 0 = the frozen sine, 1 = the
+    // polyline through the candle centres.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setLoadingMorph"),
+        1,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 1) return jsi::Value::undefined();
+          vroom_chart_set_loading_morph(
+              chart_, static_cast<float>(args[0].asNumber()));
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "beginLoadingReveal") {
+    // beginLoadingReveal() — hand-off stage two: collapse every candle onto the
+    // line at zero alpha so it grows outward from there. Call once stage one
+    // reaches 1, then drive setIntervalMorph from 0 to 1.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "beginLoadingReveal"),
+        0,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* /*args*/,
+               size_t /*count*/) -> jsi::Value {
+          vroom_chart_begin_loading_reveal(chart_);
+          return jsi::Value::undefined();
+        });
+  }
+
   if (name == "setIntervalMorph") {
     // setIntervalMorph(t) — advance the capture toward the new candles. `t` is
     // pre-eased progress: 0 = the captured frame, 1 = settled (capture freed).
@@ -761,7 +864,8 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
   if (name == "setRSI") {
     // setRSI({enabled, period, upperBand, lowerBand, maPeriod, maKind,
     // maVisible, lineColor, lineWidth, lineVisible, maColor, maWidth,
-    // bandColor, bandsVisible}) — configures the RSI pane. No render; the next
+    // bandColor, bandsVisible, extremeFill}) — configures the RSI pane. No
+    // render; the next
     // render() picks it up.
     return jsi::Function::createFromHostFunction(
         rt,
@@ -797,6 +901,8 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
               s.getProperty(rt2, "bandColor").asNumber());
           cfg.bands_visible =
               s.getProperty(rt2, "bandsVisible").asBool() ? 1 : 0;
+          cfg.extreme_fill =
+              s.getProperty(rt2, "extremeFill").asBool() ? 1 : 0;
           vroom_chart_set_rsi(chart_, &cfg);
           return jsi::Value::undefined();
         });
@@ -863,6 +969,34 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
         });
   }
 
+  if (name == "setATR") {
+    // setATR({enabled, period, smoothing, lineColor, lineWidth}) — configures
+    // the ATR pane. No render; the next render() picks it up.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setATR"),
+        1,
+        [this](jsi::Runtime& rt2,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 1 || !args[0].isObject()) return jsi::Value::undefined();
+          auto s = args[0].asObject(rt2);
+          VroomATR cfg{};
+          cfg.enabled = s.getProperty(rt2, "enabled").asBool() ? 1 : 0;
+          cfg.period = static_cast<int32_t>(
+              s.getProperty(rt2, "period").asNumber());
+          cfg.smoothing = static_cast<int32_t>(
+              s.getProperty(rt2, "smoothing").asNumber());
+          cfg.line_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "lineColor").asNumber());
+          cfg.line_width = static_cast<float>(
+              s.getProperty(rt2, "lineWidth").asNumber());
+          vroom_chart_set_atr(chart_, &cfg);
+          return jsi::Value::undefined();
+        });
+  }
+
   if (name == "setOverlays") {
     // setOverlays([{ kind, period, source, color, width }, ...]) — replaces the
     // full set of MA/EMA overlay lines. No render; the next render() picks it up.
@@ -972,6 +1106,123 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
         });
   }
 
+  if (name == "setIchimoku") {
+    // setIchimoku({enabled, tenkanPeriod, kijunPeriod, senkouBPeriod,
+    // displacement, <line>Color/<line>Width/<line>Enabled for tenkan, kijun,
+    // senkouA, senkouB and chikou, cloudEnabled, bullishCloudColor,
+    // bearishCloudColor, cloudOpacity}) — the Ichimoku overlay. No render; the
+    // next render() picks it up.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setIchimoku"),
+        1,
+        [this](jsi::Runtime& rt2,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 1 || !args[0].isObject()) return jsi::Value::undefined();
+          auto s = args[0].asObject(rt2);
+          const auto num = [&](const char* k) {
+            return s.getProperty(rt2, k).asNumber();
+          };
+          const auto flag = [&](const char* k) {
+            return s.getProperty(rt2, k).asBool() ? 1 : 0;
+          };
+          VroomIchimoku cfg{};
+          cfg.enabled = flag("enabled");
+          cfg.tenkan_period = static_cast<int32_t>(num("tenkanPeriod"));
+          cfg.kijun_period = static_cast<int32_t>(num("kijunPeriod"));
+          cfg.senkou_b_period = static_cast<int32_t>(num("senkouBPeriod"));
+          cfg.displacement = static_cast<int32_t>(num("displacement"));
+          cfg.tenkan_color = static_cast<uint32_t>(num("tenkanColor"));
+          cfg.tenkan_width = static_cast<float>(num("tenkanWidth"));
+          cfg.tenkan_enabled = flag("tenkanEnabled");
+          cfg.kijun_color = static_cast<uint32_t>(num("kijunColor"));
+          cfg.kijun_width = static_cast<float>(num("kijunWidth"));
+          cfg.kijun_enabled = flag("kijunEnabled");
+          cfg.senkou_a_color = static_cast<uint32_t>(num("senkouAColor"));
+          cfg.senkou_a_width = static_cast<float>(num("senkouAWidth"));
+          cfg.senkou_a_enabled = flag("senkouAEnabled");
+          cfg.senkou_b_color = static_cast<uint32_t>(num("senkouBColor"));
+          cfg.senkou_b_width = static_cast<float>(num("senkouBWidth"));
+          cfg.senkou_b_enabled = flag("senkouBEnabled");
+          cfg.chikou_color = static_cast<uint32_t>(num("chikouColor"));
+          cfg.chikou_width = static_cast<float>(num("chikouWidth"));
+          cfg.chikou_enabled = flag("chikouEnabled");
+          cfg.cloud_enabled = flag("cloudEnabled");
+          cfg.bullish_cloud_color =
+              static_cast<uint32_t>(num("bullishCloudColor"));
+          cfg.bearish_cloud_color =
+              static_cast<uint32_t>(num("bearishCloudColor"));
+          cfg.cloud_opacity = static_cast<float>(num("cloudOpacity"));
+          vroom_chart_set_ichimoku(chart_, &cfg);
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "setFairValueGaps") {
+    // setFairValueGaps({enabled, maxBarsBack, waitForClose, fillType,
+    // deleteAfterFill, extendBoxes, boxLength, bullishColor, bearishColor,
+    // opacity, borderEnabled, borderStyle, borderWidth, bullishBorderColor,
+    // bearishBorderColor, labelsEnabled, label, labelDistance, labelColor,
+    // labelFontSize, showInverse, inverseBullishColor, inverseBearishColor,
+    // inverseLabel}) — the Fair Value Gap overlay. No render; the next
+    // render() picks it up.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setFairValueGaps"),
+        1,
+        [this](jsi::Runtime& rt2,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 1 || !args[0].isObject()) return jsi::Value::undefined();
+          auto s = args[0].asObject(rt2);
+          const auto num = [&](const char* k) {
+            return s.getProperty(rt2, k).asNumber();
+          };
+          const auto flag = [&](const char* k) {
+            return s.getProperty(rt2, k).asBool() ? 1 : 0;
+          };
+          VroomFairValueGaps cfg{};
+          cfg.enabled = flag("enabled");
+          cfg.max_bars_back = static_cast<int32_t>(num("maxBarsBack"));
+          cfg.wait_for_close = flag("waitForClose");
+          cfg.fill_type = static_cast<int32_t>(num("fillType"));
+          cfg.delete_after_fill = flag("deleteAfterFill");
+          cfg.extend_boxes = flag("extendBoxes");
+          cfg.box_length = static_cast<int32_t>(num("boxLength"));
+          cfg.bullish_color = static_cast<uint32_t>(num("bullishColor"));
+          cfg.bearish_color = static_cast<uint32_t>(num("bearishColor"));
+          cfg.opacity = static_cast<float>(num("opacity"));
+          cfg.border_enabled = flag("borderEnabled");
+          cfg.border_style = static_cast<int32_t>(num("borderStyle"));
+          cfg.border_width = static_cast<float>(num("borderWidth"));
+          cfg.bullish_border_color =
+              static_cast<uint32_t>(num("bullishBorderColor"));
+          cfg.bearish_border_color =
+              static_cast<uint32_t>(num("bearishBorderColor"));
+          cfg.labels_enabled = flag("labelsEnabled");
+          // Held alive until the setter, which copies them.
+          const std::string label =
+              s.getProperty(rt2, "label").asString(rt2).utf8(rt2);
+          cfg.label = label.c_str();
+          cfg.label_distance = static_cast<int32_t>(num("labelDistance"));
+          cfg.label_color = static_cast<uint32_t>(num("labelColor"));
+          cfg.label_font_size = static_cast<float>(num("labelFontSize"));
+          cfg.show_inverse = flag("showInverse");
+          cfg.inverse_bullish_color =
+              static_cast<uint32_t>(num("inverseBullishColor"));
+          cfg.inverse_bearish_color =
+              static_cast<uint32_t>(num("inverseBearishColor"));
+          const std::string inverse_label =
+              s.getProperty(rt2, "inverseLabel").asString(rt2).utf8(rt2);
+          cfg.inverse_label = inverse_label.c_str();
+          vroom_chart_set_fair_value_gaps(chart_, &cfg);
+          return jsi::Value::undefined();
+        });
+  }
+
   if (name == "setVolume") {
     // setVolume({enabled, heightFrac, opacity, radiusPx, upColor, downColor})
     // — the volume bars. Negative floats / zero colors inherit the theme. No

package/cpp/_core_include/vroom/vroom_chart.h

@@ -69,6 +69,80 @@ typedef struct VroomBollinger {
     float    fill_opacity;  // 0..1, multiplied into upper_color's alpha
 } VroomBollinger;
 
+// Ichimoku Kinko Hyo overlay drawn on the price pane: five lines plus the cloud
+// (kumo) shaded between the two leading spans. No pane is reserved.
+//
+// Three of the lines are drawn away from the bar they were computed on:
+// senkou A/B lead by `displacement` slots (so the cloud runs past the newest
+// candle into empty time) and chikou lags by the same. Displacement is applied
+// at draw time, so changing it re-renders without recomputing the series.
+typedef struct VroomIchimoku {
+    int32_t  enabled;            // 0/1
+    int32_t  tenkan_period;      // conversion lookback (clamped >= 1; default 9)
+    int32_t  kijun_period;       // base lookback (clamped >= 1; default 26)
+    int32_t  senkou_b_period;    // span B lookback (clamped >= 1; default 52)
+    int32_t  displacement;       // slots the cloud leads / chikou lags (>= 0; default 26)
+    uint32_t tenkan_color;       // 0xAARRGGBB
+    float    tenkan_width;       // stroke px
+    int32_t  tenkan_enabled;     // 0/1
+    uint32_t kijun_color;
+    float    kijun_width;
+    int32_t  kijun_enabled;
+    uint32_t senkou_a_color;
+    float    senkou_a_width;
+    int32_t  senkou_a_enabled;
+    uint32_t senkou_b_color;
+    float    senkou_b_width;
+    int32_t  senkou_b_enabled;
+    uint32_t chikou_color;
+    float    chikou_width;
+    int32_t  chikou_enabled;
+    int32_t  cloud_enabled;      // 0/1: shade between the leading spans
+    uint32_t bullish_cloud_color;  // where senkou A is above senkou B
+    uint32_t bearish_cloud_color;  // where senkou A is below senkou B
+    float    cloud_opacity;      // 0..1, multiplied into the cloud color's alpha
+} VroomIchimoku;
+
+// Fair Value Gap overlay drawn on the price pane: shaded boxes over three-candle
+// imbalances, where candle i-1 and i+1's wicks fail to overlap and leave a band
+// of price that was skipped. Bullish when candles[i-1].high < candles[i+1].low,
+// bearish when candles[i-1].low > candles[i+1].high. No pane is reserved.
+//
+// Each box is anchored to the middle bar's open time and spans the untouched
+// price range; it runs `box_length` slots right, or to the pane edge when
+// `extend_boxes`. Only enabled, max_bars_back, wait_for_close and fill_type
+// recompute — geometry and style are applied at draw time.
+//
+// With `show_inverse`, a filled gap draws a second box of the opposite polarity
+// starting where the first one ends, lasting until price reclaims the band.
+typedef struct VroomFairValueGaps {
+    int32_t  enabled;             // 0/1
+    int32_t  max_bars_back;       // bars to scan (clamped >= 0; default 300)
+    int32_t  wait_for_close;      // 0/1: withhold a gap until its 3rd bar closes
+    int32_t  fill_type;           // 0 = close through the far edge, 1 = wick
+    int32_t  delete_after_fill;   // 0/1: hide a gap once filled (else truncate it)
+    int32_t  extend_boxes;        // 0/1: run boxes to the pane edge
+    int32_t  box_length;          // box width in slots (clamped >= 1; default 20)
+    uint32_t bullish_color;       // 0xAARRGGBB fill where the gap is bullish
+    uint32_t bearish_color;       // fill where the gap is bearish
+    float    opacity;             // 0..1, multiplied into the fill color's alpha
+    int32_t  border_enabled;      // 0/1: stroke the box outline
+    int32_t  border_style;        // 0 = solid, 1 = dotted, 2 = dashed
+    float    border_width;        // stroke px
+    uint32_t bullish_border_color;
+    uint32_t bearish_border_color;
+    int32_t  labels_enabled;      // 0/1: draw `label` on each box
+    const char* label;            // UTF-8, copied by the setter; NULL = "FVG"
+    int32_t  label_distance;      // slots of clearance, extend_boxes only (>= 0)
+    uint32_t label_color;         // alpha 0 falls back to the box's border color
+    float    label_font_size;     // px; <= 0 falls back to the axis font size
+    int32_t  show_inverse;        // 0/1: keep drawing a filled gap, polarity flipped
+    uint32_t inverse_bullish_color;  // fill where the inverted zone is bullish,
+                                     // i.e. where a bearish gap was violated
+    uint32_t inverse_bearish_color;  // fill where a bullish gap was violated
+    const char* inverse_label;    // UTF-8, copied by the setter; NULL = "iFVG"
+} VroomFairValueGaps;
+
 // MACD, drawn in its own pane below the candles: the difference between a fast
 // and a slow moving average of `source`, a signal line smoothing that
 // difference, and a histogram of the gap between the two.
@@ -128,8 +202,29 @@ typedef struct VroomRSI {
     float    ma_width;
     uint32_t band_color;     // both dashed rules; 0 inherits the default gray
     int32_t  bands_visible;  // 0/1
+    // Shade where the line sits past a band, fading out at the rule and
+    // deepening toward the end of the scale. Takes its colors from
+    // VROOM_COLOR_ACCENT_BULL / _BEAR, and never reaches full opacity. 0/1.
+    int32_t  extreme_fill;
 } VroomRSI;
 
+// Average True Range, drawn in its own pane below the candles: a single line
+// measuring volatility in price units. True Range is the widest of the bar's
+// own high-low span and the two gaps from its extremes to the previous close,
+// smoothed over `period` bars.
+//
+// The style fields carry the same inherit sentinel as VroomMACD: a fully
+// transparent color falls back to the built-in default and a non-positive width
+// falls back to 1.5.
+typedef struct VroomATR {
+    int32_t  enabled;    // 0/1
+    int32_t  period;     // lookback in candles (clamped >= 1; default 14)
+    int32_t  smoothing;  // 0 = Wilder's RMA, 1 = SMA, 2 = EMA
+
+    uint32_t line_color;  // 0 inherits the default teal
+    float    line_width;  // stroke px; <= 0 inherits 1.5
+} VroomATR;
+
 // Session VWAP, drawn as a single line on the price pane. The session resets
 // each UTC day shifted by `reset_offset_min` minutes, and the line lifts its pen
 // at each reset. Color 0 inherits the default cyan; a non-positive width
@@ -343,6 +438,9 @@ typedef enum {
     VROOM_COLOR_ACCENT_BULL,       // generic up color: price indicator, volume, MACD
     VROOM_COLOR_ACCENT_BEAR,       // generic down color
     VROOM_COLOR_LINE,              // line-chart-mode close-price polyline
+    // The loading line. Its own alpha is honored, then scaled by the fade-in
+    // and the stage-3 fade-out, so an opaque color here is the usual choice.
+    VROOM_COLOR_SKELETON,
     VROOM_COLOR_COUNT_
 } VroomColorKey;
 
@@ -475,10 +573,64 @@ void vroom_chart_preserve_price_envelope(VroomChart* chart,
 // to 1. No-op when nothing is visible.
 void vroom_chart_begin_interval_morph(VroomChart* chart, int32_t mode);
 
-// Advances the interval morph started by vroom_chart_begin_interval_morph. `t`
-// (clamped to 0..1) is the eased progress: 0 renders the captured geometry
-// pixel-identically to the pre-swap frame, 1 renders the new candles and
-// releases the capture. Driven per-frame by the host animation loop.
+// Captures the same geometry for a live update to the series already shown —
+// a tick to the in-progress bar. Always a transform, and unlike the interval
+// morph it leaves the axes alone: the interval hasn't changed, so the ticks
+// between the labels are still the right ones and must not be faded.
+//
+// Restarting one that is still running continues from the shape on screen
+// rather than from the data under it, so ticks arriving faster than the
+// animation lands stay smooth instead of snapping back each time.
+//
+// Call before set_candles, then drive vroom_chart_set_interval_morph from 0 to
+// 1. No-op when nothing is visible. Not for an update that appends a bar: slots
+// pair from the right edge, so a new bar would shift every candle onto its
+// neighbour's geometry — advance the visible range instead and let the series
+// translate.
+void vroom_chart_begin_stream_morph(VroomChart* chart);
+
+// Shows or hides the loading line: a single stroke drawn across the plot in a
+// slow travelling sine, for a chart that has been laid out but has no data yet.
+// Suppresses the axis text, price badge, crosshair and indicator panes for as
+// long as it's up.
+//
+// `on` must mean "loading *and* holding no data for the series being shown";
+// the core takes it at face value rather than checking the candle buffer,
+// because a host mid-asset-switch can still be holding the previous asset's
+// bars. Pass `animate` 0 for reduced motion: the line draws still, and the
+// chart is allowed to go idle instead of pinning a redraw loop.
+//
+// Passing 0 abandons any hand-off in flight, which is what a failed or
+// superseded fetch wants. To hand off to data instead, use the two stages
+// below.
+void vroom_chart_set_loading(VroomChart* chart, int32_t on, int32_t animate);
+
+// Hand-off stage one: reshapes the line into the series. Freezes the sine where
+// it is and aims each vertex at the vertical centre of the candle that will
+// occupy its column, so the line resolves into the silhouette of the data.
+//
+// Call *after* set_candles — it reads them to know where to aim — then drive
+// vroom_chart_set_loading_morph from 0 to 1. The axes and the candles stay
+// suppressed throughout; stage two brings them in. No-op if the line isn't up.
+void vroom_chart_begin_loading_morph(VroomChart* chart);
+
+// Advances stage one. `t` (clamped to 0..1) is the eased progress: 0 renders the
+// frozen sine, 1 the polyline through the candle centres.
+void vroom_chart_set_loading_morph(VroomChart* chart, float t);
+
+// Hand-off stage two: the candles take over. Captures each one collapsed onto
+// its own vertical centre at zero alpha and leaves the loading state, so the
+// bars grow outward from the line and their color fades up as it fades out.
+//
+// Call once stage one has reached 1, then drive vroom_chart_set_interval_morph
+// from 0 to 1 as usual — the line's fade-out rides that same clock, so the two
+// finish together. No-op if the line isn't up.
+void vroom_chart_begin_loading_reveal(VroomChart* chart);
+
+// Advances the morph started by either begin_*_morph above. `t` (clamped to
+// 0..1) is the eased progress: 0 renders the captured geometry pixel-identically
+// to the pre-swap frame, 1 renders the new candles and releases the capture.
+// Driven per-frame by the host animation loop.
 void vroom_chart_set_interval_morph(VroomChart* chart, float t);
 
 void vroom_chart_pan(VroomChart* chart, float dx_px, float dy_px);
@@ -581,6 +733,11 @@ void vroom_chart_set_rsi(VroomChart* chart, const VroomRSI* cfg);
 // re-render.
 void vroom_chart_set_macd(VroomChart* chart, const VroomMACD* cfg);
 
+// Configures the ATR indicator (its own pane below the candles, stacking in
+// enable order like RSI and MACD). Period and smoothing changes recompute the
+// series; color and width changes only re-render.
+void vroom_chart_set_atr(VroomChart* chart, const VroomATR* cfg);
+
 // Replaces the full set of moving-average overlay lines (SMA/EMA) drawn on the
 // price pane. Pass count 0 to clear them. Overlays don't reserve a pane.
 void vroom_chart_set_overlays(VroomChart* chart, const VroomOverlay* overlays,
@@ -596,6 +753,23 @@ void vroom_chart_set_vwap(VroomChart* chart, const VroomVWAP* cfg);
 // changes only re-render; enabled/period/mult/source/basis changes recompute.
 void vroom_chart_set_bollinger(VroomChart* chart, const VroomBollinger* cfg);
 
+// Configures the Ichimoku overlay (five price-pane lines + the cloud between
+// the leading spans; no pane is reserved). Only enabled and the three periods
+// recompute; style, visibility and displacement changes just re-render.
+//
+// Enabling it also pulls the view forward so the leading spans, which sit past
+// the newest candle, are on screen — the same future gap the default framing
+// reserves when the indicator is already on at set_candles time.
+void vroom_chart_set_ichimoku(VroomChart* chart, const VroomIchimoku* cfg);
+
+// Configures the Fair Value Gap overlay (shaded imbalance boxes on the price
+// pane; no pane is reserved). Only enabled, max_bars_back, wait_for_close and
+// fill_type recompute; box geometry, style and labels just re-render.
+//
+// `cfg->label` is copied, so the caller may free it as soon as this returns.
+void vroom_chart_set_fair_value_gaps(VroomChart* chart,
+                                     const VroomFairValueGaps* cfg);
+
 // Configures the volume bars. Render-only — the bars come straight off each
 // candle's volume, so nothing is recomputed. Bars are enabled by default; pass
 // a config with `enabled` 0 to hide them.

package/cpp/_core_src/atr.cpp

@@ -0,0 +1,67 @@
+#include "atr.h"
+
+#include <algorithm>  // std::max
+#include <cmath>      // std::fabs, std::nan
+
+#include "ma.h"
+#include "series_ma.h"
+
+namespace vroom::atr {
+
+void compute(const ::VroomCandle* candles, std::size_t n, int period,
+             int smoothing, std::vector<double>& out) {
+    out.assign(n, std::nan(""));
+    if (!candles || period < 1) return;
+    const std::size_t P = static_cast<std::size_t>(period);
+    if (n < P) return;
+
+    std::vector<double> tr(n);
+    tr[0] = candles[0].high - candles[0].low;  // no previous close to gap from
+    for (std::size_t i = 1; i < n; ++i) {
+        const double prev_close = candles[i - 1].close;
+        tr[i] = std::max({candles[i].high - candles[i].low,
+                          std::fabs(candles[i].high - prev_close),
+                          std::fabs(candles[i].low - prev_close)});
+    }
+
+    if (smoothing == kSma) {
+        vroom::series_ma::smooth(tr, vroom::ma::KIND_SMA, period, out);
+        return;
+    }
+    if (smoothing == kEma) {
+        vroom::series_ma::smooth(tr, vroom::ma::KIND_EMA, period, out);
+        return;
+    }
+
+    // Wilder's RMA: seeded with the simple average of the first P true ranges,
+    // then avg = (prevAvg * (P - 1) + current) / P.
+    double avg = 0.0;
+    for (std::size_t i = 0; i < P; ++i) avg += tr[i];
+    avg /= static_cast<double>(P);
+    out[P - 1] = avg;
+
+    const double pm1 = static_cast<double>(P - 1);
+    const double pd = static_cast<double>(P);
+    for (std::size_t i = P; i < n; ++i) {
+        avg = (avg * pm1 + tr[i]) / pd;
+        out[i] = avg;
+    }
+}
+
+double autoscale(const double* visible, std::size_t n) {
+    double scale = 0.0;
+    if (!visible) return scale;
+    for (std::size_t i = 0; i < n; ++i) {
+        if (std::isfinite(visible[i])) scale = std::max(scale, visible[i]);
+    }
+    return scale;
+}
+
+double band_fraction(double v, double scale, double y_scale) {
+    // Nothing on show yet — everything sits on the baseline rather than
+    // dividing by zero.
+    if (!(scale > 0.0)) return 0.0;
+    return (v / scale) * kBandPadFraction * y_scale;
+}
+
+}  // namespace vroom::atr

package/cpp/_core_src/atr.h

@@ -0,0 +1,44 @@
+// Average True Range — pure computation, no Skia. Kept Skia-free so it builds
+// into the unit-test target.
+//
+// True Range is the widest of the bar's own high-low span and the two gaps from
+// its extremes to the previous close, so an overnight jump the bar's range
+// misses still counts. ATR is that series smoothed over `period` bars.
+
+#pragma once
+
+#include <cstddef>
+#include <vector>
+
+#include "vroom/vroom_chart.h"  // ::VroomCandle
+
+namespace vroom::atr {
+
+// How the true-range series is smoothed. kRma is Wilder's original
+// (alpha = 1/period) and the conventional default.
+enum Smoothing { kRma = 0, kSma = 1, kEma = 2 };
+
+// How much of the pane band the curve is allowed to fill, so a peak stops short
+// of the separator above it instead of touching.
+constexpr double kBandPadFraction = 0.85;
+
+// Computes ATR over [candles, candles+n). `period` is clamped to >= 1.
+// Fills `out` (resized to n): out[i] is the ATR at candle i in price units, or
+// NaN before the first defined value. True range exists from bar 0 (which has
+// no previous close, so it falls back to high - low), so the first ATR lands at
+// index period - 1 — one earlier than RSI.
+void compute(const ::VroomCandle* candles, std::size_t n, int period,
+             int smoothing, std::vector<double>& out);
+
+// The value the pane band is fitted to: the largest finite ATR on show, or 0
+// when there is nothing to plot. ATR is strictly positive, so the domain runs
+// from 0 at the band's bottom edge up to this.
+double autoscale(const double* visible, std::size_t n);
+
+// Where a value sits in the pane band, as a fraction of its height — 0 at the
+// bottom edge, 1 at the top. `y_scale` is the user's y-axis zoom (1 = the
+// default fit). Split out of the renderer so the interval-morph capture maps
+// its geometry through the same math the pane draws with.
+double band_fraction(double v, double scale, double y_scale);
+
+}  // namespace vroom::atr