react-native-vroom-chart 0.16.0 → 0.17.0

package/cpp/VroomChartHostObject.cpp

@@ -58,6 +58,10 @@ std::vector<jsi::PropNameID> ChartHostObject::getPropertyNames(
   out.push_back(jsi::PropNameID::forAscii(rt, "preservePriceEnvelope"));
   out.push_back(jsi::PropNameID::forAscii(rt, "beginIntervalMorph"));
   out.push_back(jsi::PropNameID::forAscii(rt, "beginStreamMorph"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setLoading"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "beginLoadingMorph"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "setLoadingMorph"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "beginLoadingReveal"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setIntervalMorph"));
   out.push_back(jsi::PropNameID::forAscii(rt, "pan"));
   out.push_back(jsi::PropNameID::forAscii(rt, "translate"));
@@ -532,6 +536,83 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
         });
   }
 
+  if (name == "setLoading") {
+    // setLoading(on, animate?) — show or hide the loading line. `on` must mean
+    // "loading *and* holding no data"; the core takes it at face value.
+    // `animate` defaults to true; pass false for reduced motion.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setLoading"),
+        2,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 1) return jsi::Value::undefined();
+          const bool on = args[0].isBool() ? args[0].getBool()
+                                           : args[0].asNumber() != 0;
+          bool animate = true;
+          if (count >= 2 && !args[1].isUndefined() && !args[1].isNull()) {
+            animate = args[1].isBool() ? args[1].getBool()
+                                       : args[1].asNumber() != 0;
+          }
+          vroom_chart_set_loading(chart_, on ? 1 : 0, animate ? 1 : 0);
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "beginLoadingMorph") {
+    // beginLoadingMorph() — hand-off stage one: aim the loading line at the
+    // centres of the candles that just landed. Call *after* setCandles, then
+    // drive setLoadingMorph from 0 to 1.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "beginLoadingMorph"),
+        0,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* /*args*/,
+               size_t /*count*/) -> jsi::Value {
+          vroom_chart_begin_loading_morph(chart_);
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "setLoadingMorph") {
+    // setLoadingMorph(t) — advance stage one. 0 = the frozen sine, 1 = the
+    // polyline through the candle centres.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "setLoadingMorph"),
+        1,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* args,
+               size_t count) -> jsi::Value {
+          if (count < 1) return jsi::Value::undefined();
+          vroom_chart_set_loading_morph(
+              chart_, static_cast<float>(args[0].asNumber()));
+          return jsi::Value::undefined();
+        });
+  }
+
+  if (name == "beginLoadingReveal") {
+    // beginLoadingReveal() — hand-off stage two: collapse every candle onto the
+    // line at zero alpha so it grows outward from there. Call once stage one
+    // reaches 1, then drive setIntervalMorph from 0 to 1.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "beginLoadingReveal"),
+        0,
+        [this](jsi::Runtime& /*rt2*/,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* /*args*/,
+               size_t /*count*/) -> jsi::Value {
+          vroom_chart_begin_loading_reveal(chart_);
+          return jsi::Value::undefined();
+        });
+  }
+
   if (name == "setIntervalMorph") {
     // setIntervalMorph(t) — advance the capture toward the new candles. `t` is
     // pre-eased progress: 0 = the captured frame, 1 = settled (capture freed).

package/cpp/_core_include/vroom/vroom_chart.h

@@ -438,6 +438,9 @@ typedef enum {
     VROOM_COLOR_ACCENT_BULL,       // generic up color: price indicator, volume, MACD
     VROOM_COLOR_ACCENT_BEAR,       // generic down color
     VROOM_COLOR_LINE,              // line-chart-mode close-price polyline
+    // The loading line. Its own alpha is honored, then scaled by the fade-in
+    // and the stage-3 fade-out, so an opaque color here is the usual choice.
+    VROOM_COLOR_SKELETON,
     VROOM_COLOR_COUNT_
 } VroomColorKey;
 
@@ -586,6 +589,44 @@ void vroom_chart_begin_interval_morph(VroomChart* chart, int32_t mode);
 // translate.
 void vroom_chart_begin_stream_morph(VroomChart* chart);
 
+// Shows or hides the loading line: a single stroke drawn across the plot in a
+// slow travelling sine, for a chart that has been laid out but has no data yet.
+// Suppresses the axis text, price badge, crosshair and indicator panes for as
+// long as it's up.
+//
+// `on` must mean "loading *and* holding no data for the series being shown";
+// the core takes it at face value rather than checking the candle buffer,
+// because a host mid-asset-switch can still be holding the previous asset's
+// bars. Pass `animate` 0 for reduced motion: the line draws still, and the
+// chart is allowed to go idle instead of pinning a redraw loop.
+//
+// Passing 0 abandons any hand-off in flight, which is what a failed or
+// superseded fetch wants. To hand off to data instead, use the two stages
+// below.
+void vroom_chart_set_loading(VroomChart* chart, int32_t on, int32_t animate);
+
+// Hand-off stage one: reshapes the line into the series. Freezes the sine where
+// it is and aims each vertex at the vertical centre of the candle that will
+// occupy its column, so the line resolves into the silhouette of the data.
+//
+// Call *after* set_candles — it reads them to know where to aim — then drive
+// vroom_chart_set_loading_morph from 0 to 1. The axes and the candles stay
+// suppressed throughout; stage two brings them in. No-op if the line isn't up.
+void vroom_chart_begin_loading_morph(VroomChart* chart);
+
+// Advances stage one. `t` (clamped to 0..1) is the eased progress: 0 renders the
+// frozen sine, 1 the polyline through the candle centres.
+void vroom_chart_set_loading_morph(VroomChart* chart, float t);
+
+// Hand-off stage two: the candles take over. Captures each one collapsed onto
+// its own vertical centre at zero alpha and leaves the loading state, so the
+// bars grow outward from the line and their color fades up as it fades out.
+//
+// Call once stage one has reached 1, then drive vroom_chart_set_interval_morph
+// from 0 to 1 as usual — the line's fade-out rides that same clock, so the two
+// finish together. No-op if the line isn't up.
+void vroom_chart_begin_loading_reveal(VroomChart* chart);
+
 // Advances the morph started by either begin_*_morph above. `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.

package/cpp/_core_src/candles.cpp

@@ -9,6 +9,7 @@
 
 #include <algorithm>
 
+#include "color_lerp.h"
 #include "theme.h"
 #include "viewport.h"
 
@@ -21,18 +22,6 @@ 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);
@@ -90,6 +79,7 @@ void draw(SkCanvas* canvas,
 
     const uint32_t fill_bull = theme.colors[VROOM_COLOR_BULL];
     const uint32_t fill_bear = theme.colors[VROOM_COLOR_BEAR];
+    const uint32_t skeleton_color = theme.colors[VROOM_COLOR_SKELETON];
 
     const float body_r = theme.floats[VROOM_FLOAT_CANDLE_RADIUS_PX];
     const bool wick_round = theme.floats[VROOM_FLOAT_WICK_ROUND_CAP] > 0.5f;
@@ -207,10 +197,21 @@ void draw(SkCanvas* canvas,
         bool draw_border = bull ? draw_border_bull : draw_border_bear;
 
         const bool flip = frm && to && frm->bull != bull;
-        if (flip || alpha < 0.999f) {
+        // A slot handed over from the loading skeleton starts grey, whatever its
+        // direction — so it takes the per-slot path from a different origin
+        // color than a flip does, and overrides it when both apply.
+        const bool from_skeleton = frm && to && frm->skeleton;
+        if (flip || from_skeleton || 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);
+                if (from_skeleton) {
+                    // lerp_argb covers the alpha channel too, so the bar's
+                    // opacity rides in on the same blend as its color.
+                    c = lerp_argb(scale_alpha(skeleton_color, frm->skeleton_alpha),
+                                  c, morph_t);
+                } else if (flip) {
+                    c = lerp_argb(bull ? c_bear : c_bull, c, morph_t);
+                }
                 return scale_alpha(c, alpha);
             };
             slot_wick = *wick_p;

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;
     }