react-native-vroom-chart 0.16.0 → 0.18.0

package/cpp/_core_src/chart.cpp

@@ -9,6 +9,7 @@
 
 #include "chart.h"
 
+#include <algorithm>
 #include <cmath>
 
 #pragma clang diagnostic push
@@ -32,6 +33,8 @@
 #include "ichimoku.h"
 #include "labels.h"
 #include "liquidity.h"
+#include "loading_line.h"
+#include "loading_wave.h"
 #include "ma.h"
 #include "ma_overlay.h"
 #include "macd.h"
@@ -42,6 +45,7 @@
 #include "rsi_pane.h"
 #include "style_inherit.h"
 #include "tip_anchor.h"
+#include "tip_geometry.h"
 #include "tip_pulse.h"
 #include "volume.h"
 #include "vwap.h"
@@ -67,13 +71,30 @@ vroom::Layout VroomChart::layout() const {
         (rsi.enabled ? 1 : 0) + (macd.enabled ? 1 : 0) + (atr.enabled ? 1 : 0);
     const float indicator_h = static_cast<float>(pane_count) * height_px *
                               theme.floats[VROOM_FLOAT_INDICATOR_HEIGHT_FRAC];
+
+    // The line chart's tip dot is anchored to the newest close and overhangs the
+    // plot's right edge by its own radius, so the gutter has to be at least that
+    // wide or the dot lands under the y-axis strip (see tip_geometry.h). Only
+    // line mode needs it, and interpolating on morph_fade rather than switching
+    // on chart_type lets the few pixels of reflow ride the candles→line
+    // crossfade instead of stepping the instant the mode changes.
+    const float base_pad = theme.floats[VROOM_FLOAT_RIGHT_PADDING_PX];
+    float right_pad = base_pad;
+    if (theme.floats[VROOM_FLOAT_LINE_TIP_DOT] > 0.5f) {
+        const float wanted = std::max(
+            base_pad, vroom::tip_geometry::gutter_px(
+                          theme.floats[VROOM_FLOAT_LINE_WIDTH_PX]));
+        right_pad = base_pad + (wanted - base_pad) *
+                                   std::clamp(morph_fade, 0.f, 1.f);
+    }
+
     return vroom::Layout{
         width_px,
         height_px,
         vroom::axis_extent(axis_w, y_axis_collapse_t),
         vroom::axis_extent(theme.floats[VROOM_FLOAT_X_AXIS_HEIGHT_PX],
                            x_axis_collapse_t),
-        theme.floats[VROOM_FLOAT_RIGHT_PADDING_PX],
+        right_pad,
         theme.floats[VROOM_FLOAT_CANDLE_WIDTH_RATIO],
         0.05f,
         0.05f,
@@ -544,6 +565,23 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
     bg.setColor(theme.colors[VROOM_COLOR_BACKGROUND]);
     canvas->drawRect(SkRect::MakeWH(width_px, height_px), bg);
 
+    // 1b. Loading line, in place of the scene (stages 1 and 2). Above the
+    //     `candles.empty()` return because `loading` is authoritative: the host
+    //     may still be holding the previous asset's bars while the new one
+    //     loads, and the line has to win over them. Returning here is also what
+    //     suppresses the axis text, price badge, crosshair and indicator panes
+    //     until stage 3 releases the flag.
+    if (loading) {
+        if (loading_fade_in < 1.f) {
+            canvas->saveLayerAlphaf(nullptr, loading_fade_in);
+            vroom::loading_line::draw(canvas, *this, lay);
+            canvas->restore();
+        } else {
+            vroom::loading_line::draw(canvas, *this, lay);
+        }
+        return;
+    }
+
     if (candles.empty()) return;
 
     // 2. Visible slice + bounds + window_ms + geometry
@@ -562,6 +600,10 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
     const float candle_area_h = vroom::price_pane_bottom(lay);
     const float candle_right =
         width_px - lay.y_axis_width_px - lay.right_padding_px;
+    // The line tip is the one plot layer allowed past candle_right: its dot
+    // overhangs the newest candle's center, which the pinned-to-latest framing
+    // puts within a few pixels of that edge. It stops at the y-axis strip.
+    const float tip_clip_right = width_px - lay.y_axis_width_px;
 
     // 3. Update label fade state ONCE per frame — both gridlines and labels
     //    share these opacities so their animations stay in lockstep.
@@ -606,6 +648,15 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
     const std::size_t morph_n_draw = reshape ? morph_n : 0;
     const float morph_t = reshape ? interval_morph_t : 1.f;
 
+    // Line-mode tip marker, resolved by whichever branch below draws the price
+    // series and painted at step 6.5. It is the only plot layer that has to
+    // outlive the axis backgrounds, so it can't be drawn in place like the rest.
+    float tip_opacity = 0.f;
+    std::size_t tip_slots = 0;
+    const vroom::CandleSnapshot* tip_from = nullptr;
+    std::size_t tip_from_n = 0;
+    float tip_morph_t = 1.f;
+
     if (fade_out) {
         // First half: only what was captured, at the axis envelope opacity.
         // Layers with no snapshot (volume, liquidity, FVG, drawings) would
@@ -653,17 +704,11 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
                     theme.floats[VROOM_FLOAT_LINE_WIDTH_PX], fade * layer,
                     morph_from.data(), morph_n, 0.f,
                     theme.floats[VROOM_FLOAT_LINE_TENSION]);
-                if (theme.floats[VROOM_FLOAT_LINE_TIP_DOT] > 0.5f) {
-                    vroom::ma_overlay::draw_close_tip(
-                        canvas, lay, bounds, visible, 0, window_ms,
-                        visible_start_ms, candle_duration_ms, candle_right,
-                        candle_area_h, theme.colors[VROOM_COLOR_LINE],
-                        theme.colors[VROOM_COLOR_BACKGROUND],
-                        theme.floats[VROOM_FLOAT_LINE_WIDTH_PX], fade * layer,
-                        theme.floats[VROOM_FLOAT_LINE_TIP_PULSE] > 0.5f,
-                        tip_pulse_elapsed_s / vroom::tip_pulse::kPeriodSeconds,
-                        morph_from.data(), morph_n, 0.f);
-                }
+                tip_opacity = fade * layer;
+                tip_slots = 0;
+                tip_from = morph_from.data();
+                tip_from_n = morph_n;
+                tip_morph_t = 0.f;
             }
 
             // Over the candles, and the panes below them. One layer for both:
@@ -702,9 +747,19 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
             }
 
             // 4.5. Volume bars — drawn under the candles so candles z-index above.
-            if (volume_collapse_t < 1.f) {
+            //      Through a loading reveal they grow up off the axis on the
+            //      same clock as the candles, borrowing the collapse they
+            //      already have. They carry no morph snapshot of their own, so
+            //      without this they'd snap in at full height while the price
+            //      series is still a thread lying on the line. A render-time
+            //      override, not a state change: the host still owns the
+            //      collapse for the volume toggle.
+            const float vol_t = loading_line_revealing
+                ? std::max(volume_collapse_t, 1.f - interval_morph_t)
+                : volume_collapse_t;
+            if (vol_t < 1.f) {
                 vroom::volume::draw(canvas, visible, n, lay, theme, volume,
-                                    volume_collapse_t, volume_collapse_easing,
+                                    vol_t, volume_collapse_easing,
                                     window_ms, visible_start_ms,
                                     candle_duration_ms);
             }
@@ -753,20 +808,16 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
             vroom::drawings::draw(canvas, *this, lay, bounds, candle_right,
                                   candle_area_h);
 
-            // 5.8. Line-mode tip marker.
-            if (fade > 0.f && theme.floats[VROOM_FLOAT_LINE_TIP_DOT] > 0.5f) {
+            // 5.8. Line-mode tip marker. The saveLayer this branch may be
+            //      wrapped in doesn't reach step 6.5, so fold its alpha in.
+            if (fade > 0.f) {
                 const auto anchor = vroom::tip_anchor::at(
                     range.start, range.end, candles.size(), reshape);
-                vroom::ma_overlay::draw_close_tip(
-                    canvas, lay, bounds, visible, anchor.slot_count, window_ms,
-                    visible_start_ms, candle_duration_ms, candle_right,
-                    candle_area_h, theme.colors[VROOM_COLOR_LINE],
-                    theme.colors[VROOM_COLOR_BACKGROUND],
-                    theme.floats[VROOM_FLOAT_LINE_WIDTH_PX], fade,
-                    theme.floats[VROOM_FLOAT_LINE_TIP_PULSE] > 0.5f,
-                    tip_pulse_elapsed_s / vroom::tip_pulse::kPeriodSeconds,
-                    anchor.use_morph ? morph_src : nullptr,
-                    anchor.use_morph ? morph_n_draw : 0, morph_t);
+                tip_opacity = fade * (wrap ? axis_phase.opacity : 1.f);
+                tip_slots = anchor.slot_count;
+                tip_from = anchor.use_morph ? morph_src : nullptr;
+                tip_from_n = anchor.use_morph ? morph_n_draw : 0;
+                tip_morph_t = morph_t;
             }
 
             // Incoming fade: indicator panes share the scene opacity (and
@@ -782,6 +833,15 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
         if (wrap) canvas->restore();
     }
 
+    // 5.9. Loading line, stage 3. Over the series it handed off to, on the same
+    //      clock, so it reads as the bars peeling away from the line rather than
+    //      two things dissolving independently. Before the axis masks below,
+    //      since it belongs inside the plot.
+    if (loading_line_revealing) {
+        vroom::loading_line::draw_fading(canvas, *this, lay,
+                                         1.f - interval_morph_t);
+    }
+
     // 6. Axis backgrounds (mask any candle overflow). The x-axis separator
     //    line is intentionally omitted for now. The bottom strip anchors at
     //    x_axis_top (below any indicator pane) so it never paints over it.
@@ -796,6 +856,24 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
         SkRect::MakeXYWH(candle_right, 0, axis_block_w, height_px),
         axis_bg);
 
+    // 6.5. Line-mode tip marker, resolved at 5.8. After the masks because the
+    //      dot sits on the newest close, which a view following the latest bar
+    //      parks within a few pixels of candle_right — closer than the dot's own
+    //      radius — so it paints into the gutter the layout widened for it. The
+    //      clip still stops at the y-axis strip, so nothing here can reach the
+    //      price labels; the pulse ring simply ends there.
+    if (tip_opacity > 0.f && theme.floats[VROOM_FLOAT_LINE_TIP_DOT] > 0.5f) {
+        vroom::ma_overlay::draw_close_tip(
+            canvas, lay, bounds, visible, tip_slots, window_ms,
+            visible_start_ms, candle_duration_ms, candle_right, tip_clip_right,
+            candle_area_h, theme.colors[VROOM_COLOR_LINE],
+            theme.colors[VROOM_COLOR_BACKGROUND],
+            theme.floats[VROOM_FLOAT_LINE_WIDTH_PX], tip_opacity,
+            theme.floats[VROOM_FLOAT_LINE_TIP_PULSE] > 0.5f,
+            tip_pulse_elapsed_s / vroom::tip_pulse::kPeriodSeconds, tip_from,
+            tip_from_n, tip_morph_t);
+    }
+
     // 7. Labels (read from y_fades / x_fades, no state mutation here)
     vroom::labels::draw_y_labels(canvas, *this, lay, axis_bounds);
     vroom::labels::draw_x_labels(canvas, *this, lay, axis_start_ms, axis_end_ms);
@@ -805,8 +883,19 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
     //      Hidden during a fade's outgoing half: the close is already the new
     //      series and there is no snapshot to fade.
     if (!fade_out) {
-        vroom::price_indicator::draw(canvas, *this, lay, bounds,
-                                     candle_right, candle_area_h);
+        // Eased off the same capture the candles reshape through, so the badge
+        // rides the bar's close edge instead of landing on the new price a
+        // whole animation early. The pairing rule is the tip marker's: the
+        // capture only stands for the newest candle while that candle is the
+        // one at the right edge.
+        const auto price_anchor = vroom::tip_anchor::at(
+            range.start, range.end, candles.size(), reshape);
+        const vroom::CandleSnapshot* price_from =
+            (price_anchor.use_morph && morph_src && morph_n_draw > 0)
+                ? morph_src
+                : nullptr;
+        vroom::price_indicator::draw(canvas, *this, lay, bounds, candle_right,
+                                     candle_area_h, price_from, morph_t);
 
         // 7.54. Fair Value Gap labels — the boxes themselves are back behind
         //       the candles, but their text has to clear the bars it sits over.
@@ -882,6 +971,182 @@ void VroomChart::begin_frame() {
     // and a chart left open for hours would otherwise lose float precision on it.
     tip_pulse_elapsed_s =
         std::fmod(tip_pulse_elapsed_s + dt, vroom::tip_pulse::kPeriodSeconds);
+
+    if (loading) {
+        // Frozen once a capture exists: stage 2 morphs away from the phase the
+        // sine held when the data landed, and advancing it underneath would
+        // drag the morph's own start point around.
+        if (loading_animate && loading_line.empty()) {
+            loading_elapsed_s = std::fmod(loading_elapsed_s + dt,
+                                          vroom::loading_wave::kPeriodSeconds);
+        }
+        // Ramps regardless of `loading_animate`: reduced motion suppresses the
+        // wave's movement, not the appearance of the line itself, which would
+        // otherwise pop in at full strength.
+        constexpr float kFadeInSeconds = 0.3f;
+        loading_fade_in = std::min(1.f, loading_fade_in + dt / kFadeInSeconds);
+    }
+}
+
+void VroomChart::set_loading(bool on, bool animate) {
+    loading_animate = animate;
+    if (on == loading) return;  // a re-push of the same state isn't a restart
+    loading = on;
+
+    // Either direction abandons any hand-off in flight. Going false without
+    // passing through the two stages is the cancel path (fetch failed, asset
+    // switched again mid-load), and it should leave nothing behind.
+    loading_line.clear();
+    loading_line_t = 1.f;
+    loading_line_revealing = false;
+    if (!on) {
+        mark_dirty();
+        return;
+    }
+
+    loading_elapsed_s = 0.f;
+    loading_fade_in = 0.f;
+    mark_dirty();
+}
+
+// Visible slice + price bounds the two hand-off stages both need. Mirrors what
+// draw_chart computes in step 2; `n == 0` means there is nothing to hand off to.
+VroomChart::LoadingTarget VroomChart::loading_target() const {
+    LoadingTarget t{};
+    if (candles.empty()) return t;
+    const auto range = vroom::visible_indices(candles.data(), candles.size(),
+                                              visible_start_ms, visible_end_ms);
+    const std::size_t n = range.end - range.start;
+    if (n == 0) return t;
+    t.visible = candles.data() + range.start;
+    t.n = n;
+    t.bounds = price_bounds_manual
+        ? price_bounds
+        : vroom::auto_price_bounds(t.visible, n);
+    return t;
+}
+
+void VroomChart::begin_loading_morph() {
+    if (!loading) return;
+
+    const auto lay = layout();
+    const float area_w = vroom::candle_area_width(lay);
+    const auto target = loading_target();
+    if (target.n == 0 || area_w <= 0.f) return;
+
+    const int64_t window_ms = visible_end_ms - visible_start_ms;
+    const float elapsed = loading_animate ? loading_elapsed_s : 0.f;
+
+    const auto push = [&](float xf, float to_y) {
+        vroom::LinePoint p{};
+        p.x = xf;
+        // Sampling the sine at this vertex's own x is what makes the freeze
+        // invisible: the curve the user was watching passes through this point
+        // already, so stage 2 starts on the pixels stage 1 ended on.
+        p.from_y = vroom::loading_wave::y_frac(elapsed,
+                                               std::clamp(xf, 0.f, 1.f));
+        p.to_y = to_y;
+        loading_line.push_back(p);
+    };
+    // Mid-range, not mid-body: the bars grow outward symmetrically from this
+    // line, so anchoring on the body would leave one wick reaching further
+    // than the other.
+    const auto center_frac = [&](const ::VroomCandle& c) {
+        return static_cast<float>(
+            vroom::price_fraction(target.bounds, (c.high + c.low) * 0.5));
+    };
+    const auto center_x_frac = [&](const ::VroomCandle& c) {
+        return vroom::candle_center_x(lay, c.time_ms, candle_duration_ms,
+                                      visible_start_ms, window_ms) / area_w;
+    };
+
+    // Left to right, the order a polyline wants. (The reveal below indexes from
+    // the right instead, because that's what the morph machinery expects.)
+    loading_line.clear();
+    loading_line.reserve(target.n + 2);
+
+    // Spans the data doesn't reach — a short series in a wider window — are
+    // sampled at the idle curve's own resolution and flattened to the nearest
+    // candle's level. So the line still begins as the curve across the *whole*
+    // plot and eases into a level run leading into the series; leaving those
+    // spans out instead would snap the line's length on the first frame.
+    const int across = vroom::loading_wave::sample_count(area_w);
+    const float step = 1.f / static_cast<float>(across);
+    const float first_xf = center_x_frac(target.visible[0]);
+    const float last_xf = center_x_frac(target.visible[target.n - 1]);
+
+    for (int i = 0; static_cast<float>(i) * step < first_xf; ++i) {
+        push(static_cast<float>(i) * step, center_frac(target.visible[0]));
+    }
+    for (std::size_t i = 0; i < target.n; ++i) {
+        push(center_x_frac(target.visible[i]), center_frac(target.visible[i]));
+    }
+    for (int i = static_cast<int>(std::ceil(last_xf / step)); i <= across; ++i) {
+        push(static_cast<float>(i) * step,
+             center_frac(target.visible[target.n - 1]));
+    }
+
+    loading_line_t = 0.f;
+    // `loading` stays set: the axes, price badge and panes have no business
+    // appearing until the candles themselves do, in stage 3.
+    mark_dirty();
+}
+
+void VroomChart::begin_loading_reveal() {
+    if (!loading) return;
+    loading = false;
+
+    const auto lay = layout();
+    const float area_w = vroom::candle_area_width(lay);
+    const auto target = loading_target();
+    if (target.n == 0 || area_w <= 0.f) {
+        loading_line.clear();
+        mark_dirty();
+        return;
+    }
+
+    const int64_t window_ms = visible_end_ms - visible_start_ms;
+
+    // Right-to-left, matching how the morph machinery indexes slots (slot 0 =
+    // newest bar at the right edge).
+    morph_from.clear();
+    morph_from.reserve(target.n);
+    for (std::size_t slot = 0; slot < target.n; ++slot) {
+        const ::VroomCandle& c = target.visible[target.n - 1 - slot];
+        const float center = static_cast<float>(
+            vroom::price_fraction(target.bounds, (c.high + c.low) * 0.5));
+
+        vroom::CandleSnapshot s{};
+        s.x = vroom::candle_center_x(lay, c.time_ms, candle_duration_ms,
+                                     visible_start_ms, window_ms) / area_w;
+        // Every price collapsed onto the centre, so the slot starts as a
+        // zero-height sliver sitting on the line and the existing lerp is what
+        // grows it out to full open/high/low/close.
+        s.open = s.high = s.low = s.close = center;
+        s.bull = c.close >= c.open;
+        // Starts the colour blend from fully transparent rather than from the
+        // skeleton grey: the bar emerges from the line, so a grey body would
+        // just smear the line thicker on the first frames.
+        s.skeleton = true;
+        s.skeleton_alpha = 0.f;
+        morph_from.push_back(s);
+    }
+
+    morph_from_bounds = target.bounds;
+    interval_morph_t = 0.f;
+    // Slot-lerp, not crossfade: each bar has a counterpart to grow out of, so
+    // pairing column to column is what makes the line *become* the data instead
+    // of one scene dissolving into another.
+    interval_morph_fade = false;
+    // Keeps the axes out of the interval envelope (see labels::interval_phase),
+    // which is what the flag actually selects. A timeframe switch runs the
+    // outgoing ticks out and the new ones in; here there are no outgoing ticks
+    // — stages 1 and 2 draw no axis at all — so that envelope would hold the
+    // real labels back for the first half of the reveal. Per-label fades bring
+    // them up from nothing instead, in step with the bars.
+    morph_is_stream = true;
+    loading_line_revealing = true;
+    mark_dirty();
 }
 
 bool VroomChart::tip_pulse_active() const {
@@ -902,6 +1167,10 @@ bool VroomChart::is_animating_now() const {
     // The pulse never finishes on its own, so this is what keeps the host loops
     // requeueing frames for it.
     if (tip_pulse_active()) return true;
+    // Same deal for the loading line's wave, except a still line (reduced
+    // motion, once faded in) has nothing left to redraw and may go idle. The
+    // two hand-off stages are host-driven, so they need nothing here.
+    if (loading && (loading_animate || loading_fade_in < 1.f)) return true;
     for (const auto& f : y_fades) {
         if (f.opacity != f.target) return true;
     }

package/cpp/_core_src/chart.h

@@ -92,6 +92,42 @@ struct VroomChart {
     // is_animating_now keeps the host's redraw loop alive (see tip_pulse.h).
     float tip_pulse_elapsed_s = 0.f;
 
+    // --- loading line -------------------------------------------------------
+    // See loading_line.h for the three stages this state drives.
+    //
+    // Authoritative, not inferred: the host tells us it's loading *and* that it
+    // has no data, because an empty `candles` alone can't be trusted here. The
+    // hosts' data effects skip pushing an empty array (it would read as "hold
+    // the last frame"), so a chart mid-asset-switch can be loading while still
+    // holding the previous asset's bars — inferring from emptiness would show
+    // that stale series as if it were the new one's.
+    //
+    // True for stages 1 and 2 both: the line stands in for the chart until the
+    // candles actually take over in stage 3.
+    bool loading = false;
+    // Whether the wave travels. Cleared for reduced motion, which both freezes
+    // the line at phase 0 and keeps is_animating_now from pinning a host loop.
+    bool loading_animate = true;
+    // Phase of the wave, in seconds, advanced by begin_frame like the tip pulse
+    // above and wrapped for the same reason.
+    float loading_elapsed_s = 0.f;
+    // Fades the line in on arrival, so a chart that resolves instantly from
+    // cache doesn't flash a placeholder.
+    float loading_fade_in = 0.f;
+
+    // The line's morph vertices, left to right, captured when the data lands.
+    // Empty means stage 1 — nothing to morph toward yet — which is what
+    // loading_line::draw switches on.
+    std::vector<vroom::LinePoint> loading_line;
+    // Stage 2's progress, 0 = the frozen sine, 1 = through the candle centres.
+    // Parked at 1 when no morph is running.
+    float loading_line_t = 1.f;
+    // Set for stage 3, where the line rides `interval_morph_t` out on the same
+    // clock as the candles growing out of it. A flag rather than its own float
+    // because the two have to finish together to avoid a line left hanging over
+    // a settled chart.
+    bool loading_line_revealing = false;
+
     // Interval morph: the outgoing candle geometry captured when a timeframe
     // switch begins, indexed from the right of the visible slice (slot 0 =
     // newest). `interval_morph_fade` is the host's choice at capture time:
@@ -508,6 +544,38 @@ struct VroomChart {
     // draw_chart.
     void begin_frame();
 
+    // Enters or leaves the loading line. `animate` false pins it still for
+    // reduced motion. Entering restarts the phase and the fade-in; leaving
+    // outright (rather than through the two calls below) drops the line with no
+    // hand-off, which is what an error or a cancelled fetch wants.
+    void set_loading(bool on, bool animate);
+
+    // Stage 2. Call *after* pushing the real candles: it needs them to know
+    // where the line is heading. Freezes the sine at its current phase and
+    // pairs each vertex with the vertical centre of the candle that will occupy
+    // that column, then hands `loading_line_t` to the host to drive 0 → 1.
+    //
+    // Freezing rather than letting the wave run underneath is deliberate — a
+    // moving source makes the morph read as two animations fighting instead of
+    // one shape resolving.
+    void begin_loading_morph();
+
+    // The visible slice and price bounds the hand-off aims at, as draw_chart
+    // would resolve them. `n == 0` when there is nothing to hand off to.
+    struct LoadingTarget {
+        const ::VroomCandle* visible = nullptr;
+        std::size_t n = 0;
+        vroom::PriceBounds bounds{};
+    };
+    LoadingTarget loading_target() const;
+
+    // Stage 3. Captures every candle collapsed onto its own vertical centre at
+    // zero alpha and hands it to the interval-morph machinery, so the existing
+    // slot lerp grows each bar outward from the line while candles::draw blends
+    // its colour up out of nothing. Also releases `loading`, letting the axes,
+    // price badge and panes come back.
+    void begin_loading_reveal();
+
     // True when the line tip's pulse ring is on screen and looping. Gated on
     // line mode and on having data, so a chart that isn't showing the ring can
     // still go idle.
@@ -517,7 +585,8 @@ struct VroomChart {
     // SkPictureRecorder.
     void rebuild_chart_picture();
 
-    // True if any axis label is mid-fade, or the tip pulse is running. Used by
-    // the JS-side animation loop to know when to keep ticking.
+    // True if any axis label is mid-fade, the tip pulse is running, or the
+    // loading skeleton is waving. Used by the JS-side animation loop to know
+    // when to keep ticking.
     bool is_animating_now() const;
 };

package/cpp/_core_src/chart_facade.cpp

@@ -497,6 +497,28 @@ extern "C" void vroom_chart_begin_stream_morph(VroomChart* chart) {
     chart->interval_morph_t = 0.f;
 }
 
+extern "C" void vroom_chart_set_loading(VroomChart* chart, int32_t on,
+                                        int32_t animate) {
+    if (!chart) return;
+    chart->set_loading(on != 0, animate != 0);
+}
+
+extern "C" void vroom_chart_begin_loading_morph(VroomChart* chart) {
+    if (!chart) return;
+    chart->begin_loading_morph();
+}
+
+extern "C" void vroom_chart_set_loading_morph(VroomChart* chart, float t) {
+    if (!chart) return;
+    chart->loading_line_t = std::clamp(t, 0.f, 1.f);
+    chart->mark_dirty();
+}
+
+extern "C" void vroom_chart_begin_loading_reveal(VroomChart* chart) {
+    if (!chart) return;
+    chart->begin_loading_reveal();
+}
+
 extern "C" void vroom_chart_set_interval_morph(VroomChart* chart, float t) {
     if (!chart) return;
     chart->interval_morph_t = std::clamp(t, 0.f, 1.f);
@@ -507,6 +529,11 @@ extern "C" void vroom_chart_set_interval_morph(VroomChart* chart, float t) {
         chart->morph_lines.shrink_to_fit();
         chart->interval_morph_fade = false;
         chart->morph_is_stream = false;
+        // The loading line rides this same clock out (see draw_chart 5.9), so
+        // it has to be released here too or it would hang over a settled chart.
+        chart->loading_line_revealing = false;
+        chart->loading_line.clear();
+        chart->loading_line.shrink_to_fit();
     }
     chart->mark_dirty();
 }

package/cpp/_core_src/color_lerp.h

@@ -0,0 +1,28 @@
+// Blending two packed ARGB colors.
+//
+// Shared because anything anchored to the newest candle has to cross-fade when
+// that candle changes direction mid-morph: the body itself (candles.cpp) and
+// the current-price indicator (price_indicator.cpp) both flip between the bull
+// and bear accents, and a snap in either while the other eases is visible.
+//
+// Skia-free so the pure translation units can use it.
+
+#pragma once
+
+#include <cstdint>
+
+namespace vroom {
+
+// Channel-wise, including alpha. `t` is expected in [0,1].
+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;
+}
+
+}  // namespace vroom