react-native-livechart 4.13.1 → 4.14.0

package/src/components/LiveChart.tsx

@@ -46,6 +46,7 @@ import {
   resolveScrub,
   resolveScrubAction,
   resolveTransitions,
+  resolveOverscroll,
   resolveReturnToLiveMs,
   resolveSelectionDot,
   resolveThreshold,
@@ -607,6 +608,11 @@ function useLiveChartController({
   // 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);
+  // Overscroll fraction ([0, 1)) — how far pan/zoom may travel past the data
+  // bounds into blank space. 0 (the default) keeps the classic hard stops.
+  const timeScrollOverscroll = timeScrollEnabled
+    ? resolveOverscroll(timeScroll)
+    : 0;
   const zoomCfg = resolveZoom(zoom);
   const zoomEnabled = zoomCfg !== null && !isStatic;
 
@@ -677,6 +683,7 @@ function useLiveChartController({
     static: isStatic,
     snapKey,
     scrollEnabled: timeScrollEnabled,
+    allowFutureViewEnd: timeScrollOverscroll > 0,
     returnToLiveMs,
     smoothing,
     adaptiveSpeedBoost: metricsCfg.motion.adaptiveSpeedBoost,
@@ -1089,6 +1096,7 @@ function useLiveChartController({
     minTime: scrollMinTime,
     enabled: timeScrollEnabled,
     mode: scrollGestureMode,
+    overscroll: timeScrollOverscroll,
     scrollActive,
     // Once a scrub is engaged the chart is locked: scrolling goes inert so the
     // finger only moves the price indicator across a fixed window.
@@ -1111,6 +1119,7 @@ function useLiveChartController({
     enabled: zoomEnabled,
     minTimeWindow: zoomCfg?.minTimeWindow,
     maxTimeWindow: zoomCfg?.maxTimeWindow,
+    overscroll: timeScrollOverscroll,
     onZoomStart: () => {
       "worklet";
       crosshairScrubActive.set(false);

package/src/components/LiveChartSeries.tsx

@@ -39,6 +39,7 @@ import {
   resolveMarkerCluster,
   resolveMetrics,
   resolveMultiSeriesDot,
+  resolveOverscroll,
   resolveReturnToLiveMs,
   resolveScrub,
   resolveSelectionDot,
@@ -211,6 +212,11 @@ function useLiveChartSeriesController({
   // 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);
+  // Overscroll fraction ([0, 1)) — how far pan/zoom may travel past the data
+  // bounds into blank space. 0 (the default) keeps the classic hard stops.
+  const timeScrollOverscroll = timeScrollEnabled
+    ? resolveOverscroll(timeScroll)
+    : 0;
   const zoomCfg = resolveZoom(zoom);
   const zoomEnabled = zoomCfg !== null;
   const scrollGestureMode =
@@ -367,6 +373,7 @@ function useLiveChartSeriesController({
     paused,
     snapKey,
     scrollEnabled: timeScrollEnabled,
+    allowFutureViewEnd: timeScrollOverscroll > 0,
     returnToLiveMs,
     smoothing,
     adaptiveSpeedBoost: metricsCfg.motion.adaptiveSpeedBoost,
@@ -508,6 +515,7 @@ function useLiveChartSeriesController({
     minTime: scrollMinTime,
     enabled: timeScrollEnabled,
     mode: scrollGestureMode,
+    overscroll: timeScrollOverscroll,
     scrollActive,
     // Once a scrub is engaged the chart is locked: scrolling goes inert so the
     // finger only moves the price indicator across a fixed window.
@@ -526,6 +534,7 @@ function useLiveChartSeriesController({
     enabled: zoomEnabled,
     minTimeWindow: zoomCfg?.minTimeWindow,
     maxTimeWindow: zoomCfg?.maxTimeWindow,
+    overscroll: timeScrollOverscroll,
     onZoomStart: () => {
       "worklet";
       crosshairScrubActive.set(false);

package/src/constants.ts

@@ -68,6 +68,7 @@ export const CANDLE_METRICS_DEFAULTS: CandleMetrics = {
   minBodyPx: 1,
   maxBodyPx: 40,
   bodyWidthRatio: 0.8,
+  minGapPx: 2,
   bodyRadius: 0,
   wickWidth: 1,
 };

package/src/core/liveChartEngineTick.ts

@@ -93,6 +93,15 @@ export interface EngineTickInput {
    * resumes following. Takes precedence over {@link paused}.
    */
   viewEnd?: number | null;
+  /**
+   * Honor a {@link viewEnd} parked at or past the live edge (blank future space)
+   * instead of falling through to following live. Set when `timeScroll.overscroll`
+   * is active — the pan/pinch gestures may then park the right edge beyond the
+   * live edge, and the engine must freeze there or the gestures render nothing.
+   * The `viewEnd >= firstDataTime` strand-guard applies in both modes. Default
+   * `false` (classic behavior: only a past `viewEnd` freezes).
+   */
+  allowFutureViewEnd?: boolean;
   /**
    * "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
@@ -148,9 +157,13 @@ export function tickLiveChartEngineFrame(
   // 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.
+  // below), so a stale edge can't keep the window frozen. See #164. With
+  // `allowFutureViewEnd` (timeScroll.overscroll) an edge parked past live is
+  // honored too — the data-overlap strand-guard stays in both modes.
   const scrolledBack =
-    viewEnd != null && viewEnd < liveEdge && viewEnd >= firstDataTime;
+    viewEnd != null &&
+    viewEnd >= firstDataTime &&
+    (viewEnd < liveEdge || input.allowFutureViewEnd === true);
   if (scrolledBack) {
     state.timestamp = viewEnd;
   } else if (!input.paused) {

package/src/core/liveChartSeriesEngineTick.ts

@@ -67,6 +67,13 @@ export interface MultiEngineTickInput {
    * precedence over {@link paused}.
    */
   viewEnd?: number | null;
+  /**
+   * Honor a {@link viewEnd} parked at or past the live edge (blank future space)
+   * instead of falling through to following live. Set when `timeScroll.overscroll`
+   * is active. The `viewEnd >= firstDataTime` strand-guard applies in both modes.
+   * Default `false` (classic behavior: only a past `viewEnd` freezes).
+   */
+  allowFutureViewEnd?: boolean;
   /**
    * "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`;
@@ -113,8 +120,12 @@ export function tickLiveChartSeriesEngineFrame(
   // 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.
+  // With `allowFutureViewEnd` (timeScroll.overscroll) an edge parked past live is
+  // honored too — the data-overlap strand-guard stays in both modes.
   const scrolledBack =
-    viewEnd != null && viewEnd < liveEdge && viewEnd >= firstDataTime;
+    viewEnd != null &&
+    viewEnd >= firstDataTime &&
+    (viewEnd < liveEdge || input.allowFutureViewEnd === true);
   if (scrolledBack) {
     state.timestamp = viewEnd;
   } else if (!input.paused) {

package/src/core/resolveConfig.ts

@@ -30,6 +30,7 @@ import type {
   SelectionDotRingConfig,
   ReturnToLiveConfig,
   ThresholdConfig,
+  TimeScrollConfig,
   ThresholdLineConfig,
   TradeEvent,
   TransitionConfig,
@@ -560,6 +561,27 @@ export function resolveReturnToLiveMs(
   return d > 0 ? d : 0;
 }
 
+/**
+ * Overscroll ceiling — `overscroll: 1` would let the window scroll fully past
+ * the data (an all-blank plot), so the fraction clamps just short of it.
+ */
+const MAX_OVERSCROLL = 0.99;
+
+/**
+ * Resolves `timeScroll.overscroll` to a clamped `[0, 1)` fraction of the
+ * visible window that pan / fling / pinch may travel past the data bounds.
+ * `0` (booleans, omitted, or non-positive values) keeps the classic hard
+ * stops at the oldest data and the live edge. See {@link TimeScrollConfig}.
+ */
+export function resolveOverscroll(
+  prop: boolean | TimeScrollConfig | undefined,
+): number {
+  if (prop == null || typeof prop === "boolean") return 0;
+  const v = prop.overscroll;
+  if (v == null || !(v > 0)) return 0;
+  return v < MAX_OVERSCROLL ? v : MAX_OVERSCROLL;
+}
+
 /**
  * Resolved transition durations. `undefined` for a field means "use the
  * component's built-in default" (so we don't duplicate the default constants

package/src/core/useLiveChartEngine.ts

@@ -65,6 +65,12 @@ export interface EngineConfig {
    * the chart at a past position. See #164.
    */
   scrollEnabled?: boolean;
+  /**
+   * Honor a `viewEnd` parked at or past the live edge — set when
+   * `timeScroll.overscroll` is active so the pan/pinch gestures can drag into
+   * blank future space. See {@link EngineTickInput.allowFutureViewEnd}.
+   */
+  allowFutureViewEnd?: 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
@@ -208,6 +214,8 @@ export interface EngineFrameRefs {
   pausedSV: SharedValue<boolean>;
   /** Pan-scroll right-edge override (null = follow live). Optional for callers/tests. */
   viewEndSV?: SharedValue<number | null>;
+  /** Honor a `viewEnd` past the live edge (timeScroll.overscroll). Optional. */
+  allowFutureViewEndSV?: SharedValue<boolean>;
   /** "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. */
@@ -340,6 +348,7 @@ export function applyLiveChartEngineFrame(
   input.paused = sv.pausedSV.value;
   input.snap = snap;
   input.viewEnd = sv.viewEndSV?.value;
+  input.allowFutureViewEnd = sv.allowFutureViewEndSV?.value ?? false;
   input.returnT = sv.returnTSV?.value;
   input.returnFrom = sv.returnFromSV?.value;
   input.viewWindow = sv.viewWindowSV?.value;
@@ -430,6 +439,10 @@ export function useLiveChartEngine(
   // (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);
+  // Honor a viewEnd parked past the live edge (timeScroll.overscroll).
+  const allowFutureViewEndSV = useDerivedValue(
+    () => config.allowFutureViewEnd ?? false,
+  );
   // Return-to-live glide duration (ms); 0 = instant snap. Read by the reaction.
   const returnToLiveMsSV = useDerivedValue(
     () => config.returnToLiveMs ?? RETURN_TO_LIVE_MS,
@@ -516,6 +529,7 @@ export function useLiveChartEngine(
     windowBufferSV,
     pausedSV,
     viewEndSV: viewEnd,
+    allowFutureViewEndSV,
     returnTSV: returnT,
     returnFromSV: returnFrom,
     viewWindowSV: viewWindow,

package/src/core/useLiveChartSeriesEngine.ts

@@ -39,6 +39,12 @@ export interface MultiSeriesEngineConfig {
    * strands the chart at a past position. See #164.
    */
   scrollEnabled?: boolean;
+  /**
+   * Honor a `viewEnd` parked at or past the live edge — set when
+   * `timeScroll.overscroll` is active so the pan/pinch gestures can drag into
+   * blank future space. See {@link MultiEngineTickInput.allowFutureViewEnd}.
+   */
+  allowFutureViewEnd?: boolean;
   /**
    * Duration (ms) of the return-to-live glide when {@link scrollEnabled} flips to
    * `false` while scrolled back. `0` snaps instantly. Defaults to
@@ -77,6 +83,8 @@ export interface MultiEngineFrameRefs {
   pausedSV: SharedValue<boolean>;
   /** Pan-scroll right-edge override (null = follow live). Optional for callers/tests. */
   viewEndSV?: SharedValue<number | null>;
+  /** Honor a `viewEnd` past the live edge (timeScroll.overscroll). Optional. */
+  allowFutureViewEndSV?: SharedValue<boolean>;
   /** "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. */
@@ -240,6 +248,7 @@ export function applyLiveChartSeriesEngineFrame(
   input.paused = sv.pausedSV.value;
   input.snap = snap;
   input.viewEnd = sv.viewEndSV?.value;
+  input.allowFutureViewEnd = sv.allowFutureViewEndSV?.value ?? false;
   input.returnT = sv.returnTSV?.value;
   input.returnFrom = sv.returnFromSV?.value;
   input.viewWindow = sv.viewWindowSV?.value;
@@ -287,6 +296,10 @@ export function useLiveChartSeriesEngine(
   // Whether time-scroll is active — drives the return-to-live reaction below.
   // Defaults to enabled (legacy behavior).
   const scrollEnabledSV = useDerivedValue(() => config.scrollEnabled ?? true);
+  // Honor a viewEnd parked past the live edge (timeScroll.overscroll).
+  const allowFutureViewEndSV = useDerivedValue(
+    () => config.allowFutureViewEnd ?? false,
+  );
   // Return-to-live glide duration (ms); 0 = instant snap. Read by the reaction.
   const returnToLiveMsSV = useDerivedValue(
     () => config.returnToLiveMs ?? RETURN_TO_LIVE_MS,
@@ -362,6 +375,7 @@ export function useLiveChartSeriesEngine(
     windowBufferSV,
     pausedSV,
     viewEndSV: viewEnd,
+    allowFutureViewEndSV,
     returnTSV: returnT,
     returnFromSV: returnFrom,
     viewWindowSV: viewWindow,

package/src/draw/candle.ts

@@ -144,7 +144,11 @@ export function buildCandleGeometry(
   const slotPx = (candleWidthSecs / windowSecs) * chartW;
   const bodyW = Math.max(
     1,
-    Math.min(slotPx * metrics.bodyWidthRatio, slotPx - 2, metrics.maxBodyPx),
+    Math.min(
+      slotPx * metrics.bodyWidthRatio,
+      slotPx - metrics.minGapPx,
+      metrics.maxBodyPx,
+    ),
   );
 
   const bodies: CandleRect[] = [];

package/src/draw/line.ts

@@ -229,6 +229,7 @@ export function buildLinePoints(
   canvasHeight: number,
   padding: ChartPadding,
   out?: number[],
+  omitTipBeyondData = false,
 ): number[] {
   "worklet";
   const pts: number[] = out ?? [];
@@ -328,6 +329,18 @@ export function buildLinePoints(
     }
   }
 
+  // A scrolled-back / overscrolled window can end after the last data point;
+  // the synthetic tip would then fabricate a flat segment from that point to
+  // the right edge. Callers pass `omitTipBeyondData` to end the line at the
+  // last real point instead.
+  if (
+    omitTipBeyondData &&
+    endIdx === data.length &&
+    data[endIdx - 1].time < now
+  ) {
+    return pts;
+  }
+
   // Live tip at current time with smoothed value
   pts.push(
     padding.left + chartW,

package/src/draw/volume.ts

@@ -113,7 +113,11 @@ export function buildVolumeGeometry(
   const slotPx = (candleWidthSecs / windowSecs) * chartW;
   const bodyW = Math.max(
     1,
-    Math.min(slotPx * metrics.bodyWidthRatio, slotPx - 2, metrics.maxBodyPx),
+    Math.min(
+      slotPx * metrics.bodyWidthRatio,
+      slotPx - metrics.minGapPx,
+      metrics.maxBodyPx,
+    ),
   );
 
   const winEnd = winStart + windowSecs;

package/src/hooks/useChartPaths.ts

@@ -105,6 +105,10 @@ export function useChartPaths(
       engine.canvasHeight.get(),
       padding,
       buf,
+      // Only a live-following chart may extend the line to the right edge; a
+      // parked (scrolled-back / overscrolled) window ends at its last real
+      // point rather than fabricating a flat line into dataless space.
+      engine.viewEnd.get() != null,
     );
 
     // Skip blending when fully revealed or no morphT provided

package/src/hooks/usePanScroll.ts

@@ -1,6 +1,8 @@
 import { Gesture } from "react-native-gesture-handler";
 import {
   cancelAnimation,
+  useAnimatedReaction,
+  useDerivedValue,
   useSharedValue,
   withDecay,
   type SharedValue,
@@ -71,26 +73,85 @@ export interface UsePanScrollOptions {
    * price indicator. Cleared when the finger lifts (the scrub pan's finalize).
    */
   scrubActive?: SharedValue<boolean>;
+  /**
+   * Fraction of the visible window (0–1) the pan may travel past the data
+   * bounds — into blank future space beyond the live edge and blank history
+   * before the oldest point (TradingView-style free dragging). `0` (default)
+   * keeps the classic hard stops at the data. Resolved from
+   * `timeScroll.overscroll` (see `resolveOverscroll`).
+   */
+  overscroll?: number;
 }
 
+/**
+ * Snap-to-follow zone around the live edge, as a fraction of the window. With
+ * overscroll a released drag/fling that settles within this zone re-attaches to
+ * live; anything further out stays parked where it stopped.
+ */
+export const FOLLOW_SNAP = 0.02;
+
 /**
  * Smallest valid right-edge time: keeps the window's left edge
  * (`rightEdge - window`) from passing `minTime`, and never exceeds the live edge
- * so the `[lo, liveEdge]` clamp range stays valid when history is short.
+ * so the `[lo, liveEdge]` clamp range stays valid when history is short. With
+ * `overscroll` the left edge may pass `minTime` by that fraction of the window,
+ * exposing blank space before the oldest data.
  */
 export function panLowerBound(
   minTime: number,
   windowSecs: number,
   liveEdge: number,
+  overscroll: number = 0,
+): number {
+  "worklet";
+  return Math.min(minTime + windowSecs * (1 - overscroll), liveEdge);
+}
+
+/**
+ * Largest valid right-edge time: the live edge, pushed past it by `overscroll`
+ * (a fraction of the window) so the latest data can be dragged toward the middle
+ * of the plot, leaving blank future space on the right. `0` = the live edge.
+ */
+export function panUpperBound(
+  windowSecs: number,
+  liveEdge: number,
+  overscroll: number,
 ): number {
   "worklet";
-  return Math.min(minTime + windowSecs, liveEdge);
+  return liveEdge + windowSecs * overscroll;
+}
+
+/**
+ * Re-clamp a parked right edge after the overscroll setting changes. Reducing
+ * the allowance must not leave a stale future/history position outside the new
+ * bounds; at the classic live-edge hard stop, `null` resumes following live.
+ */
+export function clampViewEndForOverscroll(
+  viewEnd: number,
+  minTime: number,
+  windowSecs: number,
+  liveEdge: number,
+  overscroll: number,
+): number | null {
+  "worklet";
+  const lo = panLowerBound(minTime, windowSecs, liveEdge, overscroll);
+  if (viewEnd < lo) return lo;
+  const hi = panUpperBound(windowSecs, liveEdge, overscroll);
+  if (viewEnd >= hi) return overscroll > 0 ? hi : null;
+  return viewEnd;
 }
 
 /**
  * Next right-edge time after dragging `changeX` px (drag right ⇒ reveal earlier
- * time ⇒ smaller right edge), clamped to `[lo, liveEdge]`. Returns `null` once
- * the drag reaches the live edge — the signal to resume following.
+ * time ⇒ smaller right edge), clamped to `[lo, panUpperBound]`. Without
+ * overscroll, returns `null` once the drag reaches the live edge — the signal to
+ * resume following.
+ *
+ * With overscroll it must NOT return `null` mid-drag: the pan's `onChange`
+ * re-derives `cur` from `viewEnd ?? liveEdge` each frame, so snapping to follow
+ * re-anchors every per-frame delta at the live edge and the drag can't escape it
+ * in either direction. Re-attaching to live happens only in the release decay
+ * callback (see `usePanScroll`), inside the {@link FOLLOW_SNAP} zone.
  */
 export function nextViewEnd(
   cur: number,
@@ -99,10 +160,16 @@ export function nextViewEnd(
   windowSecs: number,
   liveEdge: number,
   lo: number,
+  overscroll: number = 0,
 ): number | null {
   "worklet";
   let next = cur - (changeX / chartW) * windowSecs;
   if (next < lo) next = lo;
+  if (overscroll > 0) {
+    const hi = panUpperBound(windowSecs, liveEdge, overscroll);
+    if (next > hi) next = hi;
+    return next;
+  }
   if (next > liveEdge) next = liveEdge;
   return next >= liveEdge ? null : next;
 }
@@ -150,6 +217,7 @@ export function usePanScroll({
   onScrollStart,
   scrollActive,
   scrubActive,
+  overscroll = 0,
 }: UsePanScrollOptions): ReturnType<typeof Gesture.Pan> {
   const { viewEnd, liveEdge, displayWindow, canvasWidth, canvasHeight } = engine;
   const padLeft = padding.left;
@@ -161,6 +229,31 @@ export function usePanScroll({
   const startX = useSharedValue(0);
   const startY = useSharedValue(0);
   const armed = useSharedValue(false);
+  const overscrollSV = useDerivedValue(() => overscroll);
+
+  // A runtime config change (the demo exposes Off / 50% / 90%) applies to an
+  // already parked window immediately. Without this, disabling overscroll while
+  // parked in the future leaves a numeric `viewEnd`; re-enabling it later revives
+  // that stale future position and makes the chart jump without a gesture.
+  useAnimatedReaction(
+    () => overscrollSV.value,
+    /* istanbul ignore next -- UI-thread config reaction; pure clamp is unit-tested */
+    (nextOverscroll) => {
+      const cur = viewEnd.get();
+      if (cur == null) return;
+      const next = clampViewEndForOverscroll(
+        cur,
+        minTime.get(),
+        displayWindow.get(),
+        liveEdge.get(),
+        nextOverscroll,
+      );
+      if (next !== cur) {
+        cancelAnimation(viewEnd);
+        viewEnd.set(next);
+      }
+    },
+  );
 
   const onStart =
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
@@ -194,8 +287,8 @@ export function usePanScroll({
       if (chartW <= 0) return;
       const edge = liveEdge.get();
       const cur = viewEnd.get() ?? edge;
-      const lo = panLowerBound(minTime.get(), win, edge);
-      viewEnd.set(nextViewEnd(cur, e.changeX, chartW, win, edge, lo));
+      const lo = panLowerBound(minTime.get(), win, edge, overscroll);
+      viewEnd.set(nextViewEnd(cur, e.changeX, chartW, win, edge, lo, overscroll));
     };
 
   const onEnd =
@@ -208,15 +301,20 @@ export function usePanScroll({
       const chartW = canvasWidth.get() - padLeft - padRight;
       if (chartW <= 0) return;
       const edge = liveEdge.get();
-      const lo = panLowerBound(minTime.get(), win, edge);
+      const lo = panLowerBound(minTime.get(), win, edge, overscroll);
+      const hi = overscroll > 0 ? panUpperBound(win, edge, overscroll) : edge;
+      // With overscroll the snap-to-follow zone widens from the exact live edge
+      // to FOLLOW_SNAP of the window around it — this release callback is the
+      // ONLY place that re-attaches to live (never mid-drag, see nextViewEnd).
+      const snapZone = overscroll > 0 ? win * FOLLOW_SNAP : 1e-3;
       const velocity = flingVelocity(e.velocityX, chartW, win);
       cancelAnimation(viewEnd);
       viewEnd.set(
-        withDecay({ velocity, clamp: [lo, edge] }, (finished) => {
+        withDecay({ velocity, clamp: [lo, hi] }, (finished) => {
           "worklet";
-          // Landed on the live-edge clamp → resume following; stopped short →
-          // stay frozen where inertia died.
-          if (finished && (viewEnd.get() ?? edge) >= edge - 1e-3) {
+          // Landed near the live edge → resume following; stopped short (or
+          // past, with overscroll) → stay frozen where inertia died.
+          if (finished && Math.abs((viewEnd.get() ?? edge) - edge) <= snapZone) {
             viewEnd.set(null);
           }
         }),

package/src/hooks/usePinchZoom.ts

@@ -6,7 +6,7 @@ import {
 } from "react-native-reanimated";
 
 import type { ChartPadding } from "../draw/line";
-import { panLowerBound } from "./usePanScroll";
+import { FOLLOW_SNAP, panLowerBound, panUpperBound } from "./usePanScroll";
 
 /** Engine SharedValues the pinch-zoom gesture reads/writes. */
 export interface PinchZoomEngineRefs {
@@ -44,6 +44,13 @@ export interface UsePinchZoomOptions {
   maxTimeWindow?: number;
   /** Worklet fired when a pinch activates — e.g. to clear a lingering crosshair. */
   onZoomStart?: () => void;
+  /**
+   * Fraction of the visible window (0–1) the zoomed window may travel past the
+   * data bounds — blank future space beyond the live edge, blank history before
+   * the oldest point. `0` (default) keeps the classic hard stops. Shared with
+   * {@link usePanScroll} (resolved from `timeScroll.overscroll`).
+   */
+  overscroll?: number;
 }
 
 /** Clamp a window width to `[minWin, maxWin]`. */
@@ -131,6 +138,7 @@ export function usePinchZoom({
   minTimeWindow,
   maxTimeWindow,
   onZoomStart,
+  overscroll = 0,
 }: UsePinchZoomOptions): ReturnType<typeof Gesture.Pinch> {
   const { viewWindow, viewEnd, liveEdge, displayWindow, canvasWidth } = engine;
   const padLeft = padding.left;
@@ -175,14 +183,27 @@ export function usePinchZoom({
       // doesn't compound; the right edge then keeps it under the (live) focal.
       const focalT = focalTime(e.focalX, padLeft, chartW, sEnd - sWin, sWin);
       let newEnd = zoomViewEnd(focalT, e.focalX, padLeft, chartW, newWin);
-      const lo = panLowerBound(minTime.get(), newWin, edge);
+      const lo = panLowerBound(minTime.get(), newWin, edge, overscroll);
       if (newEnd < lo) newEnd = lo;
-      if (newEnd > edge) newEnd = edge;
+      const hi = overscroll > 0 ? panUpperBound(newWin, edge, overscroll) : edge;
+      if (newEnd > hi) newEnd = hi;
       viewWindow.set(newWin);
       // Track the displayed window 1:1 (bypass the frame-loop lerp lag) so the
       // focal anchor is pixel-accurate during the gesture.
       displayWindow.set(newWin);
-      viewEnd.set(newEnd >= edge ? null : newEnd);
+      // Unlike the pan (see nextViewEnd), snapping to `null` mid-gesture is safe
+      // here: the pinch maps cumulative scale/focal from a gesture-START snapshot
+      // (`startViewEnd`), not per-frame deltas, so a snap can't re-anchor it.
+      // With overscroll, snap within the FOLLOW_SNAP zone; without, at the edge.
+      viewEnd.set(
+        overscroll > 0
+          ? Math.abs(newEnd - edge) <= newWin * FOLLOW_SNAP
+            ? null
+            : newEnd
+          : newEnd >= edge
+            ? null
+            : newEnd,
+      );
     };
 
   return Gesture.Pinch().enabled(enabled).onStart(onStart).onChange(onChange);

package/src/types.ts

@@ -1700,6 +1700,8 @@ export interface CandleMetrics {
   maxBodyPx: number;
   /** Body width as a fraction of the per-candle slot width (0–1). Default `0.8`. */
   bodyWidthRatio: number;
+  /** Minimum horizontal gap (px) enforced between adjacent candle bodies. `0` lets `bodyWidthRatio` alone control body width on dense charts. Default `2`. */
+  minGapPx: number;
   /** Corner radius (px) of candle bodies. `0` = sharp corners. Default `0`. */
   bodyRadius: number;
   /** Wick (high–low line) stroke width in px. Default `1`. */
@@ -1778,6 +1780,17 @@ export interface TimeScrollConfig {
    * visible edge price, which IS in view.
    */
   hideLiveOnScrollBack?: boolean;
+  /**
+   * How far pan / fling / pinch may travel past the data bounds, as a fraction
+   * of the visible window (`0`–`1`). With overscroll you can drag the latest
+   * candle toward the middle of the plot (blank future space on the right) or
+   * pan left past the oldest point into blank history — TradingView-style free
+   * dragging. A released drag that settles within a small zone of the live edge
+   * re-attaches to live. Default `0`: the window hard-stops at the oldest data
+   * and the live edge (the classic behavior). Values outside `[0, 1)` are
+   * clamped. Applies to the pinch-zoom (`zoom`) clamps too.
+   */
+  overscroll?: number;
 }
 
 /**