react-native-vroom-chart 0.1.0 → 0.1.1

package/cpp/VroomChartHostObject.cpp

@@ -42,6 +42,7 @@ std::vector<jsi::PropNameID> ChartHostObject::getPropertyNames(
   out.push_back(jsi::PropNameID::forAscii(rt, "setCrosshair"));
   out.push_back(jsi::PropNameID::forAscii(rt, "clearCrosshair"));
   out.push_back(jsi::PropNameID::forAscii(rt, "getCrosshairCandle"));
+  out.push_back(jsi::PropNameID::forAscii(rt, "getCrosshairInfo"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setRSI"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setMACD"));
   out.push_back(jsi::PropNameID::forAscii(rt, "setOverlays"));
@@ -336,6 +337,42 @@ jsi::Value ChartHostObject::get(jsi::Runtime& rt,
         });
   }
 
+  if (name == "getCrosshairInfo") {
+    // getCrosshairInfo() -> { timeMs, candle: {...} | null } | null. The slot
+    // the crosshair snaps to (real candle or a future candle-aligned slot past
+    // the last bar); null when the crosshair is inactive. `candle` is null in
+    // the empty space ahead of the most recent candle. No rendering.
+    return jsi::Function::createFromHostFunction(
+        rt,
+        jsi::PropNameID::forAscii(rt, "getCrosshairInfo"),
+        0,
+        [this](jsi::Runtime& rt2,
+               const jsi::Value& /*thisVal*/,
+               const jsi::Value* /*args*/,
+               size_t /*count*/) -> jsi::Value {
+          VroomCrosshairInfo info{};
+          if (!vroom_chart_get_crosshair_info(chart_, &info)) {
+            return jsi::Value::null();
+          }
+          jsi::Object obj(rt2);
+          obj.setProperty(rt2, "timeMs", static_cast<double>(info.time_ms));
+          if (info.has_candle) {
+            jsi::Object c(rt2);
+            c.setProperty(rt2, "timeMs",
+                          static_cast<double>(info.candle.time_ms));
+            c.setProperty(rt2, "open", info.candle.open);
+            c.setProperty(rt2, "high", info.candle.high);
+            c.setProperty(rt2, "low", info.candle.low);
+            c.setProperty(rt2, "close", info.candle.close);
+            c.setProperty(rt2, "volume", info.candle.volume);
+            obj.setProperty(rt2, "candle", c);
+          } else {
+            obj.setProperty(rt2, "candle", jsi::Value::null());
+          }
+          return obj;
+        });
+  }
+
   if (name == "setRSI") {
     // setRSI(enabled, period, upperBand, lowerBand, maEnabled, maPeriod) —
     // configures the RSI pane. No render; the next render() picks it up.

package/cpp/_core_include/vroom/vroom_chart.h

@@ -145,6 +145,24 @@ void vroom_chart_clear_crosshair(VroomChart* chart);
 // from the current crosshair x and visible window, matching what's rendered.
 bool vroom_chart_get_crosshair_candle(VroomChart* chart, VroomCandle* out);
 
+// What the crosshair currently snaps to, including future candle-aligned slots
+// to the right of the last candle (empty space the chart leaves ahead of the
+// most recent bar). `time_ms` is the snapped slot's period-start time — always
+// valid. `has_candle` is true when a real candle sits at that slot, in which
+// case `candle` holds its OHLCV; in the future region `has_candle` is false and
+// `candle` is left untouched.
+typedef struct VroomCrosshairInfo {
+    int64_t     time_ms;
+    bool        has_candle;
+    VroomCandle candle;
+} VroomCrosshairInfo;
+
+// Fills *out with the snapped slot the crosshair currently sits on and returns
+// true. Returns false (leaving *out untouched) when the crosshair is inactive
+// or there are no visible candles. Stateless — recomputes the snap from the
+// current crosshair x and visible window, matching what's rendered.
+bool vroom_chart_get_crosshair_info(VroomChart* chart, VroomCrosshairInfo* out);
+
 // ---- Indicators -----------------------------------------------------------
 
 // Configures the RSI indicator (rendered in a pane below the candles). `period`

package/cpp/_core_src/chart.cpp

@@ -256,11 +256,17 @@ void VroomChart::draw_chart(SkCanvas* canvas) {
     //      horizontal line + ring stay in the price pane (clamped to
     //      candle_area_h).
     if (crosshair_active) {
-        const float snap_x = vroom::snap_x_to_candle(
+        // Snap once: the slot gives both the vertical line's x (its center) and
+        // the time shown in the date badge. (snap_x_to_candle does exactly this
+        // internally, so the line position is unchanged.)
+        const vroom::SnapResult snap = vroom::snap_to_slot(
             lay, visible, n, candle_duration_ms, visible_start_ms, window_ms,
             crosshair_x_px);
-        vroom::crosshair::draw(canvas, *this, candle_right, candle_area_h,
-                               vroom::x_axis_top(lay), snap_x);
+        const float snap_x = vroom::candle_center_x(
+            lay, snap.time_ms, candle_duration_ms, visible_start_ms, window_ms);
+        vroom::crosshair::draw(canvas, *this, lay, bounds, candle_right,
+                               candle_area_h, vroom::x_axis_top(lay), snap_x,
+                               snap.time_ms);
     }
 
     // 8. GC fades that have fully faded out and aren't coming back.

package/cpp/_core_src/chart_facade.cpp

@@ -9,6 +9,7 @@
 #include <algorithm>
 #include <cstddef>
 #include <cstdint>
+#include <limits>
 
 #include "chart.h"
 #include "labels.h"
@@ -29,6 +30,30 @@ constexpr double kAxisDragSensitivity = 300.0;
 constexpr double kMinCandleBodyPx = 1.5;
 constexpr double kMaxCandleBodyPx = 32.0;
 
+// Hard cap on the future gap (visible_end - last_candle): 3/4 of the window so
+// at least 25% of the chart still shows candles. Never forces an existing larger
+// gap (e.g. from the x-axis drag zoom) to snap back — only limits new growth.
+int64_t max_future_gap(int64_t window_ms, int64_t cur_future) {
+    return std::max<int64_t>((window_ms * 3) / 4, cur_future);
+}
+
+// Rubber-band a forward (into-future) pan delta: once the current future gap is
+// past the soft cap (window/2), damp the delta quadratically toward zero as it
+// nears the hard cap (3*window/4). Backward (into-past) deltas are unaffected.
+int64_t damp_future_delta(int64_t delta_ms, int64_t cur_future,
+                          int64_t window_ms) {
+    if (delta_ms <= 0) return delta_ms;       // only resist forward motion
+    const int64_t soft = window_ms / 2;
+    if (cur_future <= soft) return delta_ms;  // free until the soft cap
+    const int64_t hard = (window_ms * 3) / 4;
+    const double span = static_cast<double>(hard - soft);
+    if (span <= 0.0) return 0;
+    const double depth = std::clamp(
+        static_cast<double>(cur_future - soft) / span, 0.0, 1.0);
+    const double resist = (1.0 - depth) * (1.0 - depth);
+    return static_cast<int64_t>(static_cast<double>(delta_ms) * resist);
+}
+
 }  // namespace
 
 // ---- Lifecycle -------------------------------------------------------------
@@ -72,9 +97,11 @@ extern "C" void vroom_chart_set_candles(VroomChart* chart, const VroomCandle* da
         chart->visible_end_ms = chart->candles.back().time_ms;
     }
 
-    // Snap the price (y-axis) bounds to whatever's visible right now. After
-    // this, only zoom / axis-drags change them; panning preserves them.
-    if (!chart->candles.empty()) {
+    // 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);
@@ -154,15 +181,22 @@ extern "C" void vroom_chart_pan(VroomChart* chart, float dx_px, float /*dy_px*/)
         (-dx_px / usable_px) * static_cast<float>(window_ms));
     if (delta_ms == 0) return;
 
-    int64_t new_start = chart->visible_start_ms + delta_ms;
-    int64_t new_end = chart->visible_end_ms + delta_ms;
-
-    // Right edge can overshoot the last candle by up to half a window so the
-    // user can scroll into empty "future" space (e.g., to view right-anchored
-    // indicators). Left edge still hard-clamps at the first candle.
+    // The right edge can overshoot the last candle into empty "future" space.
+    // Free scrolling up to half a window (candles fill >= 50%); from there to
+    // 3/4 of a window (candles fill >= 25%) panning forward is rubber-banded so
+    // it slows and hard-stops at the cap. The x-axis drag zoom can leave a gap
+    // larger than the cap (it zooms in until ~one candle remains), so the cap
+    // never forces it back — it just shrinks naturally as the user scrolls.
+    // Left edge still hard-clamps at the first candle.
     const int64_t first_time = chart->candles.front().time_ms;
     const int64_t last_time = chart->candles.back().time_ms;
-    const int64_t max_future = window_ms / 2;
+    const int64_t cur_future = chart->visible_end_ms - last_time;
+    const int64_t eff_delta = damp_future_delta(delta_ms, cur_future, window_ms);
+
+    int64_t new_start = chart->visible_start_ms + eff_delta;
+    int64_t new_end = chart->visible_end_ms + eff_delta;
+
+    const int64_t max_future = max_future_gap(window_ms, cur_future);
     if (new_end > last_time + max_future) {
         new_end = last_time + max_future;
         new_start = new_end - window_ms;
@@ -202,11 +236,18 @@ extern "C" void vroom_chart_translate(VroomChart* chart, float dx_px, float dy_p
             const int64_t delta_ms = static_cast<int64_t>(
                 (-dx_px / usable_px) * static_cast<float>(window_ms));
             if (delta_ms != 0) {
-                int64_t new_start = chart->visible_start_ms + delta_ms;
-                int64_t new_end = chart->visible_end_ms + delta_ms;
+                // See vroom_chart_pan: rubber-band forward scrolling between the
+                // 50% and 25%-candles caps, and let an existing larger gap (from
+                // the x-axis drag zoom) shrink naturally instead of snapping.
                 const int64_t first_time = chart->candles.front().time_ms;
                 const int64_t last_time = chart->candles.back().time_ms;
-                const int64_t max_future = window_ms / 2;
+                const int64_t cur_future = chart->visible_end_ms - last_time;
+                const int64_t eff_delta =
+                    damp_future_delta(delta_ms, cur_future, window_ms);
+                int64_t new_start = chart->visible_start_ms + eff_delta;
+                int64_t new_end = chart->visible_end_ms + eff_delta;
+                const int64_t max_future =
+                    max_future_gap(window_ms, cur_future);
                 if (new_end > last_time + max_future) {
                     new_end = last_time + max_future;
                     new_start = new_end - window_ms;
@@ -286,23 +327,51 @@ extern "C" void vroom_chart_scale_time_axis(VroomChart* chart, float dx_px) {
     int64_t new_window_ms = static_cast<int64_t>(
         static_cast<double>(window_ms) * scale);
 
-    // Clamp window so candle body width stays in [kMinCandleBodyPx,
-    // kMaxCandleBodyPx]. body_w = usable × (dur / window) × ratio →
+    // Candle body width bounds [kMinCandleBodyPx, kMaxCandleBodyPx] map to a
+    // window range: body_w = usable × (dur / window) × ratio →
     // window for a given body_w = usable × dur × ratio / body_w.
     const auto lay = chart->layout();
     const double usable =
         lay.width_px - lay.y_axis_width_px - lay.right_padding_px;
     const double ratio = chart->theme.floats[VROOM_FLOAT_CANDLE_WIDTH_RATIO];
     const double dur = static_cast<double>(chart->candle_duration_ms);
+    int64_t min_window = 0;
+    int64_t max_window = std::numeric_limits<int64_t>::max();
     if (usable > 0.0 && ratio > 0.0 && dur > 0.0) {
-        const int64_t min_window = static_cast<int64_t>(
-            (usable * dur * ratio) / kMaxCandleBodyPx);
-        const int64_t max_window = static_cast<int64_t>(
-            (usable * dur * ratio) / kMinCandleBodyPx);
-        if (new_window_ms < min_window) new_window_ms = min_window;
-        if (new_window_ms > max_window) new_window_ms = max_window;
+        min_window = static_cast<int64_t>((usable * dur * ratio) / kMaxCandleBodyPx);
+        max_window = static_cast<int64_t>((usable * dur * ratio) / kMinCandleBodyPx);
     }
 
+    // The right edge is pinned, so when it sits in the empty "future" space
+    // past the last candle (pan/scroll allow it to overshoot by up to half a
+    // window), zooming in shrinks the window from the left and slides candles
+    // off-screen. Rather than blocking it outright, allow the zoom down to a
+    // floor that keeps the last candle on screen, and add rubber-band
+    // resistance once the future region passes 50% of the window so the
+    // discouraged zoom visibly slows before it stops.
+    const int64_t last_time = chart->candles.back().time_ms;
+    const int64_t future_ms = chart->visible_end_ms - last_time;
+    if (future_ms > 0 && new_window_ms < window_ms) {
+        const int64_t floor_window = future_ms + chart->candle_duration_ms;
+        const int64_t soft_window = 2 * future_ms;  // future occupies 50%
+        if (soft_window > floor_window) {
+            // depth 0 at the soft point, 1 at the floor; resistance eases the
+            // shrink toward zero as the window approaches the floor.
+            const double span = static_cast<double>(soft_window - floor_window);
+            double depth = (static_cast<double>(soft_window) -
+                            static_cast<double>(window_ms)) / span;
+            depth = std::clamp(depth, 0.0, 1.0);
+            const double resist = (1.0 - depth) * (1.0 - depth);
+            const int64_t raw_delta = new_window_ms - window_ms;  // negative
+            new_window_ms = window_ms + static_cast<int64_t>(
+                static_cast<double>(raw_delta) * resist);
+        }
+        if (new_window_ms < floor_window) new_window_ms = floor_window;
+    }
+
+    if (new_window_ms < min_window) new_window_ms = min_window;
+    if (new_window_ms > max_window) new_window_ms = max_window;
+
     // Pivot around the right edge — most-recent visible candle stays put.
     int64_t new_start = chart->visible_end_ms - new_window_ms;
     const int64_t first_time = chart->candles.front().time_ms;
@@ -387,7 +456,11 @@ extern "C" void vroom_chart_zoom(VroomChart* chart, float scale_x, float scale_y
                 int64_t new_end = new_start + new_window;
                 const int64_t first_time = chart->candles.front().time_ms;
                 const int64_t last_time = chart->candles.back().time_ms;
-                const int64_t max_future = new_window / 2;
+                // Cap the future gap at 3/4 of the (new) window so >= 25% of the
+                // chart still shows candles, without snapping back an existing
+                // larger gap (e.g. from the x-axis drag zoom).
+                const int64_t max_future = max_future_gap(
+                    new_window, chart->visible_end_ms - last_time);
                 if (new_end > last_time + max_future) {
                     new_end = last_time + max_future;
                     new_start = new_end - new_window;
@@ -453,6 +526,31 @@ extern "C" bool vroom_chart_get_crosshair_candle(VroomChart* chart,
     return true;
 }
 
+extern "C" bool vroom_chart_get_crosshair_info(VroomChart* chart,
+                                               VroomCrosshairInfo* out) {
+    if (!chart || !out || !chart->crosshair_active || chart->candles.empty()) {
+        return false;
+    }
+    // Mirror draw_chart's visible-slice derivation so the queried slot is
+    // exactly the one the crosshair snaps to on screen.
+    const auto lay = chart->layout();
+    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 int64_t window_ms = chart->visible_end_ms - chart->visible_start_ms;
+    if (n == 0 || window_ms <= 0) return false;
+
+    const ::VroomCandle* visible = chart->candles.data() + range.start;
+    const vroom::SnapResult snap = vroom::snap_to_slot(
+        lay, visible, n, chart->candle_duration_ms,
+        chart->visible_start_ms, window_ms, chart->crosshair_x_px);
+    out->time_ms = snap.time_ms;
+    out->has_candle = snap.has_candle;
+    if (snap.has_candle) out->candle = visible[snap.index];
+    return true;
+}
+
 // ---- Indicators -----------------------------------------------------------
 
 extern "C" void vroom_chart_set_rsi(VroomChart* chart, bool enabled, int period,

package/cpp/_core_src/crosshair.cpp

@@ -4,13 +4,22 @@
 #pragma clang diagnostic ignored "-Wdocumentation"
 #include "include/core/SkCanvas.h"
 #include "include/core/SkColor.h"
+#include "include/core/SkFont.h"
+#include "include/core/SkFontTypes.h"
 #include "include/core/SkPaint.h"
+#include "include/core/SkRRect.h"
+#include "include/core/SkRect.h"
+#include "include/core/SkTypeface.h"
 #include "include/effects/SkDashPathEffect.h"
 #pragma clang diagnostic pop
 
 #include <algorithm>
+#include <cstdio>
+#include <cstring>
+#include <ctime>
 
 #include "chart.h"
+#include "fonts.h"
 #include "theme.h"
 
 namespace vroom::crosshair {
@@ -18,14 +27,50 @@ namespace vroom::crosshair {
 namespace {
 constexpr float kRingRadius = 3.5f;  // hollow dot at the intersection
 constexpr SkScalar kDash[2] = {2.f, 2.f};
+constexpr float kPadV = 4.f;     // badge padding above/below the text
+constexpr float kPadH = 8.f;     // badge padding left/right of the text
+constexpr float kCorner = 6.f;   // rounded-badge corner radius
+
+// Draws a filled rounded-rect badge with `text` centered on (`cx`, `cy`).
+// Matches the current-price indicator's geometry (glyph-bounds centering so the
+// digits sit on the center regardless of the font's cap-height metric).
+void draw_badge(SkCanvas* canvas,
+                const SkFont& font,
+                const char* text,
+                float cx,
+                float cy,
+                SkColor fill,
+                SkColor text_color) {
+    const size_t len = std::strlen(text);
+    SkRect tb;
+    const float text_w = font.measureText(text, len, SkTextEncoding::kUTF8, &tb);
+    const float box_w = text_w + 2.f * kPadH;
+    const float box_h = tb.height() + 2.f * kPadV;
+    const SkRect rect = SkRect::MakeXYWH(cx - box_w * 0.5f, cy - box_h * 0.5f,
+                                         box_w, box_h);
+
+    SkPaint box;
+    box.setAntiAlias(true);
+    box.setColor(fill);
+    canvas->drawRRect(SkRRect::MakeRectXY(rect, kCorner, kCorner), box);
+
+    SkPaint text_paint;
+    text_paint.setAntiAlias(true);
+    text_paint.setColor(text_color);
+    canvas->drawString(text, cx - text_w * 0.5f,
+                       cy - (tb.fTop + tb.fBottom) * 0.5f, font, text_paint);
+}
 }  // namespace
 
 void draw(SkCanvas* canvas,
           const VroomChart& chart,
+          const Layout& lay,
+          const PriceBounds& bounds,
           float candle_right,
           float candle_area_h,
           float vline_bottom,
-          float snap_x) {
+          float snap_x,
+          int64_t snap_time_ms) {
     if (!canvas || candle_right <= 0.f || candle_area_h <= 0.f) return;
 
     // Vertical line + ring snap to the nearest candle's center x; the horizontal
@@ -60,6 +105,52 @@ void draw(SkCanvas* canvas,
     ring.setStyle(SkPaint::kStroke_Style);
     ring.setStrokeWidth(2.f);  // thicker border so the dot reads clearly
     canvas->drawCircle(cx, cy, kRingRadius, ring);
+
+    // Axis badges (neutral grey, white text) sit on top of the axis labels and
+    // the current-price indicator since the crosshair is the last draw step.
+    // They need the axis typeface; if it isn't loaded the lines alone suffice.
+    auto tf = vroom::axis_typeface();
+    if (!tf) return;
+
+    SkFont font(tf, chart.theme.floats[VROOM_FLOAT_AXIS_FONT_SIZE_PX]);
+    font.setSubpixel(true);
+    font.setEdging(SkFont::Edging::kSubpixelAntiAlias);
+
+    const SkColor badge_fill = chart.theme.colors[VROOM_COLOR_CROSSHAIR_TARGET];
+
+    // Date/time badge over the x-axis strip, centered on the vertical line and
+    // vertically aligned with the time labels (centered in the strip).
+    if (lay.x_axis_height_px > 0.f) {
+        char buf[32];
+        const time_t time_s = static_cast<time_t>(snap_time_ms / 1000);
+        struct tm tm_buf;
+        localtime_r(&time_s, &tm_buf);
+        std::snprintf(buf, sizeof(buf), "%02d/%02d %02d:%02d",
+                      tm_buf.tm_mon + 1, tm_buf.tm_mday, tm_buf.tm_hour,
+                      tm_buf.tm_min);
+
+        const float strip_center_y = vline_bottom + lay.x_axis_height_px * 0.5f;
+        // Keep the badge within the candle area so it never slides under the
+        // y-axis price column.
+        const size_t len = std::strlen(buf);
+        const float text_w = font.measureText(buf, len, SkTextEncoding::kUTF8);
+        const float half_w = (text_w + 2.f * kPadH) * 0.5f;
+        const float badge_cx =
+            std::clamp(cx, half_w, std::max(half_w, candle_right - half_w));
+        draw_badge(canvas, font, buf, badge_cx, strip_center_y, badge_fill,
+                   SK_ColorWHITE);
+    }
+
+    // Price badge over the y-axis strip, centered on the horizontal line and
+    // sharing the y-axis labels' column.
+    if (lay.y_axis_width_px > 0.f) {
+        const double price = vroom::y_to_price(lay, bounds, cy);
+        char buf[32];
+        std::snprintf(buf, sizeof(buf), "%.2f", price);
+        const float axis_center_x = lay.width_px - lay.y_axis_width_px * 0.5f;
+        draw_badge(canvas, font, buf, axis_center_x, cy, badge_fill,
+                   SK_ColorWHITE);
+    }
 }
 
 }  // namespace vroom::crosshair

package/cpp/_core_src/crosshair.h

@@ -8,6 +8,9 @@
 
 #pragma once
 
+#include <cstdint>
+
+#include "viewport.h"
 #include "vroom/vroom_chart.h"
 
 class SkCanvas;
@@ -22,11 +25,20 @@ namespace vroom::crosshair {
 // (the bottom of the indicator region, so it stays visible over any RSI/MACD
 // panes); pass `candle_area_h` for both when there are no panes. `snap_x` is the
 // candle-snapped x for the vertical line and ring.
+//
+// Two axis badges are drawn over the strips: a date/time badge (formatted from
+// `snap_time_ms`) centered on the vertical line in the x-axis strip, and a
+// price badge (the price at the crosshair y, via `lay`/`bounds`) centered in
+// the y-axis strip. Both render on top of the axis labels and the current-price
+// indicator since the crosshair is the last thing drawn.
 void draw(SkCanvas* canvas,
           const VroomChart& chart,
+          const vroom::Layout& lay,
+          const vroom::PriceBounds& bounds,
           float candle_right,
           float candle_area_h,
           float vline_bottom,
-          float snap_x);
+          float snap_x,
+          int64_t snap_time_ms);
 
 }  // namespace vroom::crosshair

package/cpp/_core_src/labels.cpp

@@ -171,17 +171,16 @@ void update_x_fades(VroomChart& chart, const Layout& lay) {
     if (candle_area_w <= 0.f) return;
 
     const int64_t window_ms = chart.visible_end_ms - chart.visible_start_ms;
-    const int64_t interval = vroom::pick_time_interval(window_ms, candle_area_w);
-    if (interval <= 0) return;
+    const vroom::TimeTick tick =
+        vroom::pick_time_tick(window_ms, candle_area_w);
 
     for (auto& f : chart.x_fades) f.target = 0.f;
 
-    int64_t t = (chart.visible_start_ms / interval) * interval;
-    if (t < chart.visible_start_ms) t += interval;
+    int64_t t = vroom::first_tick_at_or_after(chart.visible_start_ms, tick);
     constexpr int kMaxLabels = 64;
     int promoted = 0;
     for (; t <= chart.visible_end_ms && promoted < kMaxLabels;
-         t += interval, ++promoted) {
+         t = vroom::next_tick(t, tick), ++promoted) {
         bool found = false;
         for (auto& f : chart.x_fades) {
             if (f.time_ms == t) {
@@ -238,8 +237,9 @@ void draw_x_labels(SkCanvas* canvas,
     if (candle_area_w <= 0.f) return;
 
     const int64_t window_ms = chart.visible_end_ms - chart.visible_start_ms;
-    // Recompute interval here just to decide HH:MM vs MM/DD formatting.
-    const int64_t interval = vroom::pick_time_interval(window_ms, candle_area_w);
+    // Recompute the cadence here just to decide label formatting.
+    const vroom::TimeTick tick =
+        vroom::pick_time_tick(window_ms, candle_area_w);
 
     SkFont font(tf, chart.theme.floats[VROOM_FLOAT_AXIS_FONT_SIZE_PX]);
     font.setSubpixel(true);
@@ -257,7 +257,9 @@ void draw_x_labels(SkCanvas* canvas,
 
     const float baseline_y =
         candle_area_h + (lay.x_axis_height_px + cap_h) * 0.5f;
-    const bool use_date = interval >= 24LL * 60 * 60 * 1000;
+    const bool use_date =
+        tick.unit == vroom::TimeUnit::Fixed &&
+        tick.step_ms >= 24LL * 60 * 60 * 1000;
     for (const auto& f : chart.x_fades) {
         if (f.opacity <= 1e-3f) continue;
         const float frac =
@@ -269,7 +271,16 @@ void draw_x_labels(SkCanvas* canvas,
         const time_t time_s = static_cast<time_t>(f.time_ms / 1000);
         struct tm tm_buf;
         localtime_r(&time_s, &tm_buf);
-        if (use_date) {
+        if (tick.unit == vroom::TimeUnit::Year) {
+            std::snprintf(buf, sizeof(buf), "%d", tm_buf.tm_year + 1900);
+        } else if (tick.unit == vroom::TimeUnit::Month) {
+            // Show the year at January so month ticks read across years.
+            if (tm_buf.tm_mon == 0) {
+                std::snprintf(buf, sizeof(buf), "%d", tm_buf.tm_year + 1900);
+            } else {
+                std::strftime(buf, sizeof(buf), "%b", &tm_buf);
+            }
+        } else if (use_date) {
             std::snprintf(buf, sizeof(buf), "%02d/%02d",
                           tm_buf.tm_mon + 1, tm_buf.tm_mday);
         } else {

package/cpp/_core_src/ticks.cpp

@@ -2,10 +2,44 @@
 
 #include <algorithm>
 #include <cmath>
+#include <ctime>
 
 namespace vroom {
 
-int64_t pick_time_interval(int64_t window_ms, float candle_area_w) {
+namespace {
+
+// Approximate average lengths used only to choose a cadence (the actual ticks
+// land on exact calendar boundaries). 30.436875 d / 365.2425 d.
+constexpr int64_t kMonthMs = 2'629'746'000LL;
+constexpr int64_t kYearMs = 31'556'952'000LL;
+
+// Smallest 1/2/5 × 10ⁿ integer that is >= x (>= 1).
+int nice_ceil_int(double x) {
+    if (x <= 1.0) return 1;
+    const double mag = std::pow(10.0, std::floor(std::log10(x)));
+    for (double m : {1.0, 2.0, 5.0, 10.0}) {
+        const double cand = m * mag;
+        if (cand >= x) return static_cast<int>(cand);
+    }
+    return static_cast<int>(10.0 * mag);
+}
+
+// Local-time midnight of year/mon(0-11)/mday as epoch ms.
+int64_t ymd_to_ms(int year, int mon, int mday) {
+    std::tm t{};
+    t.tm_year = year - 1900;
+    t.tm_mon = mon;
+    t.tm_mday = mday;
+    t.tm_hour = 0;
+    t.tm_min = 0;
+    t.tm_sec = 0;
+    t.tm_isdst = -1;
+    return static_cast<int64_t>(std::mktime(&t)) * 1000;
+}
+
+}  // namespace
+
+TimeTick pick_time_tick(int64_t window_ms, float candle_area_w) {
     static constexpr int64_t kIntervals[] = {
         60'000LL,                // 1m
         5 * 60'000LL,            // 5m
@@ -20,15 +54,80 @@ int64_t pick_time_interval(int64_t window_ms, float candle_area_w) {
         2 * 24 * 60 * 60'000LL,  // 2d
         7 * 24 * 60 * 60'000LL,  // 1w
     };
-    if (window_ms <= 0 || candle_area_w <= 0.f) return kIntervals[0];
-    const double ms_per_px =
-        static_cast<double>(window_ms) / candle_area_w;
+    if (window_ms <= 0 || candle_area_w <= 0.f) {
+        return {TimeUnit::Fixed, kIntervals[0], 0};
+    }
+    const double ms_per_px = static_cast<double>(window_ms) / candle_area_w;
+
     for (int64_t i : kIntervals) {
         if (static_cast<double>(i) / ms_per_px >= kXLabelMinSpacing) {
-            return i;
+            return {TimeUnit::Fixed, i, 0};
         }
     }
-    return kIntervals[sizeof(kIntervals) / sizeof(kIntervals[0]) - 1];
+
+    static constexpr int kMonthSteps[] = {1, 3, 6};
+    for (int s : kMonthSteps) {
+        const double span = static_cast<double>(s) *
+                            static_cast<double>(kMonthMs);
+        if (span / ms_per_px >= kXLabelMinSpacing) {
+            return {TimeUnit::Month, 0, s};
+        }
+    }
+
+    // Years: smallest nice step whose spacing clears the minimum. Unbounded, so
+    // arbitrarily wide windows still get non-overlapping labels.
+    const double needed = (static_cast<double>(kXLabelMinSpacing) * ms_per_px) /
+                          static_cast<double>(kYearMs);
+    return {TimeUnit::Year, 0, nice_ceil_int(needed)};
+}
+
+int64_t first_tick_at_or_after(int64_t from_ms, const TimeTick& tick) {
+    if (tick.unit == TimeUnit::Fixed) {
+        const int64_t step = tick.step_ms;
+        if (step <= 0) return from_ms;
+        int64_t t = (from_ms / step) * step;
+        if (t < from_ms) t += step;
+        return t;
+    }
+
+    const time_t from_s = static_cast<time_t>(from_ms / 1000);
+    std::tm lt{};
+    localtime_r(&from_s, &lt);
+    const int step = tick.step > 0 ? tick.step : 1;
+
+    if (tick.unit == TimeUnit::Year) {
+        int year = ((lt.tm_year + 1900 + step - 1) / step) * step;
+        for (;;) {
+            const int64_t ms = ymd_to_ms(year, 0, 1);
+            if (ms >= from_ms) return ms;
+            year += step;
+        }
+    }
+
+    // Month: align the month index (year*12 + mon) up to a multiple of step.
+    int mi = (((lt.tm_year + 1900) * 12 + lt.tm_mon) + step - 1) / step * step;
+    for (;;) {
+        const int64_t ms = ymd_to_ms(mi / 12, mi % 12, 1);
+        if (ms >= from_ms) return ms;
+        mi += step;
+    }
+}
+
+int64_t next_tick(int64_t t, const TimeTick& tick) {
+    if (tick.unit == TimeUnit::Fixed) {
+        return t + (tick.step_ms > 0 ? tick.step_ms : 0);
+    }
+
+    const time_t s = static_cast<time_t>(t / 1000);
+    std::tm lt{};
+    localtime_r(&s, &lt);
+    const int step = tick.step > 0 ? tick.step : 1;
+
+    if (tick.unit == TimeUnit::Year) {
+        return ymd_to_ms(lt.tm_year + 1900 + step, 0, 1);
+    }
+    const int mi = (lt.tm_year + 1900) * 12 + lt.tm_mon + step;
+    return ymd_to_ms(mi / 12, mi % 12, 1);
 }
 
 double pick_price_interval(double range, float candle_area_h) {