react-native-vroom-chart 0.1.2 → 0.1.3

package/cpp/_core_include/vroom/vroom_chart.h

@@ -49,6 +49,27 @@ typedef struct VroomOverlay {
     float    width;   // stroke width in px
 } VroomOverlay;
 
+// A drawing anchor in data space (so a drawing tracks the candles on pan/zoom).
+typedef struct VroomDrawPoint {
+    int64_t time_ms;  // epoch milliseconds (not snapped to a candle slot)
+    double  price;
+} VroomDrawPoint;
+
+// A committed line drawing: a two-point trendline on the price pane.
+typedef struct VroomDrawing {
+    VroomDrawPoint a;
+    VroomDrawPoint b;
+    uint32_t       color;  // 0xAARRGGBB
+    float          width;  // stroke width in px
+} VroomDrawing;
+
+// A continuous data coordinate at a pixel position (no candle snapping). Used to
+// translate a drawing-tool click into a data-space anchor.
+typedef struct VroomCoord {
+    int64_t time_ms;
+    double  price;
+} VroomCoord;
+
 // ---- Styling keys ---------------------------------------------------------
 
 typedef enum {
@@ -109,6 +130,24 @@ void vroom_chart_set_size(VroomChart* chart, float width_px, float height_px, fl
 // ---- Viewport -------------------------------------------------------------
 
 void vroom_chart_set_visible_range(VroomChart* chart, int64_t start_ms, int64_t end_ms);
+
+// Reads the current visible time window. Either out pointer may be null.
+// Both are 0 when the window is still uninitialized.
+void vroom_chart_get_visible_range(VroomChart* chart,
+                                   int64_t* out_start_ms, int64_t* out_end_ms);
+
+// Reset to the fresh-mount view: frame the most recent ~80 candles and
+// re-enable continuous y auto-fit (the price range follows the visible candles
+// until the next manual y gesture). Use when the data series is wholesale
+// replaced — e.g. switching assets. With no candles loaded, clears the window
+// to 0/0 so the next set_candles applies the default framing.
+void vroom_chart_reset_view(VroomChart* chart);
+
+// Re-enable continuous y auto-fit only; the time window is untouched. Use
+// after repositioning the window for a same-asset data swap (e.g. a timeframe
+// switch) so the price scale re-fits the newly visible candles.
+void vroom_chart_reset_price_scale(VroomChart* chart);
+
 void vroom_chart_pan(VroomChart* chart, float dx_px, float dy_px);
 // Directional zoom. scale_x scales the time window around focus_x_px (>1 =
 // narrower window, wider candles); scale_y scales the price range around
@@ -212,6 +251,33 @@ void vroom_chart_set_overlays(VroomChart* chart, const VroomOverlay* overlays,
 void vroom_chart_set_vwap(VroomChart* chart, bool enabled, int reset_offset_min,
                           uint32_t color, float width);
 
+// ---- Drawings (line annotations) ------------------------------------------
+
+// Replaces the full set of committed line drawings (data-anchored, so they track
+// the candles on pan/zoom). Pass count 0 to clear. Drawings render on the price
+// pane above the candles/overlays and below the axis labels & crosshair.
+void vroom_chart_set_drawings(VroomChart* chart, const VroomDrawing* drawings,
+                              size_t count);
+
+// Sets the transient in-progress "draft" the drawing tool shows while the user
+// places points. Node A is always shown; when `has_b`, node B is shown too.
+// `guide != 0` also draws the guideline A->B (the live line preview); `guide == 0`
+// draws node dots only (the committed segment already renders via set_drawings).
+// `color`/`width` style the guideline to match the eventual line.
+void vroom_chart_set_draft(VroomChart* chart, int64_t a_time, double a_price,
+                           bool has_b, int64_t b_time, double b_price,
+                           bool guide, uint32_t color, float width);
+
+// Clears the draft (hides the in-progress node dots / guideline).
+void vroom_chart_clear_draft(VroomChart* chart);
+
+// Fills *out with the continuous data coordinate (time_ms, price) at pixel
+// (x_px, y_px) using the free (non-snapped) mapping, and returns true. Returns
+// false (leaving *out untouched) when there are no candles or the viewport is
+// degenerate.
+bool vroom_chart_coord_at(VroomChart* chart, float x_px, float y_px,
+                          VroomCoord* out);
+
 // ---- Rendering ------------------------------------------------------------
 
 void vroom_chart_draw(VroomChart* chart, SkCanvas* canvas);

package/cpp/_core_src/chart.cpp

@@ -21,6 +21,7 @@
 #include "candles.h"
 #include "chart_internal.h"
 #include "crosshair.h"
+#include "drawings.h"
 #include "labels.h"
 #include "ma.h"
 #include "ma_overlay.h"
@@ -116,9 +117,9 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
     if (n == 0) return;
     const ::VroomCandle* visible = candles.data() + range.start;
 
-    const auto bounds = price_bounds_initialized
+    const auto bounds = price_bounds_manual
         ? price_bounds
-        : vroom::price_bounds(visible, n);
+        : vroom::auto_price_bounds(visible, n);
     const int64_t window_ms = visible_end_ms - visible_start_ms;
 
     const float candle_area_h = vroom::price_pane_bottom(lay);
@@ -176,6 +177,11 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
         }
     }
 
+    // 5.7. Drawing annotations (committed line tools + the in-progress draft).
+    //      On the price pane above the candles/overlays, below the axis labels.
+    vroom::drawings::draw(canvas, *this, lay, bounds, candle_right,
+                          candle_area_h);
+
     // 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.

package/cpp/_core_src/chart.h

@@ -46,7 +46,7 @@ struct VroomChart {
     float height_px = 0.f;
     float px_ratio = 1.f;
 
-    // 0/0 = uninitialized; set_candles defaults to last ~60 candles.
+    // 0/0 = uninitialized; set_candles defaults to last ~80 candles.
     int64_t visible_start_ms = 0;
     int64_t visible_end_ms = 0;
 
@@ -55,10 +55,13 @@ struct VroomChart {
     float axis_width_px = 0.f;
 
     // --- price bounds (y-axis state) ---------------------------------------
-    // Persistent across pans (panning preserves the price scale). Mutated
-    // only by pinch zoom, axis drags, vertical drag-translate.
+    // Two modes. Auto (price_bounds_manual == false, the default): the y-range
+    // continuously follows the visible candles each frame and `price_bounds`
+    // is ignored. Manual: the user has touched the y-axis (pinch zoom, axis
+    // drag, vertical drag-translate) and `price_bounds` is frozen until
+    // vroom_chart_reset_view / reset_price_scale re-enables auto mode.
     vroom::PriceBounds price_bounds{0.0, 1.0};
-    bool price_bounds_initialized = false;
+    bool price_bounds_manual = false;
 
     // --- crosshair (not yet drawn) -----------------------------------------
     bool   crosshair_active = false;
@@ -119,6 +122,24 @@ struct VroomChart {
     std::vector<unsigned char> vwap_breaks;
     bool vwap_dirty = true;
 
+    // --- drawings (line annotations) ---------------------------------------
+    // Committed two-point lines, anchored in data space so they track the
+    // candles on pan/zoom. Drawn on the price pane above candles/overlays.
+    std::vector<VroomDrawing> drawings;
+
+    // Transient in-progress "draft" the drawing tool shows while placing points.
+    // draft_a is always drawn (node dot); draft_b is drawn when draft_has_b.
+    // draft_guide draws the live guideline A->B; when false only node dots show
+    // (the committed segment renders via `drawings`). draft_color/draft_width
+    // style the guideline to match the eventual line.
+    bool           draft_active = false;
+    VroomDrawPoint draft_a{};
+    bool           draft_has_b = false;
+    VroomDrawPoint draft_b{};
+    bool           draft_guide = false;
+    uint32_t       draft_color = 0xff2962ff;
+    float          draft_width = 2.f;
+
     // --- theme --------------------------------------------------------------
     vroom::Theme theme;
 

package/cpp/_core_src/chart_facade.cpp

@@ -54,6 +54,33 @@ int64_t damp_future_delta(int64_t delta_ms, int64_t cur_future,
     return static_cast<int64_t>(static_cast<double>(delta_ms) * resist);
 }
 
+// Frame the default view: the most recent ~80 candles — a narrower x-window
+// so candles read wider. No-op when there are no candles.
+void apply_default_framing(VroomChart* chart) {
+    if (chart->candles.empty()) return;
+    constexpr size_t kDefaultVisible = 80;
+    const size_t start_idx = chart->candles.size() > kDefaultVisible
+        ? chart->candles.size() - kDefaultVisible
+        : 0;
+    chart->visible_start_ms = chart->candles[start_idx].time_ms;
+    chart->visible_end_ms = chart->candles.back().time_ms;
+}
+
+// On the first manual-y gesture, adopt the on-screen auto-fit bounds so the
+// gesture continues from exactly what the user sees. No-op once manual.
+void ensure_manual_price_bounds(VroomChart* chart) {
+    if (chart->price_bounds_manual) return;
+    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) {
+        chart->price_bounds = vroom::auto_price_bounds(
+            chart->candles.data() + idx.start, idx.end - idx.start);
+    }  // else: no visible candles — keep whatever bounds we had
+    chart->price_bounds_manual = true;
+    vroom::labels::recompute_axis_width(*chart);
+}
+
 }  // namespace
 
 // ---- Lifecycle -------------------------------------------------------------
@@ -85,40 +112,12 @@ extern "C" void vroom_chart_set_candles(VroomChart* chart, const VroomCandle* da
     }
     vroom::labels::recompute_axis_width(*chart);
 
-    // Default the visible window to the most recent ~80 candles when the
-    // consumer hasn't set one — a narrower x-window so candles read wider.
-    if (chart->visible_start_ms == 0 && chart->visible_end_ms == 0 &&
-        !chart->candles.empty()) {
-        constexpr size_t kDefaultVisible = 80;
-        const size_t start_idx = chart->candles.size() > kDefaultVisible
-            ? chart->candles.size() - kDefaultVisible
-            : 0;
-        chart->visible_start_ms = chart->candles[start_idx].time_ms;
-        chart->visible_end_ms = chart->candles.back().time_ms;
-    }
-
-    // Snap the price (y-axis) bounds to whatever's visible — but only on the
-    // first load. After they're initialized, leave them alone so live data
-    // updates (new / updated candles) preserve the user's pan/scale; from then
-    // on only zoom / axis-drags / vertical translate change them.
-    if (!chart->candles.empty() && !chart->price_bounds_initialized) {
-        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) {
-            auto b = vroom::price_bounds(
-                chart->candles.data() + idx.start, idx.end - idx.start);
-            // Widen the default y-window beyond the data's min/max so candles
-            // fill less vertical space (shorter candles, more headroom). 1.0 =
-            // snug; larger = wider. Only the default — zoom/axis-drag override.
-            constexpr double kDefaultYZoom = 1.5;
-            const double mid = (b.min + b.max) * 0.5;
-            const double half = (b.max - b.min) * 0.5 * kDefaultYZoom;
-            b.min = mid - half;
-            b.max = mid + half;
-            chart->price_bounds = b;
-            chart->price_bounds_initialized = true;
-        }
+    // Default the visible window when the consumer hasn't set one. The y-axis
+    // needs no equivalent: while the price scale is in auto mode the draw path
+    // fits it to the visible candles every frame, and once the user has taken
+    // it manual, live data updates must not disturb their pan/scale.
+    if (chart->visible_start_ms == 0 && chart->visible_end_ms == 0) {
+        apply_default_framing(chart);
     }
 
     chart->mark_dirty();
@@ -168,6 +167,35 @@ extern "C" void vroom_chart_set_visible_range(VroomChart* chart, int64_t start_m
     chart->mark_dirty();
 }
 
+extern "C" void vroom_chart_get_visible_range(VroomChart* chart,
+                                              int64_t* out_start_ms,
+                                              int64_t* out_end_ms) {
+    if (!chart) return;
+    if (out_start_ms) *out_start_ms = chart->visible_start_ms;
+    if (out_end_ms) *out_end_ms = chart->visible_end_ms;
+}
+
+extern "C" void vroom_chart_reset_view(VroomChart* chart) {
+    if (!chart) return;
+    chart->visible_start_ms = 0;
+    chart->visible_end_ms = 0;
+    chart->price_bounds_manual = false;
+    apply_default_framing(chart);
+    vroom::labels::recompute_axis_width(*chart);
+    if (chart->cb.on_viewport_changed) {
+        chart->cb.on_viewport_changed(chart->user_ctx, chart->visible_start_ms,
+                                      chart->visible_end_ms);
+    }
+    chart->mark_dirty();
+}
+
+extern "C" void vroom_chart_reset_price_scale(VroomChart* chart) {
+    if (!chart || !chart->price_bounds_manual) return;
+    chart->price_bounds_manual = false;
+    vroom::labels::recompute_axis_width(*chart);
+    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;
 
@@ -269,7 +297,8 @@ extern "C" void vroom_chart_translate(VroomChart* chart, float dx_px, float dy_p
     // Vertical: shift price bounds by the price-equivalent of dy_px. Range
     // stays constant. We divide by draw_h (the 90% slice of candle area
     // that's actually used for price → y) so translation feels 1:1.
-    if (dy_px != 0.f && chart->price_bounds_initialized) {
+    if (dy_px != 0.f && !chart->candles.empty()) {
+        ensure_manual_price_bounds(chart);
         const float candle_area_h = vroom::price_pane_bottom(chart->layout());
         const double draw_h = static_cast<double>(candle_area_h) * 0.9;
         if (draw_h > 0.0) {
@@ -296,7 +325,7 @@ extern "C" void vroom_chart_translate(VroomChart* chart, float dx_px, float dy_p
 
 extern "C" void vroom_chart_scale_price_axis(VroomChart* chart, float dy_px) {
     if (!chart || dy_px == 0.f) return;
-    if (!chart->price_bounds_initialized) return;
+    ensure_manual_price_bounds(chart);
 
     const double range = chart->price_bounds.max - chart->price_bounds.min;
     if (range <= 0.0) return;
@@ -417,7 +446,7 @@ extern "C" void vroom_chart_resize_indicator_pane(VroomChart* chart, float dy_px
     // Preserve candle pixel scale: scale the price range by the price-pane
     // height ratio, anchoring the top (max) price so existing candles stay put
     // and the newly revealed space opens at the bottom.
-    if (chart->price_bounds_initialized && old_pane_bottom > 0.f) {
+    if (chart->price_bounds_manual && old_pane_bottom > 0.f) {
         const float new_pane_bottom = content_h - new_band;
         const double scale = static_cast<double>(new_pane_bottom) /
                              static_cast<double>(old_pane_bottom);
@@ -502,7 +531,8 @@ extern "C" void vroom_chart_zoom(VroomChart* chart, float scale_x, float scale_y
 
     // --- Y (price) zoom around fy ------------------------------------------
     // scale_y > 1 (vertical pinch out) narrows the price range → taller candles.
-    if (scale_y > 0.f && scale_y != 1.f && chart->price_bounds_initialized) {
+    if (scale_y > 0.f && scale_y != 1.f && !chart->candles.empty()) {
+        ensure_manual_price_bounds(chart);
         const float candle_area_h = vroom::price_pane_bottom(chart->layout());
         const double range = chart->price_bounds.max - chart->price_bounds.min;
         if (candle_area_h > 0.f && range > 0.0) {
@@ -647,6 +677,60 @@ extern "C" bool vroom_chart_get_crosshair_info(VroomChart* chart,
     return true;
 }
 
+// ---- Drawings (line annotations) ------------------------------------------
+
+extern "C" void vroom_chart_set_drawings(VroomChart* chart,
+                                         const VroomDrawing* drawings,
+                                         size_t count) {
+    if (!chart) return;
+    chart->drawings.assign(drawings, drawings + count);
+    chart->mark_dirty();
+}
+
+extern "C" void vroom_chart_set_draft(VroomChart* chart, int64_t a_time,
+                                      double a_price, bool has_b, int64_t b_time,
+                                      double b_price, bool guide, uint32_t color,
+                                      float width) {
+    if (!chart) return;
+    chart->draft_active = true;
+    chart->draft_a = VroomDrawPoint{a_time, a_price};
+    chart->draft_has_b = has_b;
+    chart->draft_b = VroomDrawPoint{b_time, b_price};
+    chart->draft_guide = guide;
+    chart->draft_color = color;
+    chart->draft_width = width;
+    chart->mark_dirty();
+}
+
+extern "C" void vroom_chart_clear_draft(VroomChart* chart) {
+    if (!chart) return;
+    if (!chart->draft_active) return;
+    chart->draft_active = false;
+    chart->mark_dirty();
+}
+
+extern "C" bool vroom_chart_coord_at(VroomChart* chart, float x_px, float y_px,
+                                     VroomCoord* out) {
+    if (!chart || !out || chart->candles.empty()) return false;
+    const int64_t window_ms = chart->visible_end_ms - chart->visible_start_ms;
+    if (window_ms <= 0) return false;
+    const auto lay = chart->layout();
+    // Mirror draw_chart's bounds: the frozen manual scale, else the auto-fit
+    // over the visible slice — so y_to_price matches what's on screen.
+    const auto range = vroom::visible_indices(
+        chart->candles.data(), chart->candles.size(),
+        chart->visible_start_ms, chart->visible_end_ms);
+    const size_t n = range.end - range.start;
+    const auto bounds =
+        chart->price_bounds_manual
+            ? chart->price_bounds
+            : vroom::auto_price_bounds(chart->candles.data() + range.start, n);
+    out->time_ms =
+        vroom::time_at_x(lay, chart->visible_start_ms, window_ms, x_px);
+    out->price = vroom::y_to_price(lay, bounds, y_px);
+    return true;
+}
+
 // ---- Indicators -----------------------------------------------------------
 
 extern "C" void vroom_chart_set_rsi(VroomChart* chart, bool enabled, int period,

package/cpp/_core_src/drawings.cpp

@@ -0,0 +1,108 @@
+#include "drawings.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/SkPoint.h"
+#include "include/core/SkRect.h"
+#pragma clang diagnostic pop
+
+#include "chart.h"
+
+namespace vroom::drawings {
+
+namespace {
+// Node-dot styling (fixed for v1, not themed): a 4px black dot with a 2px blue
+// ring around it. kNodeFillRadius is the black core; the blue stroke is centered
+// at kNodeRingRadius so it sits just outside the core.
+constexpr SkColor kNodeFill = 0xff000000;       // black core
+constexpr SkColor kNodeBorder = 0xff2962ff;     // blue ring
+constexpr float   kNodeFillRadius = 2.f;        // 4px diameter
+constexpr float   kNodeBorderWidth = 2.f;
+constexpr float   kNodeRingRadius = 3.f;        // ring centered outside the core
+
+// Maps a data-space point to pixels in the price pane.
+SkPoint to_px(const VroomChart& chart, const Layout& lay, const PriceBounds& bounds,
+              int64_t window_ms, const VroomDrawPoint& p) {
+    const float x = vroom::x_at_time(lay, chart.visible_start_ms, window_ms, p.time_ms);
+    const float y = vroom::price_to_y(lay, bounds, p.price);
+    return SkPoint{x, y};
+}
+
+void draw_node(SkCanvas* canvas, SkPoint pt) {
+    SkPaint fill;
+    fill.setAntiAlias(true);
+    fill.setColor(kNodeFill);
+    canvas->drawCircle(pt.fX, pt.fY, kNodeFillRadius, fill);
+
+    SkPaint border;
+    border.setAntiAlias(true);
+    border.setColor(kNodeBorder);
+    border.setStyle(SkPaint::kStroke_Style);
+    border.setStrokeWidth(kNodeBorderWidth);
+    canvas->drawCircle(pt.fX, pt.fY, kNodeRingRadius, border);
+}
+}  // namespace
+
+void draw(SkCanvas* canvas,
+          const VroomChart& chart,
+          const Layout& lay,
+          const PriceBounds& bounds,
+          float candle_right,
+          float candle_area_h) {
+    if (!canvas || candle_right <= 0.f || candle_area_h <= 0.f) return;
+    const int64_t window_ms = chart.visible_end_ms - chart.visible_start_ms;
+    if (window_ms <= 0) return;
+
+    const SkRect clip = SkRect::MakeLTRB(0.f, 0.f, candle_right, candle_area_h);
+
+    // 1. Committed line segments, clipped to the candle area.
+    if (!chart.drawings.empty()) {
+        canvas->save();
+        canvas->clipRect(clip);
+        for (const VroomDrawing& d : chart.drawings) {
+            const SkPoint a = to_px(chart, lay, bounds, window_ms, d.a);
+            const SkPoint b = to_px(chart, lay, bounds, window_ms, d.b);
+            SkPaint line;
+            line.setAntiAlias(true);
+            line.setColor(static_cast<SkColor>(d.color));
+            line.setStyle(SkPaint::kStroke_Style);
+            line.setStrokeWidth(d.width > 0.f ? d.width : 2.f);
+            canvas->drawLine(a, b, line);
+        }
+        canvas->restore();
+    }
+
+    if (!chart.draft_active) return;
+
+    const SkPoint a = to_px(chart, lay, bounds, window_ms, chart.draft_a);
+    const bool has_b = chart.draft_has_b;
+    const SkPoint b =
+        has_b ? to_px(chart, lay, bounds, window_ms, chart.draft_b) : a;
+
+    // 2. Guideline preview (A->B), clipped to the candle area. Only while the
+    //    second point is still being placed (draft_guide); once committed, the
+    //    solid segment comes from chart.drawings instead.
+    if (chart.draft_guide && has_b) {
+        canvas->save();
+        canvas->clipRect(clip);
+        SkPaint guide;
+        guide.setAntiAlias(true);
+        guide.setColor(static_cast<SkColor>(chart.draft_color));
+        guide.setStyle(SkPaint::kStroke_Style);
+        guide.setStrokeWidth(chart.draft_width > 0.f ? chart.draft_width : 2.f);
+        canvas->drawLine(a, b, guide);
+        canvas->restore();
+    }
+
+    // 3. Node dots on top (not clipped, so an edge dot still renders fully).
+    //    While guiding (placing the second point) only the anchor dot shows; the
+    //    moving end is conveyed by the guideline. Once selected (committed) both
+    //    endpoints show dots.
+    draw_node(canvas, a);
+    if (has_b && !chart.draft_guide) draw_node(canvas, b);
+}
+
+}  // namespace vroom::drawings

package/cpp/_core_src/drawings.h

@@ -0,0 +1,34 @@
+// Drawing annotations — user-placed line tools rendered on the price pane.
+//
+// Two kinds of geometry are drawn here:
+//   * Committed lines (chart.drawings) — two-point trendlines anchored in data
+//     space, so they stay glued to the candles as the user pans/zooms.
+//   * The transient "draft" (chart.draft_*) — the in-progress node dots and the
+//     live guideline shown while the user is placing a line.
+//
+// Like ma_overlay / crosshair this is its own module so the chart orchestrator
+// stays thin. Drawn after the overlays and before the axis backgrounds.
+
+#pragma once
+
+#include "viewport.h"
+#include "vroom/vroom_chart.h"
+
+class SkCanvas;
+struct VroomChart;
+
+namespace vroom::drawings {
+
+// Draws the committed line drawings and the in-progress draft. `candle_right` is
+// the x of the y-axis strip and `candle_area_h` the price-pane bottom; geometry
+// is clipped to that rectangle so lines never bleed into the axis strips or the
+// indicator panes below. Node dots are exempt from the clip so a dot placed at
+// the very edge still renders fully.
+void draw(SkCanvas* canvas,
+          const VroomChart& chart,
+          const vroom::Layout& lay,
+          const vroom::PriceBounds& bounds,
+          float candle_right,
+          float candle_area_h);
+
+}  // namespace vroom::drawings

package/cpp/_core_src/labels.cpp

@@ -318,7 +318,7 @@ void recompute_axis_width(VroomChart& chart) {
         return;
     }
     double hi, lo;
-    if (chart.price_bounds_initialized) {
+    if (chart.price_bounds_manual) {
         hi = chart.price_bounds.max;
         lo = chart.price_bounds.min;
     } else if (!chart.candles.empty()) {

package/cpp/_core_src/viewport.cpp

@@ -35,6 +35,31 @@ float candle_center_x(const Layout& layout,
     return static_cast<float>(static_cast<double>(usable) * frac);
 }
 
+int64_t time_at_x(const Layout& layout,
+                  int64_t visible_start_ms,
+                  int64_t window_ms,
+                  float x_px) {
+    const float usable =
+        layout.width_px - layout.y_axis_width_px - layout.right_padding_px;
+    if (usable <= 0.f || window_ms <= 0) return visible_start_ms;
+    const double frac = static_cast<double>(x_px) / static_cast<double>(usable);
+    return visible_start_ms +
+           static_cast<int64_t>(std::llround(frac * static_cast<double>(window_ms)));
+}
+
+float x_at_time(const Layout& layout,
+                int64_t visible_start_ms,
+                int64_t window_ms,
+                int64_t time_ms) {
+    if (window_ms <= 0) return 0.f;
+    const float usable =
+        layout.width_px - layout.y_axis_width_px - layout.right_padding_px;
+    const double frac =
+        static_cast<double>(time_ms - visible_start_ms) /
+        static_cast<double>(window_ms);
+    return static_cast<float>(static_cast<double>(usable) * frac);
+}
+
 size_t snap_index_to_candle(const Layout& layout,
                             const ::VroomCandle* candles,
                             size_t count,
@@ -180,6 +205,14 @@ PriceBounds price_bounds(const ::VroomCandle* candles, size_t count) {
     return b;
 }
 
+PriceBounds auto_price_bounds(const ::VroomCandle* candles, size_t count) {
+    PriceBounds b = price_bounds(candles, count);
+    if (count == 0) return b;
+    const double mid = (b.min + b.max) * 0.5;
+    const double half = (b.max - b.min) * 0.5 * kAutoYZoom;
+    return {mid - half, mid + half};
+}
+
 float price_to_y(const Layout& layout,
                  const PriceBounds& bounds,
                  double price) {

package/cpp/_core_src/viewport.h

@@ -113,9 +113,33 @@ float snap_x_to_candle(const Layout& layout,
                        int64_t window_ms,
                        float x_px);
 
+// Free (non-snapped, non-candle-centered) mapping between time and pixel x,
+// used for drawing-tool endpoints that can sit anywhere — not just on a candle
+// slot. `x_at_time` is the exact inverse of `time_at_x`:
+//   frac = (time - start) / window;  x = usable * frac
+// where `usable` is the candle area width (width - y-axis - right padding).
+// Returns 0 / visible_start_ms respectively for a degenerate window/usable.
+int64_t time_at_x(const Layout& layout,
+                  int64_t visible_start_ms,
+                  int64_t window_ms,
+                  float x_px);
+float x_at_time(const Layout& layout,
+                int64_t visible_start_ms,
+                int64_t window_ms,
+                int64_t time_ms);
+
 // Min/max of (low..high) across the given range.
 PriceBounds price_bounds(const ::VroomCandle* candles, size_t count);
 
+// Widening applied to auto-fit price bounds so candles keep some headroom
+// instead of touching the pane edges. 1.0 = snug; larger = wider.
+constexpr double kAutoYZoom = 1.5;
+
+// price_bounds() widened about its midpoint by kAutoYZoom. This is the y-range
+// used whenever the price scale is in auto (follow-the-data) mode. Returns the
+// {0, 1} sentinel when count == 0 (callers keep their previous bounds).
+PriceBounds auto_price_bounds(const ::VroomCandle* candles, size_t count);
+
 // 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);
 

package/lib/index.d.mts

@@ -84,6 +84,38 @@ type VisibleRange = {
     /** Window end (inclusive), Unix epoch milliseconds. */
     endMs: number;
 };
+/**
+ * Chart interaction mode.
+ *   'pan'  — default: drag to pan, pinch/wheel to zoom, hover/long-press crosshair.
+ *   'draw' — left-clicks place drawing points; panning/zooming are suppressed.
+ */
+type ChartMode = 'pan' | 'draw';
+/** Active drawing tool while in `draw` mode. `null` draws nothing. */
+type DrawTool = null | 'line';
+/** A drawing anchor in data space, so it stays glued to the candles on pan/zoom. */
+type DrawPoint = {
+    /** Anchor time as Unix epoch milliseconds (not snapped to a candle slot). */
+    timeMs: number;
+    /** Anchor price. */
+    price: number;
+};
+/**
+ * A committed drawing. Pass an array of these via the `drawings` prop to render
+ * persisted annotations; the chart appends a new one (via `onDrawingComplete`)
+ * each time the user finishes drawing. For now only the `'line'` (two-point
+ * trendline) type exists.
+ */
+type Drawing = {
+    /** Stable unique id (the chart generates one for drawings it creates). */
+    id: string;
+    type: 'line';
+    /** The two endpoints, in data space. */
+    points: [DrawPoint, DrawPoint];
+    /** Line color (hex string or packed ARGB number). Default solid blue. */
+    color?: VroomColor;
+    /** Stroke width in px. Default 2. */
+    width?: number;
+};
 /** RSI indicator config. Rendered in a pane below the candles when enabled. */
 type RSIConfig = {
     enabled?: boolean;
@@ -147,6 +179,14 @@ type MACDConfig = {
 type VroomChartCoreProps = {
     /** OHLCV bars to render. The only required prop. */
     candles: Candle[];
+    /**
+     * Identity of the data series (e.g. "BTC-USD"). When it changes between
+     * renders the chart resets to the default view (most recent candles + price
+     * auto-fit), regardless of what the data heuristics conclude — the escape
+     * hatch for ambiguous switches like two assets trading at similar prices.
+     * Omit to rely on automatic detection from the candle data alone.
+     */
+    seriesKey?: string;
     /**
      * Explicit size overrides in logical px. When omitted, the chart fills its
      * parent (measured at runtime). Prefer layout-driven sizing via the
@@ -171,6 +211,27 @@ type VroomChartCoreProps = {
      * touch x. Default 40.
      */
     crosshairOffset?: number;
+    /**
+     * Interaction mode. Default `'pan'`. Set to `'draw'` (with a `tool`) to let
+     * the user place drawing points; panning/zooming are suppressed while drawing.
+     */
+    mode?: ChartMode;
+    /** Active drawing tool while in `draw` mode. Default `null` (draws nothing). */
+    tool?: DrawTool;
+    /**
+     * Committed drawings to render, anchored to data so they track the candles on
+     * pan/zoom. This is a controlled prop: append the value the chart hands you in
+     * `onDrawingComplete` to persist it.
+     */
+    drawings?: Drawing[];
+    /** Fired with the finished drawing when the user completes one. */
+    onDrawingComplete?: (drawing: Drawing) => void;
+    /**
+     * Fired when the chart wants the mode changed — e.g. it requests `'pan'` after
+     * the user clicks away from a just-drawn line. Since `mode` is controlled, the
+     * host should apply the requested mode.
+     */
+    onModeChange?: (mode: ChartMode) => void;
     onCrosshair?: (e: CrosshairEvent) => void;
     onViewportChange?: (startMs: number, endMs: number) => void;
 };

package/lib/index.d.ts

@@ -84,6 +84,38 @@ type VisibleRange = {
     /** Window end (inclusive), Unix epoch milliseconds. */
     endMs: number;
 };
+/**
+ * Chart interaction mode.
+ *   'pan'  — default: drag to pan, pinch/wheel to zoom, hover/long-press crosshair.
+ *   'draw' — left-clicks place drawing points; panning/zooming are suppressed.
+ */
+type ChartMode = 'pan' | 'draw';
+/** Active drawing tool while in `draw` mode. `null` draws nothing. */
+type DrawTool = null | 'line';
+/** A drawing anchor in data space, so it stays glued to the candles on pan/zoom. */
+type DrawPoint = {
+    /** Anchor time as Unix epoch milliseconds (not snapped to a candle slot). */
+    timeMs: number;
+    /** Anchor price. */
+    price: number;
+};
+/**
+ * A committed drawing. Pass an array of these via the `drawings` prop to render
+ * persisted annotations; the chart appends a new one (via `onDrawingComplete`)
+ * each time the user finishes drawing. For now only the `'line'` (two-point
+ * trendline) type exists.
+ */
+type Drawing = {
+    /** Stable unique id (the chart generates one for drawings it creates). */
+    id: string;
+    type: 'line';
+    /** The two endpoints, in data space. */
+    points: [DrawPoint, DrawPoint];
+    /** Line color (hex string or packed ARGB number). Default solid blue. */
+    color?: VroomColor;
+    /** Stroke width in px. Default 2. */
+    width?: number;
+};
 /** RSI indicator config. Rendered in a pane below the candles when enabled. */
 type RSIConfig = {
     enabled?: boolean;
@@ -147,6 +179,14 @@ type MACDConfig = {
 type VroomChartCoreProps = {
     /** OHLCV bars to render. The only required prop. */
     candles: Candle[];
+    /**
+     * Identity of the data series (e.g. "BTC-USD"). When it changes between
+     * renders the chart resets to the default view (most recent candles + price
+     * auto-fit), regardless of what the data heuristics conclude — the escape
+     * hatch for ambiguous switches like two assets trading at similar prices.
+     * Omit to rely on automatic detection from the candle data alone.
+     */
+    seriesKey?: string;
     /**
      * Explicit size overrides in logical px. When omitted, the chart fills its
      * parent (measured at runtime). Prefer layout-driven sizing via the
@@ -171,6 +211,27 @@ type VroomChartCoreProps = {
      * touch x. Default 40.
      */
     crosshairOffset?: number;
+    /**
+     * Interaction mode. Default `'pan'`. Set to `'draw'` (with a `tool`) to let
+     * the user place drawing points; panning/zooming are suppressed while drawing.
+     */
+    mode?: ChartMode;
+    /** Active drawing tool while in `draw` mode. Default `null` (draws nothing). */
+    tool?: DrawTool;
+    /**
+     * Committed drawings to render, anchored to data so they track the candles on
+     * pan/zoom. This is a controlled prop: append the value the chart hands you in
+     * `onDrawingComplete` to persist it.
+     */
+    drawings?: Drawing[];
+    /** Fired with the finished drawing when the user completes one. */
+    onDrawingComplete?: (drawing: Drawing) => void;
+    /**
+     * Fired when the chart wants the mode changed — e.g. it requests `'pan'` after
+     * the user clicks away from a just-drawn line. Since `mode` is controlled, the
+     * host should apply the requested mode.
+     */
+    onModeChange?: (mode: ChartMode) => void;
     onCrosshair?: (e: CrosshairEvent) => void;
     onViewportChange?: (startMs: number, endMs: number) => void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-vroom-chart",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Mobile-first Skia candlestick chart for React Native",
   "license": "MIT",
   "author": "Darion Welch",
@@ -36,6 +36,13 @@
     "!**/*.test.ts",
     "!**/.*"
   ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup",
+    "vendor:core": "node scripts/vendor-core.mjs",
+    "prepack": "node scripts/vendor-core.mjs && tsup"
+  },
   "codegenConfig": {
     "name": "VroomChartSpec",
     "type": "modules",
@@ -56,6 +63,7 @@
   },
   "devDependencies": {
     "@types/react": "~19.1.0",
+    "@vroomchart/types": "workspace:*",
     "react": "19.1.0",
     "react-native": "0.81.5",
     "typescript": "~5.9.2",
@@ -63,13 +71,6 @@
     "react-native-gesture-handler": "~2.28.0",
     "react-native-reanimated": "~4.1.1",
     "tsup": "^8.5.1",
-    "vitest": "^2.1.9",
-    "@vroomchart/types": "0.0.1"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "build": "tsup",
-    "vendor:core": "node scripts/vendor-core.mjs"
+    "vitest": "^2.1.9"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Darion Welch
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.