react-native-livechart 4.2.1 → 4.4.0

package/package.json

@@ -67,5 +67,5 @@
   },
   "sideEffects": false,
   "types": "./dist/index.d.ts",
-  "version": "4.2.1"
+  "version": "4.4.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);
       }
     },

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/components/MarkerOverlay.tsx

@@ -4,6 +4,8 @@ import {
   Path,
   Skia,
   type SkFont,
+  type SkRect,
+  type SkRSXform,
 } from "@shopify/react-native-skia";
 import { useMemo, useRef, useState } from "react";
 import { PixelRatio } from "react-native";
@@ -20,6 +22,7 @@ import {
   BADGE_TEXT_SCALE,
   buildMarkerAtlas,
   defaultMarkerColor,
+  GROUP_BADGE_SIG,
   groupBgSig,
   groupCountText,
   groupGlyphSig,
@@ -47,6 +50,77 @@ import type {
 
 const OFF = -9999;
 
+/** Size of the `showGroupCount` corner badge relative to a full count badge. */
+const GROUP_CORNER_SCALE = 0.62;
+/** How far the corner count badge sits toward the glyph's top-right corner
+ *  (1 = centered exactly on the corner; < 1 pulls it inward). */
+const GROUP_CORNER_INSET = 0.82;
+
+/**
+ * Append a collapsed-cluster count badge (round bg + centered, proportionally
+ * kerned digits) to the atlas blit lists at `(cx, cy)`, scaled by `mul` — full
+ * size as the default group badge, shrunk in a glyph's corner for `showGroupCount`.
+ *
+ * A **module-level** worklet (not a closure inside the per-frame derived value):
+ * the `transforms` / `sprites` arrays are passed in by reference so the pushes land
+ * on the real per-frame lists. A nested `"worklet"` closure would capture them by
+ * serialized copy, so its pushes would be silently dropped and the badge never drawn.
+ */
+function pushGroupCountBadge(
+  transforms: SkRSXform[],
+  sprites: SkRect[],
+  cells: Record<string, AtlasCell>,
+  digitWidths: Record<string, number>,
+  invScale: number,
+  cx: number,
+  cy: number,
+  repColor: string,
+  count: number,
+  mul: number,
+): void {
+  "worklet";
+  const text = groupCountText(count);
+  const bg = cells[groupBgSig(repColor)];
+  if (bg) {
+    transforms.push(
+      Skia.RSXform(invScale * mul, 0, cx - (bg.w * mul) / 2, cy - (bg.h * mul) / 2),
+    );
+    sprites.push(bg.rect);
+  }
+  // Lay digits out proportionally (each by its own ink width), scaled to fit the
+  // small round badge, centered. A negative kern (fraction of a digit) closes the
+  // font's side-bearing gap so "12" reads tight, not "1 2".
+  const S = BADGE_TEXT_SCALE;
+  let maxDW = 1;
+  for (let d = 0; d < 10; d++) {
+    const dw = digitWidths["" + d] ?? 0;
+    if (dw > maxDW) maxDW = dw;
+  }
+  const kern = -maxDW * S * 0.42;
+  let totalW = 0;
+  for (let c = 0; c < text.length; c++) {
+    totalW += (digitWidths[text[c]] ?? 0) * S + (c > 0 ? kern : 0);
+  }
+  let dx = cx - (totalW * mul) / 2;
+  for (let c = 0; c < text.length; c++) {
+    const w = (digitWidths[text[c]] ?? 0) * S * mul;
+    const gc = cells[groupGlyphSig(text[c])];
+    if (gc) {
+      const gcx = dx + w / 2;
+      transforms.push(
+        Skia.RSXform(
+          invScale * S * mul,
+          0,
+          gcx - (gc.w * S * mul) / 2,
+          cy - (gc.h * S * mul) / 2,
+        ),
+      );
+      sprites.push(gc.rect);
+    }
+    dx += w + kern * mul;
+  }
+}
+
 /**
  * Self-projecting fallback for the axis-anchored kinds (graduation stem + flag,
  * clawback box) that can't be fixed-size atlas sprites. Rare, so the per-glyph
@@ -246,6 +320,14 @@ export function MarkerOverlay({
   // retina canvases instead of being upscaled from a logical-sized texture.
   const dpr = PixelRatio.get();
   const clusterStacked = cluster.mode === "stacked";
+  // A dedicated group badge (object form) bakes one extra atlas cell; its image
+  // identity + styling drive the rebuild key alongside the marker appearances.
+  const groupBadgeCfg =
+    typeof cluster.groupBadge === "object" ? cluster.groupBadge : undefined;
+  const groupBadgeImage = groupBadgeCfg?.image;
+  const groupBadgeKey = groupBadgeCfg
+    ? `${groupBadgeCfg.icon ?? ""}|${groupBadgeCfg.color ?? ""}|${groupBadgeCfg.pill ? 1 : 0}|${groupBadgeCfg.size ?? ""}`
+    : "";
   const atlas = useMemo(
     () =>
       buildMarkerAtlas(
@@ -254,9 +336,10 @@ export function MarkerOverlay({
         font,
         dpr,
         clusterStacked,
+        groupBadgeCfg,
       ),
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- appearanceKey/paletteKey capture the inputs that change cell pixels
-    [appearanceKey, paletteKey, font, dpr, clusterStacked],
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- appearanceKey/paletteKey/groupBadgeKey capture the inputs that change cell pixels
+    [appearanceKey, paletteKey, font, dpr, clusterStacked, groupBadgeKey, groupBadgeImage],
   );
   const cells: Record<string, AtlasCell> = atlas.cells;
   const atlasImage = atlas.image;
@@ -301,8 +384,8 @@ export function MarkerOverlay({
         lineLinear,
       });
       clusterMarkers(ms, buf, { config: cluster });
-      const transforms = [];
-      const sprites = [];
+      const transforms: SkRSXform[] = [];
+      const sprites: SkRect[] = [];
       for (let i = 0; i < ms.length; i++) {
         const pt = buf[i];
         // Collapsed-cluster members fold into their representative's badge.
@@ -311,46 +394,61 @@ export function MarkerOverlay({
         if (isConnectorMarker(m)) continue;
         // Custom-rendered markers are floated as RN views, not drawn here.
         if (customIds[m.id]) continue;
-        // Collapsed cluster: draw a count badge (bg stadium + composed digits)
-        // instead of the marker's own glyph, all within this one `drawAtlas`.
+        // Collapsed cluster. By default a round count badge; with
+        // `groupBadge: "marker"` the representative marker's own glyph, or with a
+        // `MarkerGroupBadge` object a dedicated baked badge — either optionally
+        // carrying a corner count, all within this one `drawAtlas`.
         if (pt.isGrouped) {
           const repColor = m.color ?? defaultMarkerColor(m.kind, palette);
-          const text = groupCountText(pt.groupCount);
-          const bg = cells[groupBgSig(repColor)];
-          if (bg) {
+          const gb = cluster.groupBadge;
+          // Pick the non-count glyph cell: a dedicated group badge (object form)
+          // or the representative marker's own appearance.
+          const glyphCell =
+            typeof gb === "object" && gb !== null
+              ? cells[GROUP_BADGE_SIG]
+              : gb === "marker"
+                ? cells[markerAppearanceSig(m)]
+                : undefined;
+          if (glyphCell) {
             transforms.push(
-              Skia.RSXform(invScale, 0, pt.x - bg.w / 2, pt.y - bg.h / 2),
+              Skia.RSXform(
+                invScale,
+                0,
+                pt.x - glyphCell.w / 2,
+                pt.y - glyphCell.h / 2,
+              ),
             );
-            sprites.push(bg.rect);
-          }
-          // Lay the digits out proportionally (each by its own ink width), scaled
-          // down to fit the small round badge, and center the whole number. A
-          // negative kern (fraction of a digit) closes the font's side-bearing gap
-          // so "12" reads tight, not "1 2".
-          const S = BADGE_TEXT_SCALE;
-          let maxDW = 1;
-          for (let d = 0; d < 10; d++) {
-            const dw = digitWidths["" + d] ?? 0;
-            if (dw > maxDW) maxDW = dw;
-          }
-          const kern = -maxDW * S * 0.42;
-          let totalW = 0;
-          for (let c = 0; c < text.length; c++) {
-            totalW += (digitWidths[text[c]] ?? 0) * S + (c > 0 ? kern : 0);
-          }
-          let dx = pt.x - totalW / 2;
-          for (let c = 0; c < text.length; c++) {
-            const w = (digitWidths[text[c]] ?? 0) * S;
-            const gc = cells[groupGlyphSig(text[c])];
-            if (gc) {
-              const cx = dx + w / 2;
-              transforms.push(
-                Skia.RSXform(invScale * S, 0, cx - (gc.w * S) / 2, pt.y - (gc.h * S) / 2),
+            sprites.push(glyphCell.rect);
+            if (cluster.showGroupCount) {
+              pushGroupCountBadge(
+                transforms,
+                sprites,
+                cells,
+                digitWidths,
+                invScale,
+                pt.x + (glyphCell.w / 2) * GROUP_CORNER_INSET,
+                pt.y - (glyphCell.h / 2) * GROUP_CORNER_INSET,
+                repColor,
+                pt.groupCount,
+                GROUP_CORNER_SCALE,
               );
-              sprites.push(gc.rect);
             }
-            dx += w + kern;
+            continue;
           }
+          // Default — or fall back here when a non-count badge has no baked cell
+          // (e.g. an empty group-badge config): the round count badge.
+          pushGroupCountBadge(
+            transforms,
+            sprites,
+            cells,
+            digitWidths,
+            invScale,
+            pt.x,
+            pt.y,
+            repColor,
+            pt.groupCount,
+            1,
+          );
           continue;
         }
         const cell = cells[markerAppearanceSig(m)];

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,
@@ -613,6 +634,8 @@ export function resolveMarkerCluster(
       overlap: clamp01(prop.overlap ?? MARKER_CLUSTER_OVERLAP),
       gap: MARKER_CLUSTER_GAP,
       maxBeforeGroup: prop.maxBeforeGroup ?? MARKER_CLUSTER_MAX_BEFORE_GROUP,
+      groupBadge: prop.groupBadge ?? "count",
+      showGroupCount: prop.showGroupCount ?? false,
     };
   }
   return {
@@ -621,6 +644,8 @@ export function resolveMarkerCluster(
     overlap: MARKER_CLUSTER_OVERLAP,
     gap: MARKER_CLUSTER_GAP,
     maxBeforeGroup: MARKER_CLUSTER_MAX_BEFORE_GROUP,
+    groupBadge: "count",
+    showGroupCount: false,
   };
 }
 

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