react-native-vroom-chart 0.5.0 → 0.7.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)
@@ -118,6 +209,44 @@ typedef struct VroomLiquidityStyle {
     float    width_frac;
 } VroomLiquidityStyle;
 
+// ---- Price status lines ---------------------------------------------------
+
+// Bit flags for VroomPriceLine::flags.
+typedef enum {
+    VROOM_PRICE_LINE_DRAGGABLE   = 1 << 0,  // the line can be dragged vertically
+    VROOM_PRICE_LINE_CLOSABLE    = 1 << 1,  // render the trailing close ("x") button
+    VROOM_PRICE_LINE_AXIS_LABEL  = 1 << 2,  // render the price badge in the y-axis strip
+    VROOM_PRICE_LINE_EXTEND_LEFT = 1 << 3,  // extend the line to the pane's left edge
+} VroomPriceLineFlags;
+
+// A consumer-supplied horizontal status line at a fixed price — the primitive
+// behind resting limit orders, take-profits, liquidation levels and the like.
+//
+// Visually: a line across the price pane ending in a label group made of a body
+// pill (`text`), an optional solid-filled `quantity` pill, and an optional close
+// button, plus an optional price badge in the y-axis strip.
+//
+// `text` / `quantity` are UTF-8 and copied internally, so the caller may free
+// them as soon as the call returns. A null or empty string hides that segment.
+typedef struct VroomPriceLine {
+    double      price;
+    uint32_t    color;       // 0xAARRGGBB — line, border, body text, close icon
+    float       width;       // stroke width in px
+    int32_t     line_style;  // 0 = solid, 1 = dotted, 2 = dashed
+    const char* text;        // body label
+    const char* quantity;    // trailing solid-fill segment
+    int32_t     flags;       // bitwise-or of VroomPriceLineFlags
+} VroomPriceLine;
+
+// Layout/style shared by every price line, so the per-line struct stays small.
+typedef struct VroomPriceLineStyle {
+    uint32_t body_bg;           // translucent body/close-button pill fill (0xAARRGGBB)
+    float    font_size_px;      // 0 = inherit VROOM_FLOAT_AXIS_FONT_SIZE_PX
+    float    line_length_frac;  // 0..1 of pane width: the label group's right-edge inset
+    int32_t  align;             // 0 = left, 1 = center, 2 = right
+    float    hover_boost;       // brightness multiplier for the hovered segment (1 = flat)
+} VroomPriceLineStyle;
+
 // 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 {
@@ -161,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 {
@@ -225,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
@@ -313,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
@@ -390,6 +586,38 @@ void vroom_chart_translate_drawing(VroomChart* chart, int32_t index,
 void vroom_chart_set_liquidity(VroomChart* chart, const VroomBand* bands,
                                size_t count, const VroomLiquidityStyle* style);
 
+// ---- Price status lines ---------------------------------------------------
+
+// Replaces the full set of price status lines and their shared style. Lines
+// render on the price pane above the axis labels (so their badges cover any
+// label they overlap) and below the crosshair. A line whose price maps outside
+// the price pane is skipped rather than clamped. Pass count 0 to clear;
+// `style` may be null when count is 0.
+void vroom_chart_set_price_lines(VroomChart* chart, const VroomPriceLine* lines,
+                                 size_t count,
+                                 const VroomPriceLineStyle* style);
+
+// Hit-tests pixel (x_px, y_px) against the price lines. On a hit, fills
+// *out_index with the line index and *out_part with 0 (the line or its label
+// body — the drag target) or 1 (the close button), and returns true. When
+// several lines are within tolerance the nearest in y wins. Only draggable
+// lines report part 0 and only closable lines report part 1. Returns false on a
+// miss (out params untouched). Either out pointer may be null.
+bool vroom_chart_hit_test_price_line(VroomChart* chart, float x_px, float y_px,
+                                     int32_t* out_index, int32_t* out_part);
+
+// Marks a price line's segment as hovered so it renders highlighted. `index` -1
+// clears the hover. `part` matches vroom_chart_hit_test_price_line.
+void vroom_chart_set_price_line_hover(VroomChart* chart, int32_t index,
+                                      int32_t part);
+
+// Drives the live drag preview: the line, its label and its badge render at
+// `price` instead of the committed one, and a faint ghost marks where it
+// started. `index` -1 ends the preview. The committed price is never mutated —
+// the host applies (or rejects) the new price by restating its lines.
+void vroom_chart_set_price_line_drag(VroomChart* chart, int32_t index,
+                                     double price);
+
 // Sets the transient in-progress "draft" the drawing tool shows while the user
 // places points. Node A is always shown; when `has_b`, node B is shown too.
 // `guide != 0` also draws the live preview (a guideline for a line, or a preview

package/cpp/_core_src/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