react-native-livechart 4.10.0 → 4.12.0

package/src/hooks/useChartPaths.ts

@@ -1,13 +1,28 @@
 import { Skia, type SkPath } from "@shopify/react-native-skia";
 import { useRef } from "react";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
-import type { SingleEngineState } from "../core/useLiveChartEngine";
+import type {
+  ChartEngineEdge,
+  ChartEngineScroll,
+  SingleEngineState,
+} from "../core/useLiveChartEngine";
 import { buildLinePoints, type ChartPadding } from "../draw/line";
 import { drawSpline, makeSplineScratch } from "../math/spline";
 import { sampleThresholdYAt, thresholdSampleSpanX } from "../math/threshold";
 import { blendPtsY, squigglifyPts } from "../math/squiggly";
 import { usePathBuilder } from "./usePathBuilder";
 
+/** Selects the synthetic right-edge line tip without coupling chart geometry
+ * to badge or live-indicator presentation options. */
+export function resolveLineTipValue(
+  displayValue: number,
+  edgeValue: number,
+  viewEnd: number | null,
+): number {
+  "worklet";
+  return viewEnd == null ? displayValue : edgeValue;
+}
+
 /**
  * Builds the `linePath` / `fillPath` with `Skia.PathBuilder`s reused across
  * frames (one per curve, held in a SharedValue) and finalized with `detach()` —
@@ -20,7 +35,7 @@ import { usePathBuilder } from "./usePathBuilder";
  * fillPath.
  */
 export function useChartPaths(
-  engine: SingleEngineState,
+  engine: SingleEngineState & ChartEngineScroll & ChartEngineEdge,
   padding: ChartPadding,
   morphT?: SharedValue<number>,
   /** When set, also build `thresholdFillPath` — the band between the line and this
@@ -28,14 +43,6 @@ 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,
   /** Loading squiggle wave amplitude (px) for the reveal morph. Default 14. */
   squiggleAmplitude = 14,
   /** Loading squiggle wave speed multiplier for the reveal morph. Default 1. */
@@ -55,6 +62,10 @@ export function useChartPaths(
     ptsA: number[];
     ptsB: number[];
     ptsTick: boolean;
+    squigglePts: number[];
+    morphA: number[];
+    morphB: number[];
+    morphTick: boolean;
     scratch: ReturnType<typeof makeSplineScratch>;
   } | null>(null);
   if (cacheRef.current === null) {
@@ -63,6 +74,10 @@ export function useChartPaths(
       ptsA: [] as number[],
       ptsB: [] as number[],
       ptsTick: false,
+      squigglePts: [] as number[],
+      morphA: [] as number[],
+      morphB: [] as number[],
+      morphTick: false,
       scratch: makeSplineScratch(),
     };
   }
@@ -71,11 +86,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();
+    // A historical window must end at its own right-edge price. Badge and
+    // live-indicator options affect overlays only; they must not distort the
+    // plotted series by connecting history to the off-screen live value.
+    const tipValue = resolveLineTipValue(
+      engine.displayValue.get(),
+      engine.edgeValue.get(),
+      engine.viewEnd.get(),
+    );
     const realPts = buildLinePoints(
       engine.data.get(),
       tipValue,
@@ -102,15 +120,18 @@ export function useChartPaths(
       centerY,
       squiggleAmplitude,
       squiggleSpeed,
+      cache.squigglePts,
     );
 
     // Blend center-out: centre of chart reveals first, edges last
+    cache.morphTick = !cache.morphTick;
     return blendPtsY(
       squigglyPts,
       realPts,
       t,
       padding,
       engine.canvasWidth.get(),
+      cache.morphTick ? cache.morphA : cache.morphB,
     );
   });
 

package/src/hooks/useCrosshair.ts

@@ -1,5 +1,4 @@
 import { type SkFont } from "@shopify/react-native-skia";
-import { Platform } from "react-native";
 import { Gesture } from "react-native-gesture-handler";
 import {
   useAnimatedReaction,
@@ -33,12 +32,15 @@ import {
   HIDDEN_TIME_BADGE,
   HIDDEN_TOOLTIP,
   pointInRect,
+  SCRUB_ACTIVATE_X_PX,
+  SCRUB_FAIL_Y_PX,
   snapPrice,
   type CrosshairState,
 } from "./crosshairShared";
 import {
   delayedPanTouchCancelled,
   delayedPanTouchDown,
+  delayedPanTouchMove,
   delayedPanTouchUp,
   resetDelayedPanGuard,
   shouldStartDelayedPan,
@@ -151,6 +153,12 @@ export function useCrosshair(
    * exclusion (the default; scrub covers the whole plot).
    */
   scrubBottomExclude = 0,
+  /**
+   * True while the time-scroll pan owns the touch. The hold-to-scrub pan refuses
+   * to activate while set, so a drag that already started scrolling can never
+   * mature into a scrub (see `delayedPanGuard.shouldStartDelayedPan`).
+   */
+  scrollActive?: SharedValue<boolean>,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -161,6 +169,18 @@ export function useCrosshair(
   // lifecycle helpers are also used by LiveChartSeries and unit-tested directly.
   const fingerDown = useSharedValue(false);
   const panActivated = useSharedValue(false);
+  // Where and when the current touch went down, for the stationary-hold and
+  // stale-timer guards (see delayedPanGuard).
+  const downX = useSharedValue(0);
+  const downY = useSharedValue(0);
+  const downAtMs = useSharedValue(0);
+  // Latched once the finger leaves the hold slop: this touch is a drag, so its
+  // long-press timer must not be honored even if it still fires.
+  const holdBroken = useSharedValue(false);
+  // Inert stand-in so the guard always has a latch to read when the controller
+  // wires no time-scroll (hooks must be created unconditionally).
+  const noScrollActive = useSharedValue(false);
+  const scrollActiveSV = scrollActive ?? noScrollActive;
   // Where the crosshair line should start (canvas Y) so it stops at a top-pinned
   // custom tooltip instead of running through it. -1 = no top tooltip → the line
   // starts at padding.top. Written by CustomTooltipOverlay, read by CrosshairOverlay.
@@ -501,18 +521,36 @@ export function useCrosshair(
       : panGestureDelay;
 
   let gesture = Gesture.Pan()
-    // Scrub-action: minDistance 0 — the press-hold above is the sole activator
-    // (movement during the hold fails the pan), so the crosshair never appears
-    // from a tap's travel. The Tap (maxDistance SCRUB_ACTION_TAP_SLOP) owns quick
-    // gestures; only a held press becomes a scrub/adjust drag.
-    .minDistance(!hasScrubAction && Platform.OS === "android" ? 10 : 0)
-    .activateAfterLongPress(longPressMs)
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
     .onTouchesDown(
-      /* istanbul ignore next */ () => {
+      /* istanbul ignore next */ (e) => {
         "worklet";
-        delayedPanTouchDown(longPressMs, fingerDown);
+        delayedPanTouchDown(
+          longPressMs,
+          e,
+          fingerDown,
+          downX,
+          downY,
+          downAtMs,
+          holdBroken,
+        );
+      },
+    )
+    // Stationary hold: drift beyond the slop while the long-press is still
+    // pending fails the pan, so a drag can never mature into a scrub.
+    .onTouchesMove(
+      /* istanbul ignore next */ (e, manager) => {
+        "worklet";
+        delayedPanTouchMove(
+          longPressMs,
+          e,
+          manager,
+          panActivated,
+          downX,
+          downY,
+          holdBroken,
+        );
       },
     )
     .onTouchesUp(
@@ -540,7 +578,17 @@ export function useCrosshair(
     .onStart(
       /* istanbul ignore next */ (e) => {
         "worklet";
-        if (!shouldStartDelayedPan(longPressMs, fingerDown, panActivated)) return;
+        if (
+          !shouldStartDelayedPan(
+            longPressMs,
+            fingerDown,
+            panActivated,
+            downAtMs,
+            holdBroken,
+            scrollActiveSV,
+          )
+        )
+          return;
         if (!enabled) return;
         // Scrub-action: once a reticle is placed, drag adjusts it (2D — the Y is
         // the price). The ephemeral live-scrub never engages, so scrubActive
@@ -605,7 +653,7 @@ export function useCrosshair(
     .onFinalize(
       /* istanbul ignore next */ () => {
         "worklet";
-        resetDelayedPanGuard(fingerDown, panActivated);
+        resetDelayedPanGuard(fingerDown, panActivated, holdBroken);
         // A lock-adjust drag leaves the reticle in place (scrubActive was never
         // set); a live-scrub clears its crosshair. Always clear scrubActive so a
         // stray scrub can never linger behind a placed reticle.
@@ -620,11 +668,22 @@ export function useCrosshair(
       },
     );
 
-  /* istanbul ignore next -- Android-only gesture axis config */
-  if (Platform.OS === "android" && !hasScrubAction) {
+  // Passing zero-valued activation modifiers lets RNGH's iOS pan recognizer
+  // activate before the axis constraints classify the drag. Only configure a
+  // hold when one is requested, and reserve minDistance(0) for scrub-action's
+  // deliberate press-hold interaction.
+  if (longPressMs > 0) {
+    gesture = gesture.activateAfterLongPress(longPressMs);
+  }
+
+  if (hasScrubAction) {
+    gesture = gesture.minDistance(0);
+  } else {
     // Lock mode needs free vertical drag (Y = price), so the failOffsetY clamp —
     // which would kill a vertical adjust — is applied only outside scrub-action.
-    gesture = gesture.activeOffsetX([-25, 25]).failOffsetY([-25, 25]);
+    gesture = gesture
+      .activeOffsetX([-SCRUB_ACTIVATE_X_PX, SCRUB_ACTIVATE_X_PX])
+      .failOffsetY([-SCRUB_FAIL_Y_PX, SCRUB_FAIL_Y_PX]);
   }
 
   // Axis-drag time-scroll: carve the bottom "time ruler" band out of the scrub's

package/src/hooks/useCrosshairSeries.ts

@@ -1,15 +1,19 @@
-import { Platform } from "react-native";
+import type { SkFont } from "@shopify/react-native-skia";
 import { Gesture } from "react-native-gesture-handler";
 import {
   useAnimatedReaction,
   useDerivedValue,
   useSharedValue,
+  type DerivedValue,
+  type SharedValue,
 } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
+import type { ResolvedPerSeriesTooltipConfig } from "../core/resolveConfig";
 import type { MultiEngineState } from "../core/useLiveChartEngine";
 import { type ChartPadding } from "../draw/line";
 import type { ScrubPointMulti } from "../types";
 import {
+  computePerSeriesTooltipLayout,
   deriveScrubValueSeries,
   interpolateSeriesAtTime,
 } from "./crosshairSeries";
@@ -18,20 +22,33 @@ import {
   computeScrubDotY,
   computeScrubTime,
   HIDDEN_TOOLTIP,
+  SCRUB_ACTIVATE_X_PX,
+  SCRUB_FAIL_Y_PX,
   type CrosshairState,
 } from "./crosshairShared";
 import {
   delayedPanTouchCancelled,
   delayedPanTouchDown,
+  delayedPanTouchMove,
   delayedPanTouchUp,
   resetDelayedPanGuard,
   shouldStartDelayedPan,
 } from "./delayedPanGuard";
 
 /**
- * LiveChartSeries crosshair + scrub. No tooltip — data is delivered via
- * `onScrub` worklet callback on the UI thread.
+ * LiveChartSeries crosshair + scrub. The optional per-series tooltip is
+ * calculated on the UI thread alongside the callback payload.
  */
+interface CrosshairSeriesTooltipOptions {
+  config: ResolvedPerSeriesTooltipConfig;
+  formatValue: (value: number) => string;
+  formatTime: (time: number) => string;
+  font: SkFont;
+  colors: string[];
+  /** Current-time anchor used to clamp the live bucket's range end. */
+  maxTime: SharedValue<number> | DerivedValue<number>;
+}
+
 export function useCrosshairSeries(
   engine: MultiEngineState,
   padding: ChartPadding,
@@ -41,6 +58,13 @@ export function useCrosshairSeries(
   panGestureDelay = 0,
   onGestureStart?: () => void,
   onGestureEnd?: () => void,
+  /**
+   * True while the time-scroll pan owns the touch. The hold-to-scrub pan refuses
+   * to activate while set, so a drag that already started scrolling can never
+   * mature into a scrub (see `delayedPanGuard.shouldStartDelayedPan`).
+   */
+  scrollActive?: SharedValue<boolean>,
+  tooltip?: CrosshairSeriesTooltipOptions,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -51,6 +75,18 @@ export function useCrosshairSeries(
   // the final pointer has already lifted on iOS.
   const fingerDown = useSharedValue(false);
   const panActivated = useSharedValue(false);
+  // Where and when the current touch went down, for the stationary-hold and
+  // stale-timer guards (see delayedPanGuard).
+  const downX = useSharedValue(0);
+  const downY = useSharedValue(0);
+  const downAtMs = useSharedValue(0);
+  // Latched once the finger leaves the hold slop: this touch is a drag, so its
+  // long-press timer must not be honored even if it still fires.
+  const holdBroken = useSharedValue(false);
+  // Inert stand-in so the guard always has a latch to read when the controller
+  // wires no time-scroll (hooks must be created unconditionally).
+  const noScrollActive = useSharedValue(false);
+  const scrollActiveSV = scrollActive ?? noScrollActive;
 
   const scrubTime = useDerivedValue(() =>
     computeScrubTime(
@@ -93,7 +129,27 @@ export function useCrosshairSeries(
     ),
   );
 
-  const tooltipLayout = useSharedValue(HIDDEN_TOOLTIP);
+  const tooltipLayout = useDerivedValue(() => {
+    if (!tooltip) return HIDDEN_TOOLTIP;
+    return computePerSeriesTooltipLayout(
+      scrubActive.get(),
+      scrubX.get(),
+      scrubTime.get(),
+      engine.series.get(),
+      engine.displaySeriesValues.get(),
+      tooltip.colors,
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      padding,
+      engine.canvasWidth.get(),
+      engine.canvasHeight.get(),
+      tooltip.maxTime.get(),
+      tooltip.formatValue,
+      tooltip.formatTime,
+      tooltip.font,
+      tooltip.config,
+    );
+  });
 
   /* istanbul ignore next */
   function handleGestureStart() {
@@ -165,14 +221,36 @@ export function useCrosshairSeries(
   );
 
   let gesture = Gesture.Pan()
-    .minDistance(Platform.OS === "android" ? 10 : 0)
-    .activateAfterLongPress(panGestureDelay)
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
     .onTouchesDown(
-      /* istanbul ignore next */ () => {
+      /* istanbul ignore next */ (e) => {
         "worklet";
-        delayedPanTouchDown(panGestureDelay, fingerDown);
+        delayedPanTouchDown(
+          panGestureDelay,
+          e,
+          fingerDown,
+          downX,
+          downY,
+          downAtMs,
+          holdBroken,
+        );
+      },
+    )
+    // Stationary hold: drift beyond the slop while the long-press is still
+    // pending fails the pan, so a drag can never mature into a scrub.
+    .onTouchesMove(
+      /* istanbul ignore next */ (e, manager) => {
+        "worklet";
+        delayedPanTouchMove(
+          panGestureDelay,
+          e,
+          manager,
+          panActivated,
+          downX,
+          downY,
+          holdBroken,
+        );
       },
     )
     .onTouchesUp(
@@ -200,7 +278,16 @@ export function useCrosshairSeries(
     .onStart(
       /* istanbul ignore next */ (e) => {
         "worklet";
-        if (!shouldStartDelayedPan(panGestureDelay, fingerDown, panActivated))
+        if (
+          !shouldStartDelayedPan(
+            panGestureDelay,
+            fingerDown,
+            panActivated,
+            downAtMs,
+            holdBroken,
+            scrollActiveSV,
+          )
+        )
           return;
         if (!enabled) return;
         scrubX.set(e.x);
@@ -219,7 +306,7 @@ export function useCrosshairSeries(
     .onFinalize(
       /* istanbul ignore next */ () => {
         "worklet";
-        resetDelayedPanGuard(fingerDown, panActivated);
+        resetDelayedPanGuard(fingerDown, panActivated, holdBroken);
         scrubActive.set(false);
         if (gestureStarted.get()) {
           gestureStarted.set(false);
@@ -228,11 +315,17 @@ export function useCrosshairSeries(
       },
     );
 
-  /* istanbul ignore next */
-  if (Platform.OS === "android") {
-    gesture = gesture.activeOffsetX([-25, 25]).failOffsetY([-25, 25]);
+  // Omit zero-valued activation modifiers so RNGH can classify direction before
+  // the pan activates on iOS. A vertical drag then remains available to a parent
+  // ScrollView/list, while a clear horizontal drag starts scrubbing.
+  if (panGestureDelay > 0) {
+    gesture = gesture.activateAfterLongPress(panGestureDelay);
   }
 
+  gesture = gesture
+    .activeOffsetX([-SCRUB_ACTIVATE_X_PX, SCRUB_ACTIVATE_X_PX])
+    .failOffsetY([-SCRUB_FAIL_Y_PX, SCRUB_FAIL_Y_PX]);
+
   return {
     scrubX,
     scrubActive,

package/src/hooks/useMomentum.ts

@@ -13,16 +13,23 @@ import type { Momentum, MomentumConfig } from "../types";
 export function resolveMomentumProp(
   prop: boolean | Momentum | MomentumConfig,
   data: readonly { time: number; value: number }[],
+  endTime?: number,
 ): Momentum {
   "worklet";
   if (prop === false) return "flat";
   if (prop === true)
-    return detectMomentum(data as { time: number; value: number }[]);
+    return detectMomentum(
+      data as { time: number; value: number }[],
+      undefined,
+      undefined,
+      endTime,
+    );
   if (typeof prop === "object")
     return detectMomentum(
       data as { time: number; value: number }[],
       prop.lookback,
       prop.threshold,
+      endTime,
     );
   return prop;
 }

package/src/hooks/useMultiSeriesLinePaths.ts

@@ -8,30 +8,37 @@ import { drawSpline, makeSplineScratch } from "../math/spline";
 import { usePathBuilders } from "./usePathBuilder";
 
 /**
- * One derived shared value holding up to `MAX_MULTI_SERIES` Skia paths (unused
- * slots reuse one cached empty path).
+ * One derived shared value holding only the active series' Skia paths, capped at
+ * `MAX_MULTI_SERIES`.
  *
  * Each visible series' path is built into a per-slot `Skia.PathBuilder` (reused
  * across frames via a SharedValue) and finalized with `detach()` — a fresh
  * immutable `SkPath` per frame, so `MultiSeriesStroke`'s per-slot
  * `useDerivedValue(() => paths.value[index])` repaints without the two-SkPath
- * ping-pong. Only visible series allocate a path.
+ * ping-pong. Only active series allocate and publish a path.
  */
 export function useMultiSeriesLinePaths(
   engine: MultiEngineState,
   padding: ChartPadding,
+  activeSeriesCount = MAX_MULTI_SERIES,
 ): SharedValue<SkPath[]> {
   const builders = usePathBuilders(MAX_MULTI_SERIES);
 
   const poolRef = useRef<{
     empty: SkPath;
     ptsBuf: number[];
+    pathsA: SkPath[];
+    pathsB: SkPath[];
+    pathsTick: boolean;
     scratch: ReturnType<typeof makeSplineScratch>;
   } | null>(null);
   if (poolRef.current === null) {
     poolRef.current = {
       empty: Skia.Path.Make(),
       ptsBuf: [] as number[],
+      pathsA: [] as SkPath[],
+      pathsB: [] as SkPath[],
+      pathsTick: false,
       scratch: makeSplineScratch(),
     };
   }
@@ -41,12 +48,11 @@ export function useMultiSeriesLinePaths(
     const slots = builders.value;
     const s = engine.series.get();
     const displays = engine.displaySeriesValues.get();
-    const out: SkPath[] = [];
-    for (let i = 0; i < MAX_MULTI_SERIES; i++) {
-      if (i >= s.length) {
-        out.push(pool.empty);
-        continue;
-      }
+    pool.pathsTick = !pool.pathsTick;
+    const out = pool.pathsTick ? pool.pathsA : pool.pathsB;
+    out.length = 0;
+    const count = Math.min(activeSeriesCount, s.length, MAX_MULTI_SERIES);
+    for (let i = 0; i < count; i++) {
       const pts = buildLinePoints(
         s[i].data,
         displays[i] ?? s[i].value,

package/src/hooks/usePanScroll.ts

@@ -57,6 +57,20 @@ export interface UsePanScrollOptions {
    * a stray scrub doesn't linger behind the pan.
    */
   onScrollStart?: () => void;
+  /**
+   * Set true for as long as this gesture owns the touch, cleared on finalize.
+   * The hold-to-scrub pan reads it and refuses to activate mid-scroll — RNGH's
+   * `Gesture.Race` declares no relation between the two pans, so this latch is
+   * the only thing stopping the scrub's long-press timer from firing while the
+   * chart is already being dragged. See `delayedPanGuard.shouldStartDelayedPan`.
+   */
+  scrollActive?: SharedValue<boolean>;
+  /**
+   * True while the scrub crosshair owns the touch. Scrolling is inert while set,
+   * so an engaged scrub locks the chart in place and the finger only moves the
+   * price indicator. Cleared when the finger lifts (the scrub pan's finalize).
+   */
+  scrubActive?: SharedValue<boolean>;
 }
 
 /**
@@ -134,6 +148,8 @@ export function usePanScroll({
   enabled,
   mode = "holdToScrub",
   onScrollStart,
+  scrollActive,
+  scrubActive,
 }: UsePanScrollOptions): ReturnType<typeof Gesture.Pan> {
   const { viewEnd, liveEdge, displayWindow, canvasWidth, canvasHeight } = engine;
   const padLeft = padding.left;
@@ -150,10 +166,21 @@ export function usePanScroll({
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     () => {
       "worklet";
+      // Stop an in-flight fling FIRST. `withDecay` keeps writing `viewEnd` after
+      // the finger lifts, and `Gesture.Race` declares no relation between the two
+      // pans, so this can run while a scrub is already engaged. Bailing out below
+      // without cancelling left the decay sliding the window underneath the
+      // crosshair — the opposite of the lock the scrub is meant to hold.
       cancelAnimation(viewEnd);
-      // Anchor at the current right edge so the first delta is relative to where
-      // the window sits (the live edge when we were following).
-      if (viewEnd.get() == null) viewEnd.set(liveEdge.get());
+      // An engaged scrub locks the chart: the finger moves the price indicator
+      // across a fixed window, so a scroll that activates underneath it must do
+      // nothing further (and must not claim the touch via `scrollActive`).
+      if (scrubActive?.get()) return;
+      scrollActive?.set(true);
+      // Keep `null` while following live. `onChange` resolves it to the current
+      // live edge before applying the first delta. Materializing that same edge
+      // here would falsely signal "scrolled back" between start and change,
+      // briefly collapsing the floating-axis gutter on a forward-only overdrag.
       onScrollStart?.();
     };
 
@@ -161,6 +188,7 @@ export function usePanScroll({
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     (e: { changeX: number }) => {
       "worklet";
+      if (scrubActive?.get()) return;
       const win = displayWindow.get();
       const chartW = canvasWidth.get() - padLeft - padRight;
       if (chartW <= 0) return;
@@ -174,6 +202,7 @@ export function usePanScroll({
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     (e: { velocityX: number }) => {
       "worklet";
+      if (scrubActive?.get()) return;
       if (viewEnd.get() == null) return;
       const win = displayWindow.get();
       const chartW = canvasWidth.get() - padLeft - padRight;
@@ -194,6 +223,16 @@ export function usePanScroll({
       );
     };
 
+  // Release the touch claim on every terminal state (END, FAIL, CANCEL), not just
+  // onEnd — a scroll that fails its offset clamps never reaches onEnd, and a
+  // stuck `scrollActive` would block scrub for the rest of the session.
+  const onFinalize =
+    /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
+    () => {
+      "worklet";
+      scrollActive?.set(false);
+    };
+
   if (mode === "axisDrag") {
     return Gesture.Pan()
       .enabled(enabled)
@@ -235,7 +274,8 @@ export function usePanScroll({
       )
       .onStart(onStart)
       .onChange(onChange)
-      .onEnd(onEnd);
+      .onEnd(onEnd)
+      .onFinalize(onFinalize);
   }
 
   // holdToScrub (default): a one-finger drag anywhere scrolls. Activate on
@@ -249,5 +289,6 @@ export function usePanScroll({
     .failOffsetY([-HOLD_SCRUB_FAIL_Y_PX, HOLD_SCRUB_FAIL_Y_PX])
     .onStart(onStart)
     .onChange(onChange)
-    .onEnd(onEnd);
+    .onEnd(onEnd)
+    .onFinalize(onFinalize);
 }

package/src/index.ts

@@ -40,6 +40,7 @@ export type {
   BadgeVariant,
   CandleMetrics,
   CandlePoint,
+  CanvasMode,
   ChartInsets,
   ChartOverlayContext,
   ChartPlotRect,
@@ -76,6 +77,7 @@ export type {
   MomentumConfig,
   MotionMetrics,
   MultiSeriesDotConfig,
+  PerSeriesTooltipConfig,
   PulseConfig,
   ReferenceLine,
   ReferenceLineBadgeConfig,