react-native-livechart 3.12.0 → 4.1.0

package/src/hooks/useBadge.ts

@@ -39,6 +39,27 @@ export function useBadge(
   background?: string,
   badgeMetrics: BadgeMetrics = BADGE_METRICS_DEFAULTS,
   badgeColorSpeed: number = MOTION_METRICS_DEFAULTS.badgeColorSpeed,
+  /**
+   * Floating-axis mode: render a tail-less pill right-aligned at the canvas edge
+   * (over a full-width plot) instead of inside a reserved right gutter. See
+   * {@link YAxisConfig.float}.
+   */
+  float = false,
+  /**
+   * Smoothed value at the visible window's right edge (engine `edgeValue`). When
+   * {@link followViewEdge} is set, the badge tracks this instead of the live value.
+   */
+  edgeValue?: SharedValue<number>,
+  /** Track the visible window's right-edge price while scrolled back. */
+  followViewEdge = false,
+  /**
+   * Pill corner radius in pixels. `undefined` → capsule (`pillHeight / 2`).
+   * Clamped to `[0, pillHeight / 2]`. The pointed tail (right-gutter mode) keeps
+   * anchoring on the vertical center regardless of this value.
+   */
+  radius?: number,
+  /** Label text color override; falls back to the variant/theme rule. */
+  textColorOverride?: string,
 ) {
   const colorR = useSharedValue(0);
   const colorG = useSharedValue(0);
@@ -71,21 +92,41 @@ export function useBadge(
     const dMin = engine.displayMin.get();
     const dMax = engine.displayMax.get();
     const valRange = dMax - dMin;
+    // Follow the visible window's right-edge price while scrolled back, else the
+    // live value (badge.followViewEdge). engine `edgeValue` already collapses to
+    // the live value when not scrolled, so the live badge is unchanged.
+    const liveVal =
+      followViewEdge && edgeValue ? edgeValue.get() : engine.displayValue.get();
     const dotY =
       valRange === 0
         ? padding.top + chartH / 2
-        : padding.top +
-          ((dMax - engine.displayValue.get()) / valRange) * chartH;
+        : padding.top + ((dMax - liveVal) / valRange) * chartH;
 
-    const text = formatValue(engine.displayValue.get());
+    const text = formatValue(liveVal);
     const textW = measureFontTextWidth(font, text);
 
     const pillH = font.getSize() + badgeMetrics.padY * 2;
-    const r = pillH / 2;
+    // `midY` is the pill's vertical center (the tail anchors here); `capR` is the
+    // corner radius — the capsule (midY) by default, or a clamped custom radius.
+    const midY = pillH / 2;
+    const capR = radius == null ? midY : Math.max(0, Math.min(radius, midY));
     const badgeY = dotY - pillH / 2;
     let textX: number;
 
-    if (position === "left") {
+    if (float) {
+      // Floating price tag: a tail-less pill right-aligned at the canvas edge,
+      // floating over the full-width plot (no reserved gutter). Its pill bg keeps
+      // the live value readable over the candles.
+      const pillW = 2 * badgeMetrics.padX + textW;
+      const bodyRight = w - badgeMetrics.marginEdge;
+      const bodyLeft = bodyRight - pillW;
+      textX = (bodyLeft + bodyRight - textW) / 2;
+      b.addRRect({
+        rect: { x: bodyLeft, y: badgeY, width: pillW, height: pillH },
+        rx: capR,
+        ry: capR,
+      });
+    } else if (position === "left") {
       // Pill to the left of the live dot; no tail (`showTail` applies to right gutter only).
       const dotXPos = w - padding.right;
       const pillW = 2 * badgeMetrics.padX + textW;
@@ -95,8 +136,8 @@ export function useBadge(
       textX = (bodyLeft + bodyRight - textW) / 2;
       b.addRRect({
         rect: { x: bodyLeft, y: badgeY, width: pillBodyW, height: pillH },
-        rx: r,
-        ry: r,
+        rx: capR,
+        ry: capR,
       });
     } else {
       // Right-gutter badge (default): asymmetric layout with optional tail.
@@ -115,28 +156,54 @@ export function useBadge(
 
       if (showTail) {
         const badgeX = w - padding.right + badgeMetrics.dotGap;
-        const cx = tl + pillW - r;
+        const bodyRightX = badgeX + tl + pillW;
 
         b.moveTo(badgeX + tl, badgeY);
-        b.lineTo(badgeX + cx, badgeY);
-        b.arcToOval(
-          { x: badgeX + cx - r, y: badgeY, width: r * 2, height: pillH },
-          -90,
-          180,
-          false,
-        );
+        if (capR >= midY) {
+          // Capsule cap: a single right-hand semicircle (the default badge).
+          const cx = tl + pillW - capR;
+          b.lineTo(badgeX + cx, badgeY);
+          b.arcToOval(
+            { x: badgeX + cx - capR, y: badgeY, width: capR * 2, height: pillH },
+            -90,
+            180,
+            false,
+          );
+        } else {
+          // Custom (smaller) corner radius: square body with rounded right corners.
+          b.lineTo(bodyRightX - capR, badgeY);
+          b.arcToOval(
+            { x: bodyRightX - capR * 2, y: badgeY, width: capR * 2, height: capR * 2 },
+            -90,
+            90,
+            false,
+          );
+          b.lineTo(bodyRightX, badgeY + pillH - capR);
+          b.arcToOval(
+            {
+              x: bodyRightX - capR * 2,
+              y: badgeY + pillH - capR * 2,
+              width: capR * 2,
+              height: capR * 2,
+            },
+            0,
+            90,
+            false,
+          );
+        }
         b.lineTo(badgeX + tl, badgeY + pillH);
+        // Tail tip stays on the vertical center (`midY`) regardless of corner radius.
         b.cubicTo(
           badgeX + badgeMetrics.tailLength + 2,
           badgeY + pillH,
           badgeX + 3,
-          badgeY + r + badgeMetrics.tailSpread,
+          badgeY + midY + badgeMetrics.tailSpread,
           badgeX,
-          badgeY + r,
+          badgeY + midY,
         );
         b.cubicTo(
           badgeX + 3,
-          badgeY + r - badgeMetrics.tailSpread,
+          badgeY + midY - badgeMetrics.tailSpread,
           badgeX + badgeMetrics.tailLength + 2,
           badgeY,
           badgeX + tl,
@@ -146,8 +213,8 @@ export function useBadge(
       } else {
         b.addRRect({
           rect: { x: bodyLeft, y: badgeY, width: pillW, height: pillH },
-          rx: r,
-          ry: r,
+          rx: capR,
+          ry: capR,
         });
       }
     }
@@ -182,7 +249,8 @@ export function useBadge(
     }
 
     const textColor =
-      variant === "minimal" ? "rgba(100,100,100,1)" : palette.badgeText;
+      textColorOverride ??
+      (variant === "minimal" ? "rgba(100,100,100,1)" : palette.badgeText);
 
     return { path: b.detach(), textX, textY, text, bgColor, textColor };
   });

package/src/hooks/useCandlePaths.ts

@@ -8,6 +8,7 @@ import {
 import { CANDLE_METRICS_DEFAULTS, MS_PER_FRAME_60FPS } from "../constants";
 import type { SingleEngineState } from "../core/useLiveChartEngine";
 import { buildCandleGeometry } from "../draw/candle";
+import { buildVolumeGeometry } from "../draw/volume";
 import type { ChartPadding } from "../draw/line";
 import { lerp } from "../math/lerp";
 import type { CandleMetrics, CandlePoint } from "../types";
@@ -29,6 +30,10 @@ export function useCandlePaths(
   candleWidthSecs: number,
   active: boolean,
   candleMetrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
+  /** Reserved volume-band height (px). `0` = no volume bars. */
+  volumeBandHeight = 0,
+  /** Corner radius (px) of the volume bars. */
+  volumeRadius = 0,
   /** Static charts run no loops: register without starting. Default `true`. */
   autostart = true,
 ) {
@@ -39,6 +44,8 @@ export function useCandlePaths(
   const downBodiesBuilder = usePathBuilder();
   const upWicksBuilder = usePathBuilder();
   const downWicksBuilder = usePathBuilder();
+  const upBarsBuilder = usePathBuilder();
+  const downBarsBuilder = usePathBuilder();
 
   useFrameCallback((frameInfo) => {
     "worklet";
@@ -76,11 +83,20 @@ export function useCandlePaths(
   const upBodiesPath = useDerivedValue(() => {
     const b = upBodiesBuilder.value;
     const { bodies } = geometry.value;
+    const radius = candleMetrics.bodyRadius;
     for (let i = 0; i < bodies.length; i++) {
       if (bodies[i].up) {
-        b.addRect(
-          Skia.XYWHRect(bodies[i].x, bodies[i].y, bodies[i].w, bodies[i].h),
-        );
+        const bd = bodies[i];
+        const rr = radius > 0 ? Math.min(radius, bd.w / 2, bd.h / 2) : 0;
+        if (rr > 0) {
+          b.addRRect({
+            rect: { x: bd.x, y: bd.y, width: bd.w, height: bd.h },
+            rx: rr,
+            ry: rr,
+          });
+        } else {
+          b.addRect(Skia.XYWHRect(bd.x, bd.y, bd.w, bd.h));
+        }
       }
     }
     return b.detach();
@@ -90,11 +106,20 @@ export function useCandlePaths(
   const downBodiesPath = useDerivedValue(() => {
     const b = downBodiesBuilder.value;
     const { bodies } = geometry.value;
+    const radius = candleMetrics.bodyRadius;
     for (let i = 0; i < bodies.length; i++) {
       if (!bodies[i].up) {
-        b.addRect(
-          Skia.XYWHRect(bodies[i].x, bodies[i].y, bodies[i].w, bodies[i].h),
-        );
+        const bd = bodies[i];
+        const rr = radius > 0 ? Math.min(radius, bd.w / 2, bd.h / 2) : 0;
+        if (rr > 0) {
+          b.addRRect({
+            rect: { x: bd.x, y: bd.y, width: bd.w, height: bd.h },
+            rx: rr,
+            ry: rr,
+          });
+        } else {
+          b.addRect(Skia.XYWHRect(bd.x, bd.y, bd.w, bd.h));
+        }
       }
     }
     return b.detach();
@@ -126,5 +151,77 @@ export function useCandlePaths(
     return b.detach();
   });
 
-  return { upBodiesPath, downBodiesPath, upWicksPath, downWicksPath } as const;
+  // Volume bars share the candle window + (lerped) candle width so each bar sits
+  // directly under its candle body. Empty unless a volume band is reserved.
+  /* istanbul ignore next -- worklet */
+  const volumeGeometry = useDerivedValue(() => {
+    if (!active || !candles || volumeBandHeight <= 0) return { bars: [] };
+    return buildVolumeGeometry(
+      candles.value,
+      liveCandle?.value ?? null,
+      padding,
+      engine.canvasWidth.value,
+      engine.canvasHeight.value,
+      engine.timestamp.value - engine.displayWindow.value,
+      engine.displayWindow.value,
+      volumeBandHeight,
+      displayCandleWidth.get(),
+      candleMetrics,
+    );
+  });
+
+  /* istanbul ignore next -- worklet */
+  const upBarsPath = useDerivedValue(() => {
+    const b = upBarsBuilder.value;
+    const { bars } = volumeGeometry.value;
+    for (let i = 0; i < bars.length; i++) {
+      if (bars[i].up) {
+        const bar = bars[i];
+        const rr =
+          volumeRadius > 0 ? Math.min(volumeRadius, bar.w / 2, bar.h / 2) : 0;
+        if (rr > 0) {
+          b.addRRect({
+            rect: { x: bar.x, y: bar.y, width: bar.w, height: bar.h },
+            rx: rr,
+            ry: rr,
+          });
+        } else {
+          b.addRect(Skia.XYWHRect(bar.x, bar.y, bar.w, bar.h));
+        }
+      }
+    }
+    return b.detach();
+  });
+
+  /* istanbul ignore next -- worklet */
+  const downBarsPath = useDerivedValue(() => {
+    const b = downBarsBuilder.value;
+    const { bars } = volumeGeometry.value;
+    for (let i = 0; i < bars.length; i++) {
+      if (!bars[i].up) {
+        const bar = bars[i];
+        const rr =
+          volumeRadius > 0 ? Math.min(volumeRadius, bar.w / 2, bar.h / 2) : 0;
+        if (rr > 0) {
+          b.addRRect({
+            rect: { x: bar.x, y: bar.y, width: bar.w, height: bar.h },
+            rx: rr,
+            ry: rr,
+          });
+        } else {
+          b.addRect(Skia.XYWHRect(bar.x, bar.y, bar.w, bar.h));
+        }
+      }
+    }
+    return b.detach();
+  });
+
+  return {
+    upBodiesPath,
+    downBodiesPath,
+    upWicksPath,
+    downWicksPath,
+    upBarsPath,
+    downBarsPath,
+  } as const;
 }

package/src/hooks/useChartOverlayContext.ts

@@ -0,0 +1,93 @@
+import { useMemo } from "react";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import type { ChartOverlayContext, ChartScale } from "../types";
+import { priceToY, timeToX, xToTime, yToPrice } from "./overlayScale";
+
+/**
+ * Builds the {@link ChartOverlayContext} handed to a custom
+ * {@link LiveChartProps.renderOverlay}: a single per-frame {@link ChartScale}
+ * SharedValue plus the pure price↔pixel / time↔pixel mapping worklets.
+ *
+ * The `scale` derived value reads the engine SharedValues (range, window, "now")
+ * and the padding each frame, so a consumer's `useAnimatedStyle` becomes reactive
+ * just by reading `scale.get()` — that read subscribes it to per-frame updates
+ * (Reanimated only observes SharedValues found directly in a worklet's closure,
+ * not those hidden behind a function call). The mappings stay pure, taking the
+ * snapshot as an argument.
+ */
+export function useChartOverlayContext(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+): ChartOverlayContext {
+  const { top: padTop, bottom: padBottom, left: padLeft, right: padRight } = padding;
+
+  const scale = useDerivedValue<ChartScale>(() => {
+    const width = engine.canvasWidth.get();
+    const height = engine.canvasHeight.get();
+    return {
+      min: engine.displayMin.get(),
+      max: engine.displayMax.get(),
+      window: engine.displayWindow.get(),
+      now: engine.timestamp.get(),
+      plot: {
+        left: padLeft,
+        top: padTop,
+        right: width - padRight,
+        bottom: height - padBottom,
+        width,
+        height,
+      },
+    };
+  }, [engine, padLeft, padTop, padRight, padBottom]);
+
+  return useMemo<ChartOverlayContext>(
+    () => ({ scale, priceToY, yToPrice, timeToX, xToTime }),
+    [scale],
+  );
+}
+
+/**
+ * Reactive Y for a price: projects `price` to its canvas Y pixel and returns it as
+ * a `SharedValue<number>` that tracks the live axis on the UI thread. The
+ * **recommended** way to place something at a price in a {@link LiveChartProps.renderOverlay}
+ * — read the returned value in your `useAnimatedStyle` like any SharedValue; the
+ * subscription to the chart's scale is handled here, so it can't be forgotten.
+ *
+ * ```tsx
+ * function PriceLevel({ ctx, price }) {
+ *   const y = usePriceY(ctx, price);
+ *   const style = useAnimatedStyle(() => ({ transform: [{ translateY: y.get() }] }));
+ *   return <Animated.View style={style} />;
+ * }
+ * ```
+ *
+ * It's a hook, so call it once per level (render one component per price). For
+ * one-off math off the render path (e.g. a gesture handler), use the pure
+ * {@link ChartOverlayContext.priceToY} with `ctx.scale.get()` instead.
+ */
+export function usePriceY(
+  ctx: ChartOverlayContext,
+  price: number,
+): SharedValue<number> {
+  const { scale, priceToY: toY } = ctx;
+  // Destructure `scale` so it sits directly in the worklet's closure (Reanimated
+  // observes top-level closure SharedValues, not ones reached via `ctx.scale`).
+  return useDerivedValue(() => toY(price, scale.get()), [scale, toY, price]);
+}
+
+/**
+ * Reactive X for a timestamp — the time↔pixel sibling of {@link usePriceY}.
+ * Projects `time` (unix seconds) to its canvas X pixel as a `SharedValue<number>`
+ * that tracks the scrolling window on the UI thread. Read it in your
+ * `useAnimatedStyle`; call once per element.
+ */
+export function useTimeX(
+  ctx: ChartOverlayContext,
+  time: number,
+): SharedValue<number> {
+  const { scale, timeToX: toX } = ctx;
+  return useDerivedValue(() => toX(time, scale.get()), [scale, toX, time]);
+}

package/src/hooks/useChartPaths.ts

@@ -27,6 +27,14 @@ export function useChartPaths(
   thresholdY?: SharedValue<number>,
   /** Draw the line/fill as a straight polyline instead of the monotone cubic. */
   linear = false,
+  /**
+   * Value at the visible window's right edge (engine `edgeValue`). With
+   * `followViewEdge`, the line's right-edge tip uses this instead of the live
+   * `displayValue` — so while time-scrolled the line ends at the last visible
+   * price rather than dropping to the (off-screen) live value.
+   */
+  edgeValue?: SharedValue<number>,
+  followViewEdge = false,
 ) {
   const lineBuilder = usePathBuilder();
   const fillBuilder = usePathBuilder();
@@ -53,9 +61,14 @@ export function useChartPaths(
     const cache = cacheRef.current!;
     cache.ptsTick = !cache.ptsTick;
     const buf = cache.ptsTick ? cache.ptsA : cache.ptsB;
+    // While scrolled back with `followViewEdge`, tip the line at the view-edge
+    // price (engine `edgeValue`) instead of the live value — otherwise the line
+    // drops from the last visible point to the off-screen live value at the edge.
+    const tipValue =
+      followViewEdge && edgeValue ? edgeValue.get() : engine.displayValue.get();
     const realPts = buildLinePoints(
       engine.data.get(),
-      engine.displayValue.get(),
+      tipValue,
       engine.timestamp.get(),
       engine.displayWindow.get(),
       engine.displayMin.get(),

package/src/hooks/useCrosshair.ts

@@ -130,13 +130,20 @@ export function useCrosshair(
    */
   deferTapHit?: (x: number, y: number) => boolean,
   /** Where the tooltip pill sits relative to the scrub line. Default `"side"`. */
-  tooltipPlacement: "side" | "top" | "bottom" = "side",
+  tooltipPlacement: "side" | "top" | "bottom" | "point" = "side",
   /** Render the value row in the default tooltip. Default `true`. */
   tooltipShowValue = true,
   /** Render the time row in the default tooltip. Default `true`. */
   tooltipShowTime = true,
   /** Gap (px) between the tooltip and the plot edge it's pinned to. Default `8`. */
   tooltipMargin = 8,
+  /**
+   * Height (px) of a bottom band to exclude from scrub recognition — the
+   * axis-drag "grab the time ruler" strip, so a drag there scrolls instead of
+   * scrubbing (and a vertical drag falls through to the parent). `0` = no
+   * exclusion (the default; scrub covers the whole plot).
+   */
+  scrubBottomExclude = 0,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -159,6 +166,7 @@ export function useCrosshair(
   const hasScrubAction = scrubAction != null;
   const hasOnScrubAction = onScrubAction != null;
   const dismissOnTapOutside = scrubAction?.dismissOnTapOutside ?? false;
+  const dismissOnAction = scrubAction?.dismissOnAction ?? false;
   const snapIncrement = scrubAction?.snap;
   const actionIcon = scrubAction?.icon ?? "+";
   const actionShowText = scrubAction?.text ?? true;
@@ -264,6 +272,7 @@ export function useCrosshair(
       tooltipShowTime,
       engine.canvasHeight.get(),
       tooltipMargin,
+      scrubDotY.get(),
     );
   });
 
@@ -506,6 +515,12 @@ export function useCrosshair(
           }
           return;
         }
+        // Defer to a marker / pressable badge under the finger: don't start a
+        // live scrub (or drop a crosshair) where the press is routed to an
+        // overlay tap. `scrubActive` is only set here, so bailing in `onStart`
+        // also keeps a follow-on drag from showing a crosshair — no `onUpdate`
+        // guard needed. (Plain-scrub counterpart of the scrub-action tap defer.)
+        if (deferTapHit !== undefined && deferTapHit(e.x, e.y)) return;
         scrubX.set(e.x);
         scrubActive.set(true);
         gestureStarted.set(true);
@@ -562,6 +577,14 @@ export function useCrosshair(
     gesture = gesture.activeOffsetX([-25, 25]).failOffsetY([-25, 25]);
   }
 
+  // Axis-drag time-scroll: carve the bottom "time ruler" band out of the scrub's
+  // hit area so a drag starting there scrolls (the pan-scroll gesture owns it)
+  // and never trips the crosshair. `shouldCancelWhenOutside(false)` above keeps a
+  // scrub that *started* in the plot tracking on into the band.
+  if (scrubBottomExclude > 0) {
+    gesture = gesture.hitSlop({ bottom: -scrubBottomExclude });
+  }
+
   // Tap: place/move the reticle, press the action badge, or dismiss the lock.
   // Composed ahead of the pan by the controller, so a tap is never swallowed.
   // Built only in scrub-action mode (the plain-scrub path never constructs a Tap).
@@ -589,6 +612,9 @@ export function useCrosshair(
               lockY.get(),
               candleJson,
             );
+          // Clear the reticle once the action fires, so no crosshair lingers after
+          // the order is placed via the badge.
+          if (dismissOnAction) lockActive.set(false);
         }
         return;
       }
@@ -626,12 +652,17 @@ export function useCrosshair(
     lockActive.set(true);
   };
 
-  const tapGesture = hasScrubAction
+  let tapGesture = hasScrubAction
     ? Gesture.Tap()
         .maxDuration(250)
         .maxDistance(SCRUB_ACTION_TAP_SLOP)
         .onEnd(handleActionTap)
     : undefined;
+  // Keep the axis-drag band scroll-only for taps too — a tap there shouldn't
+  // drop an order-ticket reticle.
+  if (tapGesture && scrubBottomExclude > 0) {
+    tapGesture = tapGesture.hitSlop({ bottom: -scrubBottomExclude });
+  }
 
   return {
     scrubX,

package/src/hooks/useLiveDot.ts

@@ -1,4 +1,4 @@
-import { useDerivedValue } from "react-native-reanimated";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import type { SingleEngineState } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 
@@ -6,8 +6,17 @@ import type { ChartPadding } from "../draw/line";
  * Derive the live dot position (right edge of the chart, mapped to current value).
  * Returns `{ dotX, dotY }` as shared values. Coordinates are set to `-100`
  * (off-screen sentinel) when canvas dimensions are unavailable.
+ *
+ * With `followViewEdge` + `edgeValue`, the dot (and the value line that shares
+ * `dotY`) tracks the visible window's right-edge price while scrolled back, so it
+ * stays aligned with a `followViewEdge` badge instead of marking the live value.
  */
-export function useLiveDot(engine: SingleEngineState, padding: ChartPadding) {
+export function useLiveDot(
+  engine: SingleEngineState,
+  padding: ChartPadding,
+  edgeValue?: SharedValue<number>,
+  followViewEdge = false,
+) {
   const dotX = useDerivedValue(() => {
     const w = engine.canvasWidth.value;
     if (w === 0) return -100;
@@ -22,9 +31,11 @@ export function useLiveDot(engine: SingleEngineState, padding: ChartPadding) {
     const dMax = engine.displayMax.value;
     const valRange = dMax - dMin;
     if (valRange === 0) return padding.top + chartH / 2;
-    return (
-      padding.top + ((dMax - engine.displayValue.value) / valRange) * chartH
-    );
+    const v =
+      followViewEdge && edgeValue
+        ? edgeValue.value
+        : engine.displayValue.value;
+    return padding.top + ((dMax - v) / valRange) * chartH;
   });
 
   return { dotX, dotY } as const;

package/src/hooks/useMarkers.ts

@@ -10,16 +10,30 @@ import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 import { projectMarkers, type ProjectedMarker } from "../math/markers";
 import { nearestMarkerIndex } from "../math/markers";
+import {
+  clusterMarkers,
+  clusterMembers,
+  type ResolvedMarkerCluster,
+} from "../math/markerCluster";
 import type {
   LiveChartPoint,
   Marker,
-  MarkerHoverEvent,
+  MarkerPressEvent,
   SeriesConfig,
 } from "../types";
 
+const ANCHORED_CLUSTER: ResolvedMarkerCluster = {
+  mode: "anchored",
+  overlap: 0.75,
+  gap: 2,
+  maxBeforeGroup: 5,
+};
+
 /**
  * Projects markers to screen positions each frame and builds a tap gesture that
- * hit-tests against them, firing `onMarkerHover` (or `null` on a miss).
+ * hit-tests against them, firing `onMarkerPress` (or `null` on a miss). Applies
+ * the {@link clusterMarkers} collision pass each frame so hit-testing matches the
+ * drawn (stacked / collapsed) positions.
  */
 export function useMarkers(
   engine: ChartEngineLayout,
@@ -27,7 +41,7 @@ export function useMarkers(
   markers: SharedValue<Marker[]>,
   active: boolean,
   hitRadius: number,
-  onMarkerHover?: (event: MarkerHoverEvent | null) => void,
+  onMarkerPress?: (event: MarkerPressEvent | null) => void,
   seriesSV?: SharedValue<SeriesConfig[]>,
   lineData?: SharedValue<LiveChartPoint[]>,
   /** Static charts run no loops: register without starting. Default `true`. */
@@ -35,6 +49,8 @@ export function useMarkers(
   /** Single-series line is drawn linear (`line.curve === "linear"`) — anchor
    *  `lineData` markers on the straight chord rather than the spline. */
   lineLinear = false,
+  /** Collision config; default `"anchored"` (no stacking). */
+  cluster: ResolvedMarkerCluster = ANCHORED_CLUSTER,
 ): {
   projected: SharedValue<ProjectedMarker[]>;
   tapGesture: ReturnType<typeof Gesture.Tap>;
@@ -51,10 +67,10 @@ export function useMarkers(
     cacheRef.current = { a: [] as ProjectedMarker[], b: [] as ProjectedMarker[], tick: false };
   }
 
-  const emitHover =
+  const emitPress =
     /* istanbul ignore next -- invoked only from the UI-thread tap worklet */
-    (event: MarkerHoverEvent | null) => {
-      onMarkerHover?.(event);
+    (event: MarkerPressEvent | null) => {
+      onMarkerPress?.(event);
     };
 
   useFrameCallback(
@@ -82,6 +98,7 @@ export function useMarkers(
         lineData: lineData?.get(),
         lineLinear,
       });
+      clusterMarkers(markers.get(), buf, { config: cluster });
       projected.set(buf);
     },
     autostart,
@@ -92,14 +109,25 @@ export function useMarkers(
       e,
     ) => {
       "worklet";
-      const idx = nearestMarkerIndex(projected.get(), e.x, e.y, hitRadius);
+      const proj = projected.get();
+      const idx = nearestMarkerIndex(proj, e.x, e.y, hitRadius);
       if (idx < 0) {
-        runOnJS(emitHover)(null);
+        runOnJS(emitPress)(null);
         return;
       }
-      const m = markers.get()[idx];
-      const p = projected.get()[idx];
-      runOnJS(emitHover)({ marker: m, point: { x: p.x, y: p.y } });
+      const ms = markers.get();
+      const m = ms[idx];
+      const p = proj[idx];
+      const isGrouped = p.isGrouped;
+      // Collapsed cluster: surface the whole bucket so the consumer can list it.
+      const members = isGrouped ? clusterMembers(ms, proj, idx) : undefined;
+      runOnJS(emitPress)({
+        marker: m,
+        point: { x: p.x, y: p.y },
+        index: idx,
+        isGrouped,
+        members,
+      });
     },
   );