react-native-vroom-chart 0.6.0 → 0.7.0

package/cpp/_core_src/macd_pane.cpp

@@ -20,17 +20,29 @@
 
 #include "chart.h"
 #include "fonts.h"
+#include "style_inherit.h"
 #include "theme.h"
 #include "viewport.h"
 
 namespace vroom::macd_pane {
 
 namespace {
+using vroom::style::color_or;
+using vroom::style::width_or;
+
 constexpr SkColor kMacdLine = 0xff2962ff;    // blue MACD line
 constexpr SkColor kSignalLine = 0xffff6d00;  // orange signal line
 constexpr SkColor kZeroLine = 0xff484f58;    // zero reference
 constexpr SkColor kDivider = 0xff21262d;     // pane separator
 constexpr float kPadFrac = 0.85f;            // keep curves off the band edges
+constexpr float kLineWidth = 1.5f;           // default stroke for both lines
+constexpr float kFadedAlpha = 0.5f;          // easing histogram bars
+
+// The easing histogram bars default to their own base color dimmed, which is
+// how the pane read before the colors were configurable.
+SkColor faded_or(uint32_t configured, SkColor base) {
+    return vroom::style::faded_or(configured, base, kFadedAlpha);
+}
 }  // namespace
 
 void draw(SkCanvas* canvas,
@@ -51,23 +63,25 @@ void draw(SkCanvas* canvas,
     const float band_h = pane_bottom - pane_top;
     if (band_h <= 0.f) return;
 
+    const VroomMACD& cfg = chart.macd;
     const float mid = (pane_top + pane_bottom) * 0.5f;
     // User y-zoom scales the amplitude about the zero line (mid). 1.0 = the
     // default auto-fit; >1 zooms in, <1 zooms out.
     const float half =
         band_h * 0.5f * kPadFrac * static_cast<float>(chart.macd_y_scale);
 
-    // Auto-scale symmetric about zero across all visible finite values.
+    // Auto-scale symmetric about zero across the finite values on show, so
+    // hiding a series lets the rest fill the pane.
     double scale = 0.0;
-    auto track = [&](const double* s) {
-        if (!s) return;
+    auto track = [&](const double* s, bool shown) {
+        if (!s || !shown) return;
         for (std::size_t i = 0; i < n; ++i) {
             if (std::isfinite(s[i])) scale = std::max(scale, std::abs(s[i]));
         }
     };
-    track(macd_visible);
-    track(signal_visible);
-    track(hist_visible);
+    track(macd_visible, cfg.line_visible != 0);
+    track(signal_visible, cfg.signal_visible != 0);
+    track(hist_visible, cfg.hist_visible != 0);
 
     auto y_for = [&](double v) -> float {
         if (scale <= 0.0) return mid;
@@ -90,34 +104,44 @@ void draw(SkCanvas* canvas,
     canvas->clipRect(SkRect::MakeLTRB(0.f, pane_top, candle_right, pane_bottom));
 
     // Zero line.
-    SkPaint zero;
-    zero.setAntiAlias(true);
-    zero.setColor(kZeroLine);
-    zero.setStrokeWidth(1.f);
-    canvas->drawLine(0.f, mid, candle_right, mid, zero);
-
-    // Histogram bars: from the zero line to y_for(hist), 4-color (green above /
-    // red below, full alpha when accelerating, half when decelerating).
-    if (hist_visible) {
+    if (cfg.zero_visible) {
+        SkPaint zero;
+        zero.setAntiAlias(true);
+        zero.setColor(color_or(cfg.zero_color, kZeroLine));
+        zero.setStrokeWidth(1.f);
+        canvas->drawLine(0.f, mid, candle_right, mid, zero);
+    }
+
+    // Histogram bars: from the zero line to y_for(hist), 4-color — above or
+    // below zero, each in a building and an easing shade. A bar is building
+    // while it grows away from zero and easing while it falls back toward it.
+    if (hist_visible && cfg.hist_visible) {
         const float body_w =
             vroom::candle_body_width(lay, window_ms, candle_duration_ms);
         const float half_body = body_w * 0.5f;
         const float zero_y = y_for(0.0);
-        const SkColor bull = chart.theme.colors[VROOM_COLOR_ACCENT_BULL];
-        const SkColor bear = chart.theme.colors[VROOM_COLOR_ACCENT_BEAR];
+        const SkColor up =
+            color_or(cfg.hist_up_color, chart.theme.colors[VROOM_COLOR_ACCENT_BULL]);
+        const SkColor down =
+            color_or(cfg.hist_down_color, chart.theme.colors[VROOM_COLOR_ACCENT_BEAR]);
+        const SkColor up_easing = faded_or(cfg.hist_up_fading_color, up);
+        const SkColor down_easing = faded_or(cfg.hist_down_fading_color, down);
         for (std::size_t i = 0; i < n; ++i) {
             const double h = hist_visible[i];
             if (!std::isfinite(h)) continue;
             const bool have_prev = i > 0 && std::isfinite(hist_visible[i - 1]);
             const double prev = have_prev ? hist_visible[i - 1] : h;
-            bool accelerating = true;
+            bool building = true;
             if (have_prev) {
-                accelerating = h >= 0.0 ? h >= prev : h <= prev;
+                building = h >= 0.0 ? h >= prev : h <= prev;
             }
             SkPaint bar;
             bar.setAntiAlias(true);
-            bar.setColor(h >= 0.0 ? bull : bear);
-            bar.setAlphaf(accelerating ? 1.0f : 0.5f);
+            if (h >= 0.0) {
+                bar.setColor(building ? up : up_easing);
+            } else {
+                bar.setColor(building ? down : down_easing);
+            }
             const float cx = vroom::candle_center_x(
                 lay, visible[i].time_ms, candle_duration_ms, visible_start_ms,
                 window_ms);
@@ -130,7 +154,7 @@ void draw(SkCanvas* canvas,
     }
 
     // MACD + signal lines.
-    auto stroke_series = [&](const double* series, SkColor color) {
+    auto stroke_series = [&](const double* series, SkColor color, float width) {
         if (!series) return;
         SkPathBuilder path;
         bool pen_down = false;
@@ -155,11 +179,17 @@ void draw(SkCanvas* canvas,
         line.setAntiAlias(true);
         line.setColor(color);
         line.setStyle(SkPaint::kStroke_Style);
-        line.setStrokeWidth(1.5f);
+        line.setStrokeWidth(width);
         canvas->drawPath(path.detach(), line);
     };
-    stroke_series(signal_visible, kSignalLine);
-    stroke_series(macd_visible, kMacdLine);  // MACD over signal
+    if (cfg.signal_visible) {
+        stroke_series(signal_visible, color_or(cfg.signal_color, kSignalLine),
+                      width_or(cfg.signal_width, kLineWidth));
+    }
+    if (cfg.line_visible) {  // MACD over signal
+        stroke_series(macd_visible, color_or(cfg.line_color, kMacdLine),
+                      width_or(cfg.line_width, kLineWidth));
+    }
 
     // Caption, top-left of the pane.
     auto tf = vroom::axis_typeface();
@@ -168,8 +198,8 @@ void draw(SkCanvas* canvas,
         font.setSubpixel(true);
         font.setEdging(SkFont::Edging::kSubpixelAntiAlias);
         char caption[40];
-        std::snprintf(caption, sizeof(caption), "MACD %d %d %d", chart.macd_fast,
-                      chart.macd_slow, chart.macd_signal);
+        std::snprintf(caption, sizeof(caption), "MACD %d %d %d", cfg.fast,
+                      cfg.slow, cfg.signal);
         SkRect cb;
         font.measureText(caption, std::strlen(caption), SkTextEncoding::kUTF8,
                          &cb);

package/cpp/_core_src/price_line_layout.h

@@ -17,7 +17,7 @@ constexpr float kPadV = 4.f;    // above/below the text
 constexpr float kCorner = 6.f;  // rounded-pill corner radius
 
 // Extra grab band above and below the stroke, so a 1px line is still an easy
-// target. Matches the tolerance TradingView's own chart libraries settled on.
+// target. Matches the tolerance mainstream chart libraries settled on.
 constexpr float kLineHitTolerance = 7.f;
 
 // Gap between the label group and the price axis when right-aligned. Wide enough

package/cpp/_core_src/rsi.cpp

@@ -2,6 +2,8 @@
 
 #include <cmath>  // std::nan, std::isfinite
 
+#include "series_ma.h"
+
 namespace vroom::rsi {
 
 namespace {
@@ -46,25 +48,9 @@ void compute(const ::VroomCandle* candles, std::size_t n, int period,
     }
 }
 
-void compute_ma(const std::vector<double>& rsi, int ma_period,
+void compute_ma(const std::vector<double>& rsi, int ma_period, int kind,
                 std::vector<double>& out) {
-    const std::size_t n = rsi.size();
-    out.assign(n, std::nan(""));
-    if (ma_period < 1) return;
-    const std::size_t P = static_cast<std::size_t>(ma_period);
-    if (n < P) return;
-    for (std::size_t i = P - 1; i < n; ++i) {
-        double sum = 0.0;
-        bool ok = true;
-        for (std::size_t k = i + 1 - P; k <= i; ++k) {
-            if (!std::isfinite(rsi[k])) {
-                ok = false;
-                break;
-            }
-            sum += rsi[k];
-        }
-        if (ok) out[i] = sum / static_cast<double>(P);
-    }
+    vroom::series_ma::smooth(rsi, kind, ma_period, out);
 }
 
 }  // namespace vroom::rsi

package/cpp/_core_src/rsi.h

@@ -21,12 +21,12 @@ namespace vroom::rsi {
 void compute(const ::VroomCandle* candles, std::size_t n, int period,
              std::vector<double>& out);
 
-// Simple moving average of an RSI series (the "RSI-based MA" / trendline that
-// most RSI indicators overlay; crossovers of RSI vs. this line are the common
-// signal). `ma_period` is clamped to >= 1. Fills `out` (resized to rsi.size()):
-// out[i] is the mean of rsi[i-ma_period+1 .. i] when all those are finite, else
-// NaN (so it's only defined once `ma_period` valid RSI values exist).
-void compute_ma(const std::vector<double>& rsi, int ma_period,
+// Moving average of an RSI series (the "RSI-based MA" / trendline that most RSI
+// indicators overlay; crossovers of RSI vs. this line are the common signal).
+// `kind` is a vroom::ma KIND_* value. `ma_period` is clamped to >= 1. Fills
+// `out` (resized to rsi.size()), NaN until `ma_period` valid RSI values exist —
+// either kind produces its first value at the same index.
+void compute_ma(const std::vector<double>& rsi, int ma_period, int kind,
                 std::vector<double>& out);
 
 }  // namespace vroom::rsi

package/cpp/_core_src/rsi_pane.cpp

@@ -20,17 +20,22 @@
 
 #include "chart.h"
 #include "fonts.h"
+#include "style_inherit.h"
 #include "theme.h"
 #include "viewport.h"
 
 namespace vroom::rsi_pane {
 
 namespace {
-constexpr SkColor kRsiLine = 0xff8957e5;    // violet RSI line (themable later)
+using vroom::style::color_or;
+using vroom::style::width_or;
+
+constexpr SkColor kRsiLine = 0xff8957e5;    // violet RSI line
 constexpr SkColor kRsiMaLine = 0xffd29922;  // amber RSI moving-average trendline
 constexpr SkColor kRefLine = 0xff30363d;    // band reference lines
 constexpr SkColor kDivider = 0xff21262d;    // pane separator
 constexpr SkScalar kDash[2] = {3.f, 3.f};
+constexpr float kLineWidth = 1.5f;          // default stroke for both lines
 }  // namespace
 
 void draw(SkCanvas* canvas,
@@ -53,6 +58,7 @@ void draw(SkCanvas* canvas,
     // Map 0..100 about the pane center so the user y-zoom scales symmetrically
     // around 50. z == 1 reproduces the default fit (0 -> pane_bottom, 100 ->
     // pane_top); z > 1 zooms in (taller), z < 1 zooms out (flatter).
+    const VroomRSI& cfg = chart.rsi;
     const float center_y = (pane_top + pane_bottom) * 0.5f;
     const float z = static_cast<float>(chart.rsi_y_scale);
     auto y_for = [&](double v) -> float {
@@ -78,19 +84,21 @@ void draw(SkCanvas* canvas,
     canvas->clipRect(SkRect::MakeLTRB(0.f, pane_top, candle_right, pane_bottom));
 
     // Configurable band reference lines (overbought / oversold).
-    SkPaint ref;
-    ref.setAntiAlias(true);
-    ref.setColor(kRefLine);
-    ref.setStrokeWidth(1.f);
-    ref.setPathEffect(SkDashPathEffect::Make(kDash, 0.f));
-    const float y_upper = y_for(chart.rsi_upper);
-    const float y_lower = y_for(chart.rsi_lower);
-    canvas->drawLine(0.f, y_upper, candle_right, y_upper, ref);
-    canvas->drawLine(0.f, y_lower, candle_right, y_lower, ref);
+    const float y_upper = y_for(cfg.upper_band);
+    const float y_lower = y_for(cfg.lower_band);
+    if (cfg.bands_visible) {
+        SkPaint ref;
+        ref.setAntiAlias(true);
+        ref.setColor(color_or(cfg.band_color, kRefLine));
+        ref.setStrokeWidth(1.f);
+        ref.setPathEffect(SkDashPathEffect::Make(kDash, 0.f));
+        canvas->drawLine(0.f, y_upper, candle_right, y_upper, ref);
+        canvas->drawLine(0.f, y_lower, candle_right, y_lower, ref);
+    }
 
     // Strokes a value series as a polyline; a NaN lifts the pen so undefined
     // leading values (i < period) leave a gap.
-    auto stroke_series = [&](const double* series, SkColor color) {
+    auto stroke_series = [&](const double* series, SkColor color, float width) {
         if (!series) return;
         SkPathBuilder path;
         bool pen_down = false;
@@ -115,11 +123,17 @@ void draw(SkCanvas* canvas,
         line.setAntiAlias(true);
         line.setColor(color);
         line.setStyle(SkPaint::kStroke_Style);
-        line.setStrokeWidth(1.5f);
+        line.setStrokeWidth(width);
         canvas->drawPath(path.detach(), line);
     };
-    stroke_series(rsi_visible, kRsiLine);
-    stroke_series(rsi_ma_visible, kRsiMaLine);  // trendline on top
+    if (cfg.line_visible) {
+        stroke_series(rsi_visible, color_or(cfg.line_color, kRsiLine),
+                      width_or(cfg.line_width, kLineWidth));
+    }
+    // Trendline on top. Its own visibility is handled upstream: a hidden
+    // trendline isn't computed, so the caller passes null.
+    stroke_series(rsi_ma_visible, color_or(cfg.ma_color, kRsiMaLine),
+                  width_or(cfg.ma_width, kLineWidth));
 
     // Caption, top-left of the pane.
     auto tf = vroom::axis_typeface();
@@ -129,7 +143,7 @@ void draw(SkCanvas* canvas,
         font.setEdging(SkFont::Edging::kSubpixelAntiAlias);
 
         char caption[24];
-        std::snprintf(caption, sizeof(caption), "RSI %d", chart.rsi_period);
+        std::snprintf(caption, sizeof(caption), "RSI %d", cfg.period);
         SkRect cb;
         font.measureText(caption, std::strlen(caption), SkTextEncoding::kUTF8,
                          &cb);
@@ -142,8 +156,9 @@ void draw(SkCanvas* canvas,
     canvas->restore();
 
     // 70 / 30 labels in the y-axis strip (drawn after the clip; the strip's
-    // background was already masked by draw_chart before this call).
-    if (tf) {
+    // background was already masked by draw_chart before this call). They label
+    // the band rules, so they go with them.
+    if (tf && cfg.bands_visible) {
         SkFont font(tf, chart.theme.floats[VROOM_FLOAT_AXIS_FONT_SIZE_PX]);
         font.setSubpixel(true);
         font.setEdging(SkFont::Edging::kSubpixelAntiAlias);
@@ -162,8 +177,8 @@ void draw(SkCanvas* canvas,
         };
         char ub[8];
         char lb[8];
-        std::snprintf(ub, sizeof(ub), "%.0f", chart.rsi_upper);
-        std::snprintf(lb, sizeof(lb), "%.0f", chart.rsi_lower);
+        std::snprintf(ub, sizeof(ub), "%.0f", cfg.upper_band);
+        std::snprintf(lb, sizeof(lb), "%.0f", cfg.lower_band);
         label(ub, y_upper);
         label(lb, y_lower);
     }

package/cpp/_core_src/series_ma.cpp

@@ -0,0 +1,64 @@
+#include "series_ma.h"
+
+#include <cmath>  // std::nan, std::isfinite
+#include <cstddef>
+
+#include "ma.h"
+
+namespace vroom::series_ma {
+
+void ema_seeded(const std::vector<double>& src, int period,
+                std::vector<double>& out) {
+    const std::size_t n = src.size();
+    out.assign(n, std::nan(""));
+    if (period < 1) return;
+    const std::size_t P = static_cast<std::size_t>(period);
+
+    std::size_t f = 0;
+    while (f < n && !std::isfinite(src[f])) ++f;
+    if (f >= n || f + P > n) return;  // not enough finite values to seed
+
+    const std::size_t seed = f + P - 1;
+    double sum = 0.0;
+    for (std::size_t k = f; k <= seed; ++k) sum += src[k];
+    double prev = sum / static_cast<double>(P);
+    out[seed] = prev;
+
+    const double alpha = 2.0 / (static_cast<double>(P) + 1.0);
+    for (std::size_t i = seed + 1; i < n; ++i) {
+        if (!std::isfinite(src[i])) break;  // series are contiguous after f
+        prev = alpha * src[i] + (1.0 - alpha) * prev;
+        out[i] = prev;
+    }
+}
+
+void sma_seeded(const std::vector<double>& src, int period,
+                std::vector<double>& out) {
+    const std::size_t n = src.size();
+    out.assign(n, std::nan(""));
+    if (period < 1) return;
+    const std::size_t P = static_cast<std::size_t>(period);
+
+    std::size_t f = 0;
+    while (f < n && !std::isfinite(src[f])) ++f;
+    if (f >= n || f + P > n) return;
+
+    double sum = 0.0;
+    for (std::size_t i = f; i < n; ++i) {
+        if (!std::isfinite(src[i])) break;  // series are contiguous after f
+        sum += src[i];
+        if (i >= f + P) sum -= src[i - P];
+        if (i >= f + P - 1) out[i] = sum / static_cast<double>(P);
+    }
+}
+
+void smooth(const std::vector<double>& src, int kind, int period,
+            std::vector<double>& out) {
+    if (kind == vroom::ma::KIND_SMA) {
+        sma_seeded(src, period, out);
+    } else {
+        ema_seeded(src, period, out);
+    }
+}
+
+}  // namespace vroom::series_ma

package/cpp/_core_src/series_ma.h

@@ -0,0 +1,30 @@
+// Moving averages over an already-computed series — pure computation, no Skia.
+//
+// Distinct from ma.h, which averages a *price* source off the candles. These
+// smooth a derived series that may open with a run of NaN warmup (the MACD
+// difference, an RSI line), so they skip that run and start counting from the
+// first finite value. Both smoothers therefore produce their first value at the
+// same index, which is what lets the MA kind be a config toggle.
+
+#pragma once
+
+#include <vector>
+
+namespace vroom::series_ma {
+
+// SMA-seeded EMA over `src`. Fills `out` (resized to src.size()): NaN until the
+// seed index, the seed = SMA of the first `period` finite values, then
+// ema = alpha*src + (1-alpha)*prev.
+void ema_seeded(const std::vector<double>& src, int period,
+                std::vector<double>& out);
+
+// Rolling SMA over `src`, skipping the same leading NaN run as ema_seeded.
+void sma_seeded(const std::vector<double>& src, int period,
+                std::vector<double>& out);
+
+// Dispatches on a vroom::ma KIND_* value: KIND_SMA picks sma_seeded, anything
+// else ema_seeded.
+void smooth(const std::vector<double>& src, int kind, int period,
+            std::vector<double>& out);
+
+}  // namespace vroom::series_ma

package/cpp/_core_src/style_inherit.h

@@ -0,0 +1,35 @@
+// Resolution of the indicator style "inherit sentinels".
+//
+// Every indicator style field is optional at the public API, so the marshalled
+// struct needs a value that means "the host didn't set this". A fully
+// transparent color and a non-positive width are those sentinels: they can't
+// name anything drawable, so they're free to carry the meaning. The renderer
+// swaps them for the theme value or the built-in default at draw time, which
+// keeps the fallback in one place instead of freezing it into every bridge.
+
+#pragma once
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdocumentation"
+#include "include/core/SkColor.h"
+#pragma clang diagnostic pop
+
+namespace vroom::style {
+
+inline SkColor color_or(uint32_t configured, SkColor fallback) {
+    return SkColorGetA(configured) == 0 ? fallback : configured;
+}
+
+// For an element whose default is another element's color dimmed — the easing
+// MACD histogram bars, say.
+inline SkColor faded_or(uint32_t configured, SkColor base, float alpha_frac) {
+    if (SkColorGetA(configured) != 0) return configured;
+    return SkColorSetA(base,
+                       static_cast<U8CPU>(SkColorGetA(base) * alpha_frac));
+}
+
+inline float width_or(float configured, float fallback) {
+    return configured > 0.f ? configured : fallback;
+}
+
+}  // namespace vroom::style

package/cpp/_core_src/theme.cpp

@@ -22,7 +22,7 @@ constexpr uint32_t kDefaultColors[VROOM_COLOR_COUNT_] = {
     0x00000000,  // WICK_BEAR   — transparent sentinel: inherit BEAR fill
     0xff26a69a,  // ACCENT_BULL — classic teal-green (price indicator, volume, MACD)
     0xffef5350,  // ACCENT_BEAR — classic red
-    0xffc9d1d9,  // LINE — line-chart close polyline; neutral foreground (AXIS_TEXT tone)
+    0xff8957e5,  // LINE — line-chart close polyline; violet, matching the RSI line
 };
 
 constexpr float kDefaultFloats[VROOM_FLOAT_COUNT_] = {
@@ -38,6 +38,7 @@ constexpr float kDefaultFloats[VROOM_FLOAT_COUNT_] = {
     0.f,    // WICK_ROUND_CAP — butt caps by default
     0.f,    // VOLUME_RADIUS_PX — square by default
     1.5f,   // LINE_WIDTH_PX — line-chart polyline stroke width
+    0.28f,  // LINE_GRADIENT_OPACITY — fill under the line, ramped to 0 at the pane bottom
 };
 
 }  // namespace

package/cpp/_core_src/viewport.cpp

@@ -10,8 +10,7 @@ float candle_body_width(const Layout& layout,
                         int64_t window_ms,
                         int64_t candle_duration_ms) {
     if (window_ms <= 0 || candle_duration_ms <= 0) return 0.f;
-    const float usable =
-        layout.width_px - layout.y_axis_width_px - layout.right_padding_px;
+    const float usable = candle_area_width(layout);
     const double slot = static_cast<double>(usable) *
         (static_cast<double>(candle_duration_ms) /
          static_cast<double>(window_ms));
@@ -24,8 +23,7 @@ float candle_center_x(const Layout& layout,
                       int64_t visible_start_ms,
                       int64_t window_ms) {
     if (window_ms <= 0) return 0.f;
-    const float usable =
-        layout.width_px - layout.y_axis_width_px - layout.right_padding_px;
+    const float usable = candle_area_width(layout);
     const double center_time =
         static_cast<double>(time_ms) +
         static_cast<double>(candle_duration_ms) * 0.5;
@@ -213,19 +211,45 @@ PriceBounds auto_price_bounds(const ::VroomCandle* candles, size_t count) {
     return {mid - half, mid + half};
 }
 
-float price_to_y(const Layout& layout,
-                 const PriceBounds& bounds,
-                 double price) {
+PriceBounds preserve_envelope_bounds(const PriceBounds& old_axis,
+                                     const PriceBounds& old_env,
+                                     const PriceBounds& new_env) {
+    const double axis_range = old_axis.max - old_axis.min;
+    const double old_span = old_env.max - old_env.min;
+    const double new_span = new_env.max - new_env.min;
+    if (axis_range <= 0.0 || old_span <= 0.0 || new_span <= 0.0) return old_axis;
+
+    // Same span/range ratio => same pixel height for the envelope.
+    const double new_range = axis_range * (new_span / old_span);
+    // Fraction of the axis (from the bottom) where the old envelope's midpoint
+    // sat; putting the new midpoint at the same fraction pins the envelope box.
+    const double t =
+        ((old_env.min + old_env.max) * 0.5 - old_axis.min) / axis_range;
+    const double new_mid = (new_env.min + new_env.max) * 0.5;
+    return {new_mid - t * new_range, new_mid + (1.0 - t) * new_range};
+}
+
+double price_fraction(const PriceBounds& bounds, double price) {
+    const double range = bounds.max - bounds.min;
+    // Degenerate range: everything sits at the band midpoint, which keeps
+    // price_to_y's flat-series fallback intact.
+    if (range <= 0.0) return 0.5;
+    return (price - bounds.min) / range;  // 0 at min, 1 at max
+}
+
+float y_at_fraction(const Layout& layout, double frac) {
     // The candle drawing area is the full height minus the x-axis strip and
     // any below-chart indicator pane.
     const float candle_area_h = price_pane_bottom(layout);
     const float top = candle_area_h * layout.top_padding_frac;
     const float bot = candle_area_h * (1.f - layout.bottom_padding_frac);
-    const float draw_h = bot - top;
-    const double range = bounds.max - bounds.min;
-    if (range <= 0.0) return (top + bot) * 0.5f;
-    const double t = (price - bounds.min) / range;  // 0..1, 0 at min
-    return bot - static_cast<float>(t) * draw_h;    // invert: high price → low y
+    return bot - static_cast<float>(frac) * (bot - top);  // invert: high → low y
+}
+
+float price_to_y(const Layout& layout,
+                 const PriceBounds& bounds,
+                 double price) {
+    return y_at_fraction(layout, price_fraction(bounds, price));
 }
 
 double y_to_price(const Layout& layout,

package/cpp/_core_src/viewport.h

@@ -34,6 +34,12 @@ inline float x_axis_top(const Layout& l) {
     return l.height_px - l.x_axis_height_px;
 }
 
+// Width available to candles: the full width minus the y-axis strip and the
+// right-hand gutter.
+inline float candle_area_width(const Layout& l) {
+    return l.width_px - l.y_axis_width_px - l.right_padding_px;
+}
+
 struct PriceBounds {
     double min;
     double max;
@@ -45,6 +51,27 @@ struct IndexRange {
     size_t end;
 };
 
+// One candle's geometry captured in normalized form for the interval morph:
+// x as a fraction of the candle-area width, prices as fractions of the price
+// band. Resolution-independent, so a resize mid-morph stays correct — and
+// independent of the price bounds, so the captured geometry keeps its pixel
+// position after a timeframe switch re-scales the y-axis.
+struct CandleSnapshot {
+    float x;
+    float open, high, low, close;
+    bool  bull;  // close >= open; selects the fill / wick / border color
+};
+
+// How many captured slots still contribute to a frame — 0 once the morph is
+// done, which releases the capture. Drawing routines take max(n, this) as their
+// slot count, pairing the new candle at slot k (visible[n - 1 - k]) with the
+// captured one (from[k]), both counting back from the right edge.
+inline std::size_t morph_from_count(const CandleSnapshot* from,
+                                    std::size_t from_n,
+                                    float morph_t) {
+    return (from && morph_t < 1.f) ? from_n : 0;
+}
+
 // Returns the indices of candles whose time_ms falls in [start_ms, end_ms].
 // When both are 0, returns the full range (Phase 1 default-everything behavior).
 // Candles must be sorted ascending by time_ms (invariant of the public API).
@@ -140,9 +167,32 @@ constexpr double kAutoYZoom = 1.5;
 // {0, 1} sentinel when count == 0 (callers keep their previous bounds).
 PriceBounds auto_price_bounds(const ::VroomCandle* candles, size_t count);
 
+// Rescales an axis range so a data envelope keeps the pixel height *and* the
+// pixel position it had before a data swap — the "scale lock" applied on a
+// timeframe switch, where the same price action re-buckets into a smaller or
+// larger high-low span.
+//
+// `old_axis` is the axis range that was in effect; `old_env` / `new_env` are the
+// visible high-low envelopes (as returned by price_bounds) before and after the
+// swap. Resolution-independent: both envelopes share the same draw band, so the
+// band height cancels out. Returns `old_axis` unchanged when any span is
+// degenerate.
+PriceBounds preserve_envelope_bounds(const PriceBounds& old_axis,
+                                     const PriceBounds& old_env,
+                                     const PriceBounds& new_env);
+
 // Map a price to y in pixels. y=0 is top of the chart.
 float price_to_y(const Layout& layout, const PriceBounds& bounds, double price);
 
+// Fraction of the price band a price sits at: 0 = bounds.min, 1 = bounds.max.
+// Returns 0.5 for a degenerate range, matching price_to_y's midpoint fallback.
+double price_fraction(const PriceBounds& bounds, double price);
+
+// The y of a band fraction. Splits price_to_y in two so geometry can be stored
+// independently of the price bounds (see CandleSnapshot):
+//   price_to_y(l, b, p) == y_at_fraction(l, price_fraction(b, p))
+float y_at_fraction(const Layout& layout, double frac);
+
 // Inverse of price_to_y: map a pixel y in the price pane back to a price.
 // Returns bounds.min for a degenerate range or draw band.
 double y_to_price(const Layout& layout, const PriceBounds& bounds, float y);