react-native-vroom-chart 0.6.0 → 0.8.0

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)
@@ -81,17 +172,20 @@ typedef struct VroomDrawPoint {
 //                and `b`; the other two corners (a.x,b.y) and (b.x,a.y) derive.
 //   2 = pencil — a freehand path through `points` (in draw order). `a`/`b` mirror
 //                the first/last point so bounds and handle code stay uniform.
+//   3 = path   — straight segments through `points` (in draw order), ending in
+//                an arrowhead on the last one. Same storage as a pencil, but
+//                rendered unsmoothed and with every vertex a grab handle.
 //
-// `points`/`point_count` are only read for kind 2; line and box leave them
-// null/0. Like the rest of this API the points are copied internally, so the
-// caller may free them as soon as the call returns.
+// `points`/`point_count` are only read for kinds 2 and 3; line and box leave
+// them null/0. Like the rest of this API the points are copied internally, so
+// the caller may free them as soon as the call returns.
 typedef struct VroomDrawing {
     VroomDrawPoint        a;
     VroomDrawPoint        b;
     uint32_t              color;        // 0xAARRGGBB
     float                 width;        // stroke width in px
-    int32_t               kind;         // 0 = line, 1 = box, 2 = pencil
-    const VroomDrawPoint* points;       // pencil path (kind 2), else null
+    int32_t               kind;         // 0 = line, 1 = box, 2 = pencil, 3 = path
+    const VroomDrawPoint* points;       // pencil/path points (kind 2/3), else null
     int32_t               point_count;  // number of `points`, else 0
 } VroomDrawing;
 
@@ -199,9 +293,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 +373,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 +500,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
@@ -393,18 +554,31 @@ void vroom_chart_set_drawings(VroomChart* chart, const VroomDrawing* drawings,
                               size_t count);
 
 // Hit-tests pixel (x_px, y_px) against the committed drawings. On a hit, fills
-// *out_index with the drawing index, *out_part with 0 (endpoint A), 1
-// (endpoint B), or 2 (line body), *out_t with the 0..1 grab position along the
-// segment (A→B; 0/1 for handle hits), and returns true. Endpoint hits are only
-// reported for the currently selected drawing (whose handles are visible).
-// Returns false on a miss (out params untouched). Any out pointer may be null.
+// *out_index with the drawing index, *out_part with the sub-part that was hit,
+// *out_t with the 0..1 grab position along the segment (A→B; 0/1 for handle
+// hits, 0 for the shapes that have no meaningful t), and returns true. Handle
+// hits are only reported for the currently selected drawing (whose handles are
+// visible). Returns false on a miss (out params untouched). Any out pointer may
+// be null.
+//
+// `out_part` is per-kind (see VroomDrawing.kind):
+//   line   — 0 (endpoint A), 1 (endpoint B), 2 (body).
+//   box    — 0..3 (corners, in the order a, (b.x,a.y), b, (a.x,b.y)), 4 (body).
+//   pencil — 5 (body; a stroke has no handles).
+//   path   — 6 (body), or VROOM_DRAW_PART_VERTEX + i for vertex i. The offset
+//            keeps a vertex index from colliding with the small part numbers
+//            above, and is why a path is capped at VROOM_PATH_MAX_POINTS.
+#define VROOM_DRAW_PART_VERTEX 100
+#define VROOM_PATH_MAX_POINTS  64
 bool vroom_chart_hit_test_drawing(VroomChart* chart, float x_px, float y_px,
                                   int32_t* out_index, int32_t* out_part,
                                   float* out_t);
 
-// Selects a committed drawing (renders its endpoint handles). `index` -1 clears
-// the selection. `grabbed_endpoint` 0/1 renders that handle 50% larger while it's
-// being dragged; -1 for none. An out-of-range index clears the selection.
+// Selects a committed drawing (renders its handles). `index` -1 clears the
+// selection. `grabbed_endpoint` renders that handle 50% larger while it's being
+// dragged (0/1 for a line, 0 for the box corner the host normalized to, the
+// vertex index for a path); -1 for none. An out-of-range index clears the
+// selection.
 void vroom_chart_set_selected_drawing(VroomChart* chart, int32_t index,
                                       int32_t grabbed_endpoint);
 
@@ -414,8 +588,16 @@ void vroom_chart_move_drawing_endpoint(VroomChart* chart, int32_t index,
                                        int32_t endpoint, int64_t time_ms,
                                        double price);
 
+// Moves one vertex of a committed path (kind 3) to a new data-space anchor, for
+// live handle dragging. `vertex` indexes `points`; a/b are re-mirrored onto the
+// first/last point afterwards. No-op for an out-of-range drawing/vertex index or
+// a drawing that isn't a path.
+void vroom_chart_move_drawing_vertex(VroomChart* chart, int32_t index,
+                                     int32_t vertex, int64_t time_ms,
+                                     double price);
+
 // Shifts a whole committed drawing by a *relative* data-space delta — `a`, `b`,
-// and (for a pencil) every path point. Used for live body dragging of shapes
+// and (for a pencil or path) every point. Used for live body dragging of shapes
 // whose points can't be restated cheaply. No-op for an out-of-range index.
 void vroom_chart_translate_drawing(VroomChart* chart, int32_t index,
                                    int64_t d_time_ms, double d_price);
@@ -484,6 +666,19 @@ void vroom_chart_start_draft_stroke(VroomChart* chart, uint32_t color,
 void vroom_chart_append_draft_point(VroomChart* chart, int64_t time_ms,
                                     double price);
 
+// Restates the whole in-progress path (kind 3) draft: `count` vertices placed so
+// far, plus — when `has_cursor` — a rubber-band segment from the last vertex to
+// (cursor_time, cursor_price) carrying the arrow tip. Each placed vertex renders
+// a node dot. A path is placed one deliberate click at a time (so `count` stays
+// small, see VROOM_PATH_MAX_POINTS), which is why this restates rather than
+// appending: the host stays the sole owner of the vertex list, and undoing a
+// point is just a shorter array. Pass count 0 with has_cursor false to show
+// nothing; the points are copied, so the caller may free them on return.
+void vroom_chart_set_draft_path(VroomChart* chart, const VroomDrawPoint* points,
+                                int32_t count, bool has_cursor,
+                                int64_t cursor_time, double cursor_price,
+                                uint32_t color, float width);
+
 // Clears the draft (hides the in-progress node dots / guideline / stroke).
 void vroom_chart_clear_draft(VroomChart* chart);
 

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.

package/cpp/_core_src/candles.cpp

@@ -20,6 +20,31 @@ namespace {
 inline uint32_t resolve_color(uint32_t color, uint32_t fill) {
     return (color >> 24) == 0 ? fill : color;
 }
+
+// Channel-wise ARGB blend, for a candle that changes direction mid-morph.
+inline uint32_t lerp_argb(uint32_t a, uint32_t b, float t) {
+    uint32_t out = 0;
+    for (int shift = 0; shift < 32; shift += 8) {
+        const float ca = static_cast<float>((a >> shift) & 0xFFu);
+        const float cb = static_cast<float>((b >> shift) & 0xFFu);
+        const auto v = static_cast<uint32_t>(ca + (cb - ca) * t + 0.5f);
+        out |= v << shift;
+    }
+    return out;
+}
+
+inline uint32_t scale_alpha(uint32_t argb, float a) {
+    const auto alpha =
+        static_cast<uint32_t>(static_cast<float>((argb >> 24) & 0xFFu) * a + 0.5f);
+    return (alpha << 24) | (argb & 0x00FFFFFFu);
+}
+
+inline float lerp(float a, float b, float t) { return a + (b - a) * t; }
+
+// One slot's wick/body extents in pixels.
+struct SlotGeom {
+    float x, open, high, low, close;
+};
 }  // namespace
 
 void draw(SkCanvas* canvas,
@@ -32,13 +57,23 @@ void draw(SkCanvas* canvas,
           int64_t visible_start_ms,
           int64_t candle_duration_ms,
           float collapse,
-          float opacity) {
-    if (!canvas || n == 0) return;
+          float opacity,
+          const CandleSnapshot* from,
+          std::size_t from_n,
+          float morph_t) {
+    if (!canvas) return;
 
     collapse = std::clamp(collapse, 0.f, 1.f);
     opacity = std::clamp(opacity, 0.f, 1.f);
+    morph_t = std::clamp(morph_t, 0.f, 1.f);
     if (opacity <= 0.f) return;
 
+    // A finished morph drops the capture, reducing the loop below to the plain
+    // candle path.
+    const std::size_t from_count = vroom::morph_from_count(from, from_n, morph_t);
+    const std::size_t slots = std::max(n, from_count);
+    if (slots == 0) return;
+
     // During the candle→line morph, fade the entire candle layer as one unit so
     // overlapping bars/wicks composite cleanly instead of stacking alpha.
     const bool fade_layer = opacity < 0.999f;
@@ -60,13 +95,20 @@ void draw(SkCanvas* canvas,
     const bool wick_round = theme.floats[VROOM_FLOAT_WICK_ROUND_CAP] > 0.5f;
 
     constexpr float kBorderWidthPx = 1.f;
+    const uint32_t wick_color_bull =
+        resolve_color(theme.colors[VROOM_COLOR_WICK_BULL], fill_bull);
+    const uint32_t wick_color_bear =
+        resolve_color(theme.colors[VROOM_COLOR_WICK_BEAR], fill_bear);
+    const uint32_t border_color_bull =
+        resolve_color(theme.colors[VROOM_COLOR_BORDER_BULL], fill_bull);
+    const uint32_t border_color_bear =
+        resolve_color(theme.colors[VROOM_COLOR_BORDER_BEAR], fill_bear);
+
     // 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;
+    const bool draw_border_bull = border_color_bull != fill_bull;
+    const bool draw_border_bear = border_color_bear != fill_bear;
 
     SkPaint bull_paint;
     bull_paint.setAntiAlias(true);
@@ -78,15 +120,13 @@ void draw(SkCanvas* canvas,
 
     SkPaint wick_bull;
     wick_bull.setAntiAlias(true);
-    wick_bull.setColor(
-        resolve_color(theme.colors[VROOM_COLOR_WICK_BULL], fill_bull));
+    wick_bull.setColor(wick_color_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));
+    wick_bear.setColor(wick_color_bear);
 
     // 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
@@ -95,52 +135,110 @@ void draw(SkCanvas* canvas,
     border_bull.setAntiAlias(true);
     border_bull.setStyle(SkPaint::kStroke_Style);
     border_bull.setStrokeWidth(kBorderWidthPx);
-    border_bull.setColor(
-        resolve_color(theme.colors[VROOM_COLOR_BORDER_BULL], fill_bull));
+    border_bull.setColor(border_color_bull);
 
     SkPaint border_bear = border_bull;
-    border_bear.setColor(
-        resolve_color(theme.colors[VROOM_COLOR_BORDER_BEAR], fill_bear));
+    border_bear.setColor(border_color_bear);
+
+    // Scratch paints for the slots that need a per-slot color (see below).
+    SkPaint slot_wick, slot_fill, slot_border;
 
     const float half_body = body_w * 0.5f;
+    const float area_w = vroom::candle_area_width(lay);
 
-    for (std::size_t i = 0; i < n; ++i) {
-        const auto& c = visible[i];
-        const bool bull = c.close >= c.open;
+    // Iterate slots counting back from the right edge — the pairing a timeframe
+    // switch preserves — descending so the paint order stays oldest-first and
+    // touching wicks/borders composite exactly as they do without a morph.
+    for (std::size_t k = slots; k-- > 0;) {
+        const ::VroomCandle* to = (k < n) ? &visible[n - 1 - k] : nullptr;
+        const CandleSnapshot* frm = (k < from_count) ? &from[k] : nullptr;
+
+        SlotGeom g{};
+        bool bull;
+        float alpha = 1.f;
+
+        if (to) {
+            const SlotGeom t{
+                vroom::candle_center_x(lay, to->time_ms, candle_duration_ms,
+                                       visible_start_ms, window_ms),
+                vroom::price_to_y(lay, bounds, to->open),
+                vroom::price_to_y(lay, bounds, to->high),
+                vroom::price_to_y(lay, bounds, to->low),
+                vroom::price_to_y(lay, bounds, to->close),
+            };
+            bull = to->close >= to->open;
+            if (frm) {
+                // The snapshot is in band fractions, so it lands on the same
+                // pixels it occupied pre-switch even though the bounds changed.
+                g.x = lerp(frm->x * area_w, t.x, morph_t);
+                g.open = lerp(vroom::y_at_fraction(lay, frm->open), t.open, morph_t);
+                g.high = lerp(vroom::y_at_fraction(lay, frm->high), t.high, morph_t);
+                g.low = lerp(vroom::y_at_fraction(lay, frm->low), t.low, morph_t);
+                g.close =
+                    lerp(vroom::y_at_fraction(lay, frm->close), t.close, morph_t);
+            } else {
+                g = t;
+                // A slot with no counterpart: fade in rather than pop.
+                if (from_count > 0) alpha = morph_t;
+            }
+        } else {
+            g = {frm->x * area_w,
+                 vroom::y_at_fraction(lay, frm->open),
+                 vroom::y_at_fraction(lay, frm->high),
+                 vroom::y_at_fraction(lay, frm->low),
+                 vroom::y_at_fraction(lay, frm->close)};
+            bull = frm->bull;
+            alpha = 1.f - morph_t;  // the new data dropped this slot
+        }
+        if (alpha <= 0.f) continue;
 
-        const float cx = vroom::candle_center_x(
-            lay, c.time_ms, candle_duration_ms,
-            visible_start_ms, window_ms);
-        const float y_close = vroom::price_to_y(lay, bounds, c.close);
         // Collapse high/low/open toward the close so the candle folds into its
         // close point (the line vertex) as `collapse` → 1.
-        const float y_high =
-            vroom::price_to_y(lay, bounds, c.high) * (1.f - collapse) +
-            y_close * collapse;
-        const float y_low =
-            vroom::price_to_y(lay, bounds, c.low) * (1.f - collapse) +
-            y_close * collapse;
-        const float y_open =
-            vroom::price_to_y(lay, bounds, c.open) * (1.f - collapse) +
-            y_close * collapse;
-
-        canvas->drawLine(cx, y_high, cx, y_low,
-                         bull ? wick_bull : wick_bear);
+        const float y_close = g.close;
+        const float y_high = g.high * (1.f - collapse) + y_close * collapse;
+        const float y_low = g.low * (1.f - collapse) + y_close * collapse;
+        const float y_open = g.open * (1.f - collapse) + y_close * collapse;
+
+        // Fast path: the prebuilt bull/bear paints. A faded slot and a candle
+        // that changes direction mid-morph both need per-slot colors.
+        const SkPaint* wick_p = bull ? &wick_bull : &wick_bear;
+        const SkPaint* fill_p = bull ? &bull_paint : &bear_paint;
+        const SkPaint* border_p = bull ? &border_bull : &border_bear;
+        bool draw_border = bull ? draw_border_bull : draw_border_bear;
+
+        const bool flip = frm && to && frm->bull != bull;
+        if (flip || alpha < 0.999f) {
+            const auto blend = [&](uint32_t c_bull, uint32_t c_bear) {
+                uint32_t c = bull ? c_bull : c_bear;
+                if (flip) c = lerp_argb(bull ? c_bear : c_bull, c, morph_t);
+                return scale_alpha(c, alpha);
+            };
+            slot_wick = *wick_p;
+            slot_wick.setColor(blend(wick_color_bull, wick_color_bear));
+            slot_fill = *fill_p;
+            slot_fill.setColor(blend(fill_bull, fill_bear));
+            slot_border = *border_p;
+            slot_border.setColor(blend(border_color_bull, border_color_bear));
+            wick_p = &slot_wick;
+            fill_p = &slot_fill;
+            border_p = &slot_border;
+            if (flip) draw_border = draw_border_bull || draw_border_bear;
+        }
+
+        canvas->drawLine(g.x, y_high, g.x, y_low, *wick_p);
 
         const float y_top = std::min(y_open, y_close);
         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);
+        const SkRect body = SkRect::MakeXYWH(g.x - half_body, y_top, body_w, h);
         // 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);
+            canvas->drawRoundRect(body, r, r, *fill_p);
         } else {
-            canvas->drawRect(body, fill);
+            canvas->drawRect(body, *fill_p);
         }
 
-        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
@@ -148,13 +246,12 @@ void draw(SkCanvas* canvas,
         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);
+                canvas->drawRoundRect(inner, ir, ir, *border_p);
             } else {
-                canvas->drawRect(inner, bp);
+                canvas->drawRect(inner, *border_p);
             }
         }
     }

package/cpp/_core_src/candles.h

@@ -12,6 +12,7 @@
 class SkCanvas;
 
 namespace vroom {
+struct CandleSnapshot;
 struct Layout;
 struct PriceBounds;
 struct Theme;
@@ -26,6 +27,12 @@ namespace vroom::candles {
 // candle→line transition: 0 = normal candle, 1 = a flat point at the close (the
 // body/wick heights and width shrink to the line). `opacity` (0..1) fades the
 // whole candle layer out as the line fades in. Both default to a no-op.
+//
+// `from` / `from_n` is the outgoing geometry of an interval morph, indexed from
+// the right of the visible slice (slot 0 = newest), and `morph_t` (0..1) is the
+// eased progress toward `visible`. Each slot's wick and body interpolate between
+// the two; slots present on only one side fade in or out. `morph_t == 1` (the
+// default) draws `visible` alone.
 void draw(SkCanvas* canvas,
           const ::VroomCandle* visible,
           std::size_t n,
@@ -36,6 +43,9 @@ void draw(SkCanvas* canvas,
           int64_t visible_start_ms,
           int64_t candle_duration_ms,
           float collapse = 0.f,
-          float opacity = 1.f);
+          float opacity = 1.f,
+          const CandleSnapshot* from = nullptr,
+          std::size_t from_n = 0,
+          float morph_t = 1.f);
 
 }  // namespace vroom::candles