react-native-livechart 3.12.0 → 4.1.0

package/src/components/ReferenceLineOverlay.tsx

@@ -6,14 +6,16 @@ import {
   Text as SkiaText,
   type SkFont,
 } from "@shopify/react-native-skia";
-import { useDerivedValue } from "react-native-reanimated";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
+import { useChartSkiaFont } from "../hooks/useChartSkiaFont";
 import { usePathBuilder } from "../hooks/usePathBuilder";
 import { useReferenceLine } from "../hooks/useReferenceLine";
+import { MONO_FONT_FAMILY } from "../lib/monoFontFamily";
 import { referenceLineForm, resolveReferenceBadge } from "../math/referenceLines";
-import type { LiveChartPalette, ReferenceLine } from "../types";
+import type { FontConfig, LiveChartPalette, ReferenceLine } from "../types";
 
 /** Translucent fill alpha for value / time bands. */
 const BAND_FILL_OPACITY = 0.16;
@@ -35,7 +37,12 @@ export function ReferenceLineOverlay({
   palette,
   formatValue,
   font,
+  fontProp,
   badgeLayer = false,
+  suppressTag = false,
+  groupHidden,
+  dragValues,
+  index = 0,
 }: {
   engine: ChartEngineLayout;
   padding: ChartPadding;
@@ -43,6 +50,12 @@ export function ReferenceLineOverlay({
   palette: LiveChartPalette;
   formatValue: (v: number) => string;
   font: SkFont;
+  /**
+   * The chart's raw font config — used to build a per-badge font when the line's
+   * {@link ReferenceLineBadgeConfig} sets `fontSize` / `fontFamily` / `fontWeight`.
+   * When no badge font knob is set, the resolved `font` is used as-is.
+   */
+  fontProp?: FontConfig;
   /**
    * Render only the badge + label (`true`) or only the lines / bands (`false`,
    * default). The caller draws the base pass behind the chart content and the
@@ -50,13 +63,65 @@ export function ReferenceLineOverlay({
    * of being erased by the fade's `dstOut` blend.
    */
   badgeLayer?: boolean;
+  /**
+   * Suppress the built-in tag (badge pill + connector + chevron + icon + gutter
+   * label) for this line — used when a custom `renderReferenceLine` element owns
+   * the tag. The line / band stroke still draws. No effect on the base pass.
+   */
+  suppressTag?: boolean;
+  /**
+   * Per-frame grouping flags (index-aligned): when this line's slot is `true` it's
+   * collapsed into a group count handle, so its tag is suppressed (the line / band
+   * stroke still draws).
+   */
+  groupHidden?: SharedValue<boolean[]>;
+  /** Per-line live value overrides (dragged values), index-aligned with `referenceLines`. */
+  dragValues?: SharedValue<number[]>;
+  /** This line's index into {@link dragValues}. */
+  index?: number;
 }) {
   const form = referenceLineForm(line);
   const isBand = form === "value-band" || form === "time-band";
-  const layout = useReferenceLine(engine, padding, line, formatValue, font);
 
   const color = line.color ?? palette.refLine;
-  const labelColor = line.labelColor ?? line.color ?? palette.refLabel;
+
+  // Resolved badge appearance (badge config → fallback flat fields → theme).
+  const badge = resolveReferenceBadge(line);
+
+  // Per-badge font (size/family/weight) override; reuses the chart `font` when no
+  // badge font knob is set, so plain lines and gutter labels are unchanged. The
+  // built font drives pill measurement (via useReferenceLine) and the badge text.
+  const badgeHasFontOverride =
+    badge != null &&
+    (badge.fontSize != null ||
+      badge.fontFamily != null ||
+      badge.fontWeight != null);
+  const badgeFontOverride = useChartSkiaFont(
+    badgeHasFontOverride
+      ? {
+          ...fontProp,
+          fontFamily: badge?.fontFamily ?? fontProp?.fontFamily,
+          fontSize: badge?.fontSize ?? fontProp?.fontSize,
+          fontWeight: badge?.fontWeight ?? fontProp?.fontWeight,
+        }
+      : fontProp,
+    MONO_FONT_FAMILY,
+    palette.labelFontSize,
+  );
+  const badgeFont = badgeHasFontOverride ? badgeFontOverride : font;
+
+  const layout = useReferenceLine(
+    engine,
+    padding,
+    line,
+    formatValue,
+    badgeFont,
+    dragValues,
+    index,
+  );
+
+  const labelColor =
+    badge?.textColor ?? line.labelColor ?? line.color ?? palette.refLabel;
   const strokeWidth = line.strokeWidth ?? 1;
   const intervals = line.intervals ?? [4, 4];
 
@@ -64,11 +129,17 @@ export function ReferenceLineOverlay({
   const bandFillOpacity = line.fillOpacity ?? BAND_FILL_OPACITY;
   const hasBandBorder = isBand && line.strokeWidth !== undefined;
 
-  // Resolved badge appearance (badge config → fallback flat fields → theme).
-  const badge = resolveReferenceBadge(line);
   const badgeBackground = badge?.background ?? palette.tooltipBg;
   const badgeBorderColor = badge?.borderColor ?? color;
+  const badgeBorderWidth = badge?.borderWidth ?? 1;
   const badgeRadius = badge?.radius ?? BADGE_PILL_RADIUS;
+  // Nudge the whole badge (connector + pill + chevron + icon + label) off its anchor.
+  const badgeOffsetX = badge?.offsetX ?? 0;
+  const badgeOffsetY = badge?.offsetY ?? 0;
+  const badgeTransform =
+    badgeOffsetX !== 0 || badgeOffsetY !== 0
+      ? [{ translateX: badgeOffsetX }, { translateY: badgeOffsetY }]
+      : undefined;
 
   const lineBuilder = usePathBuilder();
   const bandBuilder = usePathBuilder();
@@ -79,11 +150,11 @@ export function ReferenceLineOverlay({
   const linePath = useDerivedValue(() => {
     const b = lineBuilder.value;
     const l = layout.get();
-    // A plain full-width line. A badge instead draws a pill + a connector to the
-    // opposite edge, below.
-    if (l.visible && !l.badge && !isBand) {
-      b.moveTo(l.x1, l.y);
-      b.lineTo(l.x2, l.y);
+    // A plain horizontal line, drawn at the line extent (full-width when opted in).
+    // A non-full-width badge instead draws a pill + connector to the edge, below.
+    if (l.visible && l.drawLine && !isBand) {
+      b.moveTo(l.lineX1, l.y);
+      b.lineTo(l.lineX2, l.y);
     }
     return b.detach();
   });
@@ -92,10 +163,10 @@ export function ReferenceLineOverlay({
     const b = bandBuilder.value;
     const l = layout.get();
     if (l.visible && isBand) {
-      b.moveTo(l.x1, l.y);
-      b.lineTo(l.x2, l.y);
-      b.lineTo(l.x2, l.yBottom);
-      b.lineTo(l.x1, l.yBottom);
+      b.moveTo(l.lineX1, l.y);
+      b.lineTo(l.lineX2, l.y);
+      b.lineTo(l.lineX2, l.yBottom);
+      b.lineTo(l.lineX1, l.yBottom);
       b.close();
     }
     return b.detach();
@@ -107,16 +178,16 @@ export function ReferenceLineOverlay({
     if (l.visible && hasBandBorder) {
       if (form === "time-band") {
         // Vertical edges at the band's left / right.
-        b.moveTo(l.x1, l.y);
-        b.lineTo(l.x1, l.yBottom);
-        b.moveTo(l.x2, l.y);
-        b.lineTo(l.x2, l.yBottom);
+        b.moveTo(l.lineX1, l.y);
+        b.lineTo(l.lineX1, l.yBottom);
+        b.moveTo(l.lineX2, l.y);
+        b.lineTo(l.lineX2, l.yBottom);
       } else {
         // Horizontal edges at the band's top / bottom.
-        b.moveTo(l.x1, l.y);
-        b.lineTo(l.x2, l.y);
-        b.moveTo(l.x1, l.yBottom);
-        b.lineTo(l.x2, l.yBottom);
+        b.moveTo(l.lineX1, l.y);
+        b.lineTo(l.lineX2, l.y);
+        b.moveTo(l.lineX1, l.yBottom);
+        b.lineTo(l.lineX2, l.yBottom);
       }
     }
     return b.detach();
@@ -155,7 +226,7 @@ export function ReferenceLineOverlay({
 
   const lineOpacity = useDerivedValue(() => {
     const l = layout.get();
-    return l.visible && !l.badge && !isBand ? 1 : 0;
+    return l.visible && l.drawLine && !isBand ? 1 : 0;
   });
   const bandOpacity = useDerivedValue(() =>
     layout.get().visible && isBand ? bandFillOpacity : 0,
@@ -165,12 +236,14 @@ export function ReferenceLineOverlay({
   );
   const badgeOpacity = useDerivedValue(() => {
     const l = layout.get();
-    return l.visible && l.badge ? 1 : 0;
+    const grouped = groupHidden ? groupHidden.get()[index] === true : false;
+    return !suppressTag && !grouped && l.visible && l.badge ? 1 : 0;
   });
   // Text + icon ride in the badge pass too, so they stay crisp above the fade.
   const labelOpacity = useDerivedValue(() => {
     const l = layout.get();
-    return l.visible && l.label.length > 0 ? 1 : 0;
+    const grouped = groupHidden ? groupHidden.get()[index] === true : false;
+    return !suppressTag && !grouped && l.visible && l.label.length > 0 ? 1 : 0;
   });
   const iconOpacity = useDerivedValue(() => {
     const l = layout.get();
@@ -186,7 +259,7 @@ export function ReferenceLineOverlay({
   // Font metrics depend only on the (stable) font, so read them once instead of
   // on every frame inside the pill worklet (`getMetrics` allocates + crosses JSI).
   const { ascent: fontAscent, height: pillH } = (() => {
-    const fm = font.getMetrics();
+    const fm = badgeFont.getMetrics();
     return {
       ascent: fm.ascent,
       height: fm.descent - fm.ascent + BADGE_PILL_PAD_Y * 2,
@@ -238,7 +311,7 @@ export function ReferenceLineOverlay({
 
       {/* Badge pass — connector + pill + chevron + icon, above the left-edge fade. */}
       {badgeLayer && (
-        <Group opacity={badgeOpacity}>
+        <Group opacity={badgeOpacity} transform={badgeTransform}>
           <Path
             path={connPath}
             style="stroke"
@@ -263,7 +336,7 @@ export function ReferenceLineOverlay({
             r={badgeRadius}
             color={badgeBorderColor}
             style="stroke"
-            strokeWidth={1}
+            strokeWidth={badgeBorderWidth}
           />
           <Path
             path={chevronPath}
@@ -278,7 +351,7 @@ export function ReferenceLineOverlay({
               x={iconX}
               y={labelY}
               text={iconText}
-              font={font}
+              font={badgeFont}
               color={labelColor}
             />
           </Group>
@@ -287,12 +360,12 @@ export function ReferenceLineOverlay({
 
       {/* Labels ride in the badge pass too, so they stay crisp above the fade. */}
       {badgeLayer && (
-        <Group opacity={labelOpacity}>
+        <Group opacity={labelOpacity} transform={badgeTransform}>
           <SkiaText
             x={labelX}
             y={labelY}
             text={labelText}
-            font={font}
+            font={badgeFont}
             color={labelColor}
           />
         </Group>

package/src/components/XAxisOverlay.tsx

@@ -19,12 +19,19 @@ export function XAxisOverlay({
   padding,
   palette,
   font,
+  volumeBandHeight = 0,
 }: {
   entries: SharedValue<XAxisEntry[]>;
   engine: ChartEngineLayout;
   padding: ChartPadding;
   palette: LiveChartPalette;
   font: SkFont;
+  /**
+   * Reserved volume-band height (px) folded into `padding.bottom`. The axis line
+   * + labels shift back down by this so they stay at the very bottom, below the
+   * band, while the price plot above shrinks. `0` = no band (default).
+   */
+  volumeBandHeight?: number;
 }) {
   const axisBuilder = usePathBuilder();
 
@@ -33,7 +40,7 @@ export function XAxisOverlay({
     const b = axisBuilder.value;
     const w = engine.canvasWidth.get();
     const h = engine.canvasHeight.get();
-    const lineY = h - padding.bottom;
+    const lineY = h - padding.bottom + volumeBandHeight;
 
     // Bottom axis line
     b.moveTo(padding.left, lineY);
@@ -53,7 +60,7 @@ export function XAxisOverlay({
     "worklet";
     const items = entries.get();
     const h = engine.canvasHeight.get();
-    const y = h - padding.bottom + LABEL_OFFSET_Y;
+    const y = h - padding.bottom + volumeBandHeight + LABEL_OFFSET_Y;
     const n = items.length;
     const out: { x: number; y: number; label: string; alpha: number }[] = [];
     for (let i = 0; i < n; i++) {

package/src/components/YAxisOverlay.tsx

@@ -5,7 +5,7 @@ import {
   type SkFont,
 } from "@shopify/react-native-skia";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
-import { BADGE_METRICS_DEFAULTS } from "../constants";
+import { BADGE_METRICS_DEFAULTS, MAX_Y_LABELS } from "../constants";
 import type { ResolvedGridStyleConfig } from "../core/resolveConfig";
 import type { YAxisEntry } from "../draw/grid";
 import {
@@ -21,7 +21,8 @@ import type { BadgeMetrics, LiveChartPalette } from "../types";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import { AnimatedLabel } from "./AnimatedLabel";
 
-const MAX_Y_LABELS = 15;
+/** Right margin (px) for floating labels — keeps them just off the canvas edge. */
+const FLOAT_LABEL_RIGHT_MARGIN = 6;
 
 export function YAxisOverlay({
   entries,
@@ -34,6 +35,8 @@ export function YAxisOverlay({
   badgeMetrics = BADGE_METRICS_DEFAULTS,
   seriesLabelInset = 0,
   gridStyle,
+  variant = "all",
+  float = false,
 }: {
   entries: SharedValue<YAxisEntry[]>;
   engine: ChartEngineLayout;
@@ -50,6 +53,17 @@ export function YAxisOverlay({
   seriesLabelInset?: number;
   /** Grid-line styling overrides. Omit for the legacy solid 1px line. */
   gridStyle?: ResolvedGridStyleConfig;
+  /**
+   * Which parts to draw. `"all"` (default) renders grid lines + labels together.
+   * `"grid"` / `"labels"` split them so a chart can draw the grid behind the data
+   * and the labels (over a soft fade) on top — see {@link YAxisEdgeFade}.
+   */
+  variant?: "all" | "grid" | "labels";
+  /**
+   * Floating-axis mode: right-align labels at the canvas edge (over a full-width
+   * plot) instead of centering them in a reserved gutter. See {@link YAxisConfig.float}.
+   */
+  float?: boolean;
 }) {
   const gridColor = gridStyle?.color ?? palette.gridLine;
   const gridWidth = gridStyle?.strokeWidth ?? 1;
@@ -59,6 +73,7 @@ export function YAxisOverlay({
 
   const gridLinesPath = useDerivedValue(() => {
     const b = gridBuilder.value;
+    if (variant === "labels") return b.detach();
     const items = entries.get();
     const w = engine.canvasWidth.get();
     for (let i = 0; i < items.length; i++) {
@@ -72,6 +87,7 @@ export function YAxisOverlay({
     badgeMetrics.dotGap + badgeTailAndCap(font.getSize(), badgeTail, badgeMetrics);
 
   const labelEntries = useDerivedValue(() => {
+    if (variant === "grid") return [];
     const items = entries.get();
     const w = engine.canvasWidth.get();
     const fm = font.getMetrics();
@@ -80,11 +96,13 @@ export function YAxisOverlay({
     for (let i = 0; i < items.length; i++) {
       const e = items[i];
       const textW = measureFontTextWidth(font, e.label);
-      const x = badge
-        ? pillTextLeftX(w, padding.right, leftInset, textW, badgeMetrics)
-        : seriesLabelInset > 0
-          ? gutterRightAlignedTextLeftX(w, textW)
-          : gutterCenteredTextLeftX(w, padding.right, textW);
+      const x = float
+        ? gutterRightAlignedTextLeftX(w, textW, FLOAT_LABEL_RIGHT_MARGIN)
+        : badge
+          ? pillTextLeftX(w, padding.right, leftInset, textW, badgeMetrics)
+          : seriesLabelInset > 0
+            ? gutterRightAlignedTextLeftX(w, textW)
+            : gutterCenteredTextLeftX(w, padding.right, textW);
       result.push({
         x,
         y: e.y - baselineOffset,
@@ -97,27 +115,30 @@ export function YAxisOverlay({
 
   return (
     <Group>
-      <Group opacity={gridOpacity}>
-        <Path
-          path={gridLinesPath}
-          style="stroke"
-          strokeWidth={gridWidth}
-          color={gridColor}
-        >
-          {gridIntervals.length > 0 && (
-            <DashPathEffect intervals={gridIntervals} />
-          )}
-        </Path>
-      </Group>
-      {Array.from({ length: MAX_Y_LABELS }, (_, i) => (
-        <AnimatedLabel
-          key={i}
-          entries={labelEntries}
-          index={i}
-          font={font}
-          color={palette.gridLabel}
-        />
-      ))}
+      {variant !== "labels" && (
+        <Group opacity={gridOpacity}>
+          <Path
+            path={gridLinesPath}
+            style="stroke"
+            strokeWidth={gridWidth}
+            color={gridColor}
+          >
+            {gridIntervals.length > 0 && (
+              <DashPathEffect intervals={gridIntervals} />
+            )}
+          </Path>
+        </Group>
+      )}
+      {variant !== "grid" &&
+        Array.from({ length: MAX_Y_LABELS }, (_, i) => (
+          <AnimatedLabel
+            key={i}
+            entries={labelEntries}
+            index={i}
+            font={font}
+            color={palette.gridLabel}
+          />
+        ))}
     </Group>
   );
 }

package/src/constants.ts

@@ -9,6 +9,21 @@ import type {
 /** Milliseconds per frame at 60 fps — baseline for frame-rate-independent lerp. */
 export const MS_PER_FRAME_60FPS = 16.67;
 
+/**
+ * Size of the pre-allocated Y-axis label pool — the most price labels the axis
+ * ever renders at once. Caps both the dynamic (nice-interval) grid and the
+ * fixed-`count` mode (see {@link YAxisConfig.count}).
+ */
+export const MAX_Y_LABELS = 15;
+
+/**
+ * Default press-and-hold (ms) before scrub engages in the `holdToScrub`
+ * time-scroll mode, so a quick one-finger drag scrolls instead. Overridden by
+ * `timeScroll.scrubHoldMs`, then `scrub.panGestureDelay`. Shared by `LiveChart`
+ * and `LiveChartSeries`.
+ */
+export const HOLD_TO_SCRUB_MS = 500;
+
 // ─── 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
@@ -29,6 +44,8 @@ export const CANDLE_METRICS_DEFAULTS: CandleMetrics = {
   minBodyPx: 1,
   maxBodyPx: 40,
   bodyWidthRatio: 0.8,
+  bodyRadius: 0,
+  wickWidth: 1,
 };
 
 /** Default grid + axis-label fade speeds. */

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;