react-native-livechart 4.2.0 → 4.3.0

package/src/components/LiveChart.tsx

@@ -37,6 +37,7 @@ import {
   resolvePulse,
   resolveScrub,
   resolveScrubAction,
+  resolveReturnToLiveMs,
   resolveSelectionDot,
   resolveThreshold,
   resolveTradeStream,
@@ -216,6 +217,7 @@ function useLiveChartController({
   windowBuffer = 0,
   nowOverride,
   timeScroll = false,
+  returnToLive,
   zoom = false,
   accessibilityLabel,
   accessibilityRole = "image",
@@ -494,6 +496,9 @@ function useLiveChartController({
   // onto the JS thread (set by the reaction below, after the engine exists).
   const [scrolledBack, setScrolledBack] = useState(false);
   const timeScrollEnabled = Boolean(timeScroll) && !isStatic;
+  // Glide duration for the return-to-live animation (0 = instant). A sibling of
+  // `timeScroll` so it survives `timeScroll={false}` (the disable that triggers it).
+  const returnToLiveMs = resolveReturnToLiveMs(returnToLive);
   const zoomCfg = resolveZoom(zoom);
   const zoomEnabled = zoomCfg !== null && !isStatic;
 
@@ -552,6 +557,8 @@ function useLiveChartController({
     timeWindow,
     paused,
     static: isStatic,
+    scrollEnabled: timeScrollEnabled,
+    returnToLiveMs,
     smoothing,
     adaptiveSpeedBoost: metricsCfg.motion.adaptiveSpeedBoost,
     exaggerate,
@@ -568,12 +575,16 @@ function useLiveChartController({
 
   // Mirror the UI-thread scroll state to React so the floating y-axis can keep
   // a right gutter at the live edge and collapse it only while scrolled back.
-  // Fires once per null↔frozen transition, and only matters for float+timeScroll.
+  // Fires once per null↔frozen transition. `viewEnd` is only non-null while
+  // time-scroll is enabled and actively scrolled (the engine resets it to null
+  // when time-scroll is disabled — see #164), so we don't gate on
+  // `timeScrollEnabled` here: that would strand `scrolledBack` at `true` after a
+  // disable-while-scrolled, wrongly floating the y-axis on a later re-enable.
   useAnimatedReaction(
     () => engine.viewEnd.value != null,
     /* istanbul ignore next -- Reanimated reaction; state mirrored on the JS thread, not exercised under Jest */
     (isScrolled, prev) => {
-      if (isScrolled !== prev && yAxisFloat && timeScrollEnabled) {
+      if (isScrolled !== prev && yAxisFloat) {
         scheduleOnRN(setScrolledBack, isScrolled);
       }
     },
@@ -798,13 +809,30 @@ function useLiveChartController({
       dragValues,
     );
 
-  // Combined "defer" hit-test for the scrub-action place-tap: yield to a marker or
-  // a pressable badge under the finger so the tap is routed there instead of
-  // dropping a reticle. (Both hit-tests return false when their feature is off.)
+  // Draggable reference lines: a per-line vertical pan that grabs a line near its
+  // value and drags it along the Y-axis (with snap / bounds / callbacks). Built
+  // unconditionally for stable hook order (and before `useCrosshair` so the scrub
+  // can defer to a line under the finger); the gesture self-disables when no line
+  // opts in, and it's only composed into the root when `refDragEnabled`.
+  const refDragEnabled =
+    !isStatic && allRefLines.some((l) => l.draggable === true);
+  const { gesture: refDragGesture, hitTest: refDragHitTest } = useReferenceDrag(
+    engine,
+    effectivePadding,
+    allRefLines,
+    dragValues,
+    dragActive,
+    !isStatic,
+  );
+
+  // Combined "defer" hit-test: the scrub-action place-tap and the live scrub both
+  // yield to a marker, a pressable badge, or a draggable line under the finger — so
+  // a press there is routed to that overlay / drag instead of dropping a reticle or
+  // crosshair. (Each hit-test returns false when its feature is off.)
   /* istanbul ignore next -- worklet runs on the UI thread, not in Jest */
   const deferTapHit = (x: number, y: number): boolean => {
     "worklet";
-    return markerHitTest(x, y) || refLineHitTest(x, y);
+    return markerHitTest(x, y) || refLineHitTest(x, y) || refDragHitTest(x, y);
   };
 
   // Time-scroll activation. `holdToScrub`: a quick one-finger drag scrolls while
@@ -843,7 +871,7 @@ function useLiveChartController({
     scrubActionCfg,
     onScrubAction,
     metricsCfg.badge,
-    markersActive || refPressActive ? deferTapHit : undefined,
+    markersActive || refPressActive || refDragEnabled ? deferTapHit : undefined,
     scrubCfg?.tooltipPlacement ?? "side",
     scrubCfg?.tooltipShowValue ?? true,
     scrubCfg?.tooltipShowTime ?? true,
@@ -876,21 +904,6 @@ function useLiveChartController({
     },
   });
 
-  // Draggable reference lines: a per-line vertical pan that grabs a line near its
-  // value and drags it along the Y-axis (with snap / bounds / callbacks). Built
-  // unconditionally for stable hook order; the gesture self-disables when no line
-  // opts in, and it's only composed into the root when `refDragEnabled`.
-  const refDragEnabled =
-    !isStatic && allRefLines.some((l) => l.draggable === true);
-  const refDragGesture = useReferenceDrag(
-    engine,
-    effectivePadding,
-    allRefLines,
-    dragValues,
-    dragActive,
-    !isStatic,
-  );
-
   // Pinch-to-zoom the visible window (two-finger). Anchors at the focal point and
   // writes viewWindow + viewEnd; composes via Simultaneous (it's two-finger, so
   // disjoint from the one-finger pan/scrub). See `zoom`.

package/src/components/LiveChartSeries.tsx

@@ -36,6 +36,7 @@ import {
   resolveMarkerCluster,
   resolveMetrics,
   resolveMultiSeriesDot,
+  resolveReturnToLiveMs,
   resolveScrub,
   resolveSelectionDot,
   resolveXAxis,
@@ -147,6 +148,7 @@ function useLiveChartSeriesController({
   scrub = true,
   selectionDot,
   timeScroll = false,
+  returnToLive,
   zoom = false,
   onScrub,
   onGestureStart,
@@ -181,6 +183,9 @@ function useLiveChartSeriesController({
   // gesture to wait for a press-and-hold so a quick drag scrolls instead — the
   // hold delay is threaded into `useCrosshairSeries` below.
   const timeScrollEnabled = Boolean(timeScroll);
+  // Return-to-live glide duration (0 = instant); sibling of `timeScroll` so it
+  // survives `timeScroll={false}` (the disable that triggers it). See #164.
+  const returnToLiveMs = resolveReturnToLiveMs(returnToLive);
   const zoomCfg = resolveZoom(zoom);
   const zoomEnabled = zoomCfg !== null;
   const scrollGestureMode =
@@ -296,6 +301,8 @@ function useLiveChartSeriesController({
     series: effectiveSeries,
     timeWindow,
     paused,
+    scrollEnabled: timeScrollEnabled,
+    returnToLiveMs,
     smoothing,
     adaptiveSpeedBoost: metricsCfg.motion.adaptiveSpeedBoost,
     exaggerate,

package/src/constants.ts

@@ -24,6 +24,13 @@ export const MAX_Y_LABELS = 15;
  */
 export const HOLD_TO_SCRUB_MS = 500;
 
+/**
+ * Duration (ms) of the "return to live" glide — how long the window takes to ease
+ * from a scrolled-back position to the live edge when `timeScroll` is disabled
+ * (or a mode switch turns it off). Eased out so it decelerates onto live. See #164.
+ */
+export const RETURN_TO_LIVE_MS = 450;
+
 // ─── Metric default tokens (single source of truth for LiveChartMetrics) ─────
 // The resolved `metrics` config (see resolveMetrics) is assembled from these
 // objects. Draw/worklet helpers default their metric params to the matching

package/src/core/liveChartEngineTick.ts

@@ -69,6 +69,17 @@ export interface EngineTickInput {
    * resumes following. Takes precedence over {@link paused}.
    */
   viewEnd?: number | null;
+  /**
+   * "Return to live" glide (see #164). When time-scroll is disabled while scrolled
+   * back, the engine hook clears {@link viewEnd} and animates {@link returnT} from
+   * `0`→`1`; each frame the right edge interpolates from {@link returnFrom} (the
+   * frozen edge captured at that moment) to the *current* live edge by `returnT`,
+   * so the window glides forward and lands exactly on live (no end-snap). At
+   * `1`/`undefined` it pins to the live edge — the normal follow behavior.
+   */
+  returnT?: number;
+  /** Frozen right-edge time the {@link returnT} glide starts from. See {@link returnT}. */
+  returnFrom?: number;
   /**
    * Absolute visible-window width (seconds) to freeze at, or `null`/`undefined`
    * to follow the configured {@link timeWindow}. Set by the pinch-zoom gesture
@@ -98,13 +109,38 @@ export function tickLiveChartEngineFrame(
   const liveEdge = baseNow + (input.windowBuffer ?? 0) * input.timeWindow;
   state.liveEdge = liveEdge;
   const viewEnd = input.viewEnd;
-  if (viewEnd != null && viewEnd < liveEdge) {
-    // Scrolled back in time: freeze the right edge at an absolute timestamp so
-    // the window stops tracking "now" (see usePanScroll / the `timeScroll` prop).
+  // First time of the visible series' data — the floor a frozen edge must stay
+  // at or above. `-Infinity` when there's no data to bound against, so the freeze
+  // still works (we can't strand a plot we have no time bounds for).
+  let firstDataTime = -Infinity;
+  if (input.mode === "candle") {
+    const cs = input.candles;
+    if (cs && cs.length > 0) firstDataTime = cs[0].time;
+  } else if (input.points.length > 0) {
+    firstDataTime = input.points[0].time;
+  }
+  // Freeze the right edge while the pan gesture has parked `viewEnd` behind the
+  // live edge AND that edge still sits within the data. A frozen edge stranded
+  // before the active series' first point falls through to following live (so a
+  // line/candle span mismatch never strands the window on an empty plot). When
+  // time-scroll is disabled the hook clears `viewEnd` (and kicks off the glide
+  // below), so a stale edge can't keep the window frozen. See #164.
+  const scrolledBack =
+    viewEnd != null && viewEnd < liveEdge && viewEnd >= firstDataTime;
+  if (scrolledBack) {
     state.timestamp = viewEnd;
   } else if (!input.paused) {
-    // Following the live edge — viewEnd is null/undefined or has caught back up.
-    state.timestamp = liveEdge;
+    // Following live. While a "return to live" glide is in flight (returnT < 1)
+    // ease the right edge from the frozen `returnFrom` to the *current* live edge
+    // by returnT — converges exactly on live with no end-snap. Otherwise pin to
+    // the live edge (the steady-state follow).
+    const returnT = input.returnT;
+    if (returnT != null && returnT < 1 && input.returnFrom != null) {
+      state.timestamp =
+        input.returnFrom + (liveEdge - input.returnFrom) * returnT;
+    } else {
+      state.timestamp = liveEdge;
+    }
   }
   // else: paused with no active pan → leave the frozen timestamp untouched.
 
@@ -272,8 +308,7 @@ export function tickLiveChartEngineFrame(
   // Edge value: the price at the visible window's right edge. Following live →
   // track the live value (badge unchanged). Scrolled back → track the last
   // visible point/candle close, lerped so a `followViewEdge` badge glides to the
-  // last price as you pan.
-  const scrolledBack = viewEnd != null && viewEnd < liveEdge;
+  // last price as you pan. Reuses the gated `scrolledBack` computed above.
   if (!scrolledBack) {
     state.edgeValue = state.displayValue;
   } else {

package/src/core/liveChartSeriesEngineTick.ts

@@ -56,6 +56,16 @@ export interface MultiEngineTickInput {
    * precedence over {@link paused}.
    */
   viewEnd?: number | null;
+  /**
+   * "Return to live" glide (see #164). When time-scroll is disabled while scrolled
+   * back, the hook clears {@link viewEnd} and animates {@link returnT} `0`→`1`;
+   * each frame the right edge interpolates from {@link returnFrom} to the *current*
+   * live edge by `returnT`, gliding onto live with no end-snap. `1`/`undefined`
+   * pins to the live edge.
+   */
+  returnT?: number;
+  /** Frozen right-edge time the {@link returnT} glide starts from. */
+  returnFrom?: number;
   /**
    * Absolute visible-window width (seconds) to freeze at, or `null`/`undefined`
    * to follow {@link timeWindow}. Drives pinch-zoom (see `usePinchZoom`); the
@@ -78,12 +88,34 @@ export function tickLiveChartSeriesEngineFrame(
   const liveEdge = baseNow + (input.windowBuffer ?? 0) * input.timeWindow;
   state.liveEdge = liveEdge;
   const viewEnd = input.viewEnd;
-  if (viewEnd != null && viewEnd < liveEdge) {
-    // Scrolled back in time: freeze the right edge (see usePanScroll).
+  // Earliest first-point time across visible series — the floor a frozen edge
+  // must stay at or above. `-Infinity` when no visible series has data, so the
+  // freeze still works (nothing to bound the window against).
+  let firstDataTime = Infinity;
+  for (let i = 0; i < input.series.length; i++) {
+    if (input.series[i].visible === false) continue;
+    const d = input.series[i].data;
+    if (d.length > 0 && d[0].time < firstDataTime) firstDataTime = d[0].time;
+  }
+  if (firstDataTime === Infinity) firstDataTime = -Infinity;
+  // Freeze the right edge while the gesture has parked `viewEnd` behind the live
+  // edge AND that edge still sits within the data; a stranded edge falls through
+  // to following live. When time-scroll is disabled the hook clears `viewEnd` and
+  // kicks off the glide below, so a stale edge can't keep the window frozen. #164.
+  const scrolledBack =
+    viewEnd != null && viewEnd < liveEdge && viewEnd >= firstDataTime;
+  if (scrolledBack) {
     state.timestamp = viewEnd;
   } else if (!input.paused) {
-    // Following the live edge — viewEnd is null/undefined or has caught back up.
-    state.timestamp = liveEdge;
+    // Following live; ease from the frozen `returnFrom` to the current live edge
+    // while a "return to live" glide is in flight (returnT < 1), else pin to live.
+    const returnT = input.returnT;
+    if (returnT != null && returnT < 1 && input.returnFrom != null) {
+      state.timestamp =
+        input.returnFrom + (liveEdge - input.returnFrom) * returnT;
+    } else {
+      state.timestamp = liveEdge;
+    }
   }
   // else: paused with no active pan → leave the frozen timestamp untouched.
 
@@ -115,7 +147,7 @@ export function tickLiveChartSeriesEngineFrame(
   // window's right edge, so they must track each series' value AT that edge
   // (`timestamp`), not the live value — otherwise the dot floats at the current
   // price while the line ends in the past. Mirrors single-series `edgeValue`.
-  const scrolledBack = viewEnd != null && viewEnd < liveEdge;
+  // Reuses the gated `scrolledBack` computed above.
 
   for (let i = 0; i < n; i++) {
     let target = series[i].value;

package/src/core/resolveConfig.ts

@@ -25,6 +25,7 @@ import type {
   SelectionDotConfig,
   SelectionDotProps,
   SelectionDotRingConfig,
+  ReturnToLiveConfig,
   ThresholdConfig,
   ThresholdLineConfig,
   TradeEvent,
@@ -45,6 +46,7 @@ import {
   FADE_EDGE_WIDTH,
   GRID_METRICS_DEFAULTS,
   MOTION_METRICS_DEFAULTS,
+  RETURN_TO_LIVE_MS,
 } from "../constants";
 
 // ─── Resolved types (all fields required, no optionals) ──────────────────────
@@ -456,6 +458,25 @@ export function resolveZoom(
   return resolveToggle(prop, ZOOM_DEFAULTS, false);
 }
 
+/**
+ * Resolves `timeScroll.returnToLive` to the "return to live" glide duration in ms,
+ * where `0` means an instant snap (no animation):
+ *  - `undefined` / `true` → default {@link RETURN_TO_LIVE_MS}
+ *  - `false` → `0` (instant)
+ *  - `{ duration }` → that duration (a non-positive value collapses to `0`)
+ *
+ * See {@link ReturnToLiveConfig} / #164.
+ */
+export function resolveReturnToLiveMs(
+  prop: boolean | ReturnToLiveConfig | undefined,
+): number {
+  if (prop === false) return 0;
+  if (prop == null || prop === true) return RETURN_TO_LIVE_MS;
+  const d = prop.duration;
+  if (d == null) return RETURN_TO_LIVE_MS;
+  return d > 0 ? d : 0;
+}
+
 const AXIS_LABEL_DEFAULTS: ResolvedAxisLabelConfig = {
   format: undefined,
   color: undefined,

package/src/core/useLiveChartEngine.ts

@@ -7,13 +7,16 @@
  */
 import { useEffect, useState } from "react";
 import {
+  cancelAnimation,
+  Easing,
   useAnimatedReaction,
   useDerivedValue,
   useFrameCallback,
   useSharedValue,
+  withTiming,
   type SharedValue,
 } from "react-native-reanimated";
-import { MS_PER_FRAME_60FPS } from "../constants";
+import { MS_PER_FRAME_60FPS, RETURN_TO_LIVE_MS } from "../constants";
 import type { CandlePoint, LiveChartPoint, SeriesConfig } from "../types";
 import { tickLiveChartEngineFrame } from "./liveChartEngineTick";
 
@@ -39,6 +42,20 @@ export interface EngineConfig {
   nowOverride?: number;
   windowBuffer?: number;
   paused?: boolean;
+  /**
+   * Whether the `timeScroll` gesture is active. Flipping this to `false` while
+   * scrolled back clears {@link ChartEngineScroll.viewEnd} and **glides** the
+   * window back to the live edge (a brief eased animation, not an instant jump),
+   * so disabling time-scroll — or a mode switch that turns it off — never strands
+   * the chart at a past position. See #164.
+   */
+  scrollEnabled?: boolean;
+  /**
+   * Duration (ms) of the return-to-live glide when {@link scrollEnabled} flips to
+   * `false` while scrolled back. `0` snaps instantly (no animation). Defaults to
+   * {@link RETURN_TO_LIVE_MS}. Resolved from `timeScroll.returnToLive`. See #164.
+   */
+  returnToLiveMs?: number;
   /**
    * Loop-free render: settle the display state once (smoothing forced to 1, no
    * per-frame frame callback) for many small charts in a list. See
@@ -166,6 +183,10 @@ export interface EngineFrameRefs {
   pausedSV: SharedValue<boolean>;
   /** Pan-scroll right-edge override (null = follow live). Optional for callers/tests. */
   viewEndSV?: SharedValue<number | null>;
+  /** "Return to live" glide progress (0→1); the right edge eases to live. Optional. */
+  returnTSV?: SharedValue<number>;
+  /** Frozen right-edge time the return glide starts from. Optional. */
+  returnFromSV?: SharedValue<number>;
   /** Pinch-zoom window-width override (null = follow timeWindow). Optional for callers/tests. */
   viewWindowSV?: SharedValue<number | null>;
   /** Receives the computed live edge each frame. Optional for callers/tests. */
@@ -223,6 +244,8 @@ export function applyLiveChartEngineFrame(
     nowSeconds: Date.now() / 1000,
     paused: sv.pausedSV.value,
     viewEnd: sv.viewEndSV?.value,
+    returnT: sv.returnTSV?.value,
+    returnFrom: sv.returnFromSV?.value,
     viewWindow: sv.viewWindowSV?.value,
     mode: sv.modeSV.value,
     candles: sv.candles?.value,
@@ -283,6 +306,14 @@ export function useLiveChartEngine(
   const nowOverrideSV = useDerivedValue(() => config.nowOverride);
   const windowBufferSV = useDerivedValue(() => config.windowBuffer ?? 0);
   const pausedSV = useDerivedValue(() => config.paused ?? false);
+  // Whether time-scroll is active. Drives the return-to-live reaction below
+  // (the tick no longer reads it — clearing `viewEnd` is what makes it follow).
+  // Defaults to enabled so a caller that omits it behaves as before.
+  const scrollEnabledSV = useDerivedValue(() => config.scrollEnabled ?? true);
+  // Return-to-live glide duration (ms); 0 = instant snap. Read by the reaction.
+  const returnToLiveMsSV = useDerivedValue(
+    () => config.returnToLiveMs ?? RETURN_TO_LIVE_MS,
+  );
   const modeSV = useDerivedValue(() => config.mode ?? "line");
 
   // Animation state (mutated on UI thread each frame)
@@ -303,6 +334,12 @@ export function useLiveChartEngine(
   const viewEnd = useSharedValue<number | null>(null);
   const liveEdge = useSharedValue(initialTimestamp);
   const edgeValue = useSharedValue(0);
+  // "Return to live" glide (see #164). When time-scroll is disabled while scrolled
+  // back, the reaction below clears `viewEnd`, snapshots the frozen edge into
+  // `returnFrom`, and animates `returnT` 0→1; the tick eases the right edge onto
+  // the live edge over that progress. `returnT` rests at 1 (no glide in flight).
+  const returnT = useSharedValue(1);
+  const returnFrom = useSharedValue(0);
 
   // Live data extrema (value + time of the visible high / low). NaN until the
   // first tick finds data — the extrema label stays hidden until then.
@@ -343,6 +380,8 @@ export function useLiveChartEngine(
     windowBufferSV,
     pausedSV,
     viewEndSV: viewEnd,
+    returnTSV: returnT,
+    returnFromSV: returnFrom,
     viewWindowSV: viewWindow,
     liveEdgeSV: liveEdge,
     edgeValueSV: edgeValue,
@@ -362,6 +401,37 @@ export function useLiveChartEngine(
     applyLiveChartEngineFrame(frameInfo, frameRefs);
   }, !config.static);
 
+  // When time-scroll is disabled while scrolled back, return the window to the
+  // live edge. With a positive duration this glides: snapshot the frozen edge into
+  // `returnFrom`, clear `viewEnd` (so the tick stops freezing and follows), and
+  // animate `returnT` 0→1 — the tick interpolates `returnFrom`→live by that
+  // progress, landing exactly on live. Duration 0 (`returnToLive: false`) just
+  // clears `viewEnd` for an instant snap. Clearing `viewEnd` also means a later
+  // re-enable resumes from live, not the stale frozen position. All on the UI
+  // thread, no JS round-trip. See #164.
+  useAnimatedReaction(
+    () => scrollEnabledSV.value,
+    /* istanbul ignore next -- Reanimated reaction driven by a prop→derived change; not exercised under the SharedValue mock (see the viewWindow-reset test note), verified in-app */
+    (enabled, prev) => {
+      if (prev === true && !enabled && viewEnd.value != null) {
+        const ms = returnToLiveMsSV.value;
+        if (ms > 0) {
+          returnFrom.value = viewEnd.value;
+          cancelAnimation(viewEnd);
+          viewEnd.value = null;
+          returnT.value = 0;
+          returnT.value = withTiming(1, {
+            duration: ms,
+            easing: Easing.out(Easing.cubic),
+          });
+        } else {
+          cancelAnimation(viewEnd);
+          viewEnd.value = null; // returnT stays 1 → tick pins to live (instant)
+        }
+      }
+    },
+  );
+
   // One-shot settle for static charts: the fingerprint changes when the canvas
   // lays out (width 0→real) or the framing inputs change, and the handler runs a
   // single snap tick (smoothing=1). Inert when not static — `prepare` returns a

package/src/core/useLiveChartSeriesEngine.ts

@@ -1,11 +1,15 @@
 import { useRef, useState } from "react";
 import {
+  cancelAnimation,
+  Easing,
+  useAnimatedReaction,
   useDerivedValue,
   useFrameCallback,
   useSharedValue,
+  withTiming,
   type SharedValue,
 } from "react-native-reanimated";
-import { MS_PER_FRAME_60FPS } from "../constants";
+import { MS_PER_FRAME_60FPS, RETURN_TO_LIVE_MS } from "../constants";
 import type { LiveChartPoint, SeriesConfig } from "../types";
 import { tickLiveChartSeriesEngineFrame } from "./liveChartSeriesEngineTick";
 import type { ChartEngineScroll, MultiEngineState } from "./useLiveChartEngine";
@@ -24,6 +28,19 @@ export interface MultiSeriesEngineConfig {
   nowOverride?: number;
   windowBuffer?: number;
   paused?: boolean;
+  /**
+   * Whether the `timeScroll` gesture is active. Flipping to `false` while scrolled
+   * back clears {@link ChartEngineScroll.viewEnd} and **glides** the window back to
+   * the live edge (eased, not an instant jump), so disabling time-scroll never
+   * strands the chart at a past position. See #164.
+   */
+  scrollEnabled?: boolean;
+  /**
+   * Duration (ms) of the return-to-live glide when {@link scrollEnabled} flips to
+   * `false` while scrolled back. `0` snaps instantly. Defaults to
+   * {@link RETURN_TO_LIVE_MS}. Resolved from `timeScroll.returnToLive`. See #164.
+   */
+  returnToLiveMs?: number;
 }
 
 export interface MultiEngineFrameRefs {
@@ -49,6 +66,10 @@ export interface MultiEngineFrameRefs {
   pausedSV: SharedValue<boolean>;
   /** Pan-scroll right-edge override (null = follow live). Optional for callers/tests. */
   viewEndSV?: SharedValue<number | null>;
+  /** "Return to live" glide progress (0→1); the right edge eases to live. Optional. */
+  returnTSV?: SharedValue<number>;
+  /** Frozen right-edge time the return glide starts from. Optional. */
+  returnFromSV?: SharedValue<number>;
   /** Pinch-zoom window-width override (null = follow timeWindow). Optional for callers/tests. */
   viewWindowSV?: SharedValue<number | null>;
   /** Receives the computed live edge each frame. Optional for callers/tests. */
@@ -137,6 +158,8 @@ export function applyLiveChartSeriesEngineFrame(
     nowSeconds: Date.now() / 1000,
     paused: sv.pausedSV.value,
     viewEnd: sv.viewEndSV?.value,
+    returnT: sv.returnTSV?.value,
+    returnFrom: sv.returnFromSV?.value,
     viewWindow: sv.viewWindowSV?.value,
   });
   sv.displayMin.value = state.displayMin;
@@ -173,6 +196,13 @@ export function useLiveChartSeriesEngine(
   const nowOverrideSV = useDerivedValue(() => config.nowOverride);
   const windowBufferSV = useDerivedValue(() => config.windowBuffer ?? 0);
   const pausedSV = useDerivedValue(() => config.paused ?? false);
+  // Whether time-scroll is active — drives the return-to-live reaction below.
+  // Defaults to enabled (legacy behavior).
+  const scrollEnabledSV = useDerivedValue(() => config.scrollEnabled ?? true);
+  // Return-to-live glide duration (ms); 0 = instant snap. Read by the reaction.
+  const returnToLiveMsSV = useDerivedValue(
+    () => config.returnToLiveMs ?? RETURN_TO_LIVE_MS,
+  );
 
   const displayMin = useSharedValue(0);
   const displayMax = useSharedValue(1);
@@ -186,6 +216,10 @@ export function useLiveChartSeriesEngine(
   // Pan-scroll state (see useLiveChartEngine). Defaults to following live.
   const viewEnd = useSharedValue<number | null>(null);
   const liveEdge = useSharedValue(initialTimestamp);
+  // "Return to live" glide (see #164) — `returnT` rests at 1; the reaction below
+  // animates it 0→1 from `returnFrom` when time-scroll is disabled while scrolled.
+  const returnT = useSharedValue(1);
+  const returnFrom = useSharedValue(0);
 
   const displaySeriesValues = useSharedValue<number[]>([]);
   const seriesOpacities = useSharedValue<number[]>([]);
@@ -235,6 +269,8 @@ export function useLiveChartSeriesEngine(
         windowBufferSV,
         pausedSV,
         viewEndSV: viewEnd,
+        returnTSV: returnT,
+        returnFromSV: returnFrom,
         viewWindowSV: viewWindow,
         liveEdgeSV: liveEdge,
         extremaMinValue,
@@ -246,6 +282,34 @@ export function useLiveChartSeriesEngine(
     );
   });
 
+  // Return the window to live when time-scroll is disabled while scrolled back
+  // (mirrors useLiveChartEngine): with a positive duration, glide — snapshot the
+  // frozen edge, clear `viewEnd`, and animate `returnT` 0→1 so the tick eases
+  // `returnFrom`→live; duration 0 just clears `viewEnd` for an instant snap.
+  // Clearing `viewEnd` also means a later re-enable resumes from live. See #164.
+  useAnimatedReaction(
+    () => scrollEnabledSV.value,
+    /* istanbul ignore next -- Reanimated reaction driven by a prop→derived change; not exercised under the SharedValue mock, verified in-app */
+    (enabled, prev) => {
+      if (prev === true && !enabled && viewEnd.value != null) {
+        const ms = returnToLiveMsSV.value;
+        if (ms > 0) {
+          returnFrom.value = viewEnd.value;
+          cancelAnimation(viewEnd);
+          viewEnd.value = null;
+          returnT.value = 0;
+          returnT.value = withTiming(1, {
+            duration: ms,
+            easing: Easing.out(Easing.cubic),
+          });
+        } else {
+          cancelAnimation(viewEnd);
+          viewEnd.value = null;
+        }
+      }
+    },
+  );
+
   return {
     data,
     value,