react-native-vroom-chart 0.1.3 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darion Welch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/cpp/VroomChartHostObject.cpp

@@ -27,11 +27,13 @@ ChartHostObject::~ChartHostObject() {
 std::vector<jsi::PropNameID> ChartHostObject::getPropertyNames(
     jsi::Runtime& rt) {
   std::vector<jsi::PropNameID> out;
-  out.reserve(19);
+  out.reserve(22);
   out.push_back(jsi::PropNameID::forAscii(rt, "setCandles"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setSize"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setColor"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setFloat"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setVisibleRange"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setDefaultCandleWidth"));
   out.push_back(jsi::PropNameID::forAscii(rt, "pan"));
   out.push_back(jsi::PropNameID::forAscii(rt, "translate"));
   out.push_back(jsi::PropNameID::forAscii(rt, "zoom"));
@@ -130,6 +132,25 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
         });
   }
 
+  if (name == "setFloat") {
+    // setFloat(keyIndex, value) — keyIndex is a VroomFloatKey (e.g. wick width).
+    // The core bounds-checks the key and marks dirty.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setFloat"),
+        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();
+          const int key = static_cast<int>(args[0].asNumber());
+          vroom_chart_set_float(chart_, static_cast<VroomFloatKey>(key),
+                                static_cast<float>(args[1].asNumber()));
+          return jsi::Value::undefined();
+        });
+  }
+
   if (name == "setVisibleRange") {
     // Pass 0,0 to clear (show all).
     // Timestamps are Number on the JS side — fine for ms-since-epoch since
@@ -150,6 +171,23 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
         });
   }
 
+  if (name == "setDefaultCandleWidth") {
+    // setDefaultCandleWidth(px) — target candle body width for initial framing.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setDefaultCandleWidth"),
+        1,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 1) return jsi::Value::undefined();
+          vroom_chart_set_default_candle_width(
+              chart_, static_cast<float>(args[0].asNumber()));
+          return jsi::Value::undefined();
+        });
+  }
+
   if (name == "pan") {
     // pan(dx, dy) -> JsiSkPicture
     // Mutates the visible range and renders in one JSI call so gesture

package/cpp/_core_include/vroom/vroom_chart.h

@@ -63,6 +63,29 @@ typedef struct VroomDrawing {
     float          width;  // stroke width in px
 } VroomDrawing;
 
+// A resting-liquidity band: a price interval carrying a total order size on one
+// side of the book. Anchored in price space, so it scales with the y-axis.
+typedef struct VroomBand {
+    double  min_price;  // bottom of the interval
+    double  max_price;  // top of the interval
+    int32_t side;       // 0 = buy, 1 = sell (selects the color)
+    double  volume;     // total resting size; drives the band's opacity
+} VroomBand;
+
+// Style shared by all liquidity bands. `buy_color`/`sell_color` are 0xAARRGGBB;
+// the alpha is replaced per band by its volume mapped into
+// [min_opacity, max_opacity]. `max_volume <= 0` auto-scales to the largest band.
+// The leftward reach is min(width_px, width_frac * pane_width).
+typedef struct VroomLiquidityStyle {
+    uint32_t buy_color;
+    uint32_t sell_color;
+    double   max_volume;
+    float    min_opacity;
+    float    max_opacity;
+    float    width_px;
+    float    width_frac;
+} VroomLiquidityStyle;
+
 // 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 {
@@ -101,6 +124,9 @@ typedef enum {
     VROOM_FLOAT_X_AXIS_HEIGHT_PX,        // bottom strip reserved for time labels
     VROOM_FLOAT_VOLUME_OPACITY,          // volume bar opacity (1=opaque)
     VROOM_FLOAT_INDICATOR_HEIGHT_FRAC,   // below-chart indicator pane, fraction of height
+    VROOM_FLOAT_CANDLE_RADIUS_PX,        // candle body corner radius px (0 = square)
+    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_COUNT_
 } VroomFloatKey;
 
@@ -131,6 +157,12 @@ void vroom_chart_set_size(VroomChart* chart, float width_px, float height_px, fl
 
 void vroom_chart_set_visible_range(VroomChart* chart, int64_t start_ms, int64_t end_ms);
 
+// Target candle *body* width in px for the default/reset framing. Larger = more
+// zoomed in (fewer candles), smaller = more zoomed out. 0 restores the legacy
+// "most recent ~80 candles" default. Affects initial framing only; an explicit
+// set_visible_range still overrides it.
+void vroom_chart_set_default_candle_width(VroomChart* chart, float px);
+
 // Reads the current visible time window. Either out pointer may be null.
 // Both are 0 when the window is still uninitialized.
 void vroom_chart_get_visible_range(VroomChart* chart,
@@ -195,6 +227,15 @@ void vroom_chart_get_axis_metrics(VroomChart* chart,
 // ---- Crosshair ------------------------------------------------------------
 
 void vroom_chart_set_crosshair(VroomChart* chart, float x_px, float y_px);
+
+// Show the crosshair at a data-space position (epoch ms + price) rather than
+// pixels — used to drive one chart's crosshair from another's (cross-chart
+// sync). Converts to pixels via the current visible window and price scale;
+// the vertical line then snaps to the nearest candle center at draw time, so
+// the crosshair lands on the candle for `time_ms`. The horizontal line sits at
+// `price` (clamped to the pane when off-scale).
+void vroom_chart_set_crosshair_data(VroomChart* chart, int64_t time_ms, double price);
+
 void vroom_chart_clear_crosshair(VroomChart* chart);
 
 // Fills *out with the OHLCV of the candle the crosshair currently snaps to and
@@ -211,6 +252,10 @@ bool vroom_chart_get_crosshair_candle(VroomChart* chart, VroomCandle* out);
 // `candle` is left untouched.
 typedef struct VroomCrosshairInfo {
     int64_t     time_ms;
+    // Free price under the crosshair's horizontal line — the value drawn on the
+    // price badge (not snapped to any candle). Valid whenever the call returns
+    // true, including in the future region where `has_candle` is false.
+    double      price;
     bool        has_candle;
     VroomCandle candle;
 } VroomCrosshairInfo;
@@ -259,6 +304,14 @@ void vroom_chart_set_vwap(VroomChart* chart, bool enabled, int reset_offset_min,
 void vroom_chart_set_drawings(VroomChart* chart, const VroomDrawing* drawings,
                               size_t count);
 
+// ---- Liquidity bands (order-book depth overlay) ---------------------------
+
+// Replaces the full set of resting-liquidity bands and their shared style.
+// Bands render behind the candles, anchored at the inner edge of the price axis
+// and fading left. Pass count 0 to clear; `style` may be null when count is 0.
+void vroom_chart_set_liquidity(VroomChart* chart, const VroomBand* bands,
+                               size_t count, const VroomLiquidityStyle* style);
+
 // 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 guideline A->B (the live line preview); `guide == 0`

package/cpp/_core_src/candles.cpp

@@ -39,6 +39,18 @@ void draw(SkCanvas* canvas,
     const uint32_t fill_bull = theme.colors[VROOM_COLOR_BULL];
     const uint32_t fill_bear = theme.colors[VROOM_COLOR_BEAR];
 
+    const float body_r = theme.floats[VROOM_FLOAT_CANDLE_RADIUS_PX];
+    const bool wick_round = theme.floats[VROOM_FLOAT_WICK_ROUND_CAP] > 0.5f;
+
+    constexpr float kBorderWidthPx = 1.f;
+    // Draw the border only when it differs from the fill; an inherited/transparent
+    // border color (the default, and the "hide" path) renders nothing — so a hidden
+    // border costs no pixels and never affects candle width.
+    const bool draw_border_bull =
+        resolve_color(theme.colors[VROOM_COLOR_BORDER_BULL], fill_bull) != fill_bull;
+    const bool draw_border_bear =
+        resolve_color(theme.colors[VROOM_COLOR_BORDER_BEAR], fill_bear) != fill_bear;
+
     SkPaint bull_paint;
     bull_paint.setAntiAlias(true);
     bull_paint.setColor(fill_bull);
@@ -53,17 +65,19 @@ void draw(SkCanvas* canvas,
         resolve_color(theme.colors[VROOM_COLOR_WICK_BULL], fill_bull));
     wick_bull.setStrokeWidth(theme.floats[VROOM_FLOAT_WICK_WIDTH_PX]);
     wick_bull.setStyle(SkPaint::kStroke_Style);
+    wick_bull.setStrokeCap(wick_round ? SkPaint::kRound_Cap : SkPaint::kButt_Cap);
 
     SkPaint wick_bear = wick_bull;
     wick_bear.setColor(
         resolve_color(theme.colors[VROOM_COLOR_WICK_BEAR], fill_bear));
 
-    // 1px body outlines. Default sentinel resolves to the fill color, so the
-    // border is invisible until a consumer sets borderBull/borderBear.
+    // 1px body outlines, drawn *inside* the body (see the inset at draw time) so
+    // a contrasting border never widens the candle. Default sentinel resolves to
+    // the fill color; such borders are skipped entirely (draw_border_* above).
     SkPaint border_bull;
     border_bull.setAntiAlias(true);
     border_bull.setStyle(SkPaint::kStroke_Style);
-    border_bull.setStrokeWidth(1.f);
+    border_bull.setStrokeWidth(kBorderWidthPx);
     border_bull.setColor(
         resolve_color(theme.colors[VROOM_COLOR_BORDER_BULL], fill_bull));
 
@@ -92,8 +106,32 @@ void draw(SkCanvas* canvas,
         const float y_bot = std::max(y_open, y_close);
         const float h = std::max(1.f, y_bot - y_top);
         const SkRect body = SkRect::MakeXYWH(cx - half_body, y_top, body_w, h);
-        canvas->drawRect(body, bull ? bull_paint : bear_paint);
-        canvas->drawRect(body, bull ? border_bull : border_bear);
+        // Corner radius clamped so thin candles / short bodies don't over-round.
+        const float r = std::min({body_r, body_w * 0.5f, h * 0.5f});
+        const SkPaint& fill = bull ? bull_paint : bear_paint;
+        if (r > 0.f) {
+            canvas->drawRoundRect(body, r, r, fill);
+        } else {
+            canvas->drawRect(body, fill);
+        }
+
+        const bool draw_border = bull ? draw_border_bull : draw_border_bear;
+        // Inset by half the stroke so the centered stroke falls fully within the
+        // body: the border overlaps the fill's outer edge instead of straddling
+        // it, keeping the candle's footprint exactly body_w. Skip when the body is
+        // too small to hold it.
+        if (draw_border && body_w > kBorderWidthPx && h > kBorderWidthPx) {
+            const SkRect inner =
+                body.makeInset(kBorderWidthPx * 0.5f, kBorderWidthPx * 0.5f);
+            const SkPaint& bp = bull ? border_bull : border_bear;
+            // Concentric radius so the inside border follows the rounded body.
+            const float ir = std::max(0.f, r - kBorderWidthPx * 0.5f);
+            if (ir > 0.f) {
+                canvas->drawRoundRect(inner, ir, ir, bp);
+            } else {
+                canvas->drawRect(inner, bp);
+            }
+        }
     }
 }
 

package/cpp/_core_src/chart.cpp

@@ -23,6 +23,7 @@
 #include "crosshair.h"
 #include "drawings.h"
 #include "labels.h"
+#include "liquidity.h"
 #include "ma.h"
 #include "ma_overlay.h"
 #include "macd.h"
@@ -142,6 +143,12 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
     vroom::volume::draw(canvas, visible, n, lay, theme,
                         window_ms, visible_start_ms, candle_duration_ms);
 
+    // 4.6. Liquidity bands (resting-order depth) — behind the candles so the
+    //      candle bodies paint over the volume-driven tint. Anchored in price
+    //      space, so they scale with the y-axis.
+    vroom::liquidity::draw(canvas, *this, lay, bounds, candle_right,
+                           candle_area_h);
+
     // 5. Candles (wicks + bodies)
     vroom::candles::draw(canvas, visible, n, lay, theme, bounds,
                          window_ms, visible_start_ms, candle_duration_ms);

package/cpp/_core_src/chart.h

@@ -50,6 +50,10 @@ struct VroomChart {
     int64_t visible_start_ms = 0;
     int64_t visible_end_ms = 0;
 
+    // >0: default/reset framing targets this candle *body* width in px (drives
+    // initial zoom). 0 = legacy "last ~80 candles" behavior.
+    float default_candle_px = 0.f;
+
     // Cached y-axis width in pixels, sized to fit the widest formatted price
     // label. 0 = uncomputed; layout() falls back to a width ratio.
     float axis_width_px = 0.f;
@@ -140,6 +144,12 @@ struct VroomChart {
     uint32_t       draft_color = 0xff2962ff;
     float          draft_width = 2.f;
 
+    // --- liquidity bands (order-book depth overlay) ------------------------
+    // Resting-order bands anchored in price space, drawn behind the candles and
+    // fading left from the price axis. Empty when the overlay is off.
+    std::vector<VroomBand>   bands;
+    VroomLiquidityStyle      liquidity_style{};
+
     // --- theme --------------------------------------------------------------
     vroom::Theme theme;
 

package/cpp/_core_src/chart_facade.cpp

@@ -54,10 +54,37 @@ int64_t damp_future_delta(int64_t delta_ms, int64_t cur_future,
     return static_cast<int64_t>(static_cast<double>(delta_ms) * resist);
 }
 
-// Frame the default view: the most recent ~80 candles — a narrower x-window
-// so candles read wider. No-op when there are no candles.
+// Frame the default view. When the consumer has set a target candle body width
+// (default_candle_px), size the window so each candle renders ~that wide with the
+// right edge pinned to the latest candle; otherwise fall back to the legacy
+// "most recent ~80 candles". No-op when there are no candles.
 void apply_default_framing(VroomChart* chart) {
     if (chart->candles.empty()) return;
+
+    // Px-driven framing. Reuses the inversion from vroom_chart_scale_time_axis:
+    // body_w = usable × (dur / window) × ratio  →  window = usable × dur × ratio / body_w.
+    // Needs a valid layout (width_px); until size is known it falls through to
+    // the candle-count default below.
+    if (chart->default_candle_px > 0.f) {
+        const auto lay = chart->layout();
+        const double usable =
+            lay.width_px - lay.y_axis_width_px - lay.right_padding_px;
+        const double ratio = chart->theme.floats[VROOM_FLOAT_CANDLE_WIDTH_RATIO];
+        const double dur = static_cast<double>(chart->candle_duration_ms);
+        const double body = std::clamp(static_cast<double>(chart->default_candle_px),
+                                       kMinCandleBodyPx, kMaxCandleBodyPx);
+        if (usable > 0.0 && ratio > 0.0 && dur > 0.0 && body > 0.0) {
+            int64_t window_ms = static_cast<int64_t>((usable * dur * ratio) / body);
+            const int64_t span =
+                chart->candles.back().time_ms - chart->candles.front().time_ms;
+            window_ms = std::clamp<int64_t>(window_ms, chart->candle_duration_ms,
+                                            span > 0 ? span : window_ms);
+            chart->visible_end_ms = chart->candles.back().time_ms;
+            chart->visible_start_ms = chart->visible_end_ms - window_ms;
+            return;
+        }
+    }
+
     constexpr size_t kDefaultVisible = 80;
     const size_t start_idx = chart->candles.size() > kDefaultVisible
         ? chart->candles.size() - kDefaultVisible
@@ -167,6 +194,16 @@ extern "C" void vroom_chart_set_visible_range(VroomChart* chart, int64_t start_m
     chart->mark_dirty();
 }
 
+extern "C" void vroom_chart_set_default_candle_width(VroomChart* chart, float px) {
+    if (!chart) return;
+    chart->default_candle_px = px;
+    // Re-frame so a value that arrives after set_candles still drives the initial
+    // view. Intended for initial framing only — calling it after the user has
+    // panned would snap the view back to the default frame.
+    if (!chart->candles.empty()) apply_default_framing(chart);
+    chart->mark_dirty();
+}
+
 extern "C" void vroom_chart_get_visible_range(VroomChart* chart,
                                               int64_t* out_start_ms,
                                               int64_t* out_end_ms) {
@@ -623,6 +660,28 @@ extern "C" void vroom_chart_set_crosshair(VroomChart* chart, float x, float y) {
     chart->mark_dirty();
 }
 
+extern "C" void vroom_chart_set_crosshair_data(VroomChart* chart,
+                                               int64_t time_ms, double price) {
+    if (!chart || chart->candles.empty()) return;
+    const int64_t window_ms = chart->visible_end_ms - chart->visible_start_ms;
+    if (window_ms <= 0) return;
+    const auto lay = chart->layout();
+    // Mirror coord_at's bounds so price -> y matches what's on screen.
+    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);
+    chart->crosshair_active = true;
+    chart->crosshair_x_px =
+        vroom::x_at_time(lay, chart->visible_start_ms, window_ms, time_ms);
+    chart->crosshair_y_px = vroom::price_to_y(lay, bounds, price);
+    chart->mark_dirty();
+}
+
 extern "C" void vroom_chart_clear_crosshair(VroomChart* chart) {
     if (!chart) return;
     chart->crosshair_active = false;
@@ -672,6 +731,13 @@ extern "C" bool vroom_chart_get_crosshair_info(VroomChart* chart,
         lay, visible, n, chart->candle_duration_ms,
         chart->visible_start_ms, window_ms, chart->crosshair_x_px);
     out->time_ms = snap.time_ms;
+    // Free price at the crosshair's horizontal line — same bounds as the price
+    // badge (crosshair.cpp) so the reported value equals what's drawn.
+    const auto bounds =
+        chart->price_bounds_manual
+            ? chart->price_bounds
+            : vroom::auto_price_bounds(visible, n);
+    out->price = vroom::y_to_price(lay, bounds, chart->crosshair_y_px);
     out->has_candle = snap.has_candle;
     if (snap.has_candle) out->candle = visible[snap.index];
     return true;
@@ -687,6 +753,17 @@ extern "C" void vroom_chart_set_drawings(VroomChart* chart,
     chart->mark_dirty();
 }
 
+// ---- Liquidity bands (order-book depth overlay) ---------------------------
+
+extern "C" void vroom_chart_set_liquidity(VroomChart* chart,
+                                          const VroomBand* bands, size_t count,
+                                          const VroomLiquidityStyle* style) {
+    if (!chart) return;
+    chart->bands.assign(bands, bands + count);
+    if (style) chart->liquidity_style = *style;
+    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/liquidity.cpp

@@ -0,0 +1,112 @@
+#include "liquidity.h"
+
+#include <algorithm>
+#include <cstdint>
+
+#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/SkPoint.h"
+#include "include/core/SkRect.h"
+#include "include/core/SkShader.h"
+#include "include/core/SkTileMode.h"
+// Skia's linear-gradient API differs across the Skia versions we build against:
+// the WASM build uses a newer Skia (SkGradient.h + SkShaders::LinearGradient),
+// while react-native-skia bundles an older one (SkGradientShader::MakeLinear).
+// Neither ships both headers, so select whichever is present.
+#if __has_include("include/effects/SkGradient.h")
+#  include "include/core/SkSpan.h"
+#  include "include/effects/SkGradient.h"
+#  define VROOM_SK_MODERN_GRADIENT 1
+#else
+#  include "include/effects/SkGradientShader.h"
+#  define VROOM_SK_MODERN_GRADIENT 0
+#endif
+#pragma clang diagnostic pop
+
+#include "chart.h"
+
+namespace vroom::liquidity {
+namespace {
+
+// A horizontal shader fading from transparent at the left of `pts` to `base` at
+// opacity `alpha` on the right, keeping RGB constant so the faded edge doesn't
+// darken toward black. Abstracts over the two Skia gradient APIs above.
+sk_sp<SkShader> left_fade_shader(const SkPoint pts[2], SkColor base, float alpha) {
+#if VROOM_SK_MODERN_GRADIENT
+    const float r = SkColorGetR(base) / 255.f;
+    const float g = SkColorGetG(base) / 255.f;
+    const float b = SkColorGetB(base) / 255.f;
+    const SkColor4f colors[2] = {SkColor4f{r, g, b, 0.f}, SkColor4f{r, g, b, alpha}};
+    const SkGradient::Colors grad_colors(
+        SkSpan<const SkColor4f>(colors, 2), SkTileMode::kClamp);
+    const SkGradient grad(grad_colors, SkGradient::Interpolation{});
+    return SkShaders::LinearGradient(pts, grad);
+#else
+    const auto a = static_cast<U8CPU>(alpha * 255.f + 0.5f);
+    const SkColor colors[2] = {SkColorSetA(base, 0), SkColorSetA(base, a)};
+    return SkGradientShader::MakeLinear(pts, colors, nullptr, 2, SkTileMode::kClamp);
+#endif
+}
+
+}  // namespace
+
+void draw(SkCanvas* canvas,
+          const VroomChart& chart,
+          const Layout& lay,
+          const PriceBounds& bounds,
+          float candle_right,
+          float candle_area_h) {
+    if (!canvas || candle_right <= 0.f || candle_area_h <= 0.f) return;
+    if (chart.bands.empty()) return;
+
+    const VroomLiquidityStyle& style = chart.liquidity_style;
+
+    // Leftward reach: the smaller of the px cap and the pane-fraction, clamped so
+    // the band never starts left of the pane.
+    const float frac_reach = style.width_frac > 0.f ? style.width_frac * candle_right
+                                                    : candle_right;
+    const float px_reach = style.width_px > 0.f ? style.width_px : candle_right;
+    const float reach = std::min(px_reach, frac_reach);
+    const float left_x = std::max(0.f, candle_right - reach);
+
+    // Volume that maps to peak opacity: explicit, or the largest band's volume.
+    double max_vol = style.max_volume;
+    if (max_vol <= 0.0) {
+        for (const VroomBand& b : chart.bands) max_vol = std::max(max_vol, b.volume);
+    }
+
+    const float min_op = std::clamp(style.min_opacity, 0.f, 1.f);
+    const float max_op = std::clamp(style.max_opacity, 0.f, 1.f);
+
+    canvas->save();
+    canvas->clipRect(SkRect::MakeLTRB(0.f, 0.f, candle_right, candle_area_h));
+
+    const SkPoint pts[2] = {SkPoint{left_x, 0.f}, SkPoint{candle_right, 0.f}};
+
+    for (const VroomBand& b : chart.bands) {
+        // Higher price -> smaller y, so max_price is the top edge.
+        const float y_top = vroom::price_to_y(lay, bounds, b.max_price);
+        const float y_bot = vroom::price_to_y(lay, bounds, b.min_price);
+        if (y_bot < 0.f || y_top > candle_area_h) continue;  // fully off-pane
+
+        const SkColor base =
+            static_cast<SkColor>(b.side == 0 ? style.buy_color : style.sell_color);
+
+        const double t = max_vol > 0.0
+            ? std::clamp(b.volume / max_vol, 0.0, 1.0)
+            : 0.0;
+        const float alpha = min_op + (max_op - min_op) * static_cast<float>(t);
+
+        SkPaint paint;
+        paint.setAntiAlias(true);
+        paint.setShader(left_fade_shader(pts, base, alpha));
+        canvas->drawRect(SkRect::MakeLTRB(left_x, y_top, candle_right, y_bot), paint);
+    }
+
+    canvas->restore();
+}
+
+}  // namespace vroom::liquidity

package/cpp/_core_src/liquidity.h

@@ -0,0 +1,35 @@
+// Liquidity bands — resting-order / order-book depth rendered on the price pane.
+//
+// Each band (chart.bands) is a price interval carrying a total size on one side
+// of the book. It is drawn as a horizontal rectangle anchored at the inner edge
+// of the price axis (`candle_right`), stretching left by the configured reach
+// and fading to transparent with a left->right gradient. Color comes from the
+// band's side (buy/sell); the band's alpha comes from its volume mapped into
+// [min_opacity, max_opacity]. Because the vertical extent is derived from price
+// via price_to_y, bands scale with the y-axis on zoom.
+//
+// Like ma_overlay / drawings this is its own module so the chart orchestrator
+// stays thin. Drawn BEHIND the candles (before candles::draw) so candle bodies
+// paint over the bands.
+
+#pragma once
+
+#include "viewport.h"
+#include "vroom/vroom_chart.h"
+
+class SkCanvas;
+struct VroomChart;
+
+namespace vroom::liquidity {
+
+// Draws the liquidity bands. `candle_right` is the x of the price-axis strip
+// (bands' right edge); `candle_area_h` is the price-pane bottom. Geometry is
+// clipped to that rectangle so bands never bleed into the axis strips.
+void draw(SkCanvas* canvas,
+          const VroomChart& chart,
+          const vroom::Layout& lay,
+          const vroom::PriceBounds& bounds,
+          float candle_right,
+          float candle_area_h);
+
+}  // namespace vroom::liquidity

package/cpp/_core_src/theme.cpp

@@ -33,6 +33,9 @@ constexpr float kDefaultFloats[VROOM_FLOAT_COUNT_] = {
     22.f,   // X_AXIS_HEIGHT_PX — bottom strip for time labels
     0.5f,   // VOLUME_OPACITY — candle color at 50% transparency
     0.20f,  // INDICATOR_HEIGHT_FRAC — below-chart indicator pane = 20% of height
+    0.f,    // CANDLE_RADIUS_PX — square by default
+    0.f,    // WICK_ROUND_CAP — butt caps by default
+    0.f,    // VOLUME_RADIUS_PX — square by default
 };
 
 }  // namespace

package/cpp/_core_src/volume.cpp

@@ -4,6 +4,7 @@
 #pragma clang diagnostic ignored "-Wdocumentation"
 #include "include/core/SkCanvas.h"
 #include "include/core/SkPaint.h"
+#include "include/core/SkRRect.h"
 #include "include/core/SkRect.h"
 #pragma clang diagnostic pop
 
@@ -41,6 +42,7 @@ void draw(SkCanvas* canvas,
     const float half_body = body_w * 0.5f;
 
     const float opacity = theme.floats[VROOM_FLOAT_VOLUME_OPACITY];
+    const float vol_r = theme.floats[VROOM_FLOAT_VOLUME_RADIUS_PX];
     SkPaint bull_paint;
     bull_paint.setAntiAlias(true);
     bull_paint.setColor(theme.colors[VROOM_COLOR_ACCENT_BULL]);
@@ -61,9 +63,19 @@ void draw(SkCanvas* canvas,
             visible_start_ms, window_ms);
         const float h = std::max(
             1.f, static_cast<float>(c.volume / max_vol) * region_h);
-        canvas->drawRect(
-            SkRect::MakeXYWH(cx - half_body, candle_area_h - h, body_w, h),
-            bull ? bull_paint : bear_paint);
+        const SkRect rect =
+            SkRect::MakeXYWH(cx - half_body, candle_area_h - h, body_w, h);
+        const SkPaint& paint = bull ? bull_paint : bear_paint;
+        // Round only the top corners; clamp so short/narrow bars don't over-round.
+        const float r = std::min({vol_r, body_w * 0.5f, h});
+        if (r > 0.f) {
+            SkRRect rr;
+            const SkVector radii[4] = {{r, r}, {r, r}, {0, 0}, {0, 0}};  // TL, TR, BR, BL
+            rr.setRectRadii(rect, radii);
+            canvas->drawRRect(rr, paint);
+        } else {
+            canvas->drawRect(rect, paint);
+        }
     }
 }