react-native-livechart 4.24.1 → 4.26.0

package/src/hooks/useCrosshair.ts

@@ -214,8 +214,8 @@ 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).
+  // Where and when the current touch went down, for overlay arbitration and
+  // the stationary-hold / stale-timer guards (see delayedPanGuard).
   const downX = useSharedValue(0);
   const downY = useSharedValue(0);
   const downAtMs = useSharedValue(0);
@@ -661,6 +661,14 @@ export function useCrosshair(
     .onTouchesDown(
       /* istanbul ignore next */ (e) => {
         "worklet";
+        // Overlay drags decide ownership at touch-down. Preserve that point
+        // even without a hold: the finger can enter a grabRange before the
+        // scrub reaches its horizontal activation threshold.
+        const touch = e.changedTouches[0];
+        if (touch) {
+          downX.set(touch.x);
+          downY.set(touch.y);
+        }
         delayedPanTouchDown(
           longPressMs,
           e,
@@ -751,7 +759,11 @@ export function useCrosshair(
         // 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;
+        if (
+          deferTapHit !== undefined &&
+          deferTapHit(downX.get(), downY.get())
+        )
+          return;
         startPlainScrub(
           snapCandleX(e.x),
           padding,

package/src/hooks/useDegen.ts

@@ -50,6 +50,7 @@ export function useDegen(
 ): {
   pack: SharedValue<Float64Array<ArrayBuffer>>;
   packRevision: SharedValue<number>;
+  particleTimestamp: SharedValue<number>;
   shakeTransform: DerivedValue<
     [{ translateX: number }, { translateY: number }]
   >;
@@ -57,6 +58,7 @@ export function useDegen(
   const MAX_SLOTS = 80;
   const pack = useSharedValue(new Float64Array(MAX_SLOTS * DEGEN_STRIDE));
   const packRevision = useSharedValue(0);
+  const particleTimestamp = useSharedValue(0);
   const prevM = useSharedValue<Momentum>("flat");
   const writeRot = useSharedValue(0);
   const enabledSV = useSharedValue(0);
@@ -185,10 +187,12 @@ export function useDegen(
   // ChartWithDegen only mounts while the resolved effect is enabled; static
   // charts force that config to null and unmount this callback entirely.
   useFrameCallback(
-    /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
+    /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ (frame) => {
       "worklet";
       if (isFrameLoopActive?.get() === false) return;
-      const now = engine.timestamp.get();
+      // The viewport clock advances in half-pixel steps and may be pinned by
+      // nowOverride or pan. Effects need the continuous display-frame clock.
+      const now = frame.timestamp / 1000;
       const buf = pack.get();
       const slots = slotCountSV.get();
 
@@ -273,10 +277,10 @@ export function useDegen(
       );
 
       // Repaint only while particles are alive (or on the frame they all expire,
-      // so the overlay clears). When the field is empty the 4 derived values per
-      // slot stay subscribed to `packRevision` alone and freeze — no per-frame
-      // worklet churn for an idle particle system.
+      // so the overlay clears). Publish the same clock for Atlas size/opacity,
+      // only while particles are alive, to keep an idle field from repainting.
       if (activeCount > 0 || prevActiveCount.get() > 0) {
+        particleTimestamp.set(now);
         packRevision.set(packRevision.get() + 1);
       }
       prevActiveCount.set(activeCount);
@@ -291,5 +295,5 @@ export function useDegen(
     ];
   });
 
-  return { pack, packRevision, shakeTransform };
+  return { pack, packRevision, particleTimestamp, shakeTransform };
 }

package/src/hooks/useDemandFrameLoop.ts

@@ -0,0 +1,82 @@
+import { useCallback, useEffect } from "react";
+import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+
+/** Wait through several unchanged frames, rather than mistaking one quiet frame for rest. */
+export const IDLE_SETTLE_MS = 160;
+
+function noInputs() { "worklet"; return null; }
+function noReaction() { "worklet"; }
+
+export function nextQuietTime(previous: number, changed: boolean, dt: number): number {
+  "worklet";
+  return changed ? 0 : previous + Math.min(Math.max(dt, 0), 34);
+}
+
+/**
+ * Opt-in UI-runtime RAF loop. Inputs wake it without a JS-thread round trip.
+ * `tick` returns true while work changed or a continuous effect needs frames.
+ * `prepare` must read INPUTS only: subscribing to tick outputs causes feedback.
+ * A generation token makes queued frames harmless after replacement/unmount.
+ */
+export function useDemandFrameLoop(
+  enabled: boolean,
+  prepare: () => unknown,
+  tick: (dt: number) => boolean,
+): () => void {
+  const mounted = useSharedValue(false);
+  const running = useSharedValue(false);
+  const generation = useSharedValue(0);
+  const quietTime = useSharedValue(0);
+
+  const wake = useCallback(() => {
+    "worklet";
+    if (!enabled || !mounted.get()) return;
+    quietTime.set(0);
+    if (running.get()) return;
+    running.set(true);
+    const token = generation.get();
+    let previous: number | null = null;
+    function step(timestamp: number) {
+      "worklet";
+      if (!mounted.get() || generation.get() !== token) return;
+      // Resuming never integrates the entire sleeping interval as a single frame.
+      const dt = previous === null ? 1000 / 60 : Math.min(timestamp - previous, 34);
+      previous = timestamp;
+      const quiet = nextQuietTime(quietTime.get(), tick(dt), dt);
+      quietTime.set(quiet);
+      if (quiet < IDLE_SETTLE_MS) requestAnimationFrame(step);
+      else running.set(false);
+    }
+    requestAnimationFrame(step);
+  }, [enabled, mounted, running, generation, quietTime, tick]);
+
+  useAnimatedReaction(
+    // Pass the worklet itself: Reanimated extracts SharedValue subscriptions
+    // from its closure. Wrapping it in () => prepare() hides those inputs.
+    enabled ? prepare : noInputs,
+    enabled ? wake : noReaction,
+    [enabled, enabled ? prepare : noInputs, enabled ? wake : noReaction],
+  );
+
+  useEffect(() => {
+    if (!enabled) return;
+    scheduleOnUI(() => {
+      "worklet";
+      generation.set(generation.get() + 1);
+      running.set(false);
+      mounted.set(true);
+      wake();
+    });
+    return () => {
+      scheduleOnUI(() => {
+        "worklet";
+        mounted.set(false);
+        generation.set(generation.get() + 1);
+        running.set(false);
+      });
+    };
+  }, [enabled, generation, mounted, running, wake]);
+
+  return wake;
+}

package/src/hooks/useLoadingLook.ts

@@ -0,0 +1,30 @@
+import { useState } from "react";
+
+import type { ResolvedLoadingConfig } from "../core/resolveConfig";
+
+/** Field by field, with `Object.is` (a `NaN` must equal itself, or the render
+ * below would never settle), over every field the config has. */
+function sameLook(a: ResolvedLoadingConfig, b: ResolvedLoadingConfig | null) {
+  if (b === null) return false;
+  const keys = Object.keys(a) as (keyof ResolvedLoadingConfig)[];
+  return keys.every((key) => Object.is(a[key], b[key]));
+}
+
+/**
+ * The loading shell's look: the live `loading` config while loading, and the
+ * last one after. The shell fades out and the reveal morph melts its squiggle
+ * into the line only once `loading` has turned off, when `resolveLoading`
+ * already returns `null` — so they would otherwise snap to the default color,
+ * stroke, wave and Y-axis placeholders just as the data arrives. The empty
+ * shell ("No data") shown later keeps it too; before any loading, it has none
+ * and the defaults apply.
+ */
+export function useLoadingLook(
+  loadingCfg: ResolvedLoadingConfig | null,
+): ResolvedLoadingConfig | null {
+  const [last, setLast] = useState(loadingCfg);
+  // Stored from render (React's "previous props" pattern), compared by value:
+  // `resolveLoading` returns a fresh object for an inline config every render.
+  if (loadingCfg !== null && !sameLook(loadingCfg, last)) setLast(loadingCfg);
+  return loadingCfg ?? last;
+}

package/src/hooks/useMarkers.ts

@@ -1,6 +1,7 @@
 import { useEffect, useRef } from "react";
 import { Gesture } from "react-native-gesture-handler";
 import {
+  useAnimatedReaction,
   useFrameCallback,
   useSharedValue,
   type SharedValue,
@@ -57,6 +58,8 @@ export function useMarkers(
   cluster: ResolvedMarkerCluster = ANCHORED_CLUSTER,
   /** Runtime gate shared with the chart engine. */
   isFrameLoopActive?: SharedValue<boolean>,
+  /** Experimental input-driven projection instead of continuous frames; defaults to false. */
+  autoSleep = false,
 ): {
   projected: SharedValue<ProjectedMarker[]>;
   tapGesture: ReturnType<typeof Gesture.Tap>;
@@ -79,7 +82,7 @@ export function useMarkers(
       onMarkerPress?.(event);
     };
 
-  const markerFrameCallback = useFrameCallback(
+  const project =
     /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
       "worklet";
       if (isFrameLoopActive?.get() === false) return;
@@ -111,13 +114,24 @@ export function useMarkers(
         maxY: engine.canvasHeight.get(),
       });
       projected.set(buf);
+    };
+  const legacyActive = autostart && !autoSleep;
+  const markerFrameCallback = useFrameCallback(project, legacyActive);
+  useAnimatedReaction(
+    () => {
+      if (!autoSleep || !autostart) return null;
+      return [active, markers.get(), engine.canvasWidth.get(), engine.canvasHeight.get(),
+        engine.timestamp.get(), engine.displayWindow.get(), engine.displayMin.get(),
+        engine.displayMax.get(), seriesSV?.get(), lineData?.get(), isFrameLoopActive?.get()];
+    },
+    (inputs) => {
+      if (inputs !== null) project();
     },
-    autostart,
   );
   useEffect(() => {
     // Reanimated does not reactively apply later `autostart` values.
-    markerFrameCallback.setActive(autostart);
-  }, [autostart, markerFrameCallback]);
+    markerFrameCallback.setActive(legacyActive);
+  }, [legacyActive, markerFrameCallback]);
 
   const tapGesture = Gesture.Tap().onEnd(
     /* istanbul ignore next -- gesture worklet runs on UI thread, not in Jest */ (

package/src/hooks/useMultiSeriesDegen.ts

@@ -30,6 +30,7 @@ export function useMultiSeriesDegen(
 ): {
   pack: SharedValue<Float64Array<ArrayBuffer>>;
   packRevision: SharedValue<number>;
+  particleTimestamp: SharedValue<number>;
   shakeTransform: DerivedValue<
     [{ translateX: number }, { translateY: number }]
   >;
@@ -37,6 +38,7 @@ export function useMultiSeriesDegen(
   const MAX_SLOTS = 80;
   const pack = useSharedValue(new Float64Array(MAX_SLOTS * DEGEN_STRIDE));
   const packRevision = useSharedValue(0);
+  const particleTimestamp = useSharedValue(0);
   // Per-series previous momentum (0 = flat, 1 = up, 2 = down), index-aligned to series.
   const prevMoms = useSharedValue<number[]>([]);
   const writeRot = useSharedValue(0);
@@ -131,9 +133,10 @@ export function useMultiSeriesDegen(
   ]);
 
   useFrameCallback(
-    /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
+    /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ (frame) => {
       "worklet";
-      const now = engine.timestamp.get();
+      // Effect timing is independent of the quantized/pinned viewport clock.
+      const now = frame.timestamp / 1000;
       const buf = pack.get();
       const slots = slotCountSV.get();
 
@@ -242,6 +245,7 @@ export function useMultiSeriesDegen(
       );
 
       if (activeCount > 0 || prevActiveCount.get() > 0) {
+        particleTimestamp.set(now);
         packRevision.set(packRevision.get() + 1);
       }
       prevActiveCount.set(activeCount);
@@ -256,5 +260,5 @@ export function useMultiSeriesDegen(
     ];
   });
 
-  return { pack, packRevision, shakeTransform };
+  return { pack, packRevision, particleTimestamp, shakeTransform };
 }

package/src/hooks/usePanScroll.ts

@@ -22,6 +22,8 @@ export type PanScrollGestureMode = "holdToScrub" | "axisDrag";
 
 /** Engine SharedValues the pan-scroll gesture reads/writes (subset of the engine state). */
 export interface PanScrollEngineRefs {
+  /** Wake a demand-driven engine before reading the gesture bounds. */
+  wake?: () => void;
   /** Absolute right-edge time to freeze at, or `null` to follow the live edge. */
   viewEnd: SharedValue<number | null>;
   /** Right-edge time the engine would use if following live (advances each frame). */
@@ -263,10 +265,13 @@ export function usePanScroll({
     },
   );
 
+  const wakeEngine = engine.wake;
+
   const onStart =
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     () => {
       "worklet";
+      wakeEngine?.();
       // 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

package/src/hooks/usePinchZoom.ts

@@ -10,6 +10,8 @@ import { FOLLOW_SNAP, panLowerBound, panUpperBound } from "./usePanScroll";
 
 /** Engine SharedValues the pinch-zoom gesture reads/writes. */
 export interface PinchZoomEngineRefs {
+  /** Wake a demand-driven engine before reading the gesture bounds. */
+  wake?: () => void;
   /** Visible-window width override in seconds, or `null` to follow `timeWindow`. */
   viewWindow: SharedValue<number | null>;
   /** Absolute right-edge time, or `null` to follow the live edge (shared with pan). */
@@ -170,10 +172,13 @@ export function usePinchZoom({
   const startWindow = useSharedValue(timeWindow);
   const startViewEnd = useSharedValue(0);
 
+  const wakeEngine = engine.wake;
+
   const onStart =
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     () => {
       "worklet";
+      wakeEngine?.();
       cancelAnimation(viewEnd);
       cancelAnimation(viewWindow);
       const edge = liveEdge.get();

package/src/hooks/useReferenceDrag.ts

@@ -18,11 +18,7 @@ import {
 } from "../math/referenceDrag";
 import { referenceLineForm } from "../math/referenceLines";
 import type { ReferenceLine } from "../types";
-import {
-  computeScrubDotY,
-  computeValueAtY,
-  snapPrice,
-} from "./crosshairShared";
+import { computeValueAtY, pinnedPlotY, snapPrice } from "./crosshairShared";
 
 /** Vertical reach (px) around a line within which a touch grabs it. */
 const GRAB_SLOP = 14;
@@ -37,12 +33,13 @@ const EMPTY: never[] = [];
  * Builds the per-line **drag** gesture for draggable Form-A reference lines: grab a
  * line near its value-Y and drag vertically to set a new value, with optional
  * `snap` + `bounds` clamp. Mirrors the order-ticket reticle in {@link useCrosshair}
- * (value↔Y via `computeValueAtY` / `computeScrubDotY`, frozen value re-projected
+ * (value↔Y via `computeValueAtY` / `pinnedPlotY`, frozen value re-projected
  * each frame) but per line, writing into the shared `dragValues` array the layout
  * and overlays read.
  *
  * The pan uses `manualActivation`: it grabs only when a touch starts within
- * {@link GRAB_SLOP} of a draggable line, then **owns** that touch — any drag past
+ * {@link GRAB_SLOP} of a draggable line (and inside its `grabRange`, when it has
+ * one), then **owns** that touch — any drag past
  * {@link DRAG_ACTIVATE_PX} (in either axis) drags the line. A touch off every line
  * fails fast so the chart's other gestures (scrub / scroll) run everywhere else
  * (compose this ahead of them via `Gesture.Exclusive`). Crucially it no longer
@@ -86,6 +83,7 @@ export function useReferenceDrag(
     const dMax = engine.displayMax.get();
     const top = padding.top;
     const bottom = ch - padding.bottom;
+    if (bottom <= top) return EMPTY;
     const out: number[] = [];
     for (let i = 0; i < lines.length; i++) {
       const l = lines[i];
@@ -98,12 +96,16 @@ export function useReferenceDrag(
         continue;
       }
       const v = dragValues.get()[i] ?? l.value;
-      const y = computeScrubDotY(v, dMin, dMax, ch, top, padding.bottom);
-      out.push(y < 0 ? -1 : Math.min(bottom, Math.max(top, y)));
+      out.push(pinnedPlotY(v, dMin, dMax, ch, top, padding.bottom));
     }
     return out;
   });
 
+  // Per-line grab x-ranges (`ReferenceLine.grabRange`), index-aligned with
+  // `lines`; null = anywhere along the line. Read by the gesture worklets below,
+  // which close over this render's `lines` as the callbacks do.
+  const grabRanges = lines.map((l) => l.grabRange ?? null);
+
   const dragIndex = useSharedValue(-1);
   const startX = useSharedValue(0);
   const startY = useSharedValue(0);
@@ -175,7 +177,10 @@ export function useReferenceDrag(
     "worklet";
     const t = e.changedTouches[0];
     if (!t) return;
-    const i = nearestDraggableIndex(handleYs.get(), t.y, GRAB_SLOP);
+    const i = nearestDraggableIndex(handleYs.get(), t.y, GRAB_SLOP, {
+      x: t.x,
+      ranges: grabRanges,
+    });
     if (i < 0) {
       manager.fail();
       return;
@@ -266,13 +271,22 @@ export function useReferenceDrag(
   // is grabbed the answer is yes regardless of position: the scrub asks with its
   // touch-DOWN point, which a longer drag has carried the line away from, so the
   // geometric test alone said "no line here" and a crosshair opened mid-drag.
-  // Otherwise it is the y-reach around the handles (x is unused — a Form-A line
-  // spans the full width).
+  // Otherwise it is the y-reach around the handles, along the whole line — or,
+  // for a line with a `grabRange`, only inside it.
   /* istanbul ignore next -- worklet, runs on the UI thread */
-  const hitTest = (_x: number, y: number): boolean => {
+  const hitTest = (x: number, y: number): boolean => {
     "worklet";
     if (!anyDraggable) return false;
-    return referenceDragOwnsTouch(dragIndex.get(), handleYs.get(), y, GRAB_SLOP);
+    return referenceDragOwnsTouch(
+      dragIndex.get(),
+      handleYs.get(),
+      y,
+      GRAB_SLOP,
+      {
+        x,
+        ranges: grabRanges,
+      },
+    );
   };
 
   const gesture = Gesture.Pan()

package/src/hooks/useReferenceLineGrouping.ts

@@ -0,0 +1,72 @@
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { groupReferenceLines, type ReferenceGrouping } from "../math/referenceGroup";
+import { referenceLineForm } from "../math/referenceLines";
+import type { ReferenceLine } from "../types";
+import { pinnedPlotY } from "./crosshairShared";
+
+/** Stable result while grouping is disabled. */
+const EMPTY_GROUPING: ReferenceGrouping = { hidden: [], groups: [] };
+
+/** Cluster the built-in tags that can actually render in the current plot. */
+export function useReferenceLineGrouping({
+  radius,
+  engine,
+  padding,
+  lines,
+  custom,
+  offAxisCustom,
+  dragValues,
+}: {
+  radius: number | null;
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  lines: ReferenceLine[];
+  custom: boolean[];
+  offAxisCustom: boolean[];
+  dragValues: SharedValue<number[]>;
+}) {
+  const hasOffAxisBadge = lines.map((line) => Boolean(line.badge || line.offAxisBadge));
+  const result = useDerivedValue<ReferenceGrouping>(() => {
+    if (radius == null) return EMPTY_GROUPING;
+    const canvasHeight = engine.canvasHeight.get();
+    const displayMin = engine.displayMin.get();
+    const displayMax = engine.displayMax.get();
+    const top = padding.top;
+    const yPositions: number[] = [];
+    for (let index = 0; index < lines.length; index++) {
+      const line = lines[index];
+      if (
+        referenceLineForm(line) !== "line" ||
+        line.value === undefined ||
+        custom[index] ||
+        offAxisCustom[index]
+      ) {
+        yPositions.push(-1);
+        continue;
+      }
+      const value = dragValues.get()[index] ?? line.value;
+      // Plain off-axis lines are culled by useReferenceLine. Only a configured
+      // badge can contribute a visible tag to the edge's count pill.
+      if ((value < displayMin || value > displayMax) && !hasOffAxisBadge[index]) {
+        yPositions.push(-1);
+        continue;
+      }
+      yPositions.push(
+        pinnedPlotY(
+          value,
+          displayMin,
+          displayMax,
+          canvasHeight,
+          top,
+          padding.bottom,
+        ),
+      );
+    }
+    return groupReferenceLines(yPositions, radius);
+  });
+  const hidden = useDerivedValue<boolean[]>(() => result.get().hidden);
+  return { refGroupResult: result, groupHidden: hidden };
+}

package/src/hooks/useVolumeRange.ts

@@ -0,0 +1,40 @@
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { CandlePoint } from "../types";
+import {
+  visibleMaxVolume,
+  volumeEndIndex,
+  volumeStartIndex,
+} from "../draw/volumeRange";
+
+/**
+ * Primitive index outputs suppress downstream scans while the window glides
+ * within the same buckets. The maximum also depends directly on candles, so
+ * every notified data revision (including same-length replacement or modify)
+ * invalidates it. Array length and object identity are never cache keys.
+ */
+export function useVolumeRange(
+  candles: SharedValue<CandlePoint[]> | undefined,
+  timestamp: SharedValue<number>,
+  window: SharedValue<number>,
+  width: SharedValue<number>,
+  active: boolean,
+) {
+  const start = useDerivedValue(() =>
+    !active || !candles
+      ? 0
+      : volumeStartIndex(
+          candles.get(),
+          timestamp.get() - window.get(),
+          width.get(),
+        ),
+  );
+  const end = useDerivedValue(() =>
+    !active || !candles ? 0 : volumeEndIndex(candles.get(), timestamp.get()),
+  );
+  const max = useDerivedValue(() =>
+    !active || !candles
+      ? 0
+      : visibleMaxVolume(candles.get(), start.get(), end.get()),
+  );
+  return { start, end, max };
+}

package/src/hooks/useXAxis.ts

@@ -167,11 +167,16 @@ export function useXAxis(
       const edgeAlpha =
         fromEdge >= fadeZone ? 1 : fromEdge <= 0 ? 0 : fromEdge / fadeZone;
 
-      const target = xAxisKeyIsTarget(key, targetKeys) ? edgeAlpha : 0;
+      const isTarget = xAxisKeyIsTarget(key, targetKeys);
+      const target = isTarget ? edgeAlpha : 0;
       let next = lerp(label.alpha, target, FADE, MS_PER_FRAME_60FPS);
       if (Math.abs(next - target) < 0.02) next = target;
 
-      if (next < 0.01 && target === 0) {
+      // Only a key that left the target set is deleted once it has faded out. A
+      // target key can sit at alpha 0 (the set spans one interval past each edge,
+      // outside the plot); deleting it would re-create it on the next run and
+      // write `labelAlphas`, this mapper's own input, every frame.
+      if (next < 0.01 && !isTarget) {
         delete alphas[key];
         cacheChanged = true;
       } else {
@@ -182,7 +187,12 @@ export function useXAxis(
       }
     }
 
-    if (cacheChanged) labelAlphas.set(alphas);
+    // Publish only a changed final cache so this derived value cannot keep
+    // waking itself after the engine sleeps. Off-screen target keys are retained
+    // above; this equality check also guards against other no-op cache updates.
+    if (cacheChanged && !sameXAxisLabels(previousAlphas, alphas)) {
+      labelAlphas.set(alphas);
+    }
 
     // Collect visible labels
     const raw: XAxisEntry[] = [];
@@ -226,3 +236,17 @@ export function useXAxis(
 
   return { xAxisEntries, font };
 }
+
+export function sameXAxisLabels(
+  previous: Record<number, { alpha: number; text: string }>,
+  next: Record<number, { alpha: number; text: string }>,
+): boolean {
+  "worklet";
+  const keys = Object.keys(next);
+  if (keys.length !== Object.keys(previous).length) return false;
+  for (let i = 0; i < keys.length; i++) {
+    const key = Number(keys[i]);
+    if (!previous[key] || previous[key].alpha !== next[key].alpha || previous[key].text !== next[key].text) return false;
+  }
+  return true;
+}

package/src/hooks/useYAxis.ts

@@ -28,7 +28,15 @@ export function useYAxis(
   const yAxisEntries = useDerivedValue(() => {
     const dt = MS_PER_FRAME_60FPS;
 
-    const alphas = labelAlphas.get();
+    // SharedValue payloads may be frozen after crossing the JS/UI boundary.
+    // Copy before computeGridEntries adds, updates, or removes label keys.
+    const previousAlphas = labelAlphas.get();
+    const alphas: Record<number, number> = {};
+    const previousKeys = Object.keys(previousAlphas);
+    for (let i = 0; i < previousKeys.length; i++) {
+      const key = Number(previousKeys[i]);
+      alphas[key] = previousAlphas[key];
+    }
     const result = computeGridEntries(
       engine.displayMin.get(),
       engine.displayMax.get(),
@@ -46,7 +54,15 @@ export function useYAxis(
     );
 
     prevInterval.set(result.interval);
-    labelAlphas.set(alphas);
+    // This derived value also reads the cache. Only publish actual changes so
+    // a settled axis doesn't keep scheduling itself with fresh object identities.
+    const nextKeys = Object.keys(alphas);
+    let cacheChanged = nextKeys.length !== previousKeys.length;
+    for (let i = 0; i < nextKeys.length && !cacheChanged; i++) {
+      const key = Number(nextKeys[i]);
+      if (alphas[key] !== previousAlphas[key]) cacheChanged = true;
+    }
+    if (cacheChanged) labelAlphas.set(alphas);
 
     return result.entries;
   });

package/src/index.ts

@@ -97,6 +97,7 @@ export type {
   MultiSeriesDotConfig,
   PerSeriesTooltipConfig,
   PulseConfig,
+  RangeAnimationConfig,
   ReferenceLine,
   ReferenceLineBadgeConfig,
   ReferenceLineGroupingConfig,