react-native-vroom-chart 0.6.0 → 0.7.0

package/cpp/_core_src/chart.h

@@ -64,6 +64,21 @@ struct VroomChart {
     float morph_collapse = 0.f;
     float morph_fade = 0.f;
 
+    // Interval morph: the outgoing candle geometry captured when a timeframe
+    // switch begins, indexed from the right of the visible slice (slot 0 =
+    // newest) — the pairing the preserved slot grid guarantees. Stored as
+    // normalized fractions so it survives the new bounds and a resize.
+    // Empty when not morphing.
+    std::vector<vroom::CandleSnapshot> morph_from;
+    float interval_morph_t = 1.f;  // 1 = not morphing
+    // The pre-switch price scale and time window. The candle capture above is
+    // normalized against these, and the axes keep rendering their old ticks from
+    // them while fading out (see labels::interval_phase), so a label is never
+    // drawn at a position it didn't already occupy.
+    vroom::PriceBounds morph_from_bounds{0.0, 1.0};
+    int64_t morph_from_start_ms = 0;
+    int64_t morph_from_end_ms = 0;
+
     // Cached y-axis width in pixels, sized to fit the widest formatted price
     // label. 0 = uncomputed; layout() falls back to a width ratio.
     float axis_width_px = 0.f;
@@ -86,24 +101,27 @@ struct VroomChart {
     // RSI, drawn in a pane below the candles. rsi_cache is aligned to `candles`
     // (one value per candle, NaN where undefined) and recomputed lazily by
     // ensure_rsi() when rsi_dirty (set on any data or config change).
-    bool rsi_enabled = false;
-    int  rsi_period = 14;
-    double rsi_upper = 70.0;   // overbought band
-    double rsi_lower = 30.0;   // oversold band
-    bool rsi_ma_enabled = true;  // RSI-based moving average (trendline)
-    int  rsi_ma_period = 14;
+    // Defaults: 14-period RSI with 70/30 bands and a 14-period SMA trendline,
+    // every style field on its inherit sentinel.
+    VroomRSI rsi{0, 14, 70.0, 30.0, 14, 0, 1,
+                 0u, -1.f, 1,  // RSI line
+                 0u, -1.f,     // trendline
+                 0u, 1};       // band rules
     std::vector<double> rsi_cache;     // RSI per candle (NaN where undefined)
-    std::vector<double> rsi_ma_cache;  // SMA of rsi_cache (empty if MA off)
+    std::vector<double> rsi_ma_cache;  // MA of rsi_cache (empty if MA off)
     bool rsi_dirty = true;
     // User y-axis zoom for the RSI pane (drag on its y-axis strip). 1.0 = the
     // default 0..100 fit; >1 zooms in (taller), <1 zooms out. Anchored at 50.
     double rsi_y_scale = 1.0;
 
     // MACD, drawn in its own pane. Caches aligned to `candles` (NaN warmup).
-    bool macd_enabled = false;
-    int  macd_fast = 12;
-    int  macd_slow = 26;
-    int  macd_signal = 9;
+    // Defaults: 12/26/9 EMAs of close, every style field on its inherit
+    // sentinel so an untouched chart keeps the stock look.
+    VroomMACD macd{0, 12, 26, 9, 0, 1, 1,
+                   0u, -1.f, 1,  // MACD line
+                   0u, -1.f, 1,  // signal line
+                   1, 0u, 0u, 0u, 0u,  // histogram
+                   0u, 1};             // zero line
     std::vector<double> macd_cache;
     std::vector<double> macd_signal_cache;
     std::vector<double> macd_hist_cache;
@@ -128,10 +146,8 @@ struct VroomChart {
 
     // VWAP overlay (session anchor, configurable reset time). Single line on the
     // price pane; vwap_breaks marks session resets so the line lifts the pen.
-    bool vwap_enabled = false;
-    int  vwap_reset_offset_min = 0;       // session boundary offset from UTC midnight
-    uint32_t vwap_color = 0xff00bcd4;     // cyan
-    float vwap_width = 1.5f;
+    // Style fields sit on their inherit sentinel (cyan, 1.5px).
+    VroomVWAP vwap{0, 0, 0u, -1.f};
     std::vector<double> vwap_cache;
     std::vector<unsigned char> vwap_breaks;
     bool vwap_dirty = true;
@@ -150,6 +166,18 @@ struct VroomChart {
     std::vector<double> bb_lower_cache;
     bool bollinger_dirty = true;
 
+    // Volume bars (price pane, under the candles). On by default with every
+    // style field left on its inherit sentinel, so an untouched chart looks
+    // exactly as it did before the config existed. No cache — bar heights come
+    // straight off the visible candles' volume.
+    VroomVolume volume{1, -1.f, -1.f, -1.f, 0u, 0u};
+    // Staggered collapse of those bars, driven per-frame by the host animation
+    // loop: 0 = full height, 1 = all flat. Doubles as the visibility gate, since
+    // a fully collapsed chart draws nothing — set_volume snaps it to match
+    // `volume.enabled`, and the host overrides it while animating.
+    float volume_collapse_t = 0.f;
+    int32_t volume_collapse_easing = VROOM_EASING_IN_OUT;
+
     // --- drawings (annotations) --------------------------------------------
     // Committed drawings, anchored in data space so they track the candles on
     // pan/zoom. Drawn on the price pane above candles/overlays.
@@ -235,9 +263,9 @@ struct VroomChart {
     std::chrono::steady_clock::time_point last_anim_tick{};
     bool anim_started = false;
 
-    // dt of the current rebuild — populated by rebuild_chart_picture and
-    // consumed by the label-fade updaters. Public so the labels namespace
-    // can read it without a getter.
+    // dt of the current frame — populated by begin_frame and consumed by the
+    // label-fade updaters. Public so the labels namespace can read it without a
+    // getter.
     float last_dt_seconds = 0.f;
 
     // --- methods ------------------------------------------------------------
@@ -267,11 +295,18 @@ struct VroomChart {
     // indicator is enabled.
     void ensure_bollinger();
 
-    // The main drawing pass. Calls into the labels and candles modules.
+    // The main drawing pass. Calls into the labels and candles modules, and owns
+    // the per-frame animation clock (see begin_frame) so every host gets it —
+    // the web build draws straight through vroom_chart_draw rather than the
+    // SkPicture cache below.
     void draw_chart(SkCanvas* canvas);
 
+    // Per-frame animation bookkeeping: computes `last_dt_seconds`, which paces
+    // the label fades. Called at the top of draw_chart.
+    void begin_frame();
+
     // Re-records `chart_picture` by invoking draw_chart on a fresh
-    // SkPictureRecorder. Also computes `last_dt_seconds` for fade animation.
+    // SkPictureRecorder.
     void rebuild_chart_picture();
 
     // True if any axis label is mid-fade. Used by the JS-side animation loop

package/cpp/_core_src/chart_facade.cpp

@@ -63,6 +63,13 @@ int64_t damp_future_delta(int64_t delta_ms, int64_t cur_future,
 void apply_default_framing(VroomChart* chart) {
     if (chart->candles.empty()) return;
 
+    // A candle occupies the slot [time_ms, time_ms + duration) and draws centered
+    // in it, so the right edge of the view is the last slot's *end*. Pinning it to
+    // the last candle's time_ms instead puts that candle's center half a slot past
+    // the plot area, hiding the newest candle behind the y-axis strip.
+    const int64_t right_edge_ms =
+        chart->candles.back().time_ms + chart->candle_duration_ms;
+
     // Px-driven framing. Reuses the inversion from vroom_chart_scale_time_axis:
     // body_w = usable × (dur / window) × ratio  →  window = usable × dur × ratio / body_w.
     // Needs a valid layout (width_px); until size is known it falls through to
@@ -81,7 +88,7 @@ void apply_default_framing(VroomChart* chart) {
                 chart->candles.back().time_ms - chart->candles.front().time_ms;
             window_ms = std::clamp<int64_t>(window_ms, chart->candle_duration_ms,
                                             span > 0 ? span : window_ms);
-            chart->visible_end_ms = chart->candles.back().time_ms;
+            chart->visible_end_ms = right_edge_ms;
             chart->visible_start_ms = chart->visible_end_ms - window_ms;
             return;
         }
@@ -92,7 +99,7 @@ void apply_default_framing(VroomChart* chart) {
         ? chart->candles.size() - kDefaultVisible
         : 0;
     chart->visible_start_ms = chart->candles[start_idx].time_ms;
-    chart->visible_end_ms = chart->candles.back().time_ms;
+    chart->visible_end_ms = right_edge_ms;
 }
 
 // On the first manual-y gesture, adopt the on-screen auto-fit bounds so the
@@ -242,6 +249,10 @@ extern "C" void vroom_chart_reset_view(VroomChart* chart) {
     chart->visible_start_ms = 0;
     chart->visible_end_ms = 0;
     chart->price_bounds_manual = false;
+    // An asset switch reframes wholesale, so a slot-paired morph is meaningless
+    // here — drop any capture rather than leaving it to reshape the wrong data.
+    chart->morph_from.clear();
+    chart->interval_morph_t = 1.f;
     apply_default_framing(chart);
     vroom::labels::recompute_axis_width(*chart);
     if (chart->cb.on_viewport_changed) {
@@ -258,6 +269,104 @@ extern "C" void vroom_chart_reset_price_scale(VroomChart* chart) {
     chart->mark_dirty();
 }
 
+extern "C" bool vroom_chart_get_visible_price_envelope(VroomChart* chart,
+                                                       double* out_low,
+                                                       double* out_high) {
+    if (!chart) return false;
+    const auto idx = vroom::visible_indices(
+        chart->candles.data(), chart->candles.size(),
+        chart->visible_start_ms, chart->visible_end_ms);
+    if (idx.end <= idx.start) return false;
+    const auto env = vroom::price_bounds(chart->candles.data() + idx.start,
+                                         idx.end - idx.start);
+    if (out_low) *out_low = env.min;
+    if (out_high) *out_high = env.max;
+    return true;
+}
+
+extern "C" void vroom_chart_preserve_price_envelope(VroomChart* chart,
+                                                    double prev_low,
+                                                    double prev_high) {
+    // Auto mode already holds the envelope's pixel height constant (auto_price_
+    // bounds widens it by a fixed factor), so there is nothing to preserve.
+    if (!chart || !chart->price_bounds_manual) return;
+
+    double new_low = 0.0, new_high = 0.0;
+    const bool has_new =
+        vroom_chart_get_visible_price_envelope(chart, &new_low, &new_high);
+    if (!has_new || !(prev_high > prev_low) || !(new_high > new_low)) {
+        // Nothing to scale against — fall back to re-fitting the price scale.
+        vroom_chart_reset_price_scale(chart);
+        return;
+    }
+
+    chart->price_bounds = vroom::preserve_envelope_bounds(
+        chart->price_bounds, {prev_low, prev_high}, {new_low, new_high});
+    vroom::labels::recompute_axis_width(*chart);
+    chart->mark_dirty();
+}
+
+extern "C" void vroom_chart_begin_interval_morph(VroomChart* chart) {
+    if (!chart) return;
+    chart->morph_from.clear();
+    chart->interval_morph_t = 1.f;
+
+    const auto lay = chart->layout();
+    const float area_w = vroom::candle_area_width(lay);
+    const int64_t window_ms = chart->visible_end_ms - chart->visible_start_ms;
+    if (area_w <= 0.f || window_ms <= 0) return;
+
+    const auto idx = vroom::visible_indices(
+        chart->candles.data(), chart->candles.size(),
+        chart->visible_start_ms, chart->visible_end_ms);
+    const std::size_t n = idx.end - idx.start;
+    if (n == 0) return;
+    const ::VroomCandle* visible = chart->candles.data() + idx.start;
+
+    const auto bounds = chart->price_bounds_manual
+        ? chart->price_bounds
+        : vroom::auto_price_bounds(visible, n);
+
+    // Normalized so the capture is independent of both the price bounds (which
+    // the swap is about to replace) and the surface size (which may change
+    // mid-morph). Newest candle first, matching the slot indexing in
+    // candles::draw.
+    chart->morph_from.resize(n);
+    for (std::size_t k = 0; k < n; ++k) {
+        const auto& c = visible[n - 1 - k];
+        chart->morph_from[k] = vroom::CandleSnapshot{
+            vroom::candle_center_x(lay, c.time_ms, chart->candle_duration_ms,
+                                   chart->visible_start_ms, window_ms) / area_w,
+            static_cast<float>(vroom::price_fraction(bounds, c.open)),
+            static_cast<float>(vroom::price_fraction(bounds, c.high)),
+            static_cast<float>(vroom::price_fraction(bounds, c.low)),
+            static_cast<float>(vroom::price_fraction(bounds, c.close)),
+            c.close >= c.open,
+        };
+    }
+
+    // The scale the capture was taken against — the axes render their outgoing
+    // ticks from it, and it's about to be replaced on the chart itself.
+    chart->morph_from_bounds = bounds;
+    chart->morph_from_start_ms = chart->visible_start_ms;
+    chart->morph_from_end_ms = chart->visible_end_ms;
+
+    // Open the morph at 0 rather than leaving it at 1: the caller still has to
+    // push the new candles, and any frame painted in between should show the
+    // captured geometry — which is what the pre-switch frame looked like.
+    chart->interval_morph_t = 0.f;
+}
+
+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);
+    if (chart->interval_morph_t >= 1.f) {
+        chart->morph_from.clear();
+        chart->morph_from.shrink_to_fit();
+    }
+    chart->mark_dirty();
+}
+
 extern "C" void vroom_chart_pan(VroomChart* chart, float dx_px, float /*dy_px*/) {
     if (!chart || dx_px == 0.f || chart->candles.empty()) return;
 
@@ -481,7 +590,7 @@ extern "C" void vroom_chart_scale_time_axis(VroomChart* chart, float dx_px) {
 extern "C" void vroom_chart_resize_indicator_pane(VroomChart* chart, float dy_px) {
     if (!chart || dy_px == 0.f) return;
 
-    const int pane_count = (chart->rsi_enabled ? 1 : 0) + (chart->macd_enabled ? 1 : 0);
+    const int pane_count = (chart->rsi.enabled ? 1 : 0) + (chart->macd.enabled ? 1 : 0);
     if (pane_count == 0) return;  // nothing below the chart to resize
 
     const auto lay = chart->layout();
@@ -535,8 +644,8 @@ extern "C" void vroom_chart_scale_indicator_axis(VroomChart* chart, float y_px,
     struct ActivePane { int order; int type; };  // type: 0 = RSI, 1 = MACD
     ActivePane panes[2];
     int count = 0;
-    if (chart->rsi_enabled) panes[count++] = {chart->rsi_order, 0};
-    if (chart->macd_enabled) panes[count++] = {chart->macd_order, 1};
+    if (chart->rsi.enabled) panes[count++] = {chart->rsi_order, 0};
+    if (chart->macd.enabled) panes[count++] = {chart->macd_order, 1};
     if (count == 0) return;
     if (count == 2 && panes[0].order > panes[1].order) {
         const ActivePane tmp = panes[0];
@@ -1059,61 +1168,66 @@ extern "C" void vroom_chart_translate_drawing(VroomChart* chart, int32_t index,
 
 // ---- Indicators -----------------------------------------------------------
 
-extern "C" void vroom_chart_set_rsi(VroomChart* chart, bool enabled, int period,
-                                    double upper_band, double lower_band,
-                                    bool ma_enabled, int ma_period) {
-    if (!chart) return;
-    if (period < 2) period = 2;
-    if (ma_period < 1) ma_period = 1;
-    upper_band = std::clamp(upper_band, 0.0, 100.0);
-    lower_band = std::clamp(lower_band, 0.0, 100.0);
-
-    // Only the series-affecting fields force a recompute; band changes are
-    // render-only.
-    const bool recompute = chart->rsi_enabled != enabled ||
-                           chart->rsi_period != period ||
-                           chart->rsi_ma_enabled != ma_enabled ||
-                           chart->rsi_ma_period != ma_period;
-    const bool changed = recompute || chart->rsi_upper != upper_band ||
-                         chart->rsi_lower != lower_band;
-    if (!changed) return;
+extern "C" void vroom_chart_set_rsi(VroomChart* chart, const VroomRSI* cfg) {
+    if (!chart || !cfg) return;
+    VroomRSI next = *cfg;
+    next.enabled = next.enabled ? 1 : 0;
+    next.ma_visible = next.ma_visible ? 1 : 0;
+    next.line_visible = next.line_visible ? 1 : 0;
+    next.bands_visible = next.bands_visible ? 1 : 0;
+    if (next.period < 2) next.period = 2;
+    if (next.ma_period < 1) next.ma_period = 1;
+    next.upper_band = std::clamp(next.upper_band, 0.0, 100.0);
+    next.lower_band = std::clamp(next.lower_band, 0.0, 100.0);
+
+    // Only the series-affecting fields force a recompute; band levels, color,
+    // width, and visibility changes are render-only. The trendline is one of
+    // them: it isn't computed while hidden, so revealing it needs a recompute.
+    const VroomRSI& cur = chart->rsi;
+    const bool recompute = cur.enabled != next.enabled ||
+                           cur.period != next.period ||
+                           cur.ma_visible != next.ma_visible ||
+                           cur.ma_period != next.ma_period ||
+                           cur.ma_kind != next.ma_kind;
 
     // Pane order: claim the next slot on an off->on transition, release on off.
-    if (enabled && !chart->rsi_enabled) chart->rsi_order = chart->pane_seq++;
-    else if (!enabled) chart->rsi_order = -1;
-
-    chart->rsi_enabled = enabled;
-    chart->rsi_period = period;
-    chart->rsi_upper = upper_band;
-    chart->rsi_lower = lower_band;
-    chart->rsi_ma_enabled = ma_enabled;
-    chart->rsi_ma_period = ma_period;
+    if (next.enabled && !cur.enabled) chart->rsi_order = chart->pane_seq++;
+    else if (!next.enabled) chart->rsi_order = -1;
+
+    chart->rsi = next;
     if (recompute) chart->rsi_dirty = true;
     chart->mark_dirty();
 }
 
-extern "C" void vroom_chart_set_macd(VroomChart* chart, bool enabled, int fast,
-                                     int slow, int signal) {
-    if (!chart) return;
-    if (fast < 1) fast = 1;
-    if (slow < 1) slow = 1;
-    if (slow <= fast) slow = fast + 1;
-    if (signal < 1) signal = 1;
-
-    const bool recompute = chart->macd_enabled != enabled ||
-                           chart->macd_fast != fast ||
-                           chart->macd_slow != slow ||
-                           chart->macd_signal != signal;
-    if (!recompute) return;
-
-    if (enabled && !chart->macd_enabled) chart->macd_order = chart->pane_seq++;
-    else if (!enabled) chart->macd_order = -1;
-
-    chart->macd_enabled = enabled;
-    chart->macd_fast = fast;
-    chart->macd_slow = slow;
-    chart->macd_signal = signal;
-    chart->macd_dirty = true;
+extern "C" void vroom_chart_set_macd(VroomChart* chart, const VroomMACD* cfg) {
+    if (!chart || !cfg) return;
+    VroomMACD next = *cfg;
+    next.enabled = next.enabled ? 1 : 0;
+    next.line_visible = next.line_visible ? 1 : 0;
+    next.signal_visible = next.signal_visible ? 1 : 0;
+    next.hist_visible = next.hist_visible ? 1 : 0;
+    next.zero_visible = next.zero_visible ? 1 : 0;
+    if (next.fast < 1) next.fast = 1;
+    if (next.slow < 1) next.slow = 1;
+    if (next.slow <= next.fast) next.slow = next.fast + 1;
+    if (next.signal < 1) next.signal = 1;
+
+    // Only the series-affecting fields force a recompute; color, width, and
+    // visibility changes are render-only.
+    const VroomMACD& cur = chart->macd;
+    const bool recompute = cur.enabled != next.enabled ||
+                           cur.fast != next.fast ||
+                           cur.slow != next.slow ||
+                           cur.signal != next.signal ||
+                           cur.source != next.source ||
+                           cur.ma_kind != next.ma_kind ||
+                           cur.signal_ma_kind != next.signal_ma_kind;
+
+    if (next.enabled && !cur.enabled) chart->macd_order = chart->pane_seq++;
+    else if (!next.enabled) chart->macd_order = -1;
+
+    chart->macd = next;
+    if (recompute) chart->macd_dirty = true;
     chart->mark_dirty();
 }
 
@@ -1126,19 +1240,21 @@ extern "C" void vroom_chart_set_overlays(VroomChart* chart,
     chart->mark_dirty();
 }
 
-extern "C" void vroom_chart_set_vwap(VroomChart* chart, bool enabled,
-                                     int reset_offset_min, uint32_t color,
-                                     float width) {
-    if (!chart) return;
+extern "C" void vroom_chart_set_vwap(VroomChart* chart, const VroomVWAP* cfg) {
+    if (!chart || !cfg) return;
+    VroomVWAP next = *cfg;
+    next.enabled = next.enabled ? 1 : 0;
     // Keep the offset within a day [0, 1440).
-    int off = reset_offset_min % 1440;
-    if (off < 0) off += 1440;
-    const bool recompute =
-        chart->vwap_enabled != enabled || chart->vwap_reset_offset_min != off;
-    chart->vwap_enabled = enabled;
-    chart->vwap_reset_offset_min = off;
-    chart->vwap_color = color;
-    chart->vwap_width = width;
+    next.reset_offset_min %= 1440;
+    if (next.reset_offset_min < 0) next.reset_offset_min += 1440;
+
+    // Only the series-affecting fields force a recompute; color and width
+    // changes are render-only.
+    const VroomVWAP& cur = chart->vwap;
+    const bool recompute = cur.enabled != next.enabled ||
+                           cur.reset_offset_min != next.reset_offset_min;
+
+    chart->vwap = next;
     if (recompute) chart->vwap_dirty = true;
     chart->mark_dirty();
 }
@@ -1166,6 +1282,30 @@ extern "C" void vroom_chart_set_bollinger(VroomChart* chart,
     chart->mark_dirty();
 }
 
+extern "C" void vroom_chart_set_volume(VroomChart* chart,
+                                       const VroomVolume* cfg) {
+    if (!chart || !cfg) return;
+    VroomVolume next = *cfg;
+    next.enabled = next.enabled ? 1 : 0;
+    // Negative means "inherit", so only clamp the ranges once a value is set.
+    if (next.height_frac >= 0.f) next.height_frac = std::min(next.height_frac, 1.f);
+    if (next.opacity >= 0.f) next.opacity = std::min(next.opacity, 1.f);
+    chart->volume = next;
+    // Snap the collapse to the new target, the way set_chart_type snaps the
+    // candle↔line morph. A host that wants the toggle animated overrides this
+    // from its frame loop before the next paint.
+    chart->volume_collapse_t = next.enabled ? 0.f : 1.f;
+    chart->mark_dirty();
+}
+
+extern "C" void vroom_chart_set_volume_collapse(VroomChart* chart, float t,
+                                               int32_t easing) {
+    if (!chart) return;
+    chart->volume_collapse_t = std::clamp(t, 0.f, 1.f);
+    chart->volume_collapse_easing = easing;
+    chart->mark_dirty();
+}
+
 // ---- Direct draw (used by hosts that don't need the SkPicture cache) ------
 
 extern "C" void vroom_chart_draw(VroomChart* chart, SkCanvas* canvas) {

package/cpp/_core_src/gradient.cpp

@@ -0,0 +1,46 @@
+#include "gradient.h"
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdocumentation"
+#include "include/core/SkPoint.h"
+#include "include/core/SkShader.h"
+#include "include/core/SkTileMode.h"
+// See gradient.h: the two Skia versions we build against ship different
+// linear-gradient headers, and neither ships both.
+#if __has_include("include/effects/SkGradient.h")
+#  include "include/core/SkSpan.h"
+#  include "include/effects/SkGradient.h"
+#  define VROOM_SK_MODERN_GRADIENT 1
+#else
+#  include "include/effects/SkGradientShader.h"
+#  define VROOM_SK_MODERN_GRADIENT 0
+#endif
+#pragma clang diagnostic pop
+
+namespace vroom {
+
+sk_sp<SkShader> linear_alpha_ramp(const SkPoint pts[2],
+                                  SkColor base,
+                                  float a0,
+                                  float a1) {
+#if VROOM_SK_MODERN_GRADIENT
+    const float r = SkColorGetR(base) / 255.f;
+    const float g = SkColorGetG(base) / 255.f;
+    const float b = SkColorGetB(base) / 255.f;
+    const SkColor4f colors[2] = {SkColor4f{r, g, b, a0}, SkColor4f{r, g, b, a1}};
+    const SkGradient::Colors grad_colors(
+        SkSpan<const SkColor4f>(colors, 2), SkTileMode::kClamp);
+    const SkGradient grad(grad_colors, SkGradient::Interpolation{});
+    return SkShaders::LinearGradient(pts, grad);
+#else
+    const auto to_u8 = [](float a) {
+        return static_cast<U8CPU>(a * 255.f + 0.5f);
+    };
+    const SkColor colors[2] = {SkColorSetA(base, to_u8(a0)),
+                               SkColorSetA(base, to_u8(a1))};
+    return SkGradientShader::MakeLinear(pts, colors, nullptr, 2,
+                                        SkTileMode::kClamp);
+#endif
+}
+
+}  // namespace vroom

package/cpp/_core_src/gradient.h

@@ -0,0 +1,31 @@
+// Linear-gradient helper shared by the layers that fade a fill out.
+//
+// Skia's linear-gradient API differs across the Skia versions we build against:
+// the WASM build uses a newer Skia (SkGradient.h + SkShaders::LinearGradient),
+// while react-native-skia bundles an older one (SkGradientShader::MakeLinear).
+// Neither ships both headers, so the implementation selects whichever is present
+// and callers get one signature regardless of platform.
+
+#pragma once
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdocumentation"
+#include "include/core/SkColor.h"
+#include "include/core/SkRefCnt.h"
+#pragma clang diagnostic pop
+
+struct SkPoint;
+class SkShader;
+
+namespace vroom {
+
+// A gradient along pts[0] -> pts[1] holding `base`'s RGB while ramping alpha
+// from `a0` to `a1`. RGB is held constant on purpose: interpolating toward a
+// transparent black instead would darken the faded end into a grey smear.
+// Clamps at both ends, so the shader can safely cover more than the fill does.
+sk_sp<SkShader> linear_alpha_ramp(const SkPoint pts[2],
+                                  SkColor base,
+                                  float a0,
+                                  float a1);
+
+}  // namespace vroom