react-native-vroom-chart 0.14.0 → 0.15.0

package/cpp/VroomChartHostObject.cpp

@@ -42,7 +42,7 @@ ChartHostObject::~ChartHostObject() {
 std::vector<jsi::PropNameID> ChartHostObject::getPropertyNames(
     jsi::Runtime& rt) {
   std::vector<jsi::PropNameID> out;
-  out.reserve(39);
+  out.reserve(42);
   out.push_back(jsi::PropNameID::forAscii(rt, "setCandles"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setSize"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setColor"));
@@ -82,6 +82,9 @@ std::vector<jsi::PropNameID> ChartHostObject::getPropertyNames(
   out.push_back(jsi::PropNameID::forAscii(rt, "hitTestPriceLine"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setPriceLineHover"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setPriceLineDrag"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setFootprints"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "hitTestFootprint"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setFootprintHover"));
   out.push_back(jsi::PropNameID::forAscii(rt, "render"));
   return out;
 }
@@ -1189,6 +1192,120 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
         });
   }
 
+  if (name == "setFootprints") {
+    // setFootprints({ prints: [{ timeMs, side }, ...], radiusPx, gapPx, marginPx,
+    // hoverBoost }) — replaces the full set of executed-trade badges. The core
+    // buckets them onto candles itself, so raw fill times are what to pass. No
+    // render; the next render() picks it up.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setFootprints"),
+        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 cfg = args[0].asObject(rt2);
+          auto prints_val = cfg.getProperty(rt2, "prints");
+          if (!prints_val.isObject()) return jsi::Value::undefined();
+          auto prints_obj = prints_val.asObject(rt2);
+          if (!prints_obj.isArray(rt2)) return jsi::Value::undefined();
+          auto arr = prints_obj.asArray(rt2);
+          const size_t len = arr.size(rt2);
+          std::vector<VroomFootprint> prints(len);
+          for (size_t i = 0; i < len; ++i) {
+            auto f = arr.getValueAtIndex(rt2, i).asObject(rt2);
+            prints[i].time_ms =
+                static_cast<int64_t>(f.getProperty(rt2, "timeMs").asNumber());
+            prints[i].side =
+                static_cast<int32_t>(f.getProperty(rt2, "side").asNumber());
+          }
+          VroomFootprintStyle style{};
+          style.radius_px = static_cast<float>(
+              cfg.getProperty(rt2, "radiusPx").asNumber());
+          style.gap_px = static_cast<float>(
+              cfg.getProperty(rt2, "gapPx").asNumber());
+          style.margin_px = static_cast<float>(
+              cfg.getProperty(rt2, "marginPx").asNumber());
+          style.hover_boost = static_cast<float>(
+              cfg.getProperty(rt2, "hoverBoost").asNumber());
+          vroom_chart_set_footprints(chart_, prints.data(), prints.size(), &style);
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "hitTestFootprint") {
+    // hitTestFootprint(x, y) -> { side, candleTimeMs, x, y, radius, pane,
+    // indices } | null. `indices` addresses the array last passed to
+    // setFootprints and covers *both* sides of that candle, so one call fills a
+    // tooltip; `pane` is the plot rect, for deciding which side of the badge that
+    // tooltip fits on. No rendering.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "hitTestFootprint"),
+        2,
+        [this](jsi::Runtime& rt2,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 2) return jsi::Value::null();
+          VroomFootprintHit hit{};
+          if (!vroom_chart_hit_test_footprint(
+                  chart_, static_cast<float>(args[0].asNumber()),
+                  static_cast<float>(args[1].asNumber()), &hit)) {
+            return jsi::Value::null();
+          }
+
+          const int32_t n =
+              vroom_chart_footprints_at(chart_, hit.candle_time_ms, nullptr, 0);
+          std::vector<int32_t> idx(static_cast<size_t>(n > 0 ? n : 0));
+          if (n > 0) {
+            vroom_chart_footprints_at(chart_, hit.candle_time_ms, idx.data(), n);
+          }
+          jsi::Array indices(rt2, idx.size());
+          for (size_t i = 0; i < idx.size(); ++i) {
+            indices.setValueAtIndex(rt2, i, jsi::Value(idx[i]));
+          }
+
+          jsi::Object pane(rt2);
+          pane.setProperty(rt2, "left", hit.pane_left);
+          pane.setProperty(rt2, "top", hit.pane_top);
+          pane.setProperty(rt2, "right", hit.pane_right);
+          pane.setProperty(rt2, "bottom", hit.pane_bottom);
+
+          jsi::Object obj(rt2);
+          obj.setProperty(rt2, "side", hit.side);
+          obj.setProperty(rt2, "candleTimeMs",
+                          static_cast<double>(hit.candle_time_ms));
+          obj.setProperty(rt2, "x", hit.center_x);
+          obj.setProperty(rt2, "y", hit.center_y);
+          obj.setProperty(rt2, "radius", hit.radius);
+          obj.setProperty(rt2, "pane", std::move(pane));
+          obj.setProperty(rt2, "indices", std::move(indices));
+          return obj;
+        });
+  }
+
+  if (name == "setFootprintHover") {
+    // setFootprintHover(candleTimeMs, side) — highlight one badge; side -1
+    // clears. Touch has no hover, so on RN this tracks the tapped badge.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setFootprintHover"),
+        2,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 2) return jsi::Value::undefined();
+          vroom_chart_set_footprint_hover(
+              chart_, static_cast<int64_t>(args[0].asNumber()),
+              static_cast<int32_t>(args[1].asNumber()));
+          return jsi::Value::undefined();
+        });
+  }
+
   if (name == "render") {
     return jsi::Function::createFromHostFunction(
         rt,

package/cpp/_core_include/vroom/vroom_chart.h

@@ -257,6 +257,53 @@ typedef struct VroomPriceLineStyle {
     float    hover_boost;       // brightness multiplier for the hovered segment (1 = flat)
 } VroomPriceLineStyle;
 
+// ---- Footprints (executed-trade badges) -----------------------------------
+
+typedef enum {
+    VROOM_FOOTPRINT_BUY = 0,   // position entry — "+" badge in the bull color
+    VROOM_FOOTPRINT_SELL = 1,  // position exit  — "-" badge in the bear color
+} VroomFootprintSide;
+
+// A single executed trade, drawn as a circular badge above the candle it fell in.
+//
+// `time_ms` is the raw execution time, *not* a bar-open time: the core buckets
+// each footprint into whichever candle's window contains it, so one array renders
+// correctly at every interval and re-groups by itself when the candles change.
+// Order is irrelevant — the core sorts within each bucket.
+//
+// Only the fields the renderer needs live here; a host's per-trade payload (id,
+// price, size) stays on the host side and is rejoined via the indices reported by
+// vroom_chart_footprints_at.
+typedef struct VroomFootprint {
+    int64_t time_ms;
+    int32_t side;  // VroomFootprintSide
+} VroomFootprint;
+
+// Layout/style shared by every footprint badge.
+typedef struct VroomFootprintStyle {
+    float radius_px;   // badge radius; <= 0 falls back to 9
+    float gap_px;      // vertical gap between the two stacked badges; < 0 => 4
+    float margin_px;   // gap between the candle's high and the first badge; < 0 => 8
+    float hover_boost; // brightness multiplier for the hovered badge (1 = flat)
+} VroomFootprintStyle;
+
+// The badge under a pixel, as reported by vroom_chart_hit_test_footprint.
+typedef struct VroomFootprintHit {
+    int64_t candle_time_ms;  // bar-open time of the candle the badge sits on
+    int32_t side;            // VroomFootprintSide — which of the candle's two badges
+    float   center_x;        // badge center, in the same px space as the hit test
+    float   center_y;
+    float   radius;
+    // The plot rect the badge was clipped to — same px space, axis strips
+    // excluded. Reported because a host placing its own tooltip has no other way
+    // to know it: the surface it measures includes the price and time axes, so
+    // sizing against that overstates the room next to a badge near the edge.
+    float   pane_left;
+    float   pane_top;
+    float   pane_right;
+    float   pane_bottom;
+} VroomFootprintHit;
+
 // A continuous data coordinate at a pixel position (no candle snapping). Used to
 // translate a drawing-tool click into a data-space anchor.
 typedef struct VroomCoord {
@@ -689,6 +736,43 @@ void vroom_chart_set_price_line_hover(VroomChart* chart, int32_t index,
 void vroom_chart_set_price_line_drag(VroomChart* chart, int32_t index,
                                      double price);
 
+// Replaces the full set of footprints and their shared style. Pass count 0 to
+// clear; `style` may be null when count is 0.
+//
+// Footprints are grouped onto candles by timestamp, so at most two badges render
+// per candle: one for that bar's buys and one for its sells, however many trades
+// went into each. When a candle has both, they stack upward with `gap_px` between
+// them, the side whose latest trade came first sitting nearest the bar. Badges sit
+// above the candle's high, clipped to the price pane, and re-group on their own
+// whenever the candles change (a new interval, more history) — the host never
+// re-buckets anything.
+void vroom_chart_set_footprints(VroomChart* chart, const VroomFootprint* prints,
+                                size_t count,
+                                const VroomFootprintStyle* style);
+
+// Hit-tests pixel (x_px, y_px) against the footprint badges. On a hit fills *out
+// with the badge's candle, side and pixel geometry and returns true; returns false
+// on a miss (out untouched). `out` may be null to test without reading the hit.
+// When two badges overlap the nearest center wins.
+bool vroom_chart_hit_test_footprint(VroomChart* chart, float x_px, float y_px,
+                                    VroomFootprintHit* out);
+
+// Fills `out_indices` with the indices — into the array last passed to
+// vroom_chart_set_footprints — of every footprint bucketed into the candle opening
+// at `candle_time_ms`, *both* sides, ascending by time. Returns the total count,
+// which may exceed `max` (only the first `max` are written), or 0 when that candle
+// has no footprints. Pass a null `out_indices` with max 0 to size the buffer first.
+//
+// This is how a host rejoins a hit badge to its own trade objects: hit-test to get
+// the candle, then map these indices back through the array it supplied.
+int32_t vroom_chart_footprints_at(VroomChart* chart, int64_t candle_time_ms,
+                                  int32_t* out_indices, int32_t max);
+
+// Marks one footprint badge as hovered so it renders highlighted. `side` -1
+// clears the hover; `candle_time_ms` and `side` match vroom_chart_hit_test_footprint.
+void vroom_chart_set_footprint_hover(VroomChart* chart, int64_t candle_time_ms,
+                                     int32_t side);
+
 // Sets the transient in-progress "draft" the drawing tool shows while the user
 // places points. Node A is always shown; when `has_b`, node B is shown too.
 // `guide != 0` also draws the live preview (a guideline for a line, or a preview

package/cpp/_core_src/chart.cpp

@@ -25,6 +25,7 @@
 #include "chart_internal.h"
 #include "crosshair.h"
 #include "drawings.h"
+#include "footprints.h"
 #include "labels.h"
 #include "liquidity.h"
 #include "ma.h"
@@ -125,6 +126,14 @@ void VroomChart::ensure_bollinger() {
     bollinger_dirty = false;
 }
 
+void VroomChart::ensure_footprint_buckets() {
+    if (!footprint_buckets_dirty) return;
+    footprint_buckets = vroom::footprints::build_buckets(
+        candles.data(), candles.size(), candle_duration_ms, footprints.data(),
+        footprints.size());
+    footprint_buckets_dirty = false;
+}
+
 void VroomChart::draw_chart(SkCanvas* canvas) {
     begin_frame();
     const auto lay = layout();
@@ -480,6 +489,13 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
         //       stays readable.
         vroom::price_lines::draw(canvas, *this, lay, bounds, candle_right,
                                    candle_area_h);
+
+        // 7.56. Footprint badges — data-anchored chrome that must not be hidden
+        //       by candles or overlays, so it draws with the price lines rather
+        //       than back at the drawings layer. Below the crosshair, which the
+        //       user is actively pointing with.
+        ensure_footprint_buckets();
+        vroom::footprints::draw(canvas, *this, lay, bounds, window_ms);
     }
 
     // 7.6. Indicator panes stacked below the candles, ordered by enable

package/cpp/_core_src/chart.h

@@ -22,6 +22,7 @@
 #include "include/core/SkRefCnt.h"
 #pragma clang diagnostic pop
 
+#include "footprints_layout.h"
 #include "labels.h"
 #include "price_format.h"
 #include "theme.h"
@@ -280,6 +281,28 @@ struct VroomChart {
     int32_t dragged_price_line = -1;
     double  dragged_price_line_price = 0.0;
 
+    // --- footprints (executed-trade badges) ---------------------------------
+    // Kept in the *host's* order so the indices reported by
+    // vroom_chart_footprints_at map straight back to its own trade objects.
+    std::vector<VroomFootprint> footprints;
+    VroomFootprintStyle         footprint_style{};
+
+    // Footprints grouped onto candles, which is what the renderer and hit-test
+    // actually walk. Derived from `footprints` + `candles`, so it is rebuilt
+    // lazily (see ensure_footprint_buckets) whenever either changes — that
+    // rebuild is what re-groups badges onto the right bars after an interval
+    // switch, with no involvement from the host.
+    std::vector<vroom::footprints::Bucket> footprint_buckets;
+    bool                                   footprint_buckets_dirty = true;
+
+    // Which badge renders highlighted, keyed the way the hit-test reports it.
+    // side -1 = none.
+    int64_t hovered_footprint_time_ms = 0;
+    int32_t hovered_footprint_side = -1;
+
+    // Rebuilds footprint_buckets if either input changed since the last call.
+    void ensure_footprint_buckets();
+
     // --- theme --------------------------------------------------------------
     vroom::Theme theme;
 

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).
@@ -1023,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