react-native-vroom-chart 0.16.0 → 0.18.0

package/cpp/_core_src/loading_line.cpp

@@ -0,0 +1,183 @@
+#include "loading_line.h"
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdocumentation"
+#include "include/core/SkCanvas.h"
+#include "include/core/SkColor.h"
+#include "include/core/SkPaint.h"
+#include "include/core/SkPath.h"
+#include "include/core/SkPathBuilder.h"
+#include "include/core/SkPoint.h"
+#pragma clang diagnostic pop
+
+#include <algorithm>
+#include <cstddef>
+#include <vector>
+
+#include "chart.h"
+#include "curve.h"
+#include "loading_wave.h"
+#include "theme.h"
+#include "viewport.h"
+
+namespace vroom::loading_line {
+
+namespace {
+
+constexpr float kStrokeWidthPx = 2.f;
+
+// Multiplies into whatever alpha the resolved color already carries.
+SkColor faded(SkColor c, float a) {
+    const float scaled = static_cast<float>(SkColorGetA(c)) *
+                         std::clamp(a, 0.f, 1.f);
+    return SkColorSetA(c, static_cast<U8CPU>(scaled + 0.5f));
+}
+
+// The loading line's color. A transparent `skeleton` inherits the gridline
+// color, the same sentinel convention the candle border and wick colors use.
+// The gridlines are the chart's existing vocabulary for "structure, not data",
+// which is exactly what the line is: drawing it in that tone keeps it from
+// reading as a series, without needing to be scaled down to stay quiet.
+SkColor stroke_color(const VroomChart& chart) {
+    const SkColor c = chart.theme.colors[VROOM_COLOR_SKELETON];
+    return SkColorGetA(c) == 0 ? chart.theme.colors[VROOM_COLOR_GRID] : c;
+}
+
+// Emits `pts` as a monotone cubic — the same curve the line chart draws (see
+// curve.h), so the loading line and the series it hands off to are shaped by
+// the same math and the transition has no renderer seam to hide.
+//
+// Monotone rather than a plain spline matters even here: by the end of the
+// morph these vertices *are* real price data, and an unconstrained curve would
+// overshoot a sharp reversal and bow outside the candle it is supposed to pass
+// through.
+SkPath spline(const std::vector<SkPoint>& pts) {
+    SkPathBuilder path;
+    if (pts.empty()) return path.detach();
+    path.moveTo(pts[0]);
+    // Below three points there is no interior vertex to fit a tangent to.
+    if (pts.size() < 3) {
+        for (std::size_t i = 1; i < pts.size(); ++i) path.lineTo(pts[i]);
+        return path.detach();
+    }
+
+    const auto secant_at = [&](std::size_t i) {
+        return curve::secant(pts[i].fX, pts[i].fY,
+                             pts[i + 1].fX, pts[i + 1].fY);
+    };
+    const auto tangent_at = [&](std::size_t i) {
+        if (i == 0) return secant_at(0);
+        if (i + 1 == pts.size()) return secant_at(pts.size() - 2);
+        return curve::monotone_tangent(secant_at(i - 1), secant_at(i));
+    };
+
+    for (std::size_t i = 0; i + 1 < pts.size(); ++i) {
+        // Flat or backwards spacing has no meaningful tangent, and curving
+        // through it would fold the line back on itself.
+        if (!(pts[i + 1].fX > pts[i].fX)) {
+            path.lineTo(pts[i + 1]);
+            continue;
+        }
+        const curve::Controls c = curve::segment_controls(
+            pts[i].fX, pts[i].fY, pts[i + 1].fX, pts[i + 1].fY,
+            tangent_at(i), tangent_at(i + 1), 1.f);
+        path.cubicTo(c.c1x, c.c1y, c.c2x, c.c2y, pts[i + 1].fX, pts[i + 1].fY);
+    }
+    return path.detach();
+}
+
+void stroke_path(SkCanvas* canvas,
+                 const VroomChart& chart,
+                 const SkPath& path,
+                 float alpha) {
+    SkPaint p;
+    p.setStyle(SkPaint::kStroke_Style);
+    p.setStrokeWidth(kStrokeWidthPx);
+    p.setStrokeCap(SkPaint::kRound_Cap);
+    p.setStrokeJoin(SkPaint::kRound_Join);
+    p.setAntiAlias(true);
+    p.setColor(faded(stroke_color(chart), alpha));
+    canvas->drawPath(path, p);
+}
+
+// Pinned to phase 0 under reduced motion, which leaves a still curve at
+// mid-breath rather than nothing — the placeholder is still worth showing.
+float phase(const VroomChart& chart) {
+    return chart.loading_animate ? chart.loading_elapsed_s : 0.f;
+}
+
+// Stage 1: the curve alone, sampled across the whole plot.
+SkPath idle_path(const VroomChart& chart, float area_w, float pane_h) {
+    const int samples = loading_wave::sample_count(area_w);
+    const float elapsed = phase(chart);
+    std::vector<SkPoint> pts;
+    pts.reserve(static_cast<std::size_t>(samples) + 1);
+    for (int i = 0; i <= samples; ++i) {
+        const float xf = static_cast<float>(i) / static_cast<float>(samples);
+        pts.push_back(SkPoint{xf * area_w,
+                              loading_wave::y_frac(elapsed, xf) * pane_h});
+    }
+    return spline(pts);
+}
+
+// Stages 2 and 3: the captured vertices, eased from the frozen curve toward the
+// candle centres. `t` of 1 is the shape the candles grow out of.
+SkPath morph_path(const VroomChart& chart,
+                  const Layout& lay,
+                  float area_w,
+                  float pane_h,
+                  float t) {
+    std::vector<SkPoint> pts;
+    pts.reserve(chart.loading_line.size());
+    for (const LinePoint& pt : chart.loading_line) {
+        const float from_y = pt.from_y * pane_h;
+        const float to_y = y_at_fraction(lay, pt.to_y);
+        pts.push_back(SkPoint{pt.x * area_w, from_y + (to_y - from_y) * t});
+    }
+    return spline(pts);
+}
+
+}  // namespace
+
+void draw(SkCanvas* canvas, const VroomChart& chart, const Layout& lay) {
+    if (!canvas) return;
+    const float area_w = candle_area_width(lay);
+    const float pane_h = price_pane_bottom(lay);
+    if (area_w <= 0.f || pane_h <= 0.f) return;
+
+    const float b = loading_wave::breath(phase(chart));
+
+    // A capture present means the data has landed and the line is on its way to
+    // the candle centres; absent means nothing has arrived yet.
+    if (chart.loading_line.empty()) {
+        stroke_path(canvas, chart, idle_path(chart, area_w, pane_h), b);
+        return;
+    }
+    // Settle out of the breath as the line resolves, so it holds still at full
+    // strength by the time it reaches the candle centres — subtle at the
+    // default gridline tone, but it stops a bright custom color from pulsing
+    // while the data lands. Stage 3 then fades from full, where draw_fading
+    // picks up.
+    const float alpha = b + (1.f - b) * chart.loading_line_t;
+    stroke_path(canvas, chart,
+                morph_path(chart, lay, area_w, pane_h, chart.loading_line_t),
+                alpha);
+}
+
+void draw_fading(SkCanvas* canvas,
+                 const VroomChart& chart,
+                 const Layout& lay,
+                 float alpha) {
+    if (!canvas || alpha <= 0.f) return;
+    if (chart.loading_line.empty()) return;
+    const float area_w = candle_area_width(lay);
+    const float pane_h = price_pane_bottom(lay);
+    if (area_w <= 0.f || pane_h <= 0.f) return;
+
+    // Held at the morph's end state: the line has already reached the centres,
+    // and the candles are growing out of exactly these pixels.
+    stroke_path(canvas, chart, morph_path(chart, lay, area_w, pane_h, 1.f),
+                alpha);
+}
+
+}  // namespace vroom::loading_line

package/cpp/_core_src/loading_line.h

@@ -0,0 +1,38 @@
+// The loading line: a single stroke across the plot standing in for a series
+// that hasn't arrived yet, and the bridge the real candles grow out of.
+//
+// Three stages, all drawn by the one function here:
+//
+//   1. idle    — a travelling sine across the full width (see loading_wave.h)
+//   2. morph   — that sine, frozen, easing into a polyline through the vertical
+//                centre of every candle about to be drawn
+//   3. reveal  — the polyline holding still at those centres while it fades
+//                out and the candles grow outward from it
+//
+// Stages 1 and 2 run instead of the chart, so the axis text, price badge,
+// crosshair and indicator panes stay suppressed until the data is really
+// there. Stage 3 runs over the top of the normal scene.
+
+#pragma once
+
+class SkCanvas;
+struct VroomChart;
+
+namespace vroom {
+struct Layout;
+}
+
+namespace vroom::loading_line {
+
+// Stages 1 and 2, in place of the chart. Which one it draws depends on whether
+// the chart holds a capture (see VroomChart::begin_loading_morph).
+void draw(SkCanvas* canvas, const VroomChart& chart, const Layout& lay);
+
+// Stage 3, over the settled scene. `alpha` is the line's remaining opacity, so
+// the caller can ride it on the same clock as the candles' growth.
+void draw_fading(SkCanvas* canvas,
+                 const VroomChart& chart,
+                 const Layout& lay,
+                 float alpha);
+
+}  // namespace vroom::loading_line

package/cpp/_core_src/loading_wave.h

@@ -0,0 +1,140 @@
+// The idle animation the loading line rides while a series is being fetched.
+// A position across the plot and an elapsed time in; a vertical offset and a
+// brightness out.
+//
+// Three sines, not one. A single sine is too regular to read as anything but a
+// test pattern — the eye finds the repeat immediately and the line stops
+// looking like it's waiting for something. Summing three frequencies that
+// aren't multiples of each other, each drifting at its own rate, gives a curve
+// that keeps rearranging itself.
+//
+// The other half of the effect is restraint: a small amplitude and a faint,
+// slowly breathing opacity. The line is a hint that the chart is alive, not a
+// feature competing with the data about to replace it.
+//
+// Approach adapted from Liveline (github.com/benjitaylor/liveline, MIT), whose
+// loading state solves the same problem well.
+//
+// Skia-free and header-only so the unit tests can cover it; see
+// tests/test_loading_wave.cpp.
+
+#pragma once
+
+#include <cmath>
+
+namespace vroom::loading_wave {
+
+constexpr float kTwoPi = 6.283185307179586f;
+
+// One component of the curve.
+struct Harmonic {
+    float freq;    // radians across the full plot width
+    float weight;  // share of the amplitude
+    float drift;   // multiple of the base phase speed
+};
+
+// Frequencies deliberately not integer multiples of one another: harmonics
+// would lock into one repeating shape, which is the thing being avoided. The
+// drifts are all multiples of a quarter only so the whole curve has an exact
+// period to wrap the phase clock on — see kPeriodSeconds.
+//
+// Four components, weighted toward the middle of the range, because the curve
+// has to sit convincingly next to candlesticks. A gentler two-or-three-crest
+// undulation suits a smooth live line chart, but against minute-resolution
+// price action it reads as decorative, and it makes the hand-off a real change
+// of shape rather than the same curve coming into focus.
+constexpr Harmonic kHarmonics[] = {
+    {14.0f, 0.40f, 1.00f},  // carrier — a little over two crests per screen
+    {25.0f, 0.28f, 1.25f},  // ripple, running ahead
+    {45.0f, 0.16f, 1.50f},  // fine texture, ahead again
+    {6.0f, 0.16f, 0.75f},   // a slow swell, running behind
+};
+constexpr int kHarmonicCount = 4;
+
+// Base phase speed. Slow on purpose: this plays under a chart that has nothing
+// to say yet, and anything quicker reads as activity.
+constexpr float kDriftRadPerSecond = 1.0f;
+
+// One full cycle of the *whole* curve. The drifts differ by quarters, so every
+// component returns to its starting phase only after four base cycles — which
+// is also why the shape takes ~25s to come back around. Callers wrap elapsed
+// time by this so a chart left loading doesn't lose float precision on the
+// phase, and wrapping here is seamless because it is a true period.
+constexpr float kPeriodSeconds = 4.f * kTwoPi / kDriftRadPerSecond;
+
+// Peak displacement from the centreline, as a fraction of the pane height. The
+// components rarely peak together, so the curve typically occupies well under
+// this — it is a bound, not the height it looks.
+constexpr float kAmplitudeFrac = 0.10f;
+
+// Breathing opacity. A pulse around full strength, not a dimmer: how quiet the
+// line reads is the *color's* job — it inherits the gridline tone by default —
+// and scaling an already-recessive grey down by a third again would leave the
+// curve indistinguishable from the background.
+constexpr float kBreathMin = 0.75f;
+constexpr float kBreathMax = 1.00f;
+// Ten breaths per curve cycle, so the breath wraps with the phase (~2.5s each)
+// and never syncs with the drift into one combined pulse.
+constexpr float kBreathCyclesPerPeriod = 10.f;
+
+// Offset at `x_frac` (0 = left edge of the plot, 1 = right) and `elapsed_s`, in
+// -1 .. 1. The weights sum to 1, so that range is tight. Phase runs as
+// (k*x - w*t), which walks the crests rightward — the direction the series
+// grows. Time outside one period is fine; sin wraps on its own.
+inline float at(float elapsed_s, float x_frac) {
+    const float base = kDriftRadPerSecond * elapsed_s;
+    float sum = 0.f;
+    for (int i = 0; i < kHarmonicCount; ++i) {
+        const Harmonic& h = kHarmonics[i];
+        sum += h.weight * std::sin(h.freq * x_frac - h.drift * base);
+    }
+    return sum;
+}
+
+// The curve's y as a fraction of the pane height (0 = pane top, 1 = bottom),
+// centred on the pane. This is the form the line capture stores, so a resize
+// mid-morph rescales instead of stranding the curve at old pixels.
+inline float y_frac(float elapsed_s, float x_frac) {
+    return 0.5f + kAmplitudeFrac * at(elapsed_s, x_frac);
+}
+
+// The line's opacity at `elapsed_s`, in kBreathMin .. kBreathMax.
+inline float breath(float elapsed_s) {
+    const float mid = (kBreathMin + kBreathMax) * 0.5f;
+    const float half = (kBreathMax - kBreathMin) * 0.5f;
+    return mid + half * std::sin(kTwoPi * kBreathCyclesPerPeriod * elapsed_s /
+                                 kPeriodSeconds);
+}
+
+// The tightest component in the table above.
+constexpr float max_freq() {
+    float m = 0.f;
+    for (int i = 0; i < kHarmonicCount; ++i) {
+        if (kHarmonics[i].freq > m) m = kHarmonics[i].freq;
+    }
+    return m;
+}
+
+// Vertices per cycle of that component needed to keep it from aliasing into a
+// shape the curve doesn't have. Ten is comfortably past the point where the
+// spline through the samples is indistinguishable from the real curve.
+constexpr float kSamplesPerCycle = 10.f;
+
+// How many vertices to sample the curve at across a plot `width_px` wide.
+//
+// The floor comes from the harmonic table rather than a literal, so retuning
+// the curve can't silently undersample it — a narrow chart still gets enough
+// vertices to resolve the finest component, it just spaces them more tightly.
+//
+// Both the idle curve and the morph capture size themselves through here, so
+// the two are always sampled the same way and the hand-off has no shape
+// discontinuity to hide.
+inline int sample_count(float width_px) {
+    const int floor_n =
+        static_cast<int>(max_freq() / kTwoPi * kSamplesPerCycle) + 1;
+    const int n = static_cast<int>(width_px / 8.f);
+    const int ceil_n = 4 * floor_n;
+    return n < floor_n ? floor_n : (n > ceil_n ? ceil_n : n);
+}
+
+}  // namespace vroom::loading_wave

package/cpp/_core_src/ma_overlay.cpp

@@ -19,6 +19,7 @@
 #include "curve.h"
 #include "gradient.h"
 #include "line_morph.h"
+#include "tip_geometry.h"
 #include "tip_pulse.h"
 #include "viewport.h"
 
@@ -129,10 +130,6 @@ inline std::size_t series_slots(std::size_t n, const LineMorph* from,
     return std::max(n, vroom::morph_line_count(from, morph_t));
 }
 
-// Width of the background-colored ring that separates the tip dot from the line
-// and from the pulse expanding out behind it.
-constexpr float kTipBorderPx = 2.f;
-
 // One vertex of the close polyline, in screen space. Slot `k` counts back from
 // the right edge (0 = the newest close), the pairing a timeframe switch
 // preserves.
@@ -419,6 +416,7 @@ void draw_close_tip(SkCanvas* canvas,
                     int64_t visible_start_ms,
                     int64_t candle_duration_ms,
                     float candle_right,
+                    float clip_right,
                     float candle_area_h,
                     uint32_t line_color,
                     uint32_t bg_color,
@@ -447,14 +445,21 @@ void draw_close_tip(SkCanvas* canvas,
     if (tip.fY < 0.f || tip.fY > candle_area_h) return;
     if (tip.fX < 0.f || tip.fX > candle_right) return;
 
-    // Scaling off the stroke keeps the marker proportionate at any line width;
-    // the floor stops a hairline chart from getting an invisible dot.
-    const float w = line_width > 0.f ? line_width : 1.5f;
-    const float dot_r = std::max(2.f, w * 1.5f);
-    const float border_r = dot_r + kTipBorderPx;
+    const auto geo = vroom::tip_geometry::of(line_width);
+    const float dot_r = geo.dot_r;
+    const float border_r = geo.border_r;
 
     canvas->save();
-    canvas->clipRect(SkRect::MakeLTRB(0.f, 0.f, candle_right, candle_area_h));
+    // Wider than the on-pane test above: the dot is anchored at the newest
+    // candle's center, which on a view pinned to the latest bar is closer to
+    // candle_right than the dot's own radius, so it has to reach into the gutter
+    // to draw in full. `clip_right` is the gutter's far side — the y-axis
+    // strip's edge — which the layout keeps wide enough for the dot (see
+    // tip_geometry::gutter_px). The pulse ring is much wider still and clips
+    // there; that is intended.
+    canvas->clipRect(
+        SkRect::MakeLTRB(0.f, 0.f, std::max(candle_right, clip_right),
+                         candle_area_h));
 
     // Ring first: the border paints over its inner edge, so it reads as
     // expanding out from underneath the dot rather than around it.

package/cpp/_core_src/ma_overlay.h

@@ -131,6 +131,12 @@ void draw_close_gradient(SkCanvas* canvas,
 //
 // `pulse_phase` is in cycles and wraps, so the caller can hand over elapsed time
 // divided by tip_pulse::kPeriodSeconds. Ignored unless `pulse`.
+//
+// `candle_right` bounds where the marked candle may be for the marker to draw at
+// all; `clip_right` bounds the paint, and is wider — the dot overhangs the plot
+// when the newest candle is at the right edge, so it paints into the gutter the
+// layout reserves for it. Callers must therefore draw the tip *after* the axis
+// backgrounds, which mask that gutter.
 void draw_close_tip(SkCanvas* canvas,
                     const Layout& lay,
                     const PriceBounds& bounds,
@@ -140,6 +146,7 @@ void draw_close_tip(SkCanvas* canvas,
                     int64_t visible_start_ms,
                     int64_t candle_duration_ms,
                     float candle_right,
+                    float clip_right,
                     float candle_area_h,
                     uint32_t line_color,
                     uint32_t bg_color,

package/cpp/_core_src/price_indicator.cpp

@@ -17,8 +17,10 @@
 #include <cstring>
 
 #include "chart.h"
+#include "color_lerp.h"
 #include "fonts.h"
 #include "price_format.h"
+#include "price_indicator_anim.h"
 #include "theme.h"
 #include "ticks.h"
 #include "viewport.h"
@@ -37,17 +39,29 @@ void draw(SkCanvas* canvas,
           const Layout& lay,
           const PriceBounds& bounds,
           float candle_right,
-          float candle_area_h) {
+          float candle_area_h,
+          const vroom::CandleSnapshot* morph_from,
+          float morph_t) {
     if (!canvas || chart.candles.empty()) return;
 
     // The "current price" is the latest period's close, regardless of whether
-    // that candle is horizontally in view.
+    // that candle is horizontally in view. Mid-morph it is wherever that close
+    // has eased to, so the badge stays on the candle's close edge.
     const ::VroomCandle& last = chart.candles.back();
     const bool bull = last.close >= last.open;
-    const SkColor color =
-        chart.theme.colors[bull ? VROOM_COLOR_ACCENT_BULL : VROOM_COLOR_ACCENT_BEAR];
-
-    const float y = vroom::price_to_y(lay, bounds, last.close);
+    const auto level = vroom::price_indicator_anim::level_at(
+        lay, bounds, last.close, bull, morph_from, chart.morph_from_bounds,
+        morph_t);
+
+    // Blended rather than switched, so a candle that changes direction under a
+    // tick carries the indicator's color with it instead of snapping — the same
+    // cross-fade the body itself does.
+    const SkColor color = static_cast<SkColor>(vroom::lerp_argb(
+        chart.theme.colors[bull ? VROOM_COLOR_ACCENT_BEAR : VROOM_COLOR_ACCENT_BULL],
+        chart.theme.colors[bull ? VROOM_COLOR_ACCENT_BULL : VROOM_COLOR_ACCENT_BEAR],
+        level.bull_t));
+
+    const float y = level.y;
     if (y < 0.f || y > candle_area_h) return;  // price scrolled off-range
 
     // Dotted line from the left edge to the y-axis separator.
@@ -73,7 +87,7 @@ void draw(SkCanvas* canvas,
     const vroom::PriceFormat fmt = vroom::with_tick_guard(
         chart.price_fmt,
         vroom::pick_price_interval(bounds.max - bounds.min, candle_area_h));
-    vroom::format_price(buf, sizeof(buf), last.close, fmt);
+    vroom::format_price(buf, sizeof(buf), level.price, fmt);
     const size_t len = std::strlen(buf);
 
     // Measure the tight glyph bounds (origin at the baseline) so we can center

package/cpp/_core_src/price_indicator.h

@@ -10,6 +10,7 @@ class SkCanvas;
 struct VroomChart;
 
 namespace vroom {
+struct CandleSnapshot;
 struct Layout;
 struct PriceBounds;
 }  // namespace vroom
@@ -19,11 +20,20 @@ namespace vroom::price_indicator {
 // Draws the line across [0, candle_right] at the latest close's y, plus the
 // price box in the y-axis strip. `candle_area_h` is the y of the x-axis
 // separator; the indicator is skipped if the close maps outside [0, candle_area_h].
+//
+// `morph_from` is the newest candle's outgoing capture (slot 0 of
+// VroomChart::morph_from), or null to draw the settled close. When present the
+// level eases across `morph_t` on the same clock as the candle it marks, so the
+// badge tracks the bar instead of jumping ahead of it — see
+// price_indicator_anim.h. Callers must only pass a capture that pairs with the
+// newest candle (tip_anchor.h).
 void draw(SkCanvas* canvas,
           const VroomChart& chart,
           const Layout& lay,
           const PriceBounds& bounds,
           float candle_right,
-          float candle_area_h);
+          float candle_area_h,
+          const CandleSnapshot* morph_from = nullptr,
+          float morph_t = 1.f);
 
 }  // namespace vroom::price_indicator

package/cpp/_core_src/price_indicator_anim.h

@@ -0,0 +1,81 @@
+// Where the current-price indicator sits mid-morph (see price_indicator.cpp).
+//
+// The indicator marks the latest close, so every tick moves it. Drawing it
+// straight from that close makes it jump while the candle it belongs to eases
+// into place, which reads as the badge coming loose from the chart. Instead it
+// rides the same capture the candles do: morph_from[0] is the newest candle's
+// outgoing geometry and interval_morph_t is the host's eased clock, so the
+// indicator lands on the candle's close edge on every frame rather than only at
+// the two ends.
+//
+// The y is deliberately the same expression close_vertex uses for slot 0
+// (ma_overlay.cpp). Matching it by construction, rather than by giving the two
+// the same duration, is what keeps the badge glued to the line chart's tip.
+//
+// Skia-free and header-only so the unit tests can cover it; see
+// tests/test_price_indicator_anim.cpp.
+
+#pragma once
+
+#include <algorithm>
+
+#include "viewport.h"
+
+namespace vroom::price_indicator_anim {
+
+// One frame of the indicator.
+struct Level {
+    float y;       // pixels, on the candle's close edge
+    double price;  // what the badge should read
+    float bull_t;  // 0 = the captured direction's color, 1 = the new one
+};
+
+namespace detail {
+inline float lerp(float a, float b, float t) { return a + (b - a) * t; }
+
+// The price a captured band fraction stood for. The capture stores fractions so
+// it survives a resize or a rescale, so recovering the price it came from needs
+// the band it was measured against — which is why morph_from_bounds is kept.
+inline double price_at_fraction(const PriceBounds& b, double frac) {
+    return b.min + frac * (b.max - b.min);
+}
+}  // namespace detail
+
+// `from` is the newest candle's capture, or null when nothing is morphing or
+// the capture doesn't pair with the newest candle (panned into history — see
+// tip_anchor.h, which the caller shares the pairing rule with). A null capture
+// gives the settled values, which is what the indicator drew before it
+// animated at all.
+//
+// `from_bounds` is the price band `from` was captured against
+// (VroomChart::morph_from_bounds).
+inline Level level_at(const Layout& lay,
+                      const PriceBounds& bounds,
+                      double close_new,
+                      bool bull_new,
+                      const CandleSnapshot* from,
+                      const PriceBounds& from_bounds,
+                      float morph_t) {
+    const float to_y = vroom::price_to_y(lay, bounds, close_new);
+    if (!from) return Level{to_y, close_new, 1.f};
+
+    const float t = std::clamp(morph_t, 0.f, 1.f);
+
+    // Two different spaces on purpose. The y interpolates in band fractions,
+    // because that is the space the capture is in and the space the candles
+    // move through — anything else would start the indicator off the pixel the
+    // close occupied last frame. The price interpolates in price space, so both
+    // ends read exactly the close they belong to even when this tick set a new
+    // extreme and rescaled the band underneath. The two agree whenever the band
+    // holds still, which is the overwhelmingly common case: y_at_fraction is
+    // affine, so a fraction lerp and a price lerp are then the same function.
+    const float y =
+        detail::lerp(vroom::y_at_fraction(lay, from->close), to_y, t);
+    const double close_old =
+        detail::price_at_fraction(from_bounds, from->close);
+
+    return Level{y, close_old + (close_new - close_old) * static_cast<double>(t),
+                 from->bull == bull_new ? 1.f : t};
+}
+
+}  // namespace vroom::price_indicator_anim

package/cpp/_core_src/theme.cpp

@@ -23,6 +23,11 @@ constexpr uint32_t kDefaultColors[VROOM_COLOR_COUNT_] = {
     0xff26a69a,  // ACCENT_BULL — classic teal-green (price indicator, volume, MACD)
     0xffef5350,  // ACCENT_BEAR — classic red
     0xff8957e5,  // LINE — line-chart close polyline; violet, matching the RSI line
+    // SKELETON — transparent sentinel: inherit GRID, the way BORDER_BULL and
+    // the wick colors inherit their fills. The gridlines are already the
+    // chart's tone for structure rather than data, which is what the loading
+    // line is, so matching them keeps it from being read as a series.
+    0x00000000,
 };
 
 constexpr float kDefaultFloats[VROOM_FLOAT_COUNT_] = {

package/cpp/_core_src/tip_geometry.h

@@ -0,0 +1,55 @@
+// How big the line chart's tip marker is, and how much gutter it needs.
+//
+// The dot marks the newest close, which on a view pinned to the latest bar sits
+// half a slot from the right edge of the plot — a few pixels. The dot's own
+// radius is larger than that, so it can only be drawn in full if it is allowed
+// to spill into the gutter between the plot and the y-axis strip. That makes the
+// marker's size a layout input, not just a paint detail, so the renderer
+// (draw_close_tip in ma_overlay.cpp) and the layout (VroomChart::layout) read it
+// from here rather than each carrying its own copy.
+//
+// The pulse ring is deliberately not part of this. At its widest it is 3.5x the
+// border radius, and reserving that much gutter would eat the plot; it is
+// allowed to clip against the axis.
+//
+// Skia-free and header-only so the unit tests can cover it; see
+// tests/test_tip_geometry.cpp.
+
+#pragma once
+
+#include <algorithm>
+
+namespace vroom::tip_geometry {
+
+// Width of the background-colored ring that separates the tip dot from the line
+// and from the pulse expanding out behind it.
+constexpr float kBorderPx = 2.f;
+
+// Gap left between the dot's outer edge and the y-axis strip. The dot touching
+// the price labels reads as a rendering fault even when nothing is clipped.
+constexpr float kClearPx = 4.f;
+
+struct Geometry {
+    float dot_r;     // the filled dot in the line's color
+    float border_r;  // the dot plus its background-colored halo
+};
+
+// Scaling off the stroke keeps the marker proportionate at any line width; the
+// floor stops a hairline chart from getting an invisible dot.
+inline Geometry of(float line_width) {
+    const float w = line_width > 0.f ? line_width : 1.5f;
+    const float dot_r = std::max(2.f, w * 1.5f);
+    return Geometry{dot_r, dot_r + kBorderPx};
+}
+
+// Gutter width that lets the dot draw in full with `kClearPx` to spare.
+//
+// draw_close_tip drops the marker once its center passes the plot's right edge,
+// so the center is at worst flush with that edge and the dot overhangs it by
+// exactly `border_r`. A gutter of that plus the clearance therefore makes "the
+// dot never touches the axis strip" true by construction, whatever the window.
+inline float gutter_px(float line_width) {
+    return of(line_width).border_r + kClearPx;
+}
+
+}  // namespace vroom::tip_geometry