react-native-livechart 3.11.0 → 4.0.0

package/src/components/LiveChart.tsx

@@ -1,7 +1,12 @@
-import { useLayoutEffect, useState } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
-import { useDerivedValue, useSharedValue } from "react-native-reanimated";
+import {
+  useAnimatedReaction,
+  useDerivedValue,
+  useSharedValue,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
 
 /**
  * Single-series live chart. UX and prop vocabulary parallel Benji Taylor’s
@@ -17,7 +22,7 @@ import {
   vec,
 } from "@shopify/react-native-skia";
 
-import { DEFAULT_ACCENT_COLOR } from "../constants";
+import { DEFAULT_ACCENT_COLOR, HOLD_TO_SCRUB_MS } from "../constants";
 import {
   resolveAreaDots,
   resolveAxisLabel,
@@ -27,6 +32,7 @@ import {
   resolveGradient,
   resolveGridStyle,
   resolveLeftEdgeFade,
+  resolveMarkerCluster,
   resolveMetrics,
   resolvePulse,
   resolveScrub,
@@ -35,6 +41,8 @@ import {
   resolveThreshold,
   resolveTradeStream,
   resolveValueLine,
+  resolveVolume,
+  resolveZoom,
   resolveXAxis,
   resolveYAxis,
 } from "../core/resolveConfig";
@@ -47,6 +55,7 @@ import { useBadge } from "../hooks/useBadge";
 import { useCandlePaths } from "../hooks/useCandlePaths";
 import { useCanvasLayout } from "../hooks/useCanvasLayout";
 import { useChartColors } from "../hooks/useChartColors";
+import { useChartOverlayContext } from "../hooks/useChartOverlayContext";
 import { useChartPaths } from "../hooks/useChartPaths";
 import { useChartReveal } from "../hooks/useChartReveal";
 import { useChartSkiaFont } from "../hooks/useChartSkiaFont";
@@ -55,9 +64,13 @@ import { useDegen } from "../hooks/useDegen";
 import { useLiveChartHasData } from "../hooks/useLiveChartHasData";
 import { useLiveDot } from "../hooks/useLiveDot";
 import { useMarkers } from "../hooks/useMarkers";
+import { useReferenceDrag } from "../hooks/useReferenceDrag";
 import { useReferenceLinePress } from "../hooks/useReferenceLinePress";
 import { useModeBlend } from "../hooks/useModeBlend";
 import { useMomentum } from "../hooks/useMomentum";
+import { AXIS_GRAB_MIN_PX, usePanScroll } from "../hooks/usePanScroll";
+import { usePinchZoom } from "../hooks/usePinchZoom";
+import { useVisibleRange } from "../hooks/useVisibleRange";
 import { useSegmentLineGradient } from "../hooks/useSegmentLineGradient";
 import { useSingleChartReverseMorphInputs } from "../hooks/useReverseMorphEngineInputs";
 import { useThreshold } from "../hooks/useThreshold";
@@ -69,7 +82,16 @@ import {
   formatValue as defaultFormatValue,
 } from "../lib/format";
 import { MONO_FONT_FAMILY } from "../lib/monoFontFamily";
-import { collectReferenceValues } from "../math/referenceLines";
+import { computeScrubDotY } from "../hooks/crosshairShared";
+import {
+  groupReferenceLines,
+  type ReferenceGrouping,
+} from "../math/referenceGroup";
+import {
+  collectReferenceValues,
+  referenceLineForm,
+  resolveReferenceGroupBadge,
+} from "../math/referenceLines";
 import {
   applyPaletteOverride,
   leftEdgeFadeColorsFromBgRgb,
@@ -94,8 +116,13 @@ import {
   labelConnector,
 } from "./ExtremaConnectorOverlay";
 import { CustomMarkerOverlay } from "./CustomMarkerOverlay";
+import {
+  CustomReferenceLineOverlay,
+  customReferenceLineFlags,
+} from "./CustomReferenceLineOverlay";
 import { CustomTooltipOverlay } from "./CustomTooltipOverlay";
 import { BadgeOverlay } from "./BadgeOverlay";
+import { ChartOverlayLayer } from "./ChartOverlayLayer";
 import { CrosshairOverlay } from "./CrosshairOverlay";
 import { DegenParticlesOverlay } from "./DegenParticlesOverlay";
 import { DotOverlay } from "./DotOverlay";
@@ -104,6 +131,7 @@ import { LoadingOverlay } from "./LoadingOverlay";
 import { MarkerOverlay } from "./MarkerOverlay";
 import { MultiSeriesTooltipStack } from "./MultiSeriesTooltipStack";
 import { ValueTextOverlay } from "./ValueTextOverlay";
+import { ReferenceLineGroupOverlay } from "./ReferenceLineGroupOverlay";
 import { ReferenceLineOverlay } from "./ReferenceLineOverlay";
 import { ScrubActionOverlay } from "./ScrubActionOverlay";
 import { SegmentDividerOverlay } from "./SegmentDividerOverlay";
@@ -115,6 +143,14 @@ import { YAxisOverlay } from "./YAxisOverlay";
 /** Translucent fill alpha for the threshold profit/loss band. */
 const THRESHOLD_FILL_OPACITY = 0.16;
 
+/** Stable empty grouping result (identity-stable so downstream worklets don't
+ *  re-run) used when reference-line grouping is off. */
+const EMPTY_GROUPING: ReferenceGrouping = { hidden: [], groups: [] };
+
+/** Stable empty number array so the live-reference-values worklet stays
+ *  referentially stable (no engine re-fit) when no line is draggable. */
+const EMPTY_NUMS: number[] = [];
+
 /**
  * Color stops for the threshold's hard-split vertical gradient. Both arrays pair
  * with the `[0, t, t, 1]` split positions: index 0–1 paint above the split,
@@ -144,6 +180,7 @@ function thresholdStops(
  * here so the rendered pieces (`ChartStack`, `ChartScrubLayer`, `LiveChart`) stay
  * small and presentational.
  */
+
 function useLiveChartController({
   // ── Data ────────────────────────────────────────────────────────────────
   data,
@@ -164,6 +201,7 @@ function useLiveChartController({
   candles,
   candleWidth = 60,
   liveCandle,
+  volume,
 
   // ── Behaviour ───────────────────────────────────────────────────────────
   timeWindow = 30,
@@ -177,6 +215,8 @@ function useLiveChartController({
   maxValue,
   windowBuffer = 0,
   nowOverride,
+  timeScroll = false,
+  zoom = false,
   accessibilityLabel,
   accessibilityRole = "image",
   emptyText = "No data",
@@ -207,10 +247,14 @@ function useLiveChartController({
   tradeStream,
   degen,
   markers,
-  onMarkerHover,
+  onMarkerPress,
   markerHitRadius = 16,
+  markerCluster,
   renderMarker,
   renderTooltip,
+  renderOverlay,
+  renderReferenceLine,
+  referenceLineGrouping,
   leftEdgeFade = true,
 
   // ── Callbacks ───────────────────────────────────────────────────────────
@@ -219,6 +263,8 @@ function useLiveChartController({
   onReferenceLinePress,
   onGestureStart,
   onGestureEnd,
+  onVisibleRangeChange,
+  onReachStart,
   onDegenShake,
 }: LiveChartProps) {
   const emptyTradeStream = useSharedValue<TradeEvent[]>([]);
@@ -239,6 +285,10 @@ function useLiveChartController({
   const scrubCfg = resolveScrub(scrub);
   // Static charts run no gestures, so scrub-action (tap/drag to lock a price) is off.
   const scrubActionCfg = isStatic ? null : resolveScrubAction(scrubAction);
+  // Volume bars sit below the candles — a candle-mode-only feature (inert in
+  // line mode, like the candle paths themselves).
+  const volumeCfg = isCandle ? resolveVolume(volume) : null;
+  const volumeBandHeight = volumeCfg?.maxHeight ?? 0;
   const gradientCfg = isCandle ? null : resolveGradient(gradient);
   // Dot-lattice area fill (clipped to the under-line region). Inert in candle
   // mode, same as the gradient fill.
@@ -264,6 +314,77 @@ function useLiveChartController({
   const allRefLines = referenceLines ?? [];
   const refValues = collectReferenceValues(allRefLines);
 
+  // Per-line live value overrides + drag flags for draggable lines and the custom
+  // `renderReferenceLine` slot. One array SharedValue each (the line count varies,
+  // so a single SharedValue beats N hooks). Seeded from each line's static `value`;
+  // the drag gesture overwrites a slot, and the effect re-seeds slots not being
+  // dragged when the props change (so a controlled `value` flows back in).
+  const dragValues = useSharedValue<number[]>([]);
+  const dragActive = useSharedValue<boolean[]>([]);
+  // Last `value` props used to seed each slot, so reconciliation can tell a
+  // controlled prop change (adopt it) from an unchanged prop (keep the dragged
+  // value — uncontrolled persistence) without resetting a drop on every re-render.
+  const seededRef = useRef<(number | undefined)[]>([]);
+  const refValueSig = allRefLines.map((l) => l.value ?? "_").join(",");
+  useEffect(() => {
+    const active = dragActive.value;
+    const cur = dragValues.value;
+    const seeded = seededRef.current;
+    dragValues.value = allRefLines.map((l, i) => {
+      const prop = l.value ?? 0;
+      if (active[i]) return cur[i] ?? prop; // mid-drag → keep the dragged value
+      if (l.value !== seeded[i]) return prop; // prop changed → adopt (controlled)
+      return cur[i] ?? prop; // unchanged → keep current (uncontrolled persist)
+    });
+    seededRef.current = allRefLines.map((l) => l.value);
+    if (dragActive.value.length !== allRefLines.length) {
+      dragActive.value = allRefLines.map((_, i) => active[i] ?? false);
+    }
+    // allRefLines is rebuilt every render; key off the value signature + length.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [refValueSig, allRefLines.length]);
+
+  // Form-A lines a custom `renderReferenceLine` owns → suppress their built-in tag
+  // (no double-draw). Probed on the JS thread, index-aligned with `allRefLines`.
+  const refLineCustom = customReferenceLineFlags(allRefLines, renderReferenceLine);
+
+  // Live Y values of the *draggable* Form-A lines, folded into the engine's
+  // axis-range fit so dragging a line toward / past the visible edge expands the
+  // range and the axis follows the finger in one motion (the committed values are
+  // already in `refValues`). `excludeFromRange` lines opt out, matching the static
+  // fit. Identity-stable (no re-fit) when nothing is draggable.
+  const draggableRefIdx = allRefLines
+    .map((l, i) =>
+      l.draggable && !l.excludeFromRange && referenceLineForm(l) === "line"
+        ? i
+        : -1,
+    )
+    .filter((i) => i >= 0);
+  const liveRefValues = useDerivedValue<number[]>(() => {
+    if (draggableRefIdx.length === 0) return EMPTY_NUMS;
+    const dv = dragValues.get();
+    const out: number[] = [];
+    for (let k = 0; k < draggableRefIdx.length; k++) {
+      const v = dv[draggableRefIdx[k]];
+      if (v != null) out.push(v);
+    }
+    return out;
+  });
+
+  // Reference-line grouping (collapse near-value handles). Resolved once; the
+  // per-frame clustering runs on the UI thread (see ReferenceLineGroupOverlay).
+  const refGroupingCfg =
+    typeof referenceLineGrouping === "object"
+      ? referenceLineGrouping
+      : undefined;
+  const refGroupingRadius = referenceLineGrouping
+    ? (refGroupingCfg?.radius ?? 18)
+    : null;
+  // Count-pill styling (same style/shape config as a per-line badge) + count
+  // formatter. Resolved once; theme color defaults are applied in the overlay.
+  const refGroupBadge = resolveReferenceGroupBadge(refGroupingCfg?.badge);
+  const refGroupFormat = refGroupingCfg?.format;
+
   const badgeUsesRightGutter =
     badgeCfg !== null && (badgeCfg.position ?? "right") === "right";
 
@@ -305,6 +426,47 @@ function useLiveChartController({
     palette.valueFontSize * 2,
   );
 
+  // Per-badge font (size/family/weight) override; reuses the chart font when
+  // none of the badge font knobs are set, so the gutter sizing is unchanged.
+  const badgeHasFontOverride =
+    badgeCfg?.fontSize != null ||
+    badgeCfg?.fontFamily != null ||
+    badgeCfg?.fontWeight != null;
+  const badgeFontOverride = useChartSkiaFont(
+    badgeHasFontOverride
+      ? {
+          ...fontProp,
+          fontFamily: badgeCfg?.fontFamily ?? fontProp?.fontFamily,
+          fontSize: badgeCfg?.fontSize ?? fontProp?.fontSize,
+          fontWeight: badgeCfg?.fontWeight ?? fontProp?.fontWeight,
+        }
+      : fontProp,
+    MONO_FONT_FAMILY,
+    palette.labelFontSize,
+  );
+  const badgeFont = badgeHasFontOverride ? badgeFontOverride : skiaFont;
+
+  // Per-badge font for the grouping count pill (same override pattern as above).
+  const refGroupBadgeHasFont =
+    refGroupBadge.fontSize != null ||
+    refGroupBadge.fontFamily != null ||
+    refGroupBadge.fontWeight != null;
+  const refGroupBadgeFontOverride = useChartSkiaFont(
+    refGroupBadgeHasFont
+      ? {
+          ...fontProp,
+          fontFamily: refGroupBadge.fontFamily ?? fontProp?.fontFamily,
+          fontSize: refGroupBadge.fontSize ?? fontProp?.fontSize,
+          fontWeight: refGroupBadge.fontWeight ?? fontProp?.fontWeight,
+        }
+      : fontProp,
+    MONO_FONT_FAMILY,
+    palette.labelFontSize,
+  );
+  const refGroupBadgeFont = refGroupBadgeHasFont
+    ? refGroupBadgeFontOverride
+    : skiaFont;
+
   const pulseConfig = pulseCfg
     ? {
         maxRadius: pulseCfg.maxRadius,
@@ -328,11 +490,26 @@ function useLiveChartController({
     setValueLayoutSample(value.get());
   }, [value]);
 
+  // `scrolledBack` mirrors the UI-thread scroll state (engine.viewEnd != null)
+  // onto the JS thread (set by the reaction below, after the engine exists).
+  const [scrolledBack, setScrolledBack] = useState(false);
+  const timeScrollEnabled = Boolean(timeScroll) && !isStatic;
+  const zoomCfg = resolveZoom(zoom);
+  const zoomEnabled = zoomCfg !== null && !isStatic;
+
+  const yAxisFloat = yAxisCfg?.float ?? false;
+  // With timeScroll, the floating full-width plot engages only while scrolled
+  // back; at the live edge the chart keeps a normal right gutter so the
+  // line/candles don't sit under the floating y-axis labels + badge. Without
+  // timeScroll, float behaves as before (always full-width).
+  const effectiveYAxisFloat =
+    yAxisFloat && (!timeScrollEnabled || scrolledBack);
   const { strokeWidth, padding: effectivePadding } = resolveChartLayout({
     palette,
     lineWidthOverride: lineProp?.width,
     insetsOverride: insets,
     yAxis: yAxisCfg !== null,
+    yAxisFloat: effectiveYAxisFloat,
     badge: badgeCfg !== null,
     badgeMetrics: metricsCfg.badge,
     badgeUsesRightGutter,
@@ -342,6 +519,7 @@ function useLiveChartController({
     formatValue,
     currentValue: valueLayoutSample,
     pulse: pulseConfig,
+    volumeBandHeight,
   });
 
   // ── Reveal state ────────────────────────────────────────────
@@ -378,6 +556,7 @@ function useLiveChartController({
     adaptiveSpeedBoost: metricsCfg.motion.adaptiveSpeedBoost,
     exaggerate,
     referenceValues: refValues,
+    liveReferenceValues: liveRefValues,
     nonNegative,
     maxValue,
     windowBuffer,
@@ -387,6 +566,19 @@ function useLiveChartController({
     liveCandle: isCandle ? liveEngine : liveCandle,
   });
 
+  // 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.
+  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) {
+        scheduleOnRN(setScrolledBack, isScrolled);
+      }
+    },
+  );
+
   // ── Mode crossfade (line ↔ candle) ──────────────────────────────────
   const { lineGroupOpacity, candleGroupOpacity } = useModeBlend(
     isCandle,
@@ -396,6 +588,41 @@ function useLiveChartController({
   // ── Per-frame derived values ───────────────────────────────────────────
   const { layoutWidth, layoutHeight, onLayout } = useCanvasLayout(engine);
 
+  // Reference-line grouping: cluster Form-A lines by their per-frame value-Y so a
+  // stack of nearby orders collapses into one count handle. `groupHidden` suppresses
+  // the clustered lines' individual tags; the count pills read `refGroupResult`.
+  // Identity-stable (no work) when grouping is off.
+  const refGroupResult = useDerivedValue<ReferenceGrouping>(() => {
+    if (refGroupingRadius == null) return EMPTY_GROUPING;
+    const ch = engine.canvasHeight.get();
+    const dMin = engine.displayMin.get();
+    const dMax = engine.displayMax.get();
+    const top = effectivePadding.top;
+    const bottom = ch - effectivePadding.bottom;
+    const ys: number[] = [];
+    for (let i = 0; i < allRefLines.length; i++) {
+      const l = allRefLines[i];
+      // Skip bands and lines a custom `renderReferenceLine` owns — a custom tag
+      // draws itself and isn't suppressed by grouping, so folding it into a
+      // built-in count pill would double-count it (counted *and* still shown).
+      if (
+        referenceLineForm(l) !== "line" ||
+        l.value === undefined ||
+        refLineCustom[i]
+      ) {
+        ys.push(-1);
+        continue;
+      }
+      const v = dragValues.get()[i] ?? l.value;
+      const y = computeScrubDotY(v, dMin, dMax, ch, top, effectivePadding.bottom);
+      ys.push(y < 0 ? -1 : Math.min(bottom, Math.max(top, y)));
+    }
+    return groupReferenceLines(ys, refGroupingRadius);
+  });
+  const groupHidden = useDerivedValue<boolean[]>(
+    () => refGroupResult.get().hidden,
+  );
+
   // Threshold split geometry (shared by stroke gradient, fill band, marker line).
   // Called unconditionally with a stand-in value when no threshold is set.
   const thresholdGeom = useThreshold(
@@ -407,14 +634,23 @@ function useLiveChartController({
     ? thresholdStops(thresholdCfg, palette)
     : null;
 
+  // Straight polyline instead of the monotone cubic when line.curve === "linear".
+  // Shared by the path builders and the marker anchoring so glyphs sit on the
+  // rendered line rather than the phantom spline.
+  const lineIsLinear = lineProp?.curve === "linear";
+
   const { linePath, fillPath, thresholdFillPath } = useChartPaths(
     engine,
     effectivePadding,
     reveal.morphT,
     // Only build the band path when the fill is actually on.
     thresholdCfg?.fill ? thresholdGeom.lineY : undefined,
-    // Straight polyline instead of the monotone cubic when line.curve === "linear".
-    lineProp?.curve === "linear",
+    lineIsLinear,
+    // Tip the line at the view-edge price (not the live value) while scrolled,
+    // matching the live dot — so the right edge doesn't drop to the off-screen
+    // live value when `followViewEdge` tracks the scrolled-back window.
+    engine.edgeValue,
+    badgeCfg?.followViewEdge ?? false,
   );
 
   // Area-dots fill shader color as a vec4 (channels 0..1), with the config
@@ -432,19 +668,36 @@ function useLiveChartController({
     adA * (areaDotsCfg?.opacity ?? 1),
   ];
 
-  const { upBodiesPath, downBodiesPath, upWicksPath, downWicksPath } =
-    useCandlePaths(
-      engine,
-      effectivePadding,
-      // Match engine: stashed candles while reverse-morphing in candle mode.
-      isCandle ? candlesEngine : candles,
-      isCandle ? liveEngine : liveCandle,
-      candleWidth,
-      isCandle,
-      metricsCfg.candle,
-      !isStatic, // static: no candle-width lerp loop
-    );
-  const { dotX, dotY } = useLiveDot(engine, effectivePadding);
+  const {
+    upBodiesPath,
+    downBodiesPath,
+    upWicksPath,
+    downWicksPath,
+    upBarsPath,
+    downBarsPath,
+  } = useCandlePaths(
+    engine,
+    effectivePadding,
+    // Match engine: stashed candles while reverse-morphing in candle mode.
+    isCandle ? candlesEngine : candles,
+    isCandle ? liveEngine : liveCandle,
+    candleWidth,
+    isCandle,
+    metricsCfg.candle,
+    volumeBandHeight,
+    volumeCfg?.radius ?? 0,
+    !isStatic, // static: no candle-width lerp loop
+  );
+  const { dotX, dotY } = useLiveDot(
+    engine,
+    effectivePadding,
+    engine.edgeValue,
+    badgeCfg?.followViewEdge ?? false,
+  );
+
+  // Price↔pixel / time↔pixel bridge for a custom `renderOverlay`. Built
+  // unconditionally (hooks rule); only mounted when `renderOverlay` is provided.
+  const overlayContext = useChartOverlayContext(engine, effectivePadding);
 
   const momentumSV = useMomentum(engine, momentum);
 
@@ -484,7 +737,7 @@ function useLiveChartController({
     effectivePadding,
     palette,
     formatValue,
-    skiaFont,
+    badgeFont,
     badgeCfg?.variant ?? "default",
     badgeCfg?.tail ?? true,
     momentumSV,
@@ -492,6 +745,11 @@ function useLiveChartController({
     badgeCfg?.background,
     metricsCfg.badge,
     metricsCfg.motion.badgeColorSpeed,
+    effectiveYAxisFloat,
+    engine.edgeValue,
+    badgeCfg?.followViewEdge ?? false,
+    badgeCfg?.radius,
+    badgeCfg?.textColor,
   );
 
   // Scrub/crosshair must see the same stash-backed candles as the engine.
@@ -505,6 +763,7 @@ function useLiveChartController({
     : undefined;
 
   const markersActive = markers != null;
+  const markerClusterCfg = resolveMarkerCluster(markerCluster);
   // `projected` is used internally by the hit-test gesture; the overlay
   // self-projects, so we only need the gesture + hit-test here. Built BEFORE
   // `useCrosshair` so the scrub-action tap can defer to a marker under the finger.
@@ -514,10 +773,12 @@ function useLiveChartController({
     markersSV,
     !isStatic && markersActive,
     markerHitRadius,
-    onMarkerHover,
+    onMarkerPress,
     undefined, // seriesSV — single-series has none
     engine.data, // anchor value-less markers to the line
     !isStatic, // static: no marker-projection loop
+    lineIsLinear, // match marker anchoring to the rendered curve
+    markerClusterCfg, // co-located marker stacking / collapse
   );
 
   // Pressable reference-line badges (working orders / alerts). Built before
@@ -533,6 +794,7 @@ function useLiveChartController({
       !isStatic && refPressActive,
       markerHitRadius,
       onReferenceLinePress,
+      dragValues,
     );
 
   // Combined "defer" hit-test for the scrub-action place-tap: yield to a marker or
@@ -544,6 +806,24 @@ function useLiveChartController({
     return markerHitTest(x, y) || refLineHitTest(x, y);
   };
 
+  // Time-scroll activation. `holdToScrub`: a quick one-finger drag scrolls while
+  // scrub engages on press-and-hold — so the scrub gesture needs a long-press
+  // delay (unless the caller set its own `panGestureDelay`). `timeScrollEnabled`
+  // is computed earlier (it gates the float gutter).
+  const scrollGestureMode =
+    typeof timeScroll === "object"
+      ? (timeScroll.gesture ?? "holdToScrub")
+      : "holdToScrub";
+  // In holdToScrub the scrub MUST require a hold so a quick drag scrolls instead.
+  // Precedence: explicit timeScroll.scrubHoldMs, then scrub.panGestureDelay, then
+  // the default. `||` (not `??`) skips the resolved panGestureDelay's 0 default.
+  const timeScrollHoldMs =
+    typeof timeScroll === "object" ? timeScroll.scrubHoldMs : undefined;
+  const scrubHoldMs =
+    timeScrollEnabled && scrollGestureMode === "holdToScrub"
+      ? (timeScrollHoldMs ?? (scrubCfg?.panGestureDelay || HOLD_TO_SCRUB_MS))
+      : (scrubCfg?.panGestureDelay ?? 0);
+
   const crosshair = useCrosshair(
     engine,
     effectivePadding,
@@ -556,7 +836,7 @@ function useLiveChartController({
     !isStatic && (scrubCfg !== null || scrubActionCfg !== null),
     onScrub,
     candleOpts,
-    scrubCfg?.panGestureDelay ?? 0,
+    scrubHoldMs,
     onGestureStart,
     onGestureEnd,
     scrubActionCfg,
@@ -567,8 +847,75 @@ function useLiveChartController({
     scrubCfg?.tooltipShowValue ?? true,
     scrubCfg?.tooltipShowTime ?? true,
     scrubCfg?.tooltipMargin ?? 8,
+    // Axis-drag time-scroll: keep the bottom "time ruler" band scroll-only so a
+    // drag there never trips the scrub crosshair.
+    timeScrollEnabled && scrollGestureMode === "axisDrag"
+      ? Math.max(effectivePadding.bottom, AXIS_GRAB_MIN_PX)
+      : 0,
+  );
+
+  // ── Time-scroll (drag back through history) ───────────────────────────────
+  // Experimental: a pan freezes the window at an absolute time and resumes
+  // following once dragged back to the live edge. Pan is clamped to the earliest
+  // retained point (line or candle). See `timeScroll` for the gesture model.
+  const scrollMinTime = useDerivedValue(() => {
+    const src = isCandle ? candlesEngine.get() : lineEngineData.get();
+    return src.length > 0 ? src[0].time : engine.liveEdge.get();
+  });
+  const panScrollGesture = usePanScroll({
+    engine,
+    padding: effectivePadding,
+    minTime: scrollMinTime,
+    enabled: timeScrollEnabled,
+    mode: scrollGestureMode,
+    // Clear any live crosshair when a scroll drag takes over.
+    onScrollStart: () => {
+      "worklet";
+      crosshair.scrubActive.set(false);
+    },
+  });
+
+  // Draggable reference lines: a per-line vertical pan that grabs a line near its
+  // value and drags it along the Y-axis (with snap / bounds / callbacks). Built
+  // unconditionally for stable hook order; the gesture self-disables when no line
+  // opts in, and it's only composed into the root when `refDragEnabled`.
+  const refDragEnabled =
+    !isStatic && allRefLines.some((l) => l.draggable === true);
+  const refDragGesture = useReferenceDrag(
+    engine,
+    effectivePadding,
+    allRefLines,
+    dragValues,
+    dragActive,
+    !isStatic,
   );
 
+  // Pinch-to-zoom the visible window (two-finger). Anchors at the focal point and
+  // writes viewWindow + viewEnd; composes via Simultaneous (it's two-finger, so
+  // disjoint from the one-finger pan/scrub). See `zoom`.
+  const pinchZoomGesture = usePinchZoom({
+    engine,
+    padding: effectivePadding,
+    minTime: scrollMinTime,
+    timeWindow,
+    enabled: zoomEnabled,
+    minTimeWindow: zoomCfg?.minTimeWindow,
+    maxTimeWindow: zoomCfg?.maxTimeWindow,
+    onZoomStart: () => {
+      "worklet";
+      crosshair.scrubActive.set(false);
+    },
+  });
+
+  // Paging callbacks: report the visible range / proximity to the oldest data so
+  // a host can lazily load history. Inert unless a callback is supplied.
+  useVisibleRange({
+    engine,
+    minTime: scrollMinTime,
+    onVisibleRangeChange,
+    onReachStart,
+  });
+
   // Scrub-action composes a Tap (place/move the reticle, press the badge, dismiss)
   // ahead of the pan via Exclusive, so a tap is tried first and only becomes a
   // drag (live-scrub, or lock-adjust once placed) if the finger moves. `Exclusive`
@@ -594,12 +941,37 @@ function useLiveChartController({
       overlayTaps.length === 1
         ? overlayTaps[0]
         : Gesture.Simultaneous(overlayTaps[0], overlayTaps[1]);
-    // With scrub-action the action tap shares the gesture space with the overlay
-    // taps (Simultaneous); without it the pan only needs to race the tap group.
+    // Always `Simultaneous`, never `Race`: on iOS the scrub pan uses
+    // `minDistance(0)`, so in a `Race` it activates on touch-down and cancels the
+    // overlay tap before it can recognize — `onMarkerPress`/`onReferenceLinePress`
+    // would never fire. Sharing the gesture space lets the tap recognize; the pan
+    // defers to a marker/badge under the finger via `deferTapHit` (see
+    // `useCrosshair`'s scrub `onStart`) so no stray crosshair is dropped there.
+    rootGesture = Gesture.Simultaneous(baseGesture, tapGroup);
+  }
+
+  // Compose the pan-scroll gesture. holdToScrub races the scrub/tap gestures (a
+  // quick drag scrolls; a still press-hold falls through to scrub). Axis-drag
+  // goes first via Exclusive: it fails instantly outside the axis band, so scrub
+  // runs everywhere else.
+  if (timeScrollEnabled) {
     rootGesture =
-      scrubActionCfg !== null
-        ? Gesture.Simultaneous(baseGesture, tapGroup)
-        : Gesture.Race(baseGesture, tapGroup);
+      scrollGestureMode === "axisDrag"
+        ? Gesture.Exclusive(panScrollGesture, rootGesture)
+        : Gesture.Race(panScrollGesture, rootGesture);
+  }
+
+  // Draggable reference lines take priority: a vertical grab on a line drags it.
+  // The manual-activation pan fails fast off any line (or on horizontal intent), so
+  // Exclusive falls through to scrub / scroll everywhere else.
+  if (refDragEnabled) {
+    rootGesture = Gesture.Exclusive(refDragGesture, rootGesture);
+  }
+
+  // Pinch runs alongside everything else (two-finger, so it never competes with
+  // the one-finger pan/scrub/tap gestures for the same touch).
+  if (zoomEnabled) {
+    rootGesture = Gesture.Simultaneous(rootGesture, pinchZoomGesture);
   }
 
   // ── Derived render values ──────────────────────────────────────────────
@@ -657,6 +1029,7 @@ function useLiveChartController({
     extremaTimeOffset: isCandle ? candleWidth / 2 : 0,
     // configs
     yAxisCfg,
+    yAxisFloat: effectiveYAxisFloat,
     xAxisCfg,
     badgeCfg,
     scrubCfg,
@@ -674,6 +1047,16 @@ function useLiveChartController({
     leftEdgeFadeCfg,
     metricsCfg,
     allRefLines,
+    refLineCustom,
+    dragValues,
+    dragActive,
+    renderReferenceLine,
+    refGroupingActive: refGroupingRadius != null,
+    refGroupResult,
+    groupHidden,
+    refGroupBadge,
+    refGroupBadgeFont,
+    refGroupFormat,
     resolvedSegments,
     hasRecolorSegments,
     segmentGradient,
@@ -685,7 +1068,9 @@ function useLiveChartController({
     // theme / layout / fonts
     palette,
     skiaFont,
+    fontProp,
     valueFont,
+    badgeFont,
     strokeWidth,
     effectivePadding,
     // engine + reveal
@@ -705,10 +1090,20 @@ function useLiveChartController({
     linePath,
     fillPath,
     thresholdFillPath,
+    lineIsLinear,
     upBodiesPath,
     downBodiesPath,
     upWicksPath,
     downWicksPath,
+    upBarsPath,
+    downBarsPath,
+    // Volume bars: active flag, fade-in opacity, and resolved colors (default to
+    // the candle palette). The reserved band height is read by the x-axis.
+    volumeActive: volumeCfg !== null,
+    volumeBandHeight,
+    volumeOpacity: volumeCfg?.opacity ?? 1,
+    volumeUpColor: volumeCfg?.upColor ?? palette.candleUp,
+    volumeDownColor: volumeCfg?.downColor ?? palette.candleDown,
     dotX,
     dotY,
     liveDotOpacity,
@@ -724,8 +1119,11 @@ function useLiveChartController({
     rootGesture,
     markersActive,
     markersSV,
+    markerClusterCfg,
     renderMarker,
     renderTooltip,
+    renderOverlay,
+    overlayContext,
     // selection dot: resolved config + fallback color (the chart line/accent color)
     selectionDot: selectionDotCfg,
     selectionColor: lineProp?.color ?? palette.line,
@@ -750,6 +1148,7 @@ function ChartFillLayer({ model }: { model: LiveChartModel }) {
   const {
     degenShakeTransform,
     yAxisCfg,
+    yAxisFloat,
     reveal,
     yAxisEntries,
     engine,
@@ -775,10 +1174,13 @@ function ChartFillLayer({ model }: { model: LiveChartModel }) {
 
   return (
     <Group transform={degenShakeTransform}>
-      {/* Y-axis grid */}
+      {/* Y-axis. Default: grid + labels here (in a reserved gutter). Floating
+          mode: grid only — the labels + a soft edge fade draw above the candles
+          in ChartStack so the plot runs full-width and candles dim under them. */}
       {yAxisCfg && (
         <Group opacity={reveal.yAxisOpacity}>
           <YAxisOverlay
+            variant={yAxisFloat ? "grid" : "all"}
             entries={yAxisEntries}
             engine={engine}
             padding={effectivePadding}
@@ -851,10 +1253,12 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     effectivePadding,
     palette,
     skiaFont,
+    fontProp,
     badgeCfg,
     valueLineCfg,
     dotY,
     allRefLines,
+    dragValues,
     resolvedSegments,
     hasRecolorSegments,
     segmentGradient,
@@ -864,6 +1268,7 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     formatValue,
     lineGroupOpacity,
     linePath,
+    lineIsLinear,
     strokeWidth,
     lineProp,
     candleGroupOpacity,
@@ -871,6 +1276,13 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     downWicksPath,
     upBodiesPath,
     downBodiesPath,
+    upBarsPath,
+    downBarsPath,
+    volumeActive,
+    volumeBandHeight,
+    volumeOpacity,
+    volumeUpColor,
+    volumeDownColor,
     xAxisCfg,
     xAxisEntries,
     dotX,
@@ -882,10 +1294,16 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     degenPackRevision,
     markersActive,
     markersSV,
+    markerClusterCfg,
     renderMarker,
     emptyText,
     metricsCfg,
     layoutWidth,
+    yAxisCfg,
+    yAxisFloat,
+    yAxisEntries,
+    badgeUsesRightGutter,
+    gridStyleCfg,
   } = model;
 
   return (
@@ -928,6 +1346,9 @@ function ChartStack({ model }: { model: LiveChartModel }) {
           palette={palette}
           formatValue={formatValue}
           font={skiaFont}
+          fontProp={fontProp}
+          dragValues={dragValues}
+          index={i}
         />
       ))}
 
@@ -990,13 +1411,13 @@ function ChartStack({ model }: { model: LiveChartModel }) {
         <Path
           path={upWicksPath}
           style="stroke"
-          strokeWidth={1}
+          strokeWidth={metricsCfg.candle.wickWidth}
           color={palette.wickUp}
         />
         <Path
           path={downWicksPath}
           style="stroke"
-          strokeWidth={1}
+          strokeWidth={metricsCfg.candle.wickWidth}
           color={palette.wickDown}
         />
         <Path path={upBodiesPath} style="fill" color={palette.candleUp} />
@@ -1007,7 +1428,41 @@ function ChartStack({ model }: { model: LiveChartModel }) {
         />
       </Group>
 
-      {/* X-axis time labels */}
+      {/* Volume bars in the reserved band below the candles. Fades in with the
+          candle group (outer opacity); the config opacity dims the whole band
+          (inner). Up/down bars carry their own colors (default candle palette). */}
+      {volumeActive && (
+        <Group opacity={candleGroupOpacity}>
+          <Group opacity={volumeOpacity}>
+            <Path path={upBarsPath} style="fill" color={volumeUpColor} />
+            <Path path={downBarsPath} style="fill" color={volumeDownColor} />
+          </Group>
+        </Group>
+      )}
+
+      {/* Floating axis: the labels float ABOVE the candles (right-aligned at the
+          edge) so the plot runs full-width and candles stay fully visible behind
+          them. (Default non-floating axis draws grid + labels in ChartFillLayer.) */}
+      {yAxisCfg && yAxisFloat && (
+        <Group opacity={reveal.yAxisOpacity}>
+          <YAxisOverlay
+            variant="labels"
+            float
+            entries={yAxisEntries}
+            engine={engine}
+            padding={effectivePadding}
+            palette={palette}
+            font={skiaFont}
+            badge={badgeUsesRightGutter}
+            badgeTail={badgeCfg?.tail ?? true}
+            badgeMetrics={metricsCfg.badge}
+            gridStyle={gridStyleCfg}
+          />
+        </Group>
+      )}
+
+      {/* X-axis time labels. With a volume band the bottom padding is inflated by
+          the band height; pass it so the axis shifts back to the very bottom. */}
       {xAxisCfg && (
         <XAxisOverlay
           entries={xAxisEntries}
@@ -1015,6 +1470,7 @@ function ChartStack({ model }: { model: LiveChartModel }) {
           padding={effectivePadding}
           palette={palette}
           font={skiaFont}
+          volumeBandHeight={volumeBandHeight}
         />
       )}
 
@@ -1032,6 +1488,7 @@ function ChartStack({ model }: { model: LiveChartModel }) {
             radius={dotCfg.radius}
             ring={dotCfg.ring}
             color={dotCfg.color}
+            viewEnd={engine.viewEnd}
           />
         </Group>
       )}
@@ -1060,7 +1517,9 @@ function ChartStack({ model }: { model: LiveChartModel }) {
             palette={palette}
             font={skiaFont}
             lineData={engine.data}
+            lineLinear={lineIsLinear}
             renderMarker={renderMarker}
+            cluster={markerClusterCfg}
           />
         </Group>
       )}
@@ -1234,12 +1693,19 @@ function ChartValueOverlay({ model }: { model: LiveChartModel }) {
 /** Live-price badge, drawn above the scrub dim so the dim never clips its left
  *  edge. Shares the degen shake transform so it tracks the shaken stack. */
 function ChartBadgeLayer({ model }: { model: LiveChartModel }) {
-  const { badgeCfg, badgeData, skiaFont, reveal, degenShakeTransform } = model;
+  const { badgeCfg, badgeData, badgeFont, reveal, degenShakeTransform } = model;
   if (!badgeCfg) return null;
   return (
     <Group transform={degenShakeTransform}>
       <Group opacity={reveal.badgeOpacity}>
-        <BadgeOverlay badge={badgeData} font={skiaFont} />
+        <BadgeOverlay
+          badge={badgeData}
+          font={badgeFont}
+          borderColor={badgeCfg.borderColor}
+          borderWidth={badgeCfg.borderWidth}
+          offsetX={badgeCfg.offsetX}
+          offsetY={badgeCfg.offsetY}
+        />
       </Group>
     </Group>
   );
@@ -1252,11 +1718,20 @@ function ChartBadgeLayer({ model }: { model: LiveChartModel }) {
 function ChartRefBadgeLayer({ model }: { model: LiveChartModel }) {
   const {
     allRefLines,
+    refLineCustom,
+    dragValues,
+    groupHidden,
+    refGroupResult,
+    refGroupingActive,
+    refGroupBadge,
+    refGroupBadgeFont,
+    refGroupFormat,
     engine,
     effectivePadding,
     palette,
     formatValue,
     skiaFont,
+    fontProp,
     degenShakeTransform,
   } = model;
   if (allRefLines.length === 0) return null;
@@ -1271,9 +1746,26 @@ function ChartRefBadgeLayer({ model }: { model: LiveChartModel }) {
           palette={palette}
           formatValue={formatValue}
           font={skiaFont}
+          fontProp={fontProp}
           badgeLayer
+          dragValues={dragValues}
+          index={i}
+          suppressTag={refLineCustom[i]}
+          groupHidden={refGroupingActive ? groupHidden : undefined}
         />
       ))}
+      {/* Collapsed count handles for grouped (near-value) lines. */}
+      {refGroupingActive && (
+        <ReferenceLineGroupOverlay
+          grouping={refGroupResult}
+          padding={effectivePadding}
+          canvasWidth={engine.canvasWidth}
+          palette={palette}
+          font={refGroupBadgeFont}
+          badge={refGroupBadge}
+          format={refGroupFormat}
+        />
+      )}
     </Group>
   );
 }
@@ -1330,14 +1822,23 @@ export function LiveChart(props: LiveChartProps) {
     bottomLabelCfg,
     markersActive,
     markersSV,
+    markerClusterCfg,
     renderMarker,
     renderTooltip,
+    renderOverlay,
+    renderReferenceLine,
+    allRefLines,
+    refLineCustom,
+    dragValues,
+    dragActive,
+    overlayContext,
     scrubCfg,
     crosshair,
     isCandle,
     extremaTimeOffset,
     topConnector,
     bottomConnector,
+    lineIsLinear,
   } = model;
 
   return (
@@ -1414,6 +1915,24 @@ export function LiveChart(props: LiveChartProps) {
             engine={engine}
             padding={effectivePadding}
             lineData={engine.data}
+            lineLinear={lineIsLinear}
+            cluster={markerClusterCfg}
+          />
+        )}
+
+        {/* Custom-rendered reference-line tags — RN views floated over the canvas
+            (non-Skia), pinned to each Form-A line's value. Sibling of <Canvas>.
+            Built-in Skia tags for these lines are suppressed (no double-draw). */}
+        {renderReferenceLine && allRefLines.length > 0 && (
+          <CustomReferenceLineOverlay
+            lines={allRefLines}
+            renderReferenceLine={renderReferenceLine}
+            custom={refLineCustom}
+            engine={engine}
+            padding={effectivePadding}
+            formatValue={formatValue}
+            dragValues={dragValues}
+            dragActive={dragActive}
           />
         )}
 
@@ -1435,8 +1954,16 @@ export function LiveChart(props: LiveChartProps) {
             placement={scrubCfg.tooltipPlacement}
             margin={scrubCfg.tooltipMargin}
             lineTop={crosshair.tooltipLineTop}
+            scrubDotY={crosshair.scrubDotY}
           />
         )}
+
+        {/* Custom consumer overlay — an RN view tree floated over the canvas with
+            the price↔pixel / time↔pixel bridge, for order / avg-entry / liquidation
+            tags etc. Topmost RN sibling; `box-none` so empty areas still scrub. */}
+        {renderOverlay && (
+          <ChartOverlayLayer render={renderOverlay} context={overlayContext} />
+        )}
       </View>
     </GestureDetector>
   );