react-native-vroom-chart 0.6.0 → 0.7.0

package/cpp/VroomChartHostObject.cpp

@@ -54,6 +54,8 @@ std::vector<jsi::PropNameID> ChartHostObject::getPropertyNames(
   out.push_back(jsi::PropNameID::forAscii(rt, "setOverlays"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setVWAP"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setBollinger"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setVolume"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setVolumeCollapse"));
   out.push_back(jsi::PropNameID::forAscii(rt, "coordAt"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setPriceLines"));
   out.push_back(jsi::PropNameID::forAscii(rt, "hitTestPriceLine"));
@@ -519,46 +521,106 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
   }
 
   if (name == "setRSI") {
-    // setRSI(enabled, period, upperBand, lowerBand, maEnabled, maPeriod) —
-    // configures the RSI pane. No render; the next render() picks it up.
+    // setRSI({enabled, period, upperBand, lowerBand, maPeriod, maKind,
+    // maVisible, lineColor, lineWidth, lineVisible, maColor, maWidth,
+    // bandColor, bandsVisible}) — configures the RSI pane. No render; the next
+    // render() picks it up.
     return jsi::Function::createFromHostFunction(
         rt,
         jsi::PropNameID::forAscii(rt, "setRSI"),
-        6,
-        [this](jsi::Runtime& /*rt2*/,
+        1,
+        [this](jsi::Runtime& rt2,
                const jsi::Value& /*thisVal*/,
                const jsi::Value* args,
                size_t count) -> jsi::Value {
-          if (count < 6) return jsi::Value::undefined();
-          const bool enabled = args[0].asBool();
-          const int period = static_cast<int>(args[1].asNumber());
-          const double upper = args[2].asNumber();
-          const double lower = args[3].asNumber();
-          const bool ma_enabled = args[4].asBool();
-          const int ma_period = static_cast<int>(args[5].asNumber());
-          vroom_chart_set_rsi(chart_, enabled, period, upper, lower, ma_enabled,
-                              ma_period);
+          if (count < 1 || !args[0].isObject()) return jsi::Value::undefined();
+          auto s = args[0].asObject(rt2);
+          VroomRSI cfg{};
+          cfg.enabled = s.getProperty(rt2, "enabled").asBool() ? 1 : 0;
+          cfg.period = static_cast<int32_t>(
+              s.getProperty(rt2, "period").asNumber());
+          cfg.upper_band = s.getProperty(rt2, "upperBand").asNumber();
+          cfg.lower_band = s.getProperty(rt2, "lowerBand").asNumber();
+          cfg.ma_period = static_cast<int32_t>(
+              s.getProperty(rt2, "maPeriod").asNumber());
+          cfg.ma_kind = static_cast<int32_t>(
+              s.getProperty(rt2, "maKind").asNumber());
+          cfg.ma_visible = s.getProperty(rt2, "maVisible").asBool() ? 1 : 0;
+          cfg.line_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "lineColor").asNumber());
+          cfg.line_width = static_cast<float>(
+              s.getProperty(rt2, "lineWidth").asNumber());
+          cfg.line_visible = s.getProperty(rt2, "lineVisible").asBool() ? 1 : 0;
+          cfg.ma_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "maColor").asNumber());
+          cfg.ma_width = static_cast<float>(
+              s.getProperty(rt2, "maWidth").asNumber());
+          cfg.band_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "bandColor").asNumber());
+          cfg.bands_visible =
+              s.getProperty(rt2, "bandsVisible").asBool() ? 1 : 0;
+          vroom_chart_set_rsi(chart_, &cfg);
           return jsi::Value::undefined();
         });
   }
 
   if (name == "setMACD") {
-    // setMACD(enabled, fast, slow, signal) — configures the MACD pane. No
-    // render; the next render() picks it up.
+    // setMACD({enabled, fast, slow, signal, source, maKind, signalMaKind,
+    // lineColor, lineWidth, lineVisible, signalColor, signalWidth,
+    // signalVisible, histVisible, histUpColor, histUpFadingColor,
+    // histDownColor, histDownFadingColor, zeroColor, zeroVisible}) — configures
+    // the MACD pane. No render; the next render() picks it up.
     return jsi::Function::createFromHostFunction(
         rt,
         jsi::PropNameID::forAscii(rt, "setMACD"),
-        4,
-        [this](jsi::Runtime& /*rt2*/,
+        1,
+        [this](jsi::Runtime& rt2,
                const jsi::Value& /*thisVal*/,
                const jsi::Value* args,
                size_t count) -> jsi::Value {
-          if (count < 4) return jsi::Value::undefined();
-          const bool enabled = args[0].asBool();
-          const int fast = static_cast<int>(args[1].asNumber());
-          const int slow = static_cast<int>(args[2].asNumber());
-          const int signal = static_cast<int>(args[3].asNumber());
-          vroom_chart_set_macd(chart_, enabled, fast, slow, signal);
+          if (count < 1 || !args[0].isObject()) return jsi::Value::undefined();
+          auto s = args[0].asObject(rt2);
+          VroomMACD cfg{};
+          cfg.enabled = s.getProperty(rt2, "enabled").asBool() ? 1 : 0;
+          cfg.fast = static_cast<int32_t>(
+              s.getProperty(rt2, "fast").asNumber());
+          cfg.slow = static_cast<int32_t>(
+              s.getProperty(rt2, "slow").asNumber());
+          cfg.signal = static_cast<int32_t>(
+              s.getProperty(rt2, "signal").asNumber());
+          cfg.source = static_cast<int32_t>(
+              s.getProperty(rt2, "source").asNumber());
+          cfg.ma_kind = static_cast<int32_t>(
+              s.getProperty(rt2, "maKind").asNumber());
+          cfg.signal_ma_kind = static_cast<int32_t>(
+              s.getProperty(rt2, "signalMaKind").asNumber());
+          cfg.line_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "lineColor").asNumber());
+          cfg.line_width = static_cast<float>(
+              s.getProperty(rt2, "lineWidth").asNumber());
+          cfg.line_visible =
+              s.getProperty(rt2, "lineVisible").asBool() ? 1 : 0;
+          cfg.signal_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "signalColor").asNumber());
+          cfg.signal_width = static_cast<float>(
+              s.getProperty(rt2, "signalWidth").asNumber());
+          cfg.signal_visible =
+              s.getProperty(rt2, "signalVisible").asBool() ? 1 : 0;
+          cfg.hist_visible =
+              s.getProperty(rt2, "histVisible").asBool() ? 1 : 0;
+          cfg.hist_up_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "histUpColor").asNumber());
+          cfg.hist_up_fading_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "histUpFadingColor").asNumber());
+          cfg.hist_down_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "histDownColor").asNumber());
+          cfg.hist_down_fading_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "histDownFadingColor").asNumber());
+          cfg.zero_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "zeroColor").asNumber());
+          cfg.zero_visible =
+              s.getProperty(rt2, "zeroVisible").asBool() ? 1 : 0;
+          vroom_chart_set_macd(chart_, &cfg);
           return jsi::Value::undefined();
         });
   }
@@ -602,21 +664,26 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
   }
 
   if (name == "setVWAP") {
-    // setVWAP(enabled, resetOffsetMin, color, width) — session VWAP overlay.
+    // setVWAP({enabled, resetOffsetMin, color, width}) — session VWAP overlay.
     return jsi::Function::createFromHostFunction(
         rt,
         jsi::PropNameID::forAscii(rt, "setVWAP"),
-        4,
-        [this](jsi::Runtime& /*rt2*/,
+        1,
+        [this](jsi::Runtime& rt2,
                const jsi::Value& /*thisVal*/,
                const jsi::Value* args,
                size_t count) -> jsi::Value {
-          if (count < 4) return jsi::Value::undefined();
-          const bool enabled = args[0].asBool();
-          const int reset = static_cast<int>(args[1].asNumber());
-          const uint32_t color = static_cast<uint32_t>(args[2].asNumber());
-          const float width = static_cast<float>(args[3].asNumber());
-          vroom_chart_set_vwap(chart_, enabled, reset, color, width);
+          if (count < 1 || !args[0].isObject()) return jsi::Value::undefined();
+          auto s = args[0].asObject(rt2);
+          VroomVWAP cfg{};
+          cfg.enabled = s.getProperty(rt2, "enabled").asBool() ? 1 : 0;
+          cfg.reset_offset_min = static_cast<int32_t>(
+              s.getProperty(rt2, "resetOffsetMin").asNumber());
+          cfg.color = static_cast<uint32_t>(
+              s.getProperty(rt2, "color").asNumber());
+          cfg.width = static_cast<float>(
+              s.getProperty(rt2, "width").asNumber());
+          vroom_chart_set_vwap(chart_, &cfg);
           return jsi::Value::undefined();
         });
   }
@@ -667,6 +734,57 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
         });
   }
 
+  if (name == "setVolume") {
+    // setVolume({enabled, heightFrac, opacity, radiusPx, upColor, downColor})
+    // — the volume bars. Negative floats / zero colors inherit the theme. No
+    // render; the next render() picks it up.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setVolume"),
+        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 s = args[0].asObject(rt2);
+          VroomVolume cfg{};
+          cfg.enabled = s.getProperty(rt2, "enabled").asBool() ? 1 : 0;
+          cfg.height_frac = static_cast<float>(
+              s.getProperty(rt2, "heightFrac").asNumber());
+          cfg.opacity = static_cast<float>(
+              s.getProperty(rt2, "opacity").asNumber());
+          cfg.radius_px = static_cast<float>(
+              s.getProperty(rt2, "radiusPx").asNumber());
+          cfg.up_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "upColor").asNumber());
+          cfg.down_color = static_cast<uint32_t>(
+              s.getProperty(rt2, "downColor").asNumber());
+          vroom_chart_set_volume(chart_, &cfg);
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "setVolumeCollapse") {
+    // setVolumeCollapse(t, easing) — staggered collapse of the volume bars. `t`
+    // is LINEAR progress; the core eases each bar over its own window.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setVolumeCollapse"),
+        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_volume_collapse(
+              chart_,
+              static_cast<float>(args[0].asNumber()),
+              static_cast<int32_t>(args[1].asNumber()));
+          return jsi::Value::undefined();
+        });
+  }
+
   if (name == "coordAt") {
     // coordAt(x, y) -> { timeMs, price } | null. The continuous data coordinate
     // at a pixel — not snapped to a candle slot. Null when there are no candles

package/cpp/_core_include/vroom/vroom_chart.h

@@ -51,7 +51,7 @@ typedef struct VroomOverlay {
 
 // Bollinger Bands overlay drawn on the price pane: a basis MA of `source` over
 // `period`, banded at ± `mult` × population standard deviation of the same
-// window. Per TradingView semantics the stdev always uses the window's
+// window. Per the standard semantics the stdev always uses the window's
 // arithmetic mean, even when `basis_kind` selects an EMA basis line.
 typedef struct VroomBollinger {
     int32_t  enabled;       // 0/1
@@ -69,6 +69,97 @@ typedef struct VroomBollinger {
     float    fill_opacity;  // 0..1, multiplied into upper_color's alpha
 } VroomBollinger;
 
+// MACD, drawn in its own pane below the candles: the difference between a fast
+// and a slow moving average of `source`, a signal line smoothing that
+// difference, and a histogram of the gap between the two.
+//
+// The style fields carry an inherit sentinel so an untouched config renders the
+// stock look: a fully transparent color falls back to the theme (histogram) or
+// to the built-in default (lines), and a non-positive width falls back to 1.5.
+// The two `fading` histogram colors — used when a bar moves back toward zero,
+// i.e. momentum is easing — fall back to their base color at half alpha.
+typedef struct VroomMACD {
+    int32_t  enabled;         // 0/1
+    int32_t  fast;            // fast MA length (clamped >= 1; default 12)
+    int32_t  slow;            // slow MA length (forced > fast; default 26)
+    int32_t  signal;          // signal MA length (clamped >= 1; default 9)
+    int32_t  source;          // 0=close,1=open,2=high,3=low,4=hl2,5=hlc3,6=ohlc4
+    int32_t  ma_kind;         // fast/slow legs: 0 = SMA, 1 = EMA
+    int32_t  signal_ma_kind;  // signal line: 0 = SMA, 1 = EMA
+
+    uint32_t line_color;    // MACD line; 0xAARRGGBB, 0 inherits the default blue
+    float    line_width;    // stroke px; <= 0 inherits 1.5
+    int32_t  line_visible;  // 0/1
+    uint32_t signal_color;  // 0 inherits the default orange
+    float    signal_width;
+    int32_t  signal_visible;
+
+    int32_t  hist_visible;
+    uint32_t hist_up_color;           // 0 inherits VROOM_COLOR_ACCENT_BULL
+    uint32_t hist_up_fading_color;    // 0 inherits hist_up_color at half alpha
+    uint32_t hist_down_color;         // 0 inherits VROOM_COLOR_ACCENT_BEAR
+    uint32_t hist_down_fading_color;  // 0 inherits hist_down_color at half alpha
+
+    uint32_t zero_color;    // 0 inherits the default gray
+    int32_t  zero_visible;  // 0/1
+} VroomMACD;
+
+// RSI, drawn in its own pane below the candles: the index line, an optional
+// moving-average trendline over it, and two dashed rules at the overbought and
+// oversold levels. Close-only by design (Wilder's definition), so unlike the
+// other averaged indicators it takes no `source`.
+//
+// The style fields carry the same inherit sentinel as VroomMACD: a fully
+// transparent color falls back to the built-in default and a non-positive width
+// falls back to 1.5.
+typedef struct VroomRSI {
+    int32_t  enabled;     // 0/1
+    int32_t  period;      // lookback in candles (clamped >= 2; default 14)
+    double   upper_band;  // overbought level (0..100; default 70)
+    double   lower_band;  // oversold level (0..100; default 30)
+    int32_t  ma_period;   // trendline length (clamped >= 1; default 14)
+    int32_t  ma_kind;     // trendline: 0 = SMA, 1 = EMA
+    int32_t  ma_visible;  // 0/1
+
+    uint32_t line_color;    // 0 inherits the default violet
+    float    line_width;    // stroke px; <= 0 inherits 1.5
+    int32_t  line_visible;  // 0/1
+    uint32_t ma_color;      // 0 inherits the default amber
+    float    ma_width;
+    uint32_t band_color;     // both dashed rules; 0 inherits the default gray
+    int32_t  bands_visible;  // 0/1
+} VroomRSI;
+
+// Session VWAP, drawn as a single line on the price pane. The session resets
+// each UTC day shifted by `reset_offset_min` minutes, and the line lifts its pen
+// at each reset. Color 0 inherits the default cyan; a non-positive width
+// inherits 1.5.
+typedef struct VroomVWAP {
+    int32_t  enabled;           // 0/1
+    int32_t  reset_offset_min;  // session boundary offset from UTC midnight
+    uint32_t color;             // 0xAARRGGBB; 0 inherits the default
+    float    width;             // stroke px; <= 0 inherits 1.5
+} VroomVWAP;
+
+// Volume bars on the price pane, one per candle, drawn under the candles.
+//
+// `height_frac` is a ceiling, not a reservation: raising it lets the tallest bar
+// reach further up over the candles rather than compressing them (matching the
+// conventional volume overlay). Bar heights always auto-fit the loudest volume
+// in view, so the tallest bar sits exactly at the ceiling.
+//
+// The style fields carry an inherit sentinel so the theme keeps supplying them
+// when the consumer doesn't: a negative float or a fully transparent color falls
+// back to the corresponding theme key.
+typedef struct VroomVolume {
+    int32_t  enabled;      // 0/1 — default 1: bars draw unless turned off
+    float    height_frac;  // tallest bar as a fraction of the price pane; < 0 inherits 0.2
+    float    opacity;      // 0..1 (1 = opaque); < 0 inherits VROOM_FLOAT_VOLUME_OPACITY
+    float    radius_px;    // top-corner radius; < 0 inherits VROOM_FLOAT_VOLUME_RADIUS_PX
+    uint32_t up_color;     // 0xAARRGGBB; 0 inherits VROOM_COLOR_ACCENT_BULL
+    uint32_t down_color;   // 0xAARRGGBB; 0 inherits VROOM_COLOR_ACCENT_BEAR
+} VroomVolume;
+
 // A drawing anchor in data space (so a drawing tracks the candles on pan/zoom).
 typedef struct VroomDrawPoint {
     int64_t time_ms;  // epoch milliseconds (not snapped to a candle slot)
@@ -199,9 +290,25 @@ typedef enum {
     VROOM_FLOAT_WICK_ROUND_CAP,          // 0/1: round the wick end caps
     VROOM_FLOAT_VOLUME_RADIUS_PX,        // volume bar top-corner radius px (0 = square)
     VROOM_FLOAT_LINE_WIDTH_PX,           // line-chart-mode polyline stroke width px
+    VROOM_FLOAT_LINE_GRADIENT_OPACITY,   // fill under the line at its strongest (0 disables)
     VROOM_FLOAT_COUNT_
 } VroomFloatKey;
 
+// ---- Animation ------------------------------------------------------------
+
+// Easing curves for the animations the core paces itself. Mirrors the
+// TransitionEasing union in @vroomchart/types, index for index.
+//
+// Most animations are eased by the host before it hands the core a progress
+// value; this enum exists for the ones the core has to ease internally because
+// each element runs on its own slice of the timeline.
+typedef enum {
+    VROOM_EASING_LINEAR = 0,
+    VROOM_EASING_IN,
+    VROOM_EASING_OUT,
+    VROOM_EASING_IN_OUT,  // smoothstep; the default for unknown values
+} VroomEasing;
+
 // ---- Callbacks ------------------------------------------------------------
 
 typedef struct {
@@ -263,6 +370,45 @@ void vroom_chart_reset_view(VroomChart* chart);
 // switch) so the price scale re-fits the newly visible candles.
 void vroom_chart_reset_price_scale(VroomChart* chart);
 
+// Reads the visible price *envelope* — the min low / max high across the
+// currently visible candles. This is the extent the candles actually occupy, not
+// the axis range (which is wider: see vroom_chart_preserve_price_envelope).
+// Returns false (out params untouched) when no candles are visible. Either out
+// pointer may be null.
+bool vroom_chart_get_visible_price_envelope(VroomChart* chart,
+                                            double* out_low, double* out_high);
+
+// "Scale lock" for a same-asset data swap that re-buckets the same price action
+// into a different high-low span (a timeframe switch). Rescales a *manual* price
+// range so the visible envelope keeps the exact pixel height and position that
+// the [prev_low, prev_high] envelope had before the swap — so candles don't
+// suddenly shrink or grow when the interval changes.
+//
+// Call after set_candles + set_visible_range, passing the envelope read by
+// vroom_chart_get_visible_price_envelope *before* the swap.
+//
+// No-op in auto mode: auto-fit already widens the envelope by a fixed factor, so
+// its pixel height is invariant. Falls back to reset_price_scale semantics when
+// either envelope is degenerate.
+void vroom_chart_preserve_price_envelope(VroomChart* chart,
+                                         double prev_low, double prev_high);
+
+// Captures the currently visible candle geometry so the next data swap can be
+// animated as a reshape rather than a jump: each candle's wick and body slide
+// and stretch into the shape of its counterpart in the new data.
+//
+// Candles are paired by *slot* — position counting back from the right edge of
+// the visible window, which a timeframe switch preserves. Call before
+// set_candles, then drive vroom_chart_set_interval_morph from 0 to 1.
+// No-op when nothing is visible.
+void vroom_chart_begin_interval_morph(VroomChart* chart);
+
+// Advances the interval morph started by vroom_chart_begin_interval_morph. `t`
+// (clamped to 0..1) is the eased progress: 0 renders the captured geometry
+// pixel-identically to the pre-swap frame, 1 renders the new candles and
+// releases the capture. Driven per-frame by the host animation loop.
+void vroom_chart_set_interval_morph(VroomChart* chart, float t);
+
 void vroom_chart_pan(VroomChart* chart, float dx_px, float dy_px);
 // Directional zoom. scale_x scales the time window around focus_x_px (>1 =
 // narrower window, wider candles); scale_y scales the price range around
@@ -351,39 +497,51 @@ bool vroom_chart_get_crosshair_info(VroomChart* chart, VroomCrosshairInfo* out);
 
 // ---- Indicators -----------------------------------------------------------
 
-// Configures the RSI indicator (rendered in a pane below the candles). `period`
-// is the RSI lookback in candle counts (clamped >= 2). `upper_band`/`lower_band`
-// are the overbought/oversold reference levels (0..100; default 70/30).
-// `ma_enabled` toggles the RSI-based moving-average trendline and `ma_period`
-// is its length (clamped >= 1). When enabled, the candle pane shrinks by
-// VROOM_FLOAT_INDICATOR_HEIGHT_FRAC.
-void vroom_chart_set_rsi(VroomChart* chart, bool enabled, int period,
-                         double upper_band, double lower_band,
-                         bool ma_enabled, int ma_period);
-
-// Configures the MACD indicator (its own pane below the candles). `fast`/`slow`
-// are the EMA lengths (clamped >= 1, slow forced > fast; default 12/26) and
-// `signal` is the signal-line EMA length (clamped >= 1; default 9). Panes stack
-// in enable order, most recently enabled at the bottom.
-void vroom_chart_set_macd(VroomChart* chart, bool enabled, int fast, int slow,
-                          int signal);
+// Configures the RSI indicator (rendered in a pane below the candles). When
+// enabled, the candle pane shrinks by VROOM_FLOAT_INDICATOR_HEIGHT_FRAC. Length
+// and MA-kind changes recompute the series; band levels, colors, widths, and
+// visibility changes only re-render.
+void vroom_chart_set_rsi(VroomChart* chart, const VroomRSI* cfg);
+
+// Configures the MACD indicator (its own pane below the candles). Panes stack
+// in enable order, most recently enabled at the bottom. Length, source, and MA
+// kind changes recompute the series; color, width, and visibility changes only
+// re-render.
+void vroom_chart_set_macd(VroomChart* chart, const VroomMACD* cfg);
 
 // Replaces the full set of moving-average overlay lines (SMA/EMA) drawn on the
 // price pane. Pass count 0 to clear them. Overlays don't reserve a pane.
 void vroom_chart_set_overlays(VroomChart* chart, const VroomOverlay* overlays,
                               size_t count);
 
-// Configures the session VWAP overlay (a single price-pane line). The session
-// resets each UTC day shifted by `reset_offset_min` minutes (the configurable
-// reset time). `color` is 0xAARRGGBB; `width` is the stroke px.
-void vroom_chart_set_vwap(VroomChart* chart, bool enabled, int reset_offset_min,
-                          uint32_t color, float width);
+// Configures the session VWAP overlay (a single price-pane line). Enabled and
+// reset-time changes recompute the series; color and width changes only
+// re-render.
+void vroom_chart_set_vwap(VroomChart* chart, const VroomVWAP* cfg);
 
 // Configures the Bollinger Bands overlay (three price-pane lines + an optional
 // translucent fill between the bands; no pane is reserved). Color/width/fill
 // changes only re-render; enabled/period/mult/source/basis changes recompute.
 void vroom_chart_set_bollinger(VroomChart* chart, const VroomBollinger* cfg);
 
+// Configures the volume bars. Render-only — the bars come straight off each
+// candle's volume, so nothing is recomputed. Bars are enabled by default; pass
+// a config with `enabled` 0 to hide them.
+void vroom_chart_set_volume(VroomChart* chart, const VroomVolume* cfg);
+
+// Advances the staggered volume-bar collapse: 0 leaves every bar at full height,
+// 1 has them all flat. Driven per-frame by the host animation loop.
+//
+// `t` is *linear* progress, unlike the other morph setters. Each bar falls over
+// its own slice of the timeline — the tallest starting first and every bar
+// landing at 1 — so `easing` (a VroomEasing) is applied per bar inside the core;
+// pre-easing here would compound the two curves.
+//
+// Symmetric, so driving 1 -> 0 reveals the bars: the shortest rises first and
+// the tallest arrives last. vroom_chart_set_volume snaps this to match its
+// `enabled`, so the host only needs it while animating.
+void vroom_chart_set_volume_collapse(VroomChart* chart, float t, int32_t easing);
+
 // ---- Drawings (line annotations) ------------------------------------------
 
 // Replaces the full set of committed line drawings (data-anchored, so they track

package/cpp/_core_src/bollinger.h

@@ -19,7 +19,7 @@ namespace vroom::bollinger {
 //                 period window
 //
 // The stdev always uses the window's arithmetic mean, even when basis_kind
-// selects an EMA basis line (TradingView semantics).
+// selects an EMA basis line (the standard semantics).
 //
 // Each output is resized to n; values are NaN for i < period-1 and when
 // n < period.