react-native-vroom-chart 0.14.0 → 0.15.0

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

package/lib/index.d.mts

@@ -651,6 +651,123 @@ type PriceLinesStyle = {
      */
     hoverBoost?: number;
 };
+/** Which side of a position a footprint marks. */
+type FootprintSide = 'buy' | 'sell';
+/**
+ * A single filled trade, drawn as a circular badge above the candle it fell in —
+ * the "footprint" a trader leaves on the chart: `buy` marks an entry (a `+`
+ * badge in the bull color), `sell` marks an exit (a `−` badge in the bear color).
+ *
+ * `timeMs` is the raw execution time, *not* a bar-open time. The chart buckets
+ * each footprint into whichever candle's window contains it, so the same array
+ * renders correctly at every interval — switch from 1m to 1h and the badges
+ * re-group onto the wider bars on their own.
+ *
+ * At most two badges render per candle: one for that bar's buys and one for its
+ * sells, however many trades went into each. Hovering (or tapping) a badge hands
+ * every footprint on that candle back through `onFootprint`, so a bar holding
+ * twenty fills still shows one badge and still reports all twenty.
+ */
+type Footprint = {
+    /** Stable unique id, echoed back in `onFootprint`. */
+    id: string;
+    /** Execution time as Unix epoch milliseconds, unsnapped. */
+    timeMs: number;
+    /** Entry (`'buy'`) or exit (`'sell'`) — picks the badge color and glyph. */
+    side: FootprintSide;
+    /**
+     * Execution price. Ignored by the renderer (badges sit above the bar, not at
+     * the fill), and carried through to `onFootprint` for your own UI.
+     */
+    price?: number;
+};
+/** Shared layout/style for every footprint badge, passed via `footprintsStyle`. */
+type FootprintsStyle = {
+    /** Badge radius in px. Default 9. */
+    radius?: number;
+    /**
+     * Vertical gap between the two stacked badges on a candle that has both a buy
+     * and a sell. Default 4 — wide enough that each stays independently hoverable.
+     */
+    gap?: number;
+    /** Gap between the candle's high and the first badge, in px. Default 8. */
+    margin?: number;
+    /**
+     * How much the hovered badge brightens, as a channel multiplier. 1 disables
+     * the highlight (the halo ring still draws). Default 1.25.
+     */
+    hoverBoost?: number;
+};
+/**
+ * The chart's plot area in logical px relative to the chart element's top-left:
+ * the candles and everything drawn over them, with the price and time axis
+ * strips excluded.
+ *
+ * This is the rect to test a floating UI against, and it is deliberately *not*
+ * the element's own box — the element includes the axis strips, so measuring it
+ * overstates the room beside anything near an edge.
+ */
+type PlotRect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * Fired when the pointer enters, moves between, or leaves footprint badges (on
+ * touch platforms, when one is tapped or dismissed).
+ *
+ * The chart draws no tooltip of its own — this event is the hook for yours.
+ * Position your UI off `badge` and `pane`, both in the same coordinate space as
+ * the chart element, and fill it from `footprints`.
+ *
+ * Panning or zooming fires a `'hide'`, since the bar the badge belongs to has
+ * moved: you don't need your own gesture listener to take the tooltip down.
+ */
+type FootprintEvent = {
+    /** True while a badge is hovered/tapped; false when it's dismissed. */
+    active: boolean;
+    /**
+     * Why this event fired:
+     *   'show' — a badge became hovered/tapped from nothing
+     *   'move' — the pointer moved to a *different* badge without leaving in between
+     *   'hide' — the badge was dismissed: the pointer left (or a tap missed), the
+     *            chart was panned or zoomed out from under it, or the crosshair
+     *            took the pane over
+     */
+    reason: 'show' | 'move' | 'hide';
+    /** Which badge — its buys or its sells. Null when inactive. */
+    side: FootprintSide | null;
+    /** Bar-open time (epoch ms) of the candle the badge sits on. Null when inactive. */
+    timeMs: number | null;
+    /**
+     * Every footprint bucketed into that candle, *both* sides, ascending by
+     * `timeMs`. Empty when inactive. Filter on `side` to show only the hovered
+     * badge's trades, or render the whole bar's activity at once.
+     */
+    footprints: Footprint[];
+    /**
+     * The badge's center and radius in logical px relative to the chart element's
+     * top-left — anchor your tooltip to it. Null when inactive.
+     */
+    badge: {
+        x: number;
+        y: number;
+        radius: number;
+    } | null;
+    /**
+     * The plot area the badge sits in, for choosing which side of it your tooltip
+     * fits on. Null when inactive (there is nothing to place).
+     *
+     * Only you know how big your tooltip is, so the chart reports the rect rather
+     * than picking a side:
+     *
+     * ```ts
+     * const fitsRight = badge.x + badge.radius + 8 + width <= pane.right;
+     * ```
+     */
+    pane: PlotRect | null;
+};
 /**
  * MACD indicator config. Rendered in its own pane below the candles: the gap
  * between a fast and a slow moving average, a signal line smoothing that gap,
@@ -797,6 +914,23 @@ type VroomChartCoreProps = {
     priceLines?: PriceLine[];
     /** Shared layout/style for every entry in `priceLines`. */
     priceLinesStyle?: PriceLinesStyle;
+    /**
+     * Executed trades to mark on the chart as circular badges above the bar they
+     * fell in — where a position was entered and exited.
+     *
+     * Pass raw fills with their real execution times; the chart groups them onto
+     * candles itself and re-groups on interval changes, so one array serves every
+     * timeframe. Order doesn't matter.
+     */
+    footprints?: Footprint[];
+    /** Shared layout/style for every entry in `footprints`. */
+    footprintsStyle?: FootprintsStyle;
+    /**
+     * Fired when a footprint badge is hovered (tapped on touch platforms) or
+     * dismissed. The chart renders no tooltip itself — use this to place your own,
+     * anchored to `e.badge`, kept inside `e.pane`, and filled from `e.footprints`.
+     */
+    onFootprint?: (e: FootprintEvent) => void;
     /**
      * Fired continuously while a draggable price line is being dragged, with the
      * price under the pointer. Use it for a live readout (e.g. an order ticket);
@@ -991,4 +1125,4 @@ declare function classifyTransition(prev: Candle[] | null, next: Candle[], serie
  */
 declare function timeframeWindow(oldWindow: VisibleRange, oldStepMs: number, oldLastMs: number, newStepMs: number, newLastMs: number): VisibleRange;
 
-export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type DataTransition, type DefaultDrawingStyle, type IntervalTransition, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, inferStepMs, timeframeWindow };
+export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type DataTransition, type DefaultDrawingStyle, type Footprint, type FootprintEvent, type FootprintSide, type FootprintsStyle, type IntervalTransition, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PlotRect, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, inferStepMs, timeframeWindow };

package/lib/index.d.ts

@@ -651,6 +651,123 @@ type PriceLinesStyle = {
      */
     hoverBoost?: number;
 };
+/** Which side of a position a footprint marks. */
+type FootprintSide = 'buy' | 'sell';
+/**
+ * A single filled trade, drawn as a circular badge above the candle it fell in —
+ * the "footprint" a trader leaves on the chart: `buy` marks an entry (a `+`
+ * badge in the bull color), `sell` marks an exit (a `−` badge in the bear color).
+ *
+ * `timeMs` is the raw execution time, *not* a bar-open time. The chart buckets
+ * each footprint into whichever candle's window contains it, so the same array
+ * renders correctly at every interval — switch from 1m to 1h and the badges
+ * re-group onto the wider bars on their own.
+ *
+ * At most two badges render per candle: one for that bar's buys and one for its
+ * sells, however many trades went into each. Hovering (or tapping) a badge hands
+ * every footprint on that candle back through `onFootprint`, so a bar holding
+ * twenty fills still shows one badge and still reports all twenty.
+ */
+type Footprint = {
+    /** Stable unique id, echoed back in `onFootprint`. */
+    id: string;
+    /** Execution time as Unix epoch milliseconds, unsnapped. */
+    timeMs: number;
+    /** Entry (`'buy'`) or exit (`'sell'`) — picks the badge color and glyph. */
+    side: FootprintSide;
+    /**
+     * Execution price. Ignored by the renderer (badges sit above the bar, not at
+     * the fill), and carried through to `onFootprint` for your own UI.
+     */
+    price?: number;
+};
+/** Shared layout/style for every footprint badge, passed via `footprintsStyle`. */
+type FootprintsStyle = {
+    /** Badge radius in px. Default 9. */
+    radius?: number;
+    /**
+     * Vertical gap between the two stacked badges on a candle that has both a buy
+     * and a sell. Default 4 — wide enough that each stays independently hoverable.
+     */
+    gap?: number;
+    /** Gap between the candle's high and the first badge, in px. Default 8. */
+    margin?: number;
+    /**
+     * How much the hovered badge brightens, as a channel multiplier. 1 disables
+     * the highlight (the halo ring still draws). Default 1.25.
+     */
+    hoverBoost?: number;
+};
+/**
+ * The chart's plot area in logical px relative to the chart element's top-left:
+ * the candles and everything drawn over them, with the price and time axis
+ * strips excluded.
+ *
+ * This is the rect to test a floating UI against, and it is deliberately *not*
+ * the element's own box — the element includes the axis strips, so measuring it
+ * overstates the room beside anything near an edge.
+ */
+type PlotRect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * Fired when the pointer enters, moves between, or leaves footprint badges (on
+ * touch platforms, when one is tapped or dismissed).
+ *
+ * The chart draws no tooltip of its own — this event is the hook for yours.
+ * Position your UI off `badge` and `pane`, both in the same coordinate space as
+ * the chart element, and fill it from `footprints`.
+ *
+ * Panning or zooming fires a `'hide'`, since the bar the badge belongs to has
+ * moved: you don't need your own gesture listener to take the tooltip down.
+ */
+type FootprintEvent = {
+    /** True while a badge is hovered/tapped; false when it's dismissed. */
+    active: boolean;
+    /**
+     * Why this event fired:
+     *   'show' — a badge became hovered/tapped from nothing
+     *   'move' — the pointer moved to a *different* badge without leaving in between
+     *   'hide' — the badge was dismissed: the pointer left (or a tap missed), the
+     *            chart was panned or zoomed out from under it, or the crosshair
+     *            took the pane over
+     */
+    reason: 'show' | 'move' | 'hide';
+    /** Which badge — its buys or its sells. Null when inactive. */
+    side: FootprintSide | null;
+    /** Bar-open time (epoch ms) of the candle the badge sits on. Null when inactive. */
+    timeMs: number | null;
+    /**
+     * Every footprint bucketed into that candle, *both* sides, ascending by
+     * `timeMs`. Empty when inactive. Filter on `side` to show only the hovered
+     * badge's trades, or render the whole bar's activity at once.
+     */
+    footprints: Footprint[];
+    /**
+     * The badge's center and radius in logical px relative to the chart element's
+     * top-left — anchor your tooltip to it. Null when inactive.
+     */
+    badge: {
+        x: number;
+        y: number;
+        radius: number;
+    } | null;
+    /**
+     * The plot area the badge sits in, for choosing which side of it your tooltip
+     * fits on. Null when inactive (there is nothing to place).
+     *
+     * Only you know how big your tooltip is, so the chart reports the rect rather
+     * than picking a side:
+     *
+     * ```ts
+     * const fitsRight = badge.x + badge.radius + 8 + width <= pane.right;
+     * ```
+     */
+    pane: PlotRect | null;
+};
 /**
  * MACD indicator config. Rendered in its own pane below the candles: the gap
  * between a fast and a slow moving average, a signal line smoothing that gap,
@@ -797,6 +914,23 @@ type VroomChartCoreProps = {
     priceLines?: PriceLine[];
     /** Shared layout/style for every entry in `priceLines`. */
     priceLinesStyle?: PriceLinesStyle;
+    /**
+     * Executed trades to mark on the chart as circular badges above the bar they
+     * fell in — where a position was entered and exited.
+     *
+     * Pass raw fills with their real execution times; the chart groups them onto
+     * candles itself and re-groups on interval changes, so one array serves every
+     * timeframe. Order doesn't matter.
+     */
+    footprints?: Footprint[];
+    /** Shared layout/style for every entry in `footprints`. */
+    footprintsStyle?: FootprintsStyle;
+    /**
+     * Fired when a footprint badge is hovered (tapped on touch platforms) or
+     * dismissed. The chart renders no tooltip itself — use this to place your own,
+     * anchored to `e.badge`, kept inside `e.pane`, and filled from `e.footprints`.
+     */
+    onFootprint?: (e: FootprintEvent) => void;
     /**
      * Fired continuously while a draggable price line is being dragged, with the
      * price under the pointer. Use it for a live readout (e.g. an order ticket);
@@ -991,4 +1125,4 @@ declare function classifyTransition(prev: Candle[] | null, next: Candle[], serie
  */
 declare function timeframeWindow(oldWindow: VisibleRange, oldStepMs: number, oldLastMs: number, newStepMs: number, newLastMs: number): VisibleRange;
 
-export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type DataTransition, type DefaultDrawingStyle, type IntervalTransition, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, inferStepMs, timeframeWindow };
+export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type DataTransition, type DefaultDrawingStyle, type Footprint, type FootprintEvent, type FootprintSide, type FootprintsStyle, type IntervalTransition, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PlotRect, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, inferStepMs, timeframeWindow };