react-native-livechart 3.11.0 → 4.0.0

package/src/core/liveChartEngineTick.ts

@@ -9,6 +9,20 @@ export interface EngineTickMutable {
   displayMax: number;
   displayWindow: number;
   timestamp: number;
+  /**
+   * The right-edge time the engine would use if it were following live —
+   * `now (+ windowBuffer)`. Equals {@link timestamp} while following; when
+   * scrolled back in time (see {@link EngineTickInput.viewEnd}) it keeps
+   * advancing while `timestamp` stays frozen. Exposed so the pan-scroll gesture
+   * can clamp against the live edge and detect catch-up.
+   */
+  liveEdge: number;
+  /**
+   * Smoothed value at the visible window's right edge: the live value while
+   * following, or the price at `viewEnd` while scrolled back. Lets a badge track
+   * the last visible price as you pan (see `badge.followViewEdge`).
+   */
+  edgeValue: number;
   /**
    * Value + time of the lowest / highest data point in the visible window —
    * the actual extrema, NOT the smoothed display bounds (which carry margin and
@@ -48,6 +62,21 @@ export interface EngineTickInput {
   windowBuffer?: number;
   /** When true, freeze the viewport timestamp and skip displayWindow lerp */
   paused?: boolean;
+  /**
+   * Absolute right-edge time (unix seconds) to freeze the window at, or
+   * `null`/`undefined` to follow the live edge. Set by the pan-scroll gesture
+   * to scroll back in time; once it reaches (or passes) the live edge the engine
+   * resumes following. Takes precedence over {@link paused}.
+   */
+  viewEnd?: number | null;
+  /**
+   * Absolute visible-window width (seconds) to freeze at, or `null`/`undefined`
+   * to follow the configured {@link timeWindow}. Set by the pinch-zoom gesture
+   * (see `usePinchZoom` / the `zoom` prop). The symmetric counterpart of
+   * {@link viewEnd}: `viewEnd` overrides the window's right edge, `viewWindow`
+   * overrides its width. `displayWindow` eases toward this when set.
+   */
+  viewWindow?: number | null;
   /** Chart mode — `"candle"` uses OHLC bars for Y range instead of line points. */
   mode?: "line" | "candle";
   /** Committed OHLC bars (sorted by time). Used when mode is `"candle"`. */
@@ -66,9 +95,18 @@ export function tickLiveChartEngineFrame(
 ): void {
   "worklet";
   const baseNow = input.nowOverride ?? input.nowSeconds ?? Date.now() / 1000;
-  if (!input.paused) {
-    state.timestamp = baseNow + (input.windowBuffer ?? 0) * input.timeWindow;
+  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).
+    state.timestamp = viewEnd;
+  } else if (!input.paused) {
+    // Following the live edge — viewEnd is null/undefined or has caught back up.
+    state.timestamp = liveEdge;
   }
+  // else: paused with no active pan → leave the frozen timestamp untouched.
 
   if (input.canvasWidth === 0 || input.canvasHeight === 0) return;
 
@@ -93,12 +131,10 @@ export function tickLiveChartEngineFrame(
     input.dt,
   );
 
-  state.displayWindow = lerp(
-    state.displayWindow,
-    input.timeWindow,
-    speed,
-    input.dt,
-  );
+  // Pinch-zoom: ease toward the zoom override when set, else the configured
+  // window. Mirrors the viewEnd freeze above (width vs. right edge).
+  const targetWindow = input.viewWindow ?? input.timeWindow;
+  state.displayWindow = lerp(state.displayWindow, targetWindow, speed, input.dt);
 
   const winStart = state.timestamp - state.displayWindow;
 
@@ -232,4 +268,41 @@ export function tickLiveChartEngineFrame(
       state.displayMax = lerp(state.displayMax, tMax, speed, input.dt);
     }
   }
+
+  // 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;
+  if (!scrolledBack) {
+    state.edgeValue = state.displayValue;
+  } else {
+    let edgeTarget = state.displayValue;
+    if (input.mode === "candle") {
+      const cs = input.candles;
+      if (cs && cs.length > 0) {
+        let elo = 0;
+        let ehi = cs.length;
+        while (elo < ehi) {
+          const m = (elo + ehi) >> 1;
+          if (cs[m].time <= state.timestamp) elo = m + 1;
+          else ehi = m;
+        }
+        if (elo > 0) edgeTarget = cs[elo - 1].close;
+      }
+      const lc = input.liveCandle;
+      if (lc && lc.time <= state.timestamp) edgeTarget = lc.close;
+    } else {
+      const pts = input.points;
+      let elo = 0;
+      let ehi = pts.length;
+      while (elo < ehi) {
+        const m = (elo + ehi) >> 1;
+        if (pts[m].time <= state.timestamp) elo = m + 1;
+        else ehi = m;
+      }
+      if (elo > 0) edgeTarget = pts[elo - 1].value;
+    }
+    state.edgeValue = lerp(state.edgeValue, edgeTarget, speed, input.dt);
+  }
 }

package/src/core/liveChartSeriesEngineTick.ts

@@ -7,6 +7,12 @@ export interface MultiEngineTickMutable {
   displayMax: number;
   displayWindow: number;
   timestamp: number;
+  /**
+   * The right-edge time the engine would use if following live (`now (+ buffer)`).
+   * Equals {@link timestamp} while following; keeps advancing while `timestamp`
+   * stays frozen when scrolled back (see {@link MultiEngineTickInput.viewEnd}).
+   */
+  liveEdge: number;
   displayValues: number[];
   opacities: number[];
   /**
@@ -44,6 +50,18 @@ export interface MultiEngineTickInput {
   /** Right-edge buffer as a fraction of the time window. */
   windowBuffer?: number;
   paused?: boolean;
+  /**
+   * Absolute right-edge time (unix seconds) to freeze the window at, or
+   * `null`/`undefined` to follow the live edge. Drives pan-scroll; takes
+   * precedence over {@link paused}.
+   */
+  viewEnd?: number | null;
+  /**
+   * Absolute visible-window width (seconds) to freeze at, or `null`/`undefined`
+   * to follow {@link timeWindow}. Drives pinch-zoom (see `usePinchZoom`); the
+   * symmetric counterpart of {@link viewEnd}.
+   */
+  viewWindow?: number | null;
 }
 
 /**
@@ -57,9 +75,17 @@ export function tickLiveChartSeriesEngineFrame(
 ): void {
   "worklet";
   const baseNow = input.nowOverride ?? input.nowSeconds ?? Date.now() / 1000;
-  if (!input.paused) {
-    state.timestamp = baseNow + (input.windowBuffer ?? 0) * input.timeWindow;
+  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).
+    state.timestamp = viewEnd;
+  } else if (!input.paused) {
+    // Following the live edge — viewEnd is null/undefined or has caught back up.
+    state.timestamp = liveEdge;
   }
+  // else: paused with no active pan → leave the frozen timestamp untouched.
 
   if (input.canvasWidth === 0 || input.canvasHeight === 0) return;
 
@@ -77,18 +103,33 @@ export function tickLiveChartSeriesEngineFrame(
     state.opacities.length = n;
   }
 
-  state.displayWindow = lerp(
-    state.displayWindow,
-    input.timeWindow,
-    speed,
-    input.dt,
-  );
+  // Pinch-zoom: ease toward the zoom override when set, else the configured
+  // window (mirrors the single-series tick).
+  const targetWindow = input.viewWindow ?? input.timeWindow;
+  state.displayWindow = lerp(state.displayWindow, targetWindow, speed, input.dt);
 
   const winStart = state.timestamp - state.displayWindow;
   const range = state.displayMax - state.displayMin;
 
+  // Scrolled back in time (pan/zoom): the per-series tips/dots sit at the
+  // 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;
+
   for (let i = 0; i < n; i++) {
-    const target = series[i].value;
+    let target = series[i].value;
+    if (scrolledBack) {
+      const pts = series[i].data;
+      let elo = 0;
+      let ehi = pts.length;
+      while (elo < ehi) {
+        const m = (elo + ehi) >> 1;
+        if (pts[m].time <= state.timestamp) elo = m + 1;
+        else ehi = m;
+      }
+      if (elo > 0) target = pts[elo - 1].value;
+    }
     const cur = state.displayValues[i];
     const gapRatio =
       range > 0 ? Math.min(Math.abs(target - cur) / range, 1) : 0;

package/src/core/resolveConfig.ts

@@ -14,6 +14,7 @@ import type {
   LineStyleConfig,
   LiveChartMetrics,
   LiveChartMetricsOverride,
+  MarkerClusterConfig,
   DotConfig,
   DotRingConfig,
   MultiSeriesDotConfig,
@@ -28,12 +29,15 @@ import type {
   ThresholdLineConfig,
   TradeEvent,
   ValueLineConfig,
+  VolumeConfig,
   XAxisConfig,
   YAxisConfig,
+  ZoomConfig,
 } from "../types";
 
 import type { ComponentType, ReactElement } from "react";
 import type { SharedValue } from "react-native-reanimated";
+import type { ResolvedMarkerCluster } from "../math/markerCluster";
 import {
   BADGE_METRICS_DEFAULTS,
   CANDLE_METRICS_DEFAULTS,
@@ -57,10 +61,39 @@ export interface ResolvedBadgeConfig {
   tail: boolean;
   position: "right" | "left";
   background: string | undefined;
+  /** undefined → capsule (pillHeight / 2) at render time */
+  radius: number | undefined;
+  /** undefined → no border */
+  borderColor: string | undefined;
+  borderWidth: number;
+  /** undefined → variant/theme text color at render time */
+  textColor: string | undefined;
+  fontSize: number | undefined;
+  fontFamily: string | undefined;
+  fontWeight: FontWeight | undefined;
+  offsetX: number;
+  offsetY: number;
+  /** Track the visible window's right-edge price while scrolled back. */
+  followViewEdge: boolean;
 }
 
 export interface ResolvedYAxisConfig {
   minGap: number;
+  /** Float the axis over a full-width plot (no reserved right gutter). */
+  float: boolean;
+}
+
+export interface ResolvedVolumeConfig {
+  /** undefined → use palette.candleUp at render time. */
+  upColor: string | undefined;
+  /** undefined → use palette.candleDown at render time. */
+  downColor: string | undefined;
+  /** Reserved band height (px) — the tallest a bar can be. */
+  maxHeight: number;
+  /** Corner radius (px) of bar tops. */
+  radius: number;
+  /** Opacity (0..1) applied to the whole band. */
+  opacity: number;
 }
 
 /** Resolved straight-line styling (connector, etc.). `color: undefined` → caller default. */
@@ -119,7 +152,7 @@ export interface ResolvedScrubConfig {
   /** Tooltip pill corner radius in px. */
   tooltipBorderRadius: number;
   /** Where the tooltip pill sits relative to the scrub line. */
-  tooltipPlacement: "side" | "top" | "bottom";
+  tooltipPlacement: "side" | "top" | "bottom" | "point";
   /** Gap (px) between the tooltip and the plot edge it's pinned to. */
   tooltipMargin: number;
   /** Show the value row in the default tooltip body. */
@@ -336,6 +369,16 @@ const BADGE_DEFAULTS: ResolvedBadgeConfig = {
   tail: true,
   position: "right",
   background: undefined,
+  radius: undefined,
+  borderColor: undefined,
+  borderWidth: 1,
+  textColor: undefined,
+  fontSize: undefined,
+  fontFamily: undefined,
+  fontWeight: undefined,
+  offsetX: 0,
+  offsetY: 0,
+  followViewEdge: false,
 };
 
 /**
@@ -350,6 +393,7 @@ export function resolveBadge(
 
 const Y_AXIS_DEFAULTS: ResolvedYAxisConfig = {
   minGap: 36,
+  float: false,
 };
 
 /**
@@ -362,6 +406,47 @@ export function resolveYAxis(
   return resolveToggle(prop, Y_AXIS_DEFAULTS, false);
 }
 
+const VOLUME_DEFAULTS: ResolvedVolumeConfig = {
+  upColor: undefined,
+  downColor: undefined,
+  maxHeight: 48,
+  radius: 2,
+  opacity: 0.6,
+};
+
+/**
+ * Resolves the `volume` prop to a fully-typed config or null (disabled).
+ * `true` → defaults, object → merged with defaults, falsy → null. Colors left
+ * `undefined` fall back to the candle palette at render time.
+ */
+export function resolveVolume(
+  prop: boolean | VolumeConfig | undefined,
+): ResolvedVolumeConfig | null {
+  return resolveToggle(prop, VOLUME_DEFAULTS, false);
+}
+
+export interface ResolvedZoomConfig {
+  /** Tightest window (max zoom-in), seconds. `undefined` → `timeWindow / 8`. */
+  minTimeWindow: number | undefined;
+  /** Widest window (max zoom-out), seconds. `undefined` → full data span. */
+  maxTimeWindow: number | undefined;
+}
+
+const ZOOM_DEFAULTS: ResolvedZoomConfig = {
+  minTimeWindow: undefined,
+  maxTimeWindow: undefined,
+};
+
+/**
+ * Resolves the `zoom` prop to a config or null (disabled). `true` → defaults
+ * (bounds derived at gesture time), object → merged, falsy → null.
+ */
+export function resolveZoom(
+  prop: boolean | ZoomConfig | undefined,
+): ResolvedZoomConfig | null {
+  return resolveToggle(prop, ZOOM_DEFAULTS, false);
+}
+
 const AXIS_LABEL_DEFAULTS: ResolvedAxisLabelConfig = {
   format: undefined,
   color: undefined,
@@ -496,6 +581,42 @@ export function resolveScrubAction(
   return resolveToggle(prop, SCRUB_ACTION_DEFAULTS, false);
 }
 
+/** Spacing + collapse-threshold defaults for `markerCluster: "stacked"`. */
+const MARKER_CLUSTER_GAP = 2;
+const MARKER_CLUSTER_MAX_BEFORE_GROUP = 5;
+const MARKER_CLUSTER_OVERLAP = 0.75;
+
+/**
+ * Resolves the `markerCluster` prop (a `"anchored"`/`"stacked"` shorthand or a
+ * {@link MarkerClusterConfig} object) to a full config. Always returns a config
+ * (never null) — `"anchored"` (the default) is a valid mode the cluster pass
+ * treats as "side offsets only, no bucketing". The object form implies
+ * `"stacked"` unless `mode` is set.
+ */
+export function resolveMarkerCluster(
+  prop: "anchored" | "stacked" | MarkerClusterConfig | undefined,
+): ResolvedMarkerCluster {
+  if (typeof prop === "object") {
+    return {
+      mode: prop.mode ?? "stacked",
+      overlap: clamp01(prop.overlap ?? MARKER_CLUSTER_OVERLAP),
+      gap: MARKER_CLUSTER_GAP,
+      maxBeforeGroup: prop.maxBeforeGroup ?? MARKER_CLUSTER_MAX_BEFORE_GROUP,
+    };
+  }
+  return {
+    mode: prop === "stacked" ? "stacked" : "anchored",
+    overlap: MARKER_CLUSTER_OVERLAP,
+    gap: MARKER_CLUSTER_GAP,
+    maxBeforeGroup: MARKER_CLUSTER_MAX_BEFORE_GROUP,
+  };
+}
+
+/** Clamp to [0, 0.95] so a glyph never fully covers its neighbor (overlap 1). */
+function clamp01(v: number): number {
+  return v < 0 ? 0 : v > 0.95 ? 0.95 : v;
+}
+
 const GRADIENT_DEFAULTS: ResolvedGradientConfig = {
   topOpacity: undefined,
   bottomOpacity: undefined,

package/src/core/useLiveChartEngine.ts

@@ -27,6 +27,13 @@ export interface EngineConfig {
   exaggerate?: boolean;
   referenceValue?: number;
   referenceValues?: number[];
+  /**
+   * Live, per-frame Y values to fold into the axis-range fit on top of the static
+   * {@link referenceValues} — used so a *dragging* reference line expands the range
+   * and the axis follows the finger smoothly (the committed values already sit in
+   * `referenceValues`). Read on the UI thread each frame; omit for non-draggable charts.
+   */
+  liveReferenceValues?: SharedValue<number[]>;
   nonNegative?: boolean;
   maxValue?: number;
   nowOverride?: number;
@@ -50,12 +57,14 @@ export interface ChartEngineLayout {
   /** Animating window (lerps toward {@link timeWindow}); use for positioning. */
   displayWindow: SharedValue<number>;
   /**
-   * The target window from props — the exact value `displayWindow` eases toward.
-   * Tick *selection* (which X-axis labels exist) must read this, not
-   * `displayWindow`: the lerp is asymptotic and never reaches the target, so it
-   * settles just above or just below it depending on the prior window. Bucketing
-   * that off-by-epsilon value (e.g. via `niceTimeInterval`) would otherwise make
-   * the tick cadence depend on where you came from. See issue #126.
+   * The *effective* target window — the value `displayWindow` eases toward: the
+   * pinch-zoom override ({@link ChartEngineScroll.viewWindow}) when active, else
+   * the `timeWindow` prop. Tick *selection* (which X-axis labels exist) must read
+   * this, not `displayWindow`: the lerp is asymptotic and never reaches the
+   * target, so it settles just above or just below it depending on the prior
+   * window. Bucketing that off-by-epsilon value (e.g. via `niceTimeInterval`)
+   * would otherwise make the tick cadence depend on where you came from. See
+   * issue #126.
    */
   timeWindow: SharedValue<number>;
   canvasWidth: SharedValue<number>;
@@ -76,6 +85,42 @@ export interface ChartEngineExtrema {
   extremaMaxTime: SharedValue<number>;
 }
 
+/**
+ * Time-scroll state: lets a pan gesture freeze the window at an absolute time
+ * and resume following the live edge. Returned by both engines (intersected onto
+ * the state) but kept off {@link ChartEngineLayout} so overlay components — which
+ * only read the layout — don't have to carry it.
+ */
+export interface ChartEngineScroll {
+  /**
+   * Absolute right-edge time (unix seconds) to freeze at, or `null` to follow
+   * the live edge. Written by the pan-scroll gesture; read by the engine tick.
+   */
+  viewEnd: SharedValue<number | null>;
+  /**
+   * The right-edge time the engine would use if following live — advances each
+   * frame even while {@link ChartEngineLayout.timestamp} is frozen by a pan.
+   */
+  liveEdge: SharedValue<number>;
+  /**
+   * Absolute visible-window width (seconds) to freeze at, or `null` to follow
+   * the configured `timeWindow`. Written by the pinch-zoom gesture; the
+   * symmetric counterpart of {@link viewEnd} (width vs. right edge). Folded into
+   * {@link ChartEngineLayout.timeWindow}, so downstream selection/positioning
+   * picks up the zoom for free.
+   */
+  viewWindow: SharedValue<number | null>;
+}
+
+/** Single-series only: smoothed price at the visible window's right edge. */
+export interface ChartEngineEdge {
+  /**
+   * Smoothed value at the window's right edge — the live value while following,
+   * the price at `viewEnd` while scrolled back. For a `followViewEdge` badge.
+   */
+  edgeValue: SharedValue<number>;
+}
+
 export interface SingleEngineState extends ChartEngineLayout, ChartEngineExtrema {
   data: SharedValue<LiveChartPoint[]>;
   value: SharedValue<number>;
@@ -119,6 +164,14 @@ export interface EngineFrameRefs {
   nowOverrideSV?: SharedValue<number | undefined>;
   windowBufferSV?: SharedValue<number>;
   pausedSV: SharedValue<boolean>;
+  /** Pan-scroll right-edge override (null = follow live). Optional for callers/tests. */
+  viewEndSV?: SharedValue<number | null>;
+  /** 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. */
+  liveEdgeSV?: SharedValue<number>;
+  /** Receives the smoothed right-edge value each frame. Optional for callers/tests. */
+  edgeValueSV?: SharedValue<number>;
   modeSV: SharedValue<"line" | "candle">;
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
@@ -144,6 +197,8 @@ export function applyLiveChartEngineFrame(
     displayMax: sv.displayMax.value,
     displayWindow: sv.displayWindow.value,
     timestamp: sv.timestamp.value,
+    liveEdge: sv.liveEdgeSV?.value ?? 0,
+    edgeValue: sv.edgeValueSV?.value ?? 0,
     extremaMinValue: sv.extremaMinValue.value,
     extremaMaxValue: sv.extremaMaxValue.value,
     extremaMinTime: sv.extremaMinTime.value,
@@ -167,6 +222,8 @@ export function applyLiveChartEngineFrame(
     points: sv.data.value,
     nowSeconds: Date.now() / 1000,
     paused: sv.pausedSV.value,
+    viewEnd: sv.viewEndSV?.value,
+    viewWindow: sv.viewWindowSV?.value,
     mode: sv.modeSV.value,
     candles: sv.candles?.value,
     liveCandle: sv.liveCandle?.value,
@@ -176,15 +233,27 @@ export function applyLiveChartEngineFrame(
   sv.displayMax.value = state.displayMax;
   sv.displayWindow.value = state.displayWindow;
   sv.timestamp.value = state.timestamp;
+  if (sv.liveEdgeSV) sv.liveEdgeSV.value = state.liveEdge;
+  if (sv.edgeValueSV) sv.edgeValueSV.value = state.edgeValue;
   sv.extremaMinValue.value = state.extremaMinValue;
   sv.extremaMaxValue.value = state.extremaMaxValue;
   sv.extremaMinTime.value = state.extremaMinTime;
   sv.extremaMaxTime.value = state.extremaMaxTime;
 }
 
-export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
-  // Low-frequency config → UI thread via useDerivedValue
-  const timeWindow = useDerivedValue(() => config.timeWindow);
+export function useLiveChartEngine(
+  config: EngineConfig,
+): SingleEngineState & ChartEngineScroll & ChartEngineEdge {
+  // Pinch-zoom window-width override (null = follow the configured window).
+  // Declared first so `timeWindow` below can fold it in. Defaults to null so
+  // charts without `zoom` behave exactly as before.
+  const viewWindow = useSharedValue<number | null>(null);
+
+  // Low-frequency config → UI thread via useDerivedValue. `timeWindow` is the
+  // *effective* target window: the zoom override when set, else the prop. Both
+  // the tick's window lerp and the X-axis tick selection read it, so zoom flows
+  // downstream for free (mirrors how viewEnd drives `timestamp`).
+  const timeWindow = useDerivedValue(() => viewWindow.value ?? config.timeWindow);
   // Static charts snap to their target in one tick (smoothing=1), so the single
   // settle reaction below produces the final state with no per-frame easing.
   const smoothing = useDerivedValue(() =>
@@ -193,7 +262,15 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   const adaptiveSpeedBoostSV = useDerivedValue(() => config.adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
   const referenceValue = useDerivedValue(() => config.referenceValue);
-  const referenceValues = useDerivedValue(() => config.referenceValues);
+  // Captured directly (not via `config.`) so Reanimated tracks the SharedValue and
+  // the merge re-runs each frame while a line is dragged; stable when idle.
+  const liveReferenceValuesSV = config.liveReferenceValues;
+  const referenceValues = useDerivedValue(() => {
+    const base = config.referenceValues;
+    const live = liveReferenceValuesSV?.value;
+    if (!live || live.length === 0) return base;
+    return base && base.length > 0 ? base.concat(live) : live;
+  });
   const nonNegativeSV = useDerivedValue(() => config.nonNegative ?? false);
   const maxValueSV = useDerivedValue(() => config.maxValue);
   const nowOverrideSV = useDerivedValue(() => config.nowOverride);
@@ -212,6 +289,14 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   const [initialTimestamp] = useState(() => Date.now() / 1000);
   const timestamp = useSharedValue(initialTimestamp);
 
+  // Pan-scroll state. `viewEnd` null = follow live; a number freezes the right
+  // edge at that absolute time. `liveEdge` mirrors the would-be-live timestamp
+  // each frame so the gesture can clamp / detect catch-up. Both default to
+  // "following" so charts without `timeScroll` behave exactly as before.
+  const viewEnd = useSharedValue<number | null>(null);
+  const liveEdge = useSharedValue(initialTimestamp);
+  const edgeValue = 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.
   const extremaMinValue = useSharedValue(NaN);
@@ -250,6 +335,10 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
     nowOverrideSV,
     windowBufferSV,
     pausedSV,
+    viewEndSV: viewEnd,
+    viewWindowSV: viewWindow,
+    liveEdgeSV: liveEdge,
+    edgeValueSV: edgeValue,
     modeSV,
     candles,
     liveCandle,
@@ -307,6 +396,10 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
     canvasWidth,
     canvasHeight,
     timestamp,
+    viewEnd,
+    viewWindow,
+    liveEdge,
+    edgeValue,
     extremaMinValue,
     extremaMaxValue,
     extremaMinTime,

package/src/core/useLiveChartSeriesEngine.ts

@@ -8,7 +8,7 @@ import {
 import { MS_PER_FRAME_60FPS } from "../constants";
 import type { LiveChartPoint, SeriesConfig } from "../types";
 import { tickLiveChartSeriesEngineFrame } from "./liveChartSeriesEngineTick";
-import type { MultiEngineState } from "./useLiveChartEngine";
+import type { ChartEngineScroll, MultiEngineState } from "./useLiveChartEngine";
 
 export interface MultiSeriesEngineConfig {
   series: SharedValue<SeriesConfig[]>;
@@ -47,6 +47,12 @@ export interface MultiEngineFrameRefs {
   nowOverrideSV?: SharedValue<number | undefined>;
   windowBufferSV?: SharedValue<number>;
   pausedSV: SharedValue<boolean>;
+  /** Pan-scroll right-edge override (null = follow live). Optional for callers/tests. */
+  viewEndSV?: SharedValue<number | null>;
+  /** 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. */
+  liveEdgeSV?: SharedValue<number>;
   extremaMinValue: SharedValue<number>;
   extremaMaxValue: SharedValue<number>;
   extremaMinTime: SharedValue<number>;
@@ -105,6 +111,7 @@ export function applyLiveChartSeriesEngineFrame(
     displayMax: sv.displayMax.value,
     displayWindow: sv.displayWindow.value,
     timestamp: sv.timestamp.value,
+    liveEdge: sv.liveEdgeSV?.value ?? 0,
     displayValues,
     opacities,
     extremaMinValue: sv.extremaMinValue.value,
@@ -129,11 +136,14 @@ export function applyLiveChartSeriesEngineFrame(
     series: seriesSnap,
     nowSeconds: Date.now() / 1000,
     paused: sv.pausedSV.value,
+    viewEnd: sv.viewEndSV?.value,
+    viewWindow: sv.viewWindowSV?.value,
   });
   sv.displayMin.value = state.displayMin;
   sv.displayMax.value = state.displayMax;
   sv.displayWindow.value = state.displayWindow;
   sv.timestamp.value = state.timestamp;
+  if (sv.liveEdgeSV) sv.liveEdgeSV.value = state.liveEdge;
   sv.displaySeriesValues.value = state.displayValues;
   sv.seriesOpacities.value = state.opacities;
   sv.extremaMinValue.value = state.extremaMinValue;
@@ -148,8 +158,11 @@ export function applyLiveChartSeriesEngineFrame(
  */
 export function useLiveChartSeriesEngine(
   config: MultiSeriesEngineConfig,
-): MultiEngineState {
-  const timeWindow = useDerivedValue(() => config.timeWindow);
+): MultiEngineState & ChartEngineScroll {
+  // Pinch-zoom window-width override (null = follow the configured window).
+  // Declared first so `timeWindow` folds it in — see useLiveChartEngine.
+  const viewWindow = useSharedValue<number | null>(null);
+  const timeWindow = useDerivedValue(() => viewWindow.value ?? config.timeWindow);
   const smoothing = useDerivedValue(() => config.smoothing);
   const adaptiveSpeedBoostSV = useDerivedValue(() => config.adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
@@ -170,6 +183,10 @@ export function useLiveChartSeriesEngine(
   const [initialTimestamp] = useState(() => Date.now() / 1000);
   const timestamp = useSharedValue(initialTimestamp);
 
+  // Pan-scroll state (see useLiveChartEngine). Defaults to following live.
+  const viewEnd = useSharedValue<number | null>(null);
+  const liveEdge = useSharedValue(initialTimestamp);
+
   const displaySeriesValues = useSharedValue<number[]>([]);
   const seriesOpacities = useSharedValue<number[]>([]);
 
@@ -217,6 +234,9 @@ export function useLiveChartSeriesEngine(
         nowOverrideSV,
         windowBufferSV,
         pausedSV,
+        viewEndSV: viewEnd,
+        viewWindowSV: viewWindow,
+        liveEdgeSV: liveEdge,
         extremaMinValue,
         extremaMaxValue,
         extremaMinTime,
@@ -237,6 +257,9 @@ export function useLiveChartSeriesEngine(
     canvasWidth,
     canvasHeight,
     timestamp,
+    viewEnd,
+    viewWindow,
+    liveEdge,
     series,
     displaySeriesValues,
     seriesOpacities,