react-native-vroom-chart 0.14.0 → 0.16.0

package/cpp/_core_src/chart_facade.cpp

@@ -13,6 +13,7 @@
 
 #include "chart.h"
 #include "drawings.h"
+#include "footprints.h"
 #include "labels.h"
 #include "price_lines.h"
 #include "viewport.h"
@@ -82,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
@@ -101,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;
     };
 
@@ -183,9 +211,15 @@ 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;
 
     // Infer the candle period from the first interval. Robust enough for
     // uniform-duration series (the only kind we model today).
@@ -211,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();
 }
 
@@ -222,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();
 }
 
@@ -298,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);
@@ -353,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);
@@ -393,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
@@ -406,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();
 }
@@ -627,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();
@@ -676,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;
@@ -1023,6 +1118,110 @@ extern "C" void vroom_chart_set_price_line_drag(VroomChart* chart, int32_t index
     chart->mark_dirty();
 }
 
+// ---- Footprints ------------------------------------------------------------
+
+extern "C" void vroom_chart_set_footprints(VroomChart* chart,
+                                           const VroomFootprint* prints,
+                                           size_t count,
+                                           const VroomFootprintStyle* style) {
+    if (!chart) return;
+    // Stored in the caller's order: vroom_chart_footprints_at hands these indices
+    // back, and they're only useful if they still address the caller's array.
+    if (count > 0 && prints) {
+        chart->footprints.assign(prints, prints + count);
+    } else {
+        chart->footprints.clear();
+    }
+    if (style) chart->footprint_style = *style;
+    chart->footprint_buckets_dirty = true;
+    // A badge that no longer exists must not keep its highlight.
+    if (chart->footprints.empty()) chart->hovered_footprint_side = -1;
+    chart->mark_dirty();
+}
+
+extern "C" bool vroom_chart_hit_test_footprint(VroomChart* chart, float x_px,
+                                               float y_px,
+                                               VroomFootprintHit* out) {
+    if (!chart || chart->footprints.empty() || chart->candles.empty()) return false;
+    chart->ensure_footprint_buckets();
+    if (chart->footprint_buckets.empty()) return false;
+
+    // Same bounds and pane geometry as draw_chart, so the badges hit where they
+    // render.
+    const auto lay = chart->layout();
+    const auto range = vroom::visible_indices(
+        chart->candles.data(), chart->candles.size(),
+        chart->visible_start_ms, chart->visible_end_ms);
+    const size_t n = range.end - range.start;
+    const auto bounds =
+        chart->price_bounds_manual
+            ? chart->price_bounds
+            : vroom::auto_price_bounds(chart->candles.data() + range.start, n);
+
+    const auto hit = vroom::footprints::hit_test(*chart, lay, bounds, x_px, y_px);
+    if (hit.side < 0) return false;
+    if (out) *out = hit;
+    return true;
+}
+
+extern "C" int32_t vroom_chart_footprints_at(VroomChart* chart,
+                                             int64_t candle_time_ms,
+                                             int32_t* out_indices, int32_t max) {
+    if (!chart || chart->footprints.empty()) return 0;
+    chart->ensure_footprint_buckets();
+
+    const auto& buckets = chart->footprint_buckets;
+    const auto it = std::lower_bound(
+        buckets.begin(), buckets.end(), candle_time_ms,
+        [](const vroom::footprints::Bucket& b, int64_t t) {
+            return b.candle_time_ms < t;
+        });
+    if (it == buckets.end() || it->candle_time_ms != candle_time_ms) return 0;
+
+    // Both sides, ascending by time — merge the two already-sorted lists rather
+    // than re-sorting them.
+    const auto& buys = it->buys;
+    const auto& sells = it->sells;
+    const int32_t total = static_cast<int32_t>(buys.size() + sells.size());
+    if (!out_indices || max <= 0) return total;
+
+    const auto& fps = chart->footprints;
+    int32_t written = 0;
+    size_t bi = 0;
+    size_t si = 0;
+    while (written < max && (bi < buys.size() || si < sells.size())) {
+        bool take_buy;
+        if (bi >= buys.size()) {
+            take_buy = false;
+        } else if (si >= sells.size()) {
+            take_buy = true;
+        } else {
+            const int64_t tb = fps[static_cast<size_t>(buys[bi])].time_ms;
+            const int64_t ts = fps[static_cast<size_t>(sells[si])].time_ms;
+            take_buy = tb <= ts;
+        }
+        out_indices[written++] = take_buy ? buys[bi++] : sells[si++];
+    }
+    return total;
+}
+
+extern "C" void vroom_chart_set_footprint_hover(VroomChart* chart,
+                                                int64_t candle_time_ms,
+                                                int32_t side) {
+    if (!chart) return;
+    if (side != VROOM_FOOTPRINT_BUY && side != VROOM_FOOTPRINT_SELL) {
+        side = -1;
+        candle_time_ms = 0;
+    }
+    if (chart->hovered_footprint_side == side &&
+        chart->hovered_footprint_time_ms == candle_time_ms) {
+        return;  // hover fires on every pointer move; don't redraw for nothing
+    }
+    chart->hovered_footprint_side = side;
+    chart->hovered_footprint_time_ms = candle_time_ms;
+    chart->mark_dirty();
+}
+
 extern "C" void vroom_chart_set_draft(VroomChart* chart, int64_t a_time,
                                       double a_price, bool has_b, int64_t b_time,
                                       double b_price, bool guide, uint32_t color,
@@ -1274,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);
@@ -1330,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) {
@@ -1381,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

package/cpp/_core_src/fair_value_gaps.h

@@ -0,0 +1,54 @@
+// Fair Value Gaps over a candle series — pure, no Skia, so it builds into the
+// unit-test target. Drawn as shaded price-pane boxes over three-candle
+// imbalances.
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+#include "vroom/vroom_chart.h"  // ::VroomCandle
+
+namespace vroom::fvg {
+
+// One detected imbalance, anchored in absolute time and price so the renderer
+// can place it without knowing which bar it came from.
+struct Gap {
+    int64_t time_ms = 0;    // open time of the middle bar
+    double  top = 0.0;      // upper price edge
+    double  bottom = 0.0;   // lower price edge
+    bool    bullish = false;
+    int64_t filled_ms = 0;  // open time of the bar that filled it; 0 = unfilled
+    // Open time of the bar that reclaimed the zone after it inverted; 0 while
+    // the inversion still stands. Only meaningful once filled_ms is set.
+    int64_t invalidated_ms = 0;
+};
+
+// Which price settles that a gap has been traded back through.
+enum FillType : int {
+    kFillClose = 0,  // a candle must close past the far edge
+    kFillWick = 1,   // a high or low reaching through is enough
+};
+
+// Detects the gaps in the last `max_bars_back` bars of [candles, candles+n),
+// oldest first, and resolves each one's fill.
+//
+// A gap sits around the middle bar of a three-candle run whose outer wicks miss
+// each other: bullish when candles[i-1].high < candles[i+1].low (spanning that
+// range), bearish when candles[i-1].low > candles[i+1].high. `wait_for_close`
+// withholds a gap whose third candle is still the newest, live bar.
+//
+// The fill scan walks forward from i+2 and records the first bar to reach the
+// far edge — the bottom of a bullish gap, the top of a bearish one.
+//
+// Closing through a gap inverts it: the band price just rejected becomes a
+// zone of the opposite polarity, resistance overhead where a bullish gap was
+// and support underfoot where a bearish one was. A second scan resumes after
+// the fill and records the bar that reclaims the band the other way, ending
+// the inversion. Both scans always run, so whether a filled or inverted box is
+// drawn at all stays a drawing concern.
+void compute(const ::VroomCandle* candles, std::size_t n, int max_bars_back,
+             bool wait_for_close, int fill_type, std::vector<Gap>& out);
+
+}  // namespace vroom::fvg