react-native-vroom-chart 0.15.0 → 0.16.0

package/cpp/_core_src/chart.h

@@ -9,6 +9,7 @@
 #pragma once
 
 #include <chrono>
+#include <cstddef>
 #include <string>
 #include <vector>
 
@@ -22,14 +23,33 @@
 #include "include/core/SkRefCnt.h"
 #pragma clang diagnostic pop
 
+#include "fair_value_gaps.h"
 #include "footprints_layout.h"
 #include "labels.h"
+#include "line_morph.h"
 #include "price_format.h"
 #include "theme.h"
 #include "viewport.h"
 
 class SkCanvas;
 
+namespace vroom {
+
+// Which indicator owns a below-chart pane. Panes are otherwise
+// interchangeable: they are all the same height and stack in enable order.
+enum class PaneKind { Rsi, Macd, Atr };
+
+// Count of PaneKind values — the most panes that can be stacked at once.
+constexpr int kMaxPanes = 3;
+
+// One enabled pane and the sequence number it claimed when it was turned on.
+struct IndicatorPane {
+    int order;
+    PaneKind kind;
+};
+
+}  // namespace vroom
+
 struct VroomChart {
     // --- bridge / lifecycle -------------------------------------------------
     VroomCallbacks cb{};
@@ -82,6 +102,19 @@ struct VroomChart {
     std::vector<vroom::CandleSnapshot> morph_from;
     float interval_morph_t = 1.f;  // 1 = not morphing
     bool interval_morph_fade = false;
+    // Set when the capture came from a live update rather than a timeframe
+    // switch. Same slot machinery, but the axis holds still: a stream morph
+    // only reshapes the last bar, and the ticks it sits between don't move, so
+    // running them through the interval envelope would flash the whole axis on
+    // every tick (see labels::interval_phase).
+    bool morph_is_stream = false;
+    // The outgoing shape of every indicator series that was on screen, captured
+    // alongside the candles and keyed by identity so a toggle landing in the
+    // same commit as the switch can't pair two different lines (see
+    // line_morph.h). A timeframe switch invalidates every indicator cache at
+    // once, so without this the lines would pop to their new values while the
+    // candles under them reshape.
+    std::vector<vroom::LineMorph> morph_lines;
     // The pre-switch price scale and time window. The candle capture above is
     // normalized against these, and the axes keep rendering their old ticks from
     // them while fading out (see labels::interval_phase), so a label is never
@@ -123,7 +156,8 @@ struct VroomChart {
     VroomRSI rsi{0, 14, 70.0, 30.0, 14, 0, 1,
                  0u, -1.f, 1,  // RSI line
                  0u, -1.f,     // trendline
-                 0u, 1};       // band rules
+                 0u, 1,        // band rules
+                 1};           // extreme shading
     std::vector<double> rsi_cache;     // RSI per candle (NaN where undefined)
     std::vector<double> rsi_ma_cache;  // MA of rsi_cache (empty if MA off)
     bool rsi_dirty = true;
@@ -147,11 +181,23 @@ struct VroomChart {
     // default auto-fit amplitude; >1 zooms in, <1 zooms out. Anchored at zero.
     double macd_y_scale = 1.0;
 
+    // ATR, drawn in its own pane. atr_cache is aligned to `candles` (NaN
+    // warmup), recomputed lazily by ensure_atr() when atr_dirty.
+    // Defaults: 14-period true range under Wilder smoothing, style fields on
+    // their inherit sentinel.
+    VroomATR atr{0, 14, 0, 0u, -1.f};
+    std::vector<double> atr_cache;
+    bool atr_dirty = true;
+    // User y-axis zoom for the ATR pane (drag on its y-axis strip). 1.0 = the
+    // default 0..peak fit; >1 zooms in, <1 zooms out. Anchored at the baseline.
+    double atr_y_scale = 1.0;
+
     // Stacking order for the indicator panes: each indicator gets the next
     // sequence number on its off->on transition, so the most recently enabled
     // pane sorts last (bottom). -1 = not currently enabled.
     int rsi_order = -1;
     int macd_order = -1;
+    int atr_order = -1;
     int pane_seq = 0;
 
     // Moving-average overlay lines (SMA/EMA) drawn on the price pane. Not panes
@@ -183,6 +229,46 @@ struct VroomChart {
     std::vector<double> bb_lower_cache;
     bool bollinger_dirty = true;
 
+    // Ichimoku overlay (price pane; no pane reserved). Caches aligned to
+    // `candles` (NaN warmup) and indexed by the bar each value was computed
+    // from — displacement is applied when drawing, so the caches survive a
+    // change to it. Recomputed lazily by ensure_ichimoku() when ichimoku_dirty.
+    // Defaults: the standard 9/26/52/26, blue tenkan / red kijun, green span A
+    // over orange span B, teal chikou, 15% cloud.
+    VroomIchimoku ichimoku{0, 9, 26, 52, 26,
+                           0xff2962ff, 1.f, 1,   // tenkan:   blue
+                           0xffef5350, 1.f, 1,   // kijun:    red
+                           0xff26a69a, 1.f, 1,   // senkou A: green
+                           0xffff6d00, 1.f, 1,   // senkou B: orange
+                           0xff00bcd4, 1.f, 1,   // chikou:   teal
+                           1, 0xff26a69a, 0xffef5350, 0.15f};
+    std::vector<double> ich_tenkan_cache;
+    std::vector<double> ich_kijun_cache;
+    std::vector<double> ich_senkou_a_cache;
+    std::vector<double> ich_senkou_b_cache;
+    std::vector<double> ich_chikou_cache;
+    bool ichimoku_dirty = true;
+
+    // Fair Value Gap overlay (price pane; no pane reserved). The cache holds the
+    // detected imbalances in absolute time/price, oldest first, so box geometry
+    // and style are free to change without re-scanning — only the detection
+    // inputs below dirty it. Recomputed lazily by ensure_fvg() when fvg_dirty.
+    //
+    // Defaults: 300 bars back, close-settled fills, deleted once filled, 20-slot
+    // boxes in green/red at 15%, solid 1px border, labels on.
+    VroomFairValueGaps fvg{0, 300, 0, 0, 1, 0, 20,
+                           0xff26a69a, 0xffef5350, 0.15f,
+                           1, 0, 1.f, 0xff26a69a, 0xffef5350,
+                           1, nullptr, 10, 0u, 0.f,
+                           0, 0xff26a69a, 0xffef5350, nullptr};
+    // Owns the label texts, so the caller may free theirs as soon as the setter
+    // returns. `fvg.label` and `fvg.inverse_label` are left null and these are
+    // what the renderer reads.
+    std::string fvg_label = "FVG";
+    std::string fvg_inverse_label = "iFVG";
+    std::vector<vroom::fvg::Gap> fvg_cache;
+    bool fvg_dirty = true;
+
     // Volume bars (price pane, under the candles). On by default with every
     // style field left on its inherit sentinel, so an untouched chart looks
     // exactly as it did before the config existed. No cache — bar heights come
@@ -348,6 +434,69 @@ struct VroomChart {
     // indicator is enabled.
     void ensure_bollinger();
 
+    // Recomputes the Ichimoku caches when ichimoku_dirty and the indicator is
+    // enabled.
+    void ensure_ichimoku();
+
+    // Redetects the Fair Value Gaps when fvg_dirty and the indicator is enabled.
+    void ensure_fvg();
+
+    // Recomputes the ATR cache when atr_dirty and the indicator is enabled.
+    void ensure_atr();
+
+    // Fills morph_lines with the outgoing shape of every enabled indicator,
+    // normalized the way morph_from is. Called by begin_interval_morph while
+    // the pre-switch candles and caches are still resident — after the swap
+    // there is nothing left to capture. `range` is the visible slice and
+    // `bounds` the price band the capture is taken against, both shared with
+    // the candle capture so the two land on the same pixels.
+    void capture_morph_lines(const vroom::Layout& lay,
+                             const vroom::PriceBounds& bounds,
+                             vroom::IndexRange range, int64_t window_ms);
+
+    // Source indices whose *displaced* plot time lands in the visible window,
+    // for an Ichimoku span drawn at `time_ms + shift_ms`. A bar of padding
+    // either side keeps a run reaching the pane edge instead of stopping at the
+    // last bar strictly inside it. Shared by the cloud, the lines and the
+    // interval-morph capture so all three slice the same bars.
+    vroom::IndexRange ichimoku_source_range(int64_t shift_ms) const;
+
+    // The enabled panes written to `out` top to bottom, returning how many.
+    // Both the draw pass and the y-axis hit test read this, so the stack they
+    // see can't drift apart.
+    int indicator_panes(vroom::IndicatorPane out[vroom::kMaxPanes]) const;
+
+    // Draws the pane stack into the band below the candles, starting at
+    // `pane_top`. Shared by the settled draw and the interval-morph fade, which
+    // paint the panes at different points in the z-order.
+    void draw_indicator_panes(SkCanvas* canvas, const vroom::Layout& lay,
+                              const VroomCandle* visible, std::size_t n,
+                              std::size_t first, int64_t window_ms,
+                              float candle_right, float pane_top,
+                              bool use_capture, float morph_t);
+
+    // The price-pane indicator overlays, split where the candles sit in the
+    // z-order: the Bollinger band and Ichimoku cloud go behind them, the moving
+    // averages, VWAP, Bollinger and Ichimoku lines over them.
+    //
+    // `use_capture` and `morph_t` carry the interval morph, on the same terms
+    // the candles take it. A transform pairs each series with its capture (see
+    // morph_lines) and eases toward the new shape. A fade's outgoing half
+    // passes n = 0 with morph_t = 0, replaying the capture alone. A settled
+    // frame passes no capture at all.
+    void draw_overlay_fills(SkCanvas* canvas, const vroom::Layout& lay,
+                            const vroom::PriceBounds& bounds,
+                            const VroomCandle* visible, std::size_t n,
+                            std::size_t first, int64_t window_ms,
+                            float candle_right, float candle_area_h,
+                            bool use_capture, float morph_t);
+    void draw_overlay_lines(SkCanvas* canvas, const vroom::Layout& lay,
+                            const vroom::PriceBounds& bounds,
+                            const VroomCandle* visible, std::size_t n,
+                            std::size_t first, int64_t window_ms,
+                            float candle_right, float candle_area_h,
+                            bool use_capture, float morph_t);
+
     // The main drawing pass. Calls into the labels and candles modules, and owns
     // the per-frame animation clock (see begin_frame) so every host gets it —
     // the web build draws straight through vroom_chart_draw rather than the

package/cpp/_core_src/chart_facade.cpp

@@ -83,6 +83,32 @@ int64_t damp_future_delta(int64_t delta_ms, int64_t cur_future,
     return static_cast<int64_t>(static_cast<double>(delta_ms) * resist);
 }
 
+// Empty time the Ichimoku leading spans need past the newest candle. Zero
+// unless the indicator is on — the reserve is Ichimoku's alone, since it is the
+// only thing that draws where there are no candles.
+int64_t ichimoku_future_ms(const VroomChart* chart) {
+    if (!chart->ichimoku.enabled || chart->ichimoku.displacement <= 0) return 0;
+    return static_cast<int64_t>(chart->ichimoku.displacement) *
+           chart->candle_duration_ms;
+}
+
+// Pull the view forward far enough to show the leading spans. Only ever grows
+// the future gap, and only as far as a pan gesture could already take it, so a
+// user who has scrolled ahead keeps their position. A no-op before the view is
+// framed — set_candles reserves the space itself in that case.
+void reserve_ichimoku_future(VroomChart* chart) {
+    if (chart->candles.empty()) return;
+    const int64_t want = ichimoku_future_ms(chart);
+    if (want <= 0) return;
+    const int64_t window = chart->visible_end_ms - chart->visible_start_ms;
+    if (window <= 0) return;
+    const int64_t last_time = chart->candles.back().time_ms;
+    const int64_t target = std::min(want, max_future_gap(window, 0));
+    if (chart->visible_end_ms - last_time >= target) return;
+    chart->visible_end_ms = last_time + target;
+    chart->visible_start_ms = chart->visible_end_ms - window;
+}
+
 // Frame the default view. When the consumer has set a target candle body width
 // (default_candle_px), size the window so each candle renders ~that wide with the
 // right edge pinned to the latest candle; otherwise fall back to the legacy
@@ -102,16 +128,17 @@ void apply_default_framing(VroomChart* chart) {
         lay.width_px - lay.y_axis_width_px - lay.right_padding_px;
 
     // Places a window of the given width with kRightGapPx of air past the newest
-    // candle. Shifts the window forward rather than widening it, so the framing
-    // keeps whatever candle width it just computed. Falls back to a flush right
-    // edge when the layout isn't measured yet and px can't be converted to time.
+    // candle, plus whatever empty time Ichimoku's leading spans need. Shifts the
+    // window forward rather than widening it, so the framing keeps whatever
+    // candle width it just computed. Falls back to a flush right edge when the
+    // layout isn't measured yet and px can't be converted to time.
     const auto frame = [&](int64_t window_ms) {
         const int64_t gap_ms =
             usable > 0.0 && window_ms > 0
                 ? static_cast<int64_t>((kRightGapPx * static_cast<double>(window_ms)) /
                                        usable)
                 : 0;
-        chart->visible_end_ms = right_edge_ms + gap_ms;
+        chart->visible_end_ms = right_edge_ms + gap_ms + ichimoku_future_ms(chart);
         chart->visible_start_ms = chart->visible_end_ms - window_ms;
     };
 
@@ -184,9 +211,12 @@ extern "C" void vroom_chart_set_candles(VroomChart* chart, const VroomCandle* da
     chart->candles.assign(data, data + count);
     chart->rsi_dirty = true;
     chart->macd_dirty = true;
+    chart->atr_dirty = true;
     chart->overlays_dirty = true;
     chart->vwap_dirty = true;
     chart->bollinger_dirty = true;
+    chart->ichimoku_dirty = true;
+    chart->fvg_dirty = true;
     // New bars (or a whole new interval) mean the footprint grouping no longer
     // matches the data — regroup on next use.
     chart->footprint_buckets_dirty = true;
@@ -215,9 +245,12 @@ extern "C" void vroom_chart_append_candle(VroomChart* chart, const VroomCandle*
     chart->candles.push_back(*c);
     chart->rsi_dirty = true;
     chart->macd_dirty = true;
+    chart->atr_dirty = true;
     chart->overlays_dirty = true;
     chart->vwap_dirty = true;
     chart->bollinger_dirty = true;
+    chart->ichimoku_dirty = true;
+    chart->fvg_dirty = true;
     chart->mark_dirty();
 }
 
@@ -226,9 +259,12 @@ extern "C" void vroom_chart_update_last(VroomChart* chart, const VroomCandle* c)
     chart->candles.back() = *c;
     chart->rsi_dirty = true;
     chart->macd_dirty = true;
+    chart->atr_dirty = true;
     chart->overlays_dirty = true;
     chart->vwap_dirty = true;
     chart->bollinger_dirty = true;
+    chart->ichimoku_dirty = true;
+    chart->fvg_dirty = true;
     chart->mark_dirty();
 }
 
@@ -302,6 +338,7 @@ extern "C" void vroom_chart_reset_view(VroomChart* chart) {
     // An asset switch reframes wholesale, so a slot-paired morph is meaningless
     // here — drop any capture rather than leaving it to reshape the wrong data.
     chart->morph_from.clear();
+    chart->morph_lines.clear();
     chart->interval_morph_t = 1.f;
     chart->interval_morph_fade = false;
     apply_default_framing(chart);
@@ -357,11 +394,17 @@ extern "C" void vroom_chart_preserve_price_envelope(VroomChart* chart,
     chart->mark_dirty();
 }
 
-extern "C" void vroom_chart_begin_interval_morph(VroomChart* chart, int32_t mode) {
-    if (!chart) return;
+// Captures the visible candles and every indicator on screen into the chart's
+// morph slots, normalized so the result survives the bounds change and any
+// resize that lands mid-morph. Leaves `morph_from` empty (and the morph closed)
+// when there is nothing to capture. Shared by the timeframe switch and the live
+// stream update, which differ only in what they do with the capture afterwards.
+static void capture_morph(VroomChart* chart) {
     chart->morph_from.clear();
+    chart->morph_lines.clear();
     chart->interval_morph_t = 1.f;
     chart->interval_morph_fade = false;
+    chart->morph_is_stream = false;
 
     const auto lay = chart->layout();
     const float area_w = vroom::candle_area_width(lay);
@@ -397,11 +440,21 @@ extern "C" void vroom_chart_begin_interval_morph(VroomChart* chart, int32_t mode
         };
     }
 
+    // Every indicator on screen, captured against the same slice and band so
+    // its line keeps its position relative to the candles it reshapes with.
+    chart->capture_morph_lines(lay, bounds, idx, window_ms);
+
     // The scale the capture was taken against — the axes render their outgoing
     // ticks from it, and it's about to be replaced on the chart itself.
     chart->morph_from_bounds = bounds;
     chart->morph_from_start_ms = chart->visible_start_ms;
     chart->morph_from_end_ms = chart->visible_end_ms;
+}
+
+extern "C" void vroom_chart_begin_interval_morph(VroomChart* chart, int32_t mode) {
+    if (!chart) return;
+    capture_morph(chart);
+    if (chart->morph_from.empty()) return;
 
     // Open the morph at 0 rather than leaving it at 1: the caller still has to
     // push the new candles, and any frame painted in between should show the
@@ -410,13 +463,50 @@ extern "C" void vroom_chart_begin_interval_morph(VroomChart* chart, int32_t mode
     chart->interval_morph_t = 0.f;
 }
 
+extern "C" void vroom_chart_begin_stream_morph(VroomChart* chart) {
+    if (!chart) return;
+
+    // Ticks arrive faster than the morph lands, so nearly every one interrupts
+    // the last. Keep what was on screen and fold it into the fresh capture
+    // below; dropping it would snap the bar back to its un-morphed shape on
+    // every tick. Only a stream capture is worth continuing from — a timeframe
+    // switch in flight is a different, larger motion, and a tick landing in the
+    // middle of one should let it finish rather than inherit its geometry.
+    std::vector<vroom::CandleSnapshot> interrupted;
+    std::vector<vroom::LineMorph> interrupted_lines;
+    float interrupted_t = 1.f;
+    if (chart->morph_is_stream && chart->interval_morph_t < 1.f) {
+        interrupted.swap(chart->morph_from);
+        interrupted_lines.swap(chart->morph_lines);
+        interrupted_t = chart->interval_morph_t;
+    }
+
+    capture_morph(chart);
+    if (chart->morph_from.empty()) return;
+
+    if (!interrupted.empty()) {
+        vroom::blend_candle_snapshots(chart->morph_from.data(),
+                                      chart->morph_from.size(),
+                                      interrupted.data(), interrupted.size(),
+                                      interrupted_t);
+        vroom::blend_line_morphs(chart->morph_lines, interrupted_lines,
+                                 interrupted_t);
+    }
+
+    chart->morph_is_stream = true;
+    chart->interval_morph_t = 0.f;
+}
+
 extern "C" void vroom_chart_set_interval_morph(VroomChart* chart, float t) {
     if (!chart) return;
     chart->interval_morph_t = std::clamp(t, 0.f, 1.f);
     if (chart->interval_morph_t >= 1.f) {
         chart->morph_from.clear();
         chart->morph_from.shrink_to_fit();
+        chart->morph_lines.clear();
+        chart->morph_lines.shrink_to_fit();
         chart->interval_morph_fade = false;
+        chart->morph_is_stream = false;
     }
     chart->mark_dirty();
 }
@@ -631,7 +721,9 @@ extern "C" void vroom_chart_scale_time_axis(VroomChart* chart, float dx_px) {
 extern "C" void vroom_chart_resize_indicator_pane(VroomChart* chart, float dy_px) {
     if (!chart || dy_px == 0.f) return;
 
-    const int pane_count = (chart->rsi.enabled ? 1 : 0) + (chart->macd.enabled ? 1 : 0);
+    const int pane_count = (chart->rsi.enabled ? 1 : 0) +
+                           (chart->macd.enabled ? 1 : 0) +
+                           (chart->atr.enabled ? 1 : 0);
     if (pane_count == 0) return;  // nothing below the chart to resize
 
     const auto lay = chart->layout();
@@ -680,42 +772,41 @@ extern "C" void vroom_chart_scale_indicator_axis(VroomChart* chart, float y_px,
     const auto lay = chart->layout();
     if (lay.indicator_area_h <= 0.f) return;
 
-    // Rebuild the same ordered pane stack draw_chart uses (most recently
-    // enabled pane sorts to the bottom) to find which pane y_px falls in.
-    struct ActivePane { int order; int type; };  // type: 0 = RSI, 1 = MACD
-    ActivePane panes[2];
-    int count = 0;
-    if (chart->rsi.enabled) panes[count++] = {chart->rsi_order, 0};
-    if (chart->macd.enabled) panes[count++] = {chart->macd_order, 1};
+    // The same ordered pane stack the draw pass uses, so the pane under y_px is
+    // the one the user sees there.
+    vroom::IndicatorPane panes[vroom::kMaxPanes];
+    const int count = chart->indicator_panes(panes);
     if (count == 0) return;
-    if (count == 2 && panes[0].order > panes[1].order) {
-        const ActivePane tmp = panes[0];
-        panes[0] = panes[1];
-        panes[1] = tmp;
-    }
 
     const float pane_h =
         chart->height_px * chart->theme.floats[VROOM_FLOAT_INDICATOR_HEIGHT_FRAC];
     if (pane_h <= 0.f) return;
 
-    int target = -1;  // 0 = RSI, 1 = MACD
+    const vroom::IndicatorPane* target = nullptr;
     float pane_top = vroom::price_pane_bottom(lay);
     for (int i = 0; i < count; ++i) {
         const float pane_bottom = pane_top + pane_h;
         if (y_px >= pane_top && y_px < pane_bottom) {
-            target = panes[i].type;
+            target = &panes[i];
             break;
         }
         pane_top = pane_bottom;
     }
-    if (target < 0) return;  // not over a pane
+    if (!target) return;  // not over a pane
 
     // Drag down (dy > 0) widens the visible value range (zoom out), matching
     // scale_price_axis's sign. The zoom is the inverse of the range scale.
     double range_scale = 1.0 + static_cast<double>(dy_px) / kAxisDragSensitivity;
     if (range_scale < 0.05) range_scale = 0.05;  // never collapse or flip
 
-    double& zoom = target == 0 ? chart->rsi_y_scale : chart->macd_y_scale;
+    double* zoom_ptr = nullptr;
+    switch (target->kind) {
+        case vroom::PaneKind::Rsi:  zoom_ptr = &chart->rsi_y_scale;  break;
+        case vroom::PaneKind::Macd: zoom_ptr = &chart->macd_y_scale; break;
+        case vroom::PaneKind::Atr:  zoom_ptr = &chart->atr_y_scale;  break;
+    }
+    if (!zoom_ptr) return;
+    double& zoom = *zoom_ptr;
     double next = zoom / range_scale;
     next = std::clamp(next, 0.1, 10.0);
     if (next == zoom) return;
@@ -1382,6 +1473,7 @@ extern "C" void vroom_chart_set_rsi(VroomChart* chart, const VroomRSI* cfg) {
     next.ma_visible = next.ma_visible ? 1 : 0;
     next.line_visible = next.line_visible ? 1 : 0;
     next.bands_visible = next.bands_visible ? 1 : 0;
+    next.extreme_fill = next.extreme_fill ? 1 : 0;
     if (next.period < 2) next.period = 2;
     if (next.ma_period < 1) next.ma_period = 1;
     next.upper_band = std::clamp(next.upper_band, 0.0, 100.0);
@@ -1438,6 +1530,27 @@ extern "C" void vroom_chart_set_macd(VroomChart* chart, const VroomMACD* cfg) {
     chart->mark_dirty();
 }
 
+extern "C" void vroom_chart_set_atr(VroomChart* chart, const VroomATR* cfg) {
+    if (!chart || !cfg) return;
+    VroomATR next = *cfg;
+    next.enabled = next.enabled ? 1 : 0;
+    if (next.period < 1) next.period = 1;
+
+    // Only the series-affecting fields force a recompute; color and width
+    // changes are render-only.
+    const VroomATR& cur = chart->atr;
+    const bool recompute = cur.enabled != next.enabled ||
+                           cur.period != next.period ||
+                           cur.smoothing != next.smoothing;
+
+    if (next.enabled && !cur.enabled) chart->atr_order = chart->pane_seq++;
+    else if (!next.enabled) chart->atr_order = -1;
+
+    chart->atr = next;
+    if (recompute) chart->atr_dirty = true;
+    chart->mark_dirty();
+}
+
 extern "C" void vroom_chart_set_overlays(VroomChart* chart,
                                          const VroomOverlay* overlays,
                                          size_t count) {
@@ -1489,6 +1602,79 @@ extern "C" void vroom_chart_set_bollinger(VroomChart* chart,
     chart->mark_dirty();
 }
 
+extern "C" void vroom_chart_set_ichimoku(VroomChart* chart,
+                                         const VroomIchimoku* cfg) {
+    if (!chart || !cfg) return;
+    VroomIchimoku next = *cfg;
+    next.enabled = next.enabled ? 1 : 0;
+    next.tenkan_enabled = next.tenkan_enabled ? 1 : 0;
+    next.kijun_enabled = next.kijun_enabled ? 1 : 0;
+    next.senkou_a_enabled = next.senkou_a_enabled ? 1 : 0;
+    next.senkou_b_enabled = next.senkou_b_enabled ? 1 : 0;
+    next.chikou_enabled = next.chikou_enabled ? 1 : 0;
+    next.cloud_enabled = next.cloud_enabled ? 1 : 0;
+    if (next.tenkan_period < 1) next.tenkan_period = 1;
+    if (next.kijun_period < 1) next.kijun_period = 1;
+    if (next.senkou_b_period < 1) next.senkou_b_period = 1;
+    if (next.displacement < 0) next.displacement = 0;
+    next.cloud_opacity = std::clamp(next.cloud_opacity, 0.f, 1.f);
+
+    // Only the series-affecting fields force a recompute. Displacement is not
+    // one of them — it shifts where the caches are drawn, not what's in them.
+    const VroomIchimoku& cur = chart->ichimoku;
+    const bool recompute = cur.enabled != next.enabled ||
+                           cur.tenkan_period != next.tenkan_period ||
+                           cur.kijun_period != next.kijun_period ||
+                           cur.senkou_b_period != next.senkou_b_period;
+    const bool turned_on = !cur.enabled && next.enabled;
+    chart->ichimoku = next;
+    if (recompute) chart->ichimoku_dirty = true;
+    // Turning it on mid-session misses the reserve the default framing makes,
+    // and the leading spans would sit off the right edge until the user panned.
+    if (turned_on) reserve_ichimoku_future(chart);
+    chart->mark_dirty();
+}
+
+extern "C" void vroom_chart_set_fair_value_gaps(VroomChart* chart,
+                                                const VroomFairValueGaps* cfg) {
+    if (!chart || !cfg) return;
+    VroomFairValueGaps next = *cfg;
+    next.enabled = next.enabled ? 1 : 0;
+    next.wait_for_close = next.wait_for_close ? 1 : 0;
+    next.delete_after_fill = next.delete_after_fill ? 1 : 0;
+    next.extend_boxes = next.extend_boxes ? 1 : 0;
+    next.border_enabled = next.border_enabled ? 1 : 0;
+    next.labels_enabled = next.labels_enabled ? 1 : 0;
+    next.show_inverse = next.show_inverse ? 1 : 0;
+    next.fill_type = next.fill_type == vroom::fvg::kFillWick
+                         ? vroom::fvg::kFillWick
+                         : vroom::fvg::kFillClose;
+    next.border_style = std::clamp(next.border_style, 0, 2);
+    if (next.max_bars_back < 0) next.max_bars_back = 0;
+    if (next.box_length < 1) next.box_length = 1;
+    if (next.label_distance < 0) next.label_distance = 0;
+    next.opacity = std::clamp(next.opacity, 0.f, 1.f);
+
+    // The labels are owned here; the struct's pointers are not retained, so the
+    // caller may free theirs as soon as this returns.
+    if (next.label) chart->fvg_label = next.label;
+    next.label = nullptr;
+    if (next.inverse_label) chart->fvg_inverse_label = next.inverse_label;
+    next.inverse_label = nullptr;
+
+    // Only the detection inputs force a rescan. Box geometry, colors, borders,
+    // labels and the inverse pass all read the same cache at draw time —
+    // invalidation is detected unconditionally alongside the fill.
+    const VroomFairValueGaps& cur = chart->fvg;
+    const bool recompute = cur.enabled != next.enabled ||
+                           cur.max_bars_back != next.max_bars_back ||
+                           cur.wait_for_close != next.wait_for_close ||
+                           cur.fill_type != next.fill_type;
+    chart->fvg = next;
+    if (recompute) chart->fvg_dirty = true;
+    chart->mark_dirty();
+}
+
 extern "C" void vroom_chart_set_volume(VroomChart* chart,
                                        const VroomVolume* cfg) {
     if (!chart || !cfg) return;

package/cpp/_core_src/fair_value_gaps.cpp

@@ -0,0 +1,76 @@
+#include "fair_value_gaps.h"
+
+#include <algorithm>
+
+namespace vroom::fvg {
+
+namespace {
+
+// True once `c` has traded through the far edge of the band as seen from
+// `bullish` — the bottom when bullish, the top when bearish. Under kFillClose
+// the candle has to close past it; under kFillWick the wick reaching it is
+// enough.
+//
+// Polarity is a parameter rather than `g.bullish` because the same test settles
+// both events: a gap is filled when price crosses it in its own direction, and
+// the zone it inverts into is reclaimed when price crosses back the other way.
+bool crossed(const ::VroomCandle& c, const Gap& g, bool bullish, int fill_type) {
+    if (fill_type == kFillWick) {
+        return bullish ? c.low <= g.bottom : c.high >= g.top;
+    }
+    return bullish ? c.close <= g.bottom : c.close >= g.top;
+}
+
+}  // namespace
+
+void compute(const ::VroomCandle* candles, std::size_t n, int max_bars_back,
+             bool wait_for_close, int fill_type, std::vector<Gap>& out) {
+    out.clear();
+    if (!candles || n < 3 || max_bars_back <= 0) return;
+
+    // The middle bar of the three. It needs a bar on each side, and under
+    // wait_for_close the third one must not be the still-forming newest bar.
+    const std::size_t last = wait_for_close ? n - 3 : n - 2;
+    const std::size_t window = static_cast<std::size_t>(max_bars_back);
+    const std::size_t first = std::max<std::size_t>(1, n > window ? n - window : 0);
+
+    for (std::size_t i = first; i <= last; ++i) {
+        const ::VroomCandle& prev = candles[i - 1];
+        const ::VroomCandle& next = candles[i + 1];
+
+        Gap g;
+        if (prev.high < next.low) {
+            g.bullish = true;
+            g.bottom = prev.high;
+            g.top = next.low;
+        } else if (prev.low > next.high) {
+            g.bullish = false;
+            g.bottom = next.high;
+            g.top = prev.low;
+        } else {
+            continue;  // the wicks overlap — price left nothing behind
+        }
+        g.time_ms = candles[i].time_ms;
+
+        std::size_t j = i + 2;
+        for (; j < n; ++j) {
+            if (crossed(candles[j], g, g.bullish, fill_type)) {
+                g.filled_ms = candles[j].time_ms;
+                break;
+            }
+        }
+
+        // Resume after the filling bar with the polarity flipped. Starting at
+        // j + 1 is what keeps an earlier bar that happened to sit past the
+        // opposite edge from counting — the inversion does not exist yet.
+        for (++j; g.filled_ms != 0 && j < n; ++j) {
+            if (crossed(candles[j], g, !g.bullish, fill_type)) {
+                g.invalidated_ms = candles[j].time_ms;
+                break;
+            }
+        }
+        out.push_back(g);
+    }
+}
+
+}  // namespace vroom::fvg