react-native-vroom-chart 0.13.1 → 0.15.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"
@@ -186,6 +187,9 @@ extern "C" void vroom_chart_set_candles(VroomChart* chart, const VroomCandle* da
     chart->overlays_dirty = true;
     chart->vwap_dirty = true;
     chart->bollinger_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).
@@ -299,6 +303,7 @@ extern "C" void vroom_chart_reset_view(VroomChart* chart) {
     // here — drop any capture rather than leaving it to reshape the wrong data.
     chart->morph_from.clear();
     chart->interval_morph_t = 1.f;
+    chart->interval_morph_fade = false;
     apply_default_framing(chart);
     vroom::labels::recompute_axis_width(*chart);
     if (chart->cb.on_viewport_changed) {
@@ -352,10 +357,11 @@ extern "C" void vroom_chart_preserve_price_envelope(VroomChart* chart,
     chart->mark_dirty();
 }
 
-extern "C" void vroom_chart_begin_interval_morph(VroomChart* chart) {
+extern "C" void vroom_chart_begin_interval_morph(VroomChart* chart, int32_t mode) {
     if (!chart) return;
     chart->morph_from.clear();
     chart->interval_morph_t = 1.f;
+    chart->interval_morph_fade = false;
 
     const auto lay = chart->layout();
     const float area_w = vroom::candle_area_width(lay);
@@ -400,6 +406,7 @@ extern "C" void vroom_chart_begin_interval_morph(VroomChart* chart) {
     // 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
     // captured geometry — which is what the pre-switch frame looked like.
+    chart->interval_morph_fade = vroom::interval_morph_is_fade(mode);
     chart->interval_morph_t = 0.f;
 }
 
@@ -409,6 +416,7 @@ extern "C" void vroom_chart_set_interval_morph(VroomChart* chart, float t) {
     if (chart->interval_morph_t >= 1.f) {
         chart->morph_from.clear();
         chart->morph_from.shrink_to_fit();
+        chart->interval_morph_fade = false;
     }
     chart->mark_dirty();
 }
@@ -1019,6 +1027,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,

package/cpp/_core_src/footprints.cpp

@@ -0,0 +1,226 @@
+#include "footprints.h"
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdocumentation"
+#include "include/core/SkCanvas.h"
+#include "include/core/SkColor.h"
+#include "include/core/SkPaint.h"
+#include "include/core/SkRect.h"
+#pragma clang diagnostic pop
+
+#include <algorithm>
+#include <cmath>
+
+#include "chart.h"
+#include "footprints_layout.h"
+#include "theme.h"
+#include "viewport.h"
+
+namespace vroom::footprints {
+
+namespace {
+
+// The glyph is a bar (minus) or a crossed pair of bars (plus) sized as a fraction
+// of the badge, so restyling the radius scales the whole mark.
+constexpr float kGlyphFrac = 0.52f;   // glyph length / diameter
+constexpr float kStrokeFrac = 0.20f;  // stroke width / radius
+
+// The hovered badge gets a soft ring outside its edge — the "lit up" state in the
+// reference, and the only affordance that reads at a 9px radius.
+constexpr float kHaloWidthFrac = 0.42f;  // ring stroke width / radius
+constexpr float kHaloGapFrac = 0.30f;    // clear space between badge and ring
+constexpr U8CPU kHaloAlpha = 0x66;
+
+// Brightens `c`'s channels by `mul` (clamped at white), leaving alpha alone.
+// Matches price_lines::boost so hover feels the same across both widgets.
+SkColor boost(SkColor c, float mul) {
+    if (mul <= 1.f) return c;
+    const auto up = [mul](U8CPU v) {
+        return static_cast<U8CPU>(
+            std::min(255.f, static_cast<float>(v) * mul + 0.5f));
+    };
+    return SkColorSetARGB(SkColorGetA(c), up(SkColorGetR(c)), up(SkColorGetG(c)),
+                          up(SkColorGetB(c)));
+}
+
+// One laid-out badge, in pixels.
+struct Badge {
+    float   cx = 0.f;
+    float   cy = 0.f;
+    float   radius = 0.f;
+    int32_t side = -1;
+    int64_t candle_time_ms = 0;
+};
+
+// Walks every badge that could be on screen, in draw order, handing each to `fn`.
+// Both passes go through here: the badge the user sees and the badge they can
+// hover are the same object by construction.
+template <typename Fn>
+void for_each_badge(const VroomChart& chart, const Layout& lay,
+                    const PriceBounds& bounds, int64_t window_ms, Fn&& fn) {
+    if (chart.footprint_buckets.empty() || chart.candles.empty()) return;
+    if (window_ms <= 0) return;
+
+    const Metrics m = metrics_from(&chart.footprint_style);
+    const float pane_bottom = vroom::price_pane_bottom(lay);
+    const float pane_right = vroom::candle_area_width(lay);
+
+    const ::VroomCandle* candles = chart.candles.data();
+    const size_t candle_count = chart.candles.size();
+
+    // Only the buckets whose candles are in (or just off) the window matter. One
+    // bar of slack each side keeps a badge from popping in at the edge.
+    const int64_t slack = chart.candle_duration_ms;
+    const auto& buckets = chart.footprint_buckets;
+    auto it = std::lower_bound(buckets.begin(), buckets.end(),
+                               chart.visible_start_ms - slack,
+                               [](const Bucket& b, int64_t t) {
+                                   return b.candle_time_ms < t;
+                               });
+
+    for (; it != buckets.end(); ++it) {
+        if (it->candle_time_ms > chart.visible_end_ms + slack) break;
+
+        // The bar this bucket belongs to, for its high.
+        const ::VroomCandle* c =
+            std::lower_bound(candles, candles + candle_count, it->candle_time_ms,
+                             [](const ::VroomCandle& a, int64_t t) {
+                                 return a.time_ms < t;
+                             });
+        if (c == candles + candle_count || c->time_ms != it->candle_time_ms) {
+            continue;  // the bar went away; the bucket is about to be rebuilt
+        }
+
+        const float cx = vroom::candle_center_x(lay, it->candle_time_ms,
+                                                chart.candle_duration_ms,
+                                                chart.visible_start_ms, window_ms);
+        // Cheap reject before laying the stack out.
+        if (cx < -m.radius || cx > pane_right + m.radius) continue;
+
+        const float high_y = vroom::price_to_y(lay, bounds, c->high);
+        const Stack stack = layout_stack(*it, high_y, 0.f, m.radius, m.gap, m.margin);
+
+        for (int32_t i = 0; i < stack.count; ++i) {
+            // A bar whose high is below the pane (scrolled off the bottom) parks
+            // its stack out of sight; skip rather than draw over the x-axis.
+            if (stack.y[i] - m.radius > pane_bottom) continue;
+            Badge b;
+            b.cx = cx;
+            b.cy = stack.y[i];
+            b.radius = m.radius;
+            b.side = stack.sides[i];
+            b.candle_time_ms = it->candle_time_ms;
+            fn(b, m);
+        }
+    }
+}
+
+// Buy = "+", sell = "-": one horizontal bar, plus a vertical one for an entry.
+void draw_glyph(SkCanvas* canvas, const Badge& b, SkColor color) {
+    SkPaint p;
+    p.setAntiAlias(true);
+    p.setColor(color);
+    p.setStyle(SkPaint::kStroke_Style);
+    p.setStrokeWidth(std::max(1.f, b.radius * kStrokeFrac));
+    p.setStrokeCap(SkPaint::kRound_Cap);
+
+    const float arm = b.radius * kGlyphFrac;
+    canvas->drawLine(b.cx - arm, b.cy, b.cx + arm, b.cy, p);
+    if (b.side == VROOM_FOOTPRINT_BUY) {
+        canvas->drawLine(b.cx, b.cy - arm, b.cx, b.cy + arm, p);
+    }
+}
+
+}  // namespace
+
+void draw(SkCanvas* canvas,
+          const VroomChart& chart,
+          const Layout& lay,
+          const PriceBounds& bounds,
+          int64_t window_ms) {
+    if (!canvas || chart.footprints.empty()) return;
+
+    const float pane_bottom = vroom::price_pane_bottom(lay);
+    const float pane_right = vroom::candle_area_width(lay);
+    if (pane_right <= 0.f || pane_bottom <= 0.f) return;
+
+    const SkColor bull = chart.theme.colors[VROOM_COLOR_BULL];
+    const SkColor bear = chart.theme.colors[VROOM_COLOR_BEAR];
+    const SkColor glyph = chart.theme.colors[VROOM_COLOR_BADGE_TEXT];
+
+    // Badges belong to the plot, not the axis strips: a bar at the right edge
+    // must not spill its badge over the price labels.
+    canvas->save();
+    canvas->clipRect(SkRect::MakeLTRB(0.f, 0.f, pane_right, pane_bottom));
+
+    for_each_badge(chart, lay, bounds, window_ms,
+                   [&](const Badge& b, const Metrics& m) {
+        const bool hovered = chart.hovered_footprint_side == b.side &&
+                             chart.hovered_footprint_time_ms == b.candle_time_ms;
+        const SkColor base = b.side == VROOM_FOOTPRINT_BUY ? bull : bear;
+        const SkColor fill = hovered ? boost(base, m.hover_boost) : base;
+
+        if (hovered) {
+            SkPaint halo;
+            halo.setAntiAlias(true);
+            halo.setStyle(SkPaint::kStroke_Style);
+            halo.setStrokeWidth(b.radius * kHaloWidthFrac);
+            halo.setColor(SkColorSetA(fill, kHaloAlpha));
+            const float r =
+                b.radius * (1.f + kHaloGapFrac + kHaloWidthFrac * 0.5f);
+            canvas->drawCircle(b.cx, b.cy, r, halo);
+        }
+
+        SkPaint body;
+        body.setAntiAlias(true);
+        body.setColor(fill);
+        canvas->drawCircle(b.cx, b.cy, b.radius, body);
+
+        draw_glyph(canvas, b, glyph);
+    });
+
+    canvas->restore();
+}
+
+::VroomFootprintHit hit_test(const VroomChart& chart,
+                             const Layout& lay,
+                             const PriceBounds& bounds,
+                             float x,
+                             float y) {
+    ::VroomFootprintHit best{};
+    best.side = -1;
+
+    // The rect the badges are clipped to. Reported on every hit so the host can
+    // place a tooltip against the real plot edge rather than the element's.
+    const float pane_right = vroom::candle_area_width(lay);
+    const float pane_bottom = vroom::price_pane_bottom(lay);
+    best.pane_left = 0.f;
+    best.pane_top = 0.f;
+    best.pane_right = pane_right;
+    best.pane_bottom = pane_bottom;
+
+    const int64_t window_ms = chart.visible_end_ms - chart.visible_start_ms;
+    // Outside the plot there is nothing to hit, matching the draw-time clip.
+    if (x < 0.f || x > pane_right) return best;
+    if (y < 0.f || y > pane_bottom) return best;
+
+    float best_d2 = 0.f;
+    for_each_badge(chart, lay, bounds, window_ms, [&](const Badge& b, const Metrics&) {
+        if (!hits_badge(b.cx, b.cy, b.radius, x, y)) return;
+        // Stacked badges are drawn with a gap, but a generous hit tolerance can
+        // still overlap; the nearest center is the one the user meant.
+        const float dx = x - b.cx;
+        const float dy = y - b.cy;
+        const float d2 = dx * dx + dy * dy;
+        if (best.side >= 0 && d2 >= best_d2) return;
+        best_d2 = d2;
+        best.candle_time_ms = b.candle_time_ms;
+        best.side = b.side;
+        best.center_x = b.cx;
+        best.center_y = b.cy;
+        best.radius = b.radius;
+    });
+    return best;
+}
+
+}  // namespace vroom::footprints

package/cpp/_core_src/footprints.h

@@ -0,0 +1,45 @@
+// Footprints — circular badges marking where a trader entered and exited, drawn
+// above the candle each trade fell in.
+//
+// A buy is a "+" in the bull color, a sell a "-" in the bear color, both glyphs in
+// VROOM_COLOR_BADGE_TEXT. Only one badge per side per candle renders however many
+// fills went into it; the host learns the full set through
+// vroom_chart_footprints_at and draws its own tooltip.
+//
+// Bucketing and badge geometry live in footprints_layout.h so the draw and
+// hit-test passes agree by construction.
+
+#pragma once
+
+#include <cstdint>
+
+#include "vroom/vroom_chart.h"
+
+class SkCanvas;
+struct VroomChart;
+
+namespace vroom {
+struct Layout;
+struct PriceBounds;
+}  // namespace vroom
+
+namespace vroom::footprints {
+
+// Draws every visible footprint badge, clipped to the price pane. `window_ms` is
+// the visible time span, used to place each badge over its candle's slot center.
+void draw(SkCanvas* canvas,
+          const VroomChart& chart,
+          const Layout& lay,
+          const PriceBounds& bounds,
+          int64_t window_ms);
+
+// Hit-tests pixel (x, y) against the badges. The returned hit's `side` is -1 on a
+// miss; when two badges overlap the nearest center wins. Derives geometry from the
+// same layout functions as draw, so what the user sees is what they can hover.
+::VroomFootprintHit hit_test(const VroomChart& chart,
+                             const Layout& lay,
+                             const PriceBounds& bounds,
+                             float x,
+                             float y);
+
+}  // namespace vroom::footprints

package/cpp/_core_src/footprints_layout.cpp

@@ -0,0 +1,140 @@
+#include "footprints_layout.h"
+
+#include <algorithm>
+#include <cmath>
+
+namespace vroom::footprints {
+
+int32_t bucket_index(const ::VroomCandle* candles, size_t count,
+                     int64_t duration_ms, int64_t time_ms) {
+    if (!candles || count == 0 || duration_ms <= 0) return -1;
+
+    // Last candle that opened at or before the trade.
+    const ::VroomCandle* it =
+        std::upper_bound(candles, candles + count, time_ms,
+                         [](int64_t t, const ::VroomCandle& c) { return t < c.time_ms; });
+    if (it == candles) return -1;  // before the first bar
+    const int32_t i = static_cast<int32_t>((it - 1) - candles);
+
+    // Inside that bar's window, or in a gap where no bar exists.
+    if (time_ms >= candles[i].time_ms + duration_ms) return -1;
+    return i;
+}
+
+std::vector<Bucket> build_buckets(const ::VroomCandle* candles, size_t count,
+                                  int64_t duration_ms,
+                                  const ::VroomFootprint* prints, size_t print_count) {
+    std::vector<Bucket> out;
+    if (!candles || count == 0 || !prints || print_count == 0) return out;
+
+    // Bucket per candle index, then compact. Candle counts stay in the low
+    // thousands, so a flat scratch vector beats a map on both sides of the ledger.
+    std::vector<int32_t> slot(count, -1);
+
+    for (size_t i = 0; i < print_count; ++i) {
+        const ::VroomFootprint& p = prints[i];
+        if (p.side != VROOM_FOOTPRINT_BUY && p.side != VROOM_FOOTPRINT_SELL) continue;
+
+        const int32_t ci = bucket_index(candles, count, duration_ms, p.time_ms);
+        if (ci < 0) continue;
+
+        if (slot[static_cast<size_t>(ci)] < 0) {
+            slot[static_cast<size_t>(ci)] = static_cast<int32_t>(out.size());
+            Bucket b;
+            b.candle_time_ms = candles[ci].time_ms;
+            out.push_back(std::move(b));
+        }
+        Bucket& b = out[static_cast<size_t>(slot[static_cast<size_t>(ci)])];
+        if (p.side == VROOM_FOOTPRINT_BUY) {
+            b.buys.push_back(static_cast<int32_t>(i));
+        } else {
+            b.sells.push_back(static_cast<int32_t>(i));
+        }
+    }
+
+    // The host's array can arrive in any order, so sort each side by time and read
+    // the latest off the end.
+    const auto by_time = [prints](int32_t a, int32_t b) {
+        const int64_t ta = prints[static_cast<size_t>(a)].time_ms;
+        const int64_t tb = prints[static_cast<size_t>(b)].time_ms;
+        // Fall back to the host's order so equal timestamps stay stable.
+        return ta != tb ? ta < tb : a < b;
+    };
+    for (Bucket& b : out) {
+        std::sort(b.buys.begin(), b.buys.end(), by_time);
+        std::sort(b.sells.begin(), b.sells.end(), by_time);
+        if (!b.buys.empty()) {
+            b.buy_latest_ms = prints[static_cast<size_t>(b.buys.back())].time_ms;
+        }
+        if (!b.sells.empty()) {
+            b.sell_latest_ms = prints[static_cast<size_t>(b.sells.back())].time_ms;
+        }
+    }
+
+    // Buckets were created in first-seen order; callers want them by candle.
+    std::sort(out.begin(), out.end(), [](const Bucket& a, const Bucket& b) {
+        return a.candle_time_ms < b.candle_time_ms;
+    });
+    return out;
+}
+
+Metrics metrics_from(const ::VroomFootprintStyle* style) {
+    Metrics m;
+    if (!style) return m;
+    if (style->radius_px > 0.f) m.radius = style->radius_px;
+    if (style->gap_px > 0.f) m.gap = style->gap_px;
+    if (style->margin_px > 0.f) m.margin = style->margin_px;
+    if (style->hover_boost > 0.f) m.hover_boost = style->hover_boost;
+    return m;
+}
+
+Stack layout_stack(const Bucket& bucket, float high_y, float pane_top,
+                   float radius, float gap, float margin) {
+    Stack out;
+    if (radius <= 0.f) radius = kRadius;
+    if (gap <= 0.f) gap = kGap;
+    if (margin <= 0.f) margin = kMargin;
+
+    const bool buys = bucket.has_buys();
+    const bool sells = bucket.has_sells();
+    if (!buys && !sells) return out;
+
+    if (buys && sells) {
+        // Bottom-to-top replays the order the trades happened in. Ties go to the
+        // buy, so an entry and exit stamped the same ms still lay out predictably.
+        const bool buy_first = bucket.buy_latest_ms <= bucket.sell_latest_ms;
+        out.sides[0] = buy_first ? VROOM_FOOTPRINT_BUY : VROOM_FOOTPRINT_SELL;
+        out.sides[1] = buy_first ? VROOM_FOOTPRINT_SELL : VROOM_FOOTPRINT_BUY;
+        out.count = 2;
+    } else {
+        out.sides[0] = buys ? VROOM_FOOTPRINT_BUY : VROOM_FOOTPRINT_SELL;
+        out.count = 1;
+    }
+
+    // Slot 0 clears the high by `margin`; each further slot clears the one below
+    // it by `gap`, which is what keeps them separately hoverable.
+    const float pitch = 2.f * radius + gap;
+    for (int32_t i = 0; i < out.count; ++i) {
+        out.y[i] = high_y - margin - radius - static_cast<float>(i) * pitch;
+    }
+
+    // A bar near the top of the view would push its stack off-screen; slide the
+    // whole stack down so the topmost badge stays inside the pane. Moving both
+    // together preserves the order the stack encodes.
+    const float top_edge = out.y[out.count - 1] - radius;
+    if (top_edge < pane_top) {
+        const float shift = pane_top - top_edge;
+        for (int32_t i = 0; i < out.count; ++i) out.y[i] += shift;
+    }
+    return out;
+}
+
+bool hits_badge(float cx, float cy, float radius, float x, float y) {
+    if (radius <= 0.f) return false;
+    const float dx = x - cx;
+    const float dy = y - cy;
+    const float r = radius + kHitTolerance;
+    return dx * dx + dy * dy <= r * r;
+}
+
+}  // namespace vroom::footprints

package/cpp/_core_src/footprints_layout.h

@@ -0,0 +1,94 @@
+// Footprint bucketing + badge geometry — pure functions, no Skia, no state.
+//
+// Split out from footprints.cpp for the same reason as price_line_layout.h: the
+// render pass and the hit-test pass must agree on where every badge sits, or the
+// user ends up hovering nothing where a badge clearly is. Being Skia-free it also
+// unit-tests without a Skia checkout.
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+#include "vroom/vroom_chart.h"
+
+namespace vroom::footprints {
+
+// Badge radius, the gap between two stacked badges, and the gap between the
+// candle's high and the first badge. Defaults for a zero/negative style field.
+constexpr float kRadius = 9.f;
+constexpr float kGap = 4.f;
+constexpr float kMargin = 8.f;
+constexpr float kHoverBoost = 1.25f;
+
+// Slop around the circle so a 9px badge is still a comfortable target, on a
+// mouse and under a thumb alike.
+constexpr float kHitTolerance = 3.f;
+
+// One candle's footprints, split by side. Both lists hold indices into the array
+// the host passed to vroom_chart_set_footprints — its order, so a caller can map
+// them straight back to its own trade objects — sorted ascending by time.
+struct Bucket {
+    int64_t              candle_time_ms = 0;
+    std::vector<int32_t> buys;
+    std::vector<int32_t> sells;
+    // Time of the last trade on each side, which decides the stack order. Only
+    // meaningful when the matching list is non-empty.
+    int64_t buy_latest_ms = 0;
+    int64_t sell_latest_ms = 0;
+
+    bool has_buys() const { return !buys.empty(); }
+    bool has_sells() const { return !sells.empty(); }
+    // Every candle that made it into a bucket has at least one badge to draw.
+    int32_t badge_count() const { return (has_buys() ? 1 : 0) + (has_sells() ? 1 : 0); }
+};
+
+// Index of the candle whose [time_ms, time_ms + duration_ms) window contains
+// `time_ms`, or -1 when it falls in no window — before the first candle, or in a
+// gap (a weekend, a halt) where no bar exists. Candles must be ascending.
+int32_t bucket_index(const ::VroomCandle* candles, size_t count,
+                     int64_t duration_ms, int64_t time_ms);
+
+// Groups `prints` onto candles. The result is ascending by candle time and holds
+// only candles that got at least one footprint, so it is also the dedupe: however
+// many trades a bar collected, it comes back as one bucket with at most two sides.
+// Footprints with an unknown side, or that land in no candle's window, are dropped.
+std::vector<Bucket> build_buckets(const ::VroomCandle* candles, size_t count,
+                                  int64_t duration_ms,
+                                  const ::VroomFootprint* prints, size_t print_count);
+
+// The laid-out badge stack for one candle: one or two centers, going up from the
+// candle's high. Slot 0 is the one nearest the bar.
+struct Stack {
+    int32_t count = 0;
+    int32_t sides[2]{};  // VroomFootprintSide per slot
+    float   y[2]{};      // center y per slot
+};
+
+// Stacks `bucket`'s badges above `high_y` (the pixel y of the candle's high).
+//
+// The side whose latest trade came *first* takes the lower slot, so reading the
+// stack bottom-to-top replays the order the trades happened in. The whole stack
+// shifts down if it would poke out the top of the pane, keeping badges on a bar
+// near the high of the view visible and hoverable rather than clipped away.
+//
+// Style fields at or below zero fall back to kRadius / kGap / kMargin.
+Stack layout_stack(const Bucket& bucket, float high_y, float pane_top,
+                   float radius, float gap, float margin);
+
+// True when (x, y) is within a badge of `radius` centered at (cx, cy), plus
+// kHitTolerance.
+bool hits_badge(float cx, float cy, float radius, float x, float y);
+
+// Resolves the style struct's raw fields to the values the layout should use.
+// A null `style`, or any field left at zero, takes the default.
+struct Metrics {
+    float radius = kRadius;
+    float gap = kGap;
+    float margin = kMargin;
+    float hover_boost = kHoverBoost;
+};
+Metrics metrics_from(const ::VroomFootprintStyle* style);
+
+}  // namespace vroom::footprints

package/cpp/_core_src/tip_pulse.h

@@ -1,10 +1,10 @@
 // The pulsing ring at the line chart's tip — a phase in, a radius and two
 // alphas out (VROOM_FLOAT_LINE_TIP_PULSE).
 //
-// Shape and timing follow TradingView's last-price animation, whose numbers are
-// well-tuned: expand while the fill washes out and the edge sharpens, keep
-// expanding while the edge fades, then rest. That rest is nearly half the period
-// and it is what makes the ring read as a heartbeat instead of a strobe.
+// Shape and timing follow the last-price animation charting tools converged on:
+// expand while the fill washes out and the edge sharpens, keep expanding while
+// the edge fades, then rest. That rest is nearly half the period and it is what
+// makes the ring read as a heartbeat instead of a strobe.
 //
 // Radii come out as multiples of the ring's start radius rather than pixels,
 // because the tip dot scales with the line width and the ring has to scale with