react-native-livechart 4.19.0 → 4.21.0

package/src/components/LiveChart.tsx

@@ -1,4 +1,12 @@
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { StyleSheet, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
 import Animated, {
@@ -10,8 +18,9 @@ import Animated, {
   withDelay,
   withSequence,
   withTiming,
+  type SharedValue,
 } from "react-native-reanimated";
-import { scheduleOnRN } from "react-native-worklets";
+import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
 
 /**
  * Single-series live chart. UX and prop vocabulary parallel Benji Taylor’s
@@ -37,6 +46,7 @@ import {
   resolveAreaDots,
   resolveAxisLabel,
   resolveBadge,
+  resolveCandleGaps,
   resolveDegen,
   resolveDot,
   resolveGradient,
@@ -62,7 +72,10 @@ import {
   resolveXAxis,
   resolveYAxis,
 } from "../core/resolveConfig";
-import type { ResolvedThresholdConfig } from "../core/resolveConfig";
+import type {
+  ResolvedCandleGapsConfig,
+  ResolvedThresholdConfig,
+} from "../core/resolveConfig";
 import {
   liveIndicatorScrollOpacity,
   resolveHideLiveOnScrollBack,
@@ -77,6 +90,7 @@ import {
 import { dotGlowRadialOutset, pulseRadialOutset } from "../draw/line";
 import { resolveChartLayout } from "../hooks/resolveChartLayout";
 import { useBadge } from "../hooks/useBadge";
+import { useCandleGapPaths } from "../hooks/useCandleGapPaths";
 import { useCandlePaths, useCandleWidthLerp } from "../hooks/useCandlePaths";
 import { useCanvasLayout } from "../hooks/useCanvasLayout";
 import { useChartColors } from "../hooks/useChartColors";
@@ -88,13 +102,14 @@ import { useCrosshair } from "../hooks/useCrosshair";
 import { useDegen } from "../hooks/useDegen";
 import { useLiveChartHasData } from "../hooks/useLiveChartHasData";
 import { useLiveDot } from "../hooks/useLiveDot";
+import { useLineGapPaths } from "../hooks/useLineGapPaths";
 import { useMarkers } from "../hooks/useMarkers";
 import { useReferenceDrag } from "../hooks/useReferenceDrag";
 import { useReferenceLinePress } from "../hooks/useReferenceLinePress";
 import { useModeBlend } from "../hooks/useModeBlend";
 import { resolveMomentumProp, useMomentum } from "../hooks/useMomentum";
 import { AXIS_GRAB_MIN_PX, usePanScroll } from "../hooks/usePanScroll";
-import { usePinchZoom } from "../hooks/usePinchZoom";
+import { resetPinchZoom, usePinchZoom } from "../hooks/usePinchZoom";
 import {
   SERIES_INDICATOR_FADE_MS,
   useSeriesIndicatorOpacity,
@@ -114,6 +129,10 @@ import {
   formatValue as defaultFormatValue,
 } from "../lib/format";
 import { MONO_FONT_FAMILY } from "../lib/monoFontFamily";
+import {
+  candleGapBucketStartAtTime,
+  candleGapDefaultLabel,
+} from "../math/candleGaps";
 import { computeScrubDotY } from "../hooks/crosshairShared";
 import {
   groupReferenceLines,
@@ -134,11 +153,14 @@ import {
 } from "../theme";
 import type {
   CandlePoint,
+  LiveChartHandle,
   LiveChartPalette,
   LiveChartPoint,
   LiveChartProps,
   Marker,
+  ReferenceLine,
 } from "../types";
+import { CustomThresholdBadgeOverlay } from "./CustomThresholdBadgeOverlay";
 import {
   ThresholdBadgeOverlay,
   ThresholdLineOverlay,
@@ -276,6 +298,8 @@ function useLiveChartController({
   candles,
   candleWidth = 60,
   liveCandle,
+  candleGaps,
+  lineGaps,
   volume,
 
   // ── Behaviour ───────────────────────────────────────────────────────────
@@ -333,6 +357,7 @@ function useLiveChartController({
   renderMarker,
   renderTooltip,
   renderOverlay,
+  renderThresholdBadge,
   renderReferenceLine,
   renderOffAxisReferenceLine,
   referenceLineGrouping,
@@ -371,6 +396,9 @@ function useLiveChartController({
   // 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 chartGapsCfg = resolveCandleGaps(isCandle ? candleGaps : lineGaps);
+  const candleGapsCfg = isCandle ? chartGapsCfg : null;
+  const lineGapsCfg = isCandle ? null : chartGapsCfg;
   const volumeBandHeight = volumeCfg?.maxHeight ?? 0;
   const gradientCfg = isCandle ? null : resolveGradient(gradient);
   // Dot-lattice area fill (clipped to the under-line region). Inert in candle
@@ -405,7 +433,35 @@ function useLiveChartController({
   const tradeStreamResolved = resolveTradeStream(tradeStream);
   const metricsCfg = resolveMetrics(metrics);
 
-  const allRefLines = referenceLines ?? [];
+  const chartGapBands: ReferenceLine[] =
+    chartGapsCfg?.gaps.flatMap((gap) => {
+      const gapStyle = chartGapsCfg.styles[gap.kind];
+      const band = gapStyle.band;
+      if (band === null) return [];
+      const label = gapStyle.label;
+      return [
+        {
+          id: `chart-gap:${gap.kind}:${gap.from}:${gap.to}`,
+          from: gap.from,
+          to: gap.to,
+          label:
+            label === null
+              ? undefined
+              : (gap.label ?? candleGapDefaultLabel(gap.kind)),
+          color: band.borderColor,
+          fillColor: band.fillColor,
+          fillOpacity: band.fillOpacity,
+          strokeOpacity: band.borderOpacity,
+          strokeWidth: band.borderWidth > 0 ? band.borderWidth : undefined,
+          intervals: band.intervals,
+          labelColor: label?.color,
+          labelPosition: label?.position,
+        },
+      ];
+    }) ?? [];
+  // Gap bands append after consumer reference lines so public line indices stay
+  // stable for callbacks. Time bands contribute no Y values or press targets.
+  const allRefLines = [...(referenceLines ?? []), ...chartGapBands];
   const refValues = collectReferenceValues(allRefLines);
 
   // Per-line live value overrides + drag flags for draggable lines and the custom
@@ -442,17 +498,23 @@ function useLiveChartController({
 
   // 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,
-  );
+  // Semantic gap bands are library-owned annotations: do not leak them through
+  // the consumer's reference-line renderer or change its callback cardinality.
+  const consumerRefLines = referenceLines ?? [];
+  const refLineCustom = [
+    ...customReferenceLineFlags(consumerRefLines, renderReferenceLine),
+    ...chartGapBands.map(() => false),
+  ];
   // An off-axis renderer replaces only the edge-pinned tag. A full custom tag
   // takes precedence for the same line to avoid mounting two native tags.
-  const refLineOffAxisCustom = customReferenceLineFlags(
-    allRefLines,
-    renderOffAxisReferenceLine,
-    "off-axis",
-  ).map((custom, index) => custom && !refLineCustom[index]);
+  const refLineOffAxisCustom = [
+    ...customReferenceLineFlags(
+      consumerRefLines,
+      renderOffAxisReferenceLine,
+      "off-axis",
+    ),
+    ...chartGapBands.map(() => false),
+  ].map((custom, index) => custom && !refLineCustom[index]);
   const refLineKeys = referenceLineReactKeys(allRefLines);
   // RN custom tags report their measured widths here so the Skia connector can
   // start after the native badge instead of the hidden built-in pill.
@@ -738,6 +800,13 @@ function useLiveChartController({
     mode,
     candles: isCandle ? candlesEngine : candles,
     liveCandle: isCandle ? liveEngine : liveCandle,
+    candleGaps: candleGapsCfg?.gaps,
+    candleGapBridgeNoTrades:
+      Boolean(candleGapsCfg?.styles["no-trades"].bridge),
+    candleGapBridgeUnavailable:
+      Boolean(candleGapsCfg?.styles.unavailable.bridge),
+    candleGapBridgeUnknown:
+      Boolean(candleGapsCfg?.styles.unknown.bridge),
   });
 
   // Mirror the UI-thread scroll state to React so the floating y-axis can keep
@@ -839,6 +908,7 @@ function useLiveChartController({
     thresholdValue,
     thresholdSeriesSV,
     thresholdCfg?.extendToNow ?? true,
+    thresholdCfg?.line?.labelAnchor ?? "last",
   );
   const thresholdStopColors = thresholdCfg
     ? thresholdStops(thresholdCfg, palette)
@@ -899,23 +969,38 @@ function useLiveChartController({
     thresholdSeriesGeom.clipRightX,
   );
 
-  // Marker line + badge sources: the series anchors at the value-at-now (flat-
-  // extended past its last point); the constant case at the single benchmark Y.
-  // The badge gets its own visibility — it's pinned at the value-at-now Y, which
-  // can be off-plot while older polyline segments are still visible.
+  // Marker line + badge sources: a series badge independently selects its first
+  // or last visible endpoint; the constant case stays at the single benchmark Y.
+  // The badge gets its own visibility because its selected endpoint can be
+  // off-plot while older polyline segments are still visible.
   const thresholdMarkerLineY = thresholdIsSeries
-    ? thresholdSeriesGeom.currentLineY
+    ? thresholdSeriesGeom.badgeLineY
     : thresholdGeom.lineY;
   const thresholdMarkerVisible = thresholdIsSeries
     ? thresholdSeriesGeom.visible
     : thresholdGeom.visible;
   const thresholdBadgeVisible = thresholdIsSeries
-    ? thresholdSeriesGeom.currentVisible
+    ? thresholdSeriesGeom.badgeVisible
     : thresholdGeom.visible;
   const thresholdMarkerValue =
     thresholdCfg && !thresholdIsSeries && !Array.isArray(thresholdCfg.value)
-      ? (thresholdCfg.value ?? thresholdSeriesGeom.currentValue)
-      : thresholdSeriesGeom.currentValue;
+      ? (thresholdCfg.value ?? thresholdSeriesGeom.badgeValue)
+      : thresholdSeriesGeom.badgeValue;
+  const hasCustomThresholdBadge =
+    thresholdCfg?.line != null && renderThresholdBadge != null;
+  const thresholdMarkerValueStr = useDerivedValue(() =>
+    hasCustomThresholdBadge ? formatValue(thresholdMarkerValue.get()) : "",
+  );
+  const thresholdCustomBadge =
+    thresholdCfg?.line && renderThresholdBadge
+      ? renderThresholdBadge({
+          line: thresholdCfg.line,
+          value: thresholdMarkerValue,
+          valueStr: thresholdMarkerValueStr,
+          y: thresholdMarkerLineY,
+          visible: thresholdBadgeVisible,
+        })
+      : null;
   const thresholdSeriesPts = thresholdIsSeries
     ? thresholdSeriesGeom.screenPts
     : undefined;
@@ -946,6 +1031,7 @@ function useLiveChartController({
       ? thresholdSeriesGeom.samples
       : undefined,
     lineProp?.simplify,
+    lineGapsCfg?.gaps,
   );
 
   // Area-dots fill shader color as a vec4 (channels 0..1), with the config
@@ -994,14 +1080,28 @@ function useLiveChartController({
 
   // ── Overlay hooks ─────────────────────────────────────────────────────
   // Scrub/crosshair must see the same stash-backed candles as the engine.
-  const candleOpts = isCandle
+  const crosshairChartOpts = isCandle
     ? {
         mode,
         candles: candlesEngine,
         liveCandle: liveEngine,
         candleWidthSecs: candleWidth,
+        gaps: candleGapsCfg?.gaps,
+        bridgeNoTrades:
+          Boolean(candleGapsCfg?.styles["no-trades"].bridge),
+        bridgeUnavailable:
+          Boolean(candleGapsCfg?.styles.unavailable.bridge),
+        bridgeUnknown: Boolean(candleGapsCfg?.styles.unknown.bridge),
       }
-    : undefined;
+    : lineGapsCfg
+      ? {
+          mode,
+          gaps: lineGapsCfg.gaps,
+          bridgeNoTrades: Boolean(lineGapsCfg.styles["no-trades"].bridge),
+          bridgeUnavailable: Boolean(lineGapsCfg.styles.unavailable.bridge),
+          bridgeUnknown: Boolean(lineGapsCfg.styles.unknown.bridge),
+        }
+      : undefined;
 
   const markersActive = markers != null;
   const markerClusterCfg = resolveMarkerCluster(markerCluster);
@@ -1102,7 +1202,7 @@ function useLiveChartController({
     // yet becomes scrubbable on touch. `static` only kills the continuous loop.
     scrubCfg !== null || scrubActionCfg !== null,
     onScrub,
-    candleOpts,
+    crosshairChartOpts,
     scrubHoldMs,
     onGestureStart,
     onGestureEnd,
@@ -1460,6 +1560,7 @@ function useLiveChartController({
     thresholdMarkerVisible,
     thresholdBadgeVisible,
     thresholdMarkerValue,
+    thresholdCustomBadge,
     thresholdSeriesPts,
     badgeUsesRightGutter,
     // theme / layout / fonts
@@ -1501,6 +1602,8 @@ function useLiveChartController({
     thresholdFillPath,
     lineIsLinear,
     volumeCfg,
+    candleGapsCfg,
+    lineGapsCfg,
     // 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,
@@ -1586,6 +1689,7 @@ function ChartWithYAxis({ model }: { model: LiveChartModel }) {
     yAxisCfg?.minGap ?? 36,
     metricsCfg.grid,
     yAxisCfg?.count ?? 0,
+    yAxisCfg?.intervalScale ?? 1,
   );
   if (model.degenCfg) {
     return <ChartWithDegen model={model} yAxisEntries={yAxisEntries} />;
@@ -1792,6 +1896,124 @@ function ChartFillLayer({
 }
 
 type CandlePaths = ReturnType<typeof useCandlePaths>;
+type CandleGapPaths = ReturnType<typeof useCandleGapPaths>;
+type LineGapPaths = ReturnType<typeof useLineGapPaths>;
+
+function GapBridgePathBatch({
+  paths,
+  config,
+  palette,
+}: {
+  paths: CandleGapPaths | LineGapPaths;
+  config: ResolvedCandleGapsConfig;
+  palette: LiveChartPalette;
+}) {
+  const noTrades = config.styles["no-trades"].bridge;
+  const unavailable = config.styles.unavailable.bridge;
+  const unknown = config.styles.unknown.bridge;
+  return (
+    <>
+      {noTrades !== null && (
+        <Group opacity={noTrades.opacity}>
+          <Path
+            path={paths.noTradesPath}
+            style="stroke"
+            strokeWidth={noTrades.strokeWidth}
+            strokeCap={noTrades.strokeCap}
+            color={noTrades.color ?? palette.refLine}
+          />
+        </Group>
+      )}
+      {unavailable !== null && (
+        <Group opacity={unavailable.opacity}>
+          <Path
+            path={paths.unavailablePath}
+            style="stroke"
+            strokeWidth={unavailable.strokeWidth}
+            strokeCap={unavailable.strokeCap}
+            color={unavailable.color ?? palette.refLine}
+          />
+        </Group>
+      )}
+      {unknown !== null && (
+        <Group opacity={unknown.opacity}>
+          <Path
+            path={paths.unknownPath}
+            style="stroke"
+            strokeWidth={unknown.strokeWidth}
+            strokeCap={unknown.strokeCap}
+            color={unknown.color ?? palette.refLine}
+          />
+        </Group>
+      )}
+    </>
+  );
+}
+
+function ChartCandleGapLayer({
+  model,
+  config,
+  focusOtherCandles,
+  inactiveOpacity,
+  focusedOpacity,
+  focusedClip,
+}: {
+  model: LiveChartModel;
+  config: ResolvedCandleGapsConfig;
+  focusOtherCandles: boolean;
+  inactiveOpacity: SharedValue<number>;
+  focusedOpacity: SharedValue<number>;
+  focusedClip: SharedValue<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }>;
+}) {
+  const paths = useCandleGapPaths(
+    model.engine,
+    model.effectivePadding,
+    model.candlesEngine,
+    model.liveEngine,
+    model.displayCandleWidth,
+    config,
+    model.metricsCfg.candle,
+  );
+  const batch = (
+    <GapBridgePathBatch
+      paths={paths}
+      config={config}
+      palette={model.palette}
+    />
+  );
+  return focusOtherCandles ? (
+    <>
+      <Group opacity={inactiveOpacity}>{batch}</Group>
+      <Group opacity={focusedOpacity} clip={focusedClip}>
+        {batch}
+      </Group>
+    </>
+  ) : (
+    batch
+  );
+}
+
+/** Line-mode bridge paths live in a child so candle charts register no worklets. */
+function ChartLineGapLayer({ model }: { model: LiveChartModel }) {
+  const config = model.lineGapsCfg!;
+  const paths = useLineGapPaths(
+    model.engine,
+    model.effectivePadding,
+    config,
+  );
+  return (
+    <GapBridgePathBatch
+      paths={paths}
+      config={config}
+      palette={model.palette}
+    />
+  );
+}
 
 /** One batched candle pass: two body paths and two wick paths. */
 function CandlePathBatch({
@@ -1848,6 +2070,7 @@ function ChartCandleLayer({ model }: { model: LiveChartModel }) {
     volumeOpacity,
     volumeUpColor,
     volumeDownColor,
+    candleGapsCfg,
     scrubCfg,
     crosshair,
   } = model;
@@ -1865,24 +2088,42 @@ function ChartCandleLayer({ model }: { model: LiveChartModel }) {
   const focusOtherCandles = scrubCfg?.dimTarget === "otherCandles";
   const candleDimOpacity = scrubCfg?.dimOpacity ?? 1;
   const candleDimFadeMs = scrubCfg?.dimFadeMs ?? 0;
-  // Destructure the two SharedValues before entering worklets. Closing over the
+  // Destructure SharedValues before entering worklets. Closing over the
   // whole crosshair object would also serialize its RNGH gesture instances.
   const scrubActive = crosshair.scrubActive;
   // ChartCandleLayer is single-series only; useCrosshair always supplies this
   // value (it is optional on the shared state type only for LiveChartSeries).
   const scrubCandle = crosshair.scrubCandle!;
-  // Keep the last selection after scrubCandle clears so its clipped full-
+  const scrubGap = crosshair.scrubGap!;
+  const scrubTime = crosshair.scrubTime;
+  const currentFocusBucketTime = useDerivedValue(() => {
+    if (!focusOtherCandles) return null;
+    const candle = scrubCandle.get();
+    if (candle) return candle.time;
+    const gap = scrubGap.get();
+    if (!gap) return null;
+    return candleGapBucketStartAtTime(
+      gap,
+      scrubTime.get(),
+      candlesEngine.get(),
+      liveEngine.get(),
+      displayCandleWidth.get(),
+    );
+  });
+  // Keep the last selection after the current target clears so its clipped full-
   // strength pass can cover the base batch until the release fade completes.
-  const lastScrubCandle = useSharedValue<CandlePoint | null>(null);
+  const lastFocusBucket = useSharedValue<{ time: number } | null>(null);
   useAnimatedReaction(
-    () => (focusOtherCandles ? scrubCandle.get() : null),
-    (candle) => {
-      if (candle) lastScrubCandle.set(candle);
+    () => currentFocusBucketTime.get(),
+    (time) => {
+      if (time !== null) lastFocusBucket.set({ time });
     },
   );
   const inactiveCandleOpacity = useDerivedValue(() => {
     const target =
-      focusOtherCandles && scrubActive.get() && scrubCandle.get()
+      focusOtherCandles &&
+      scrubActive.get() &&
+      currentFocusBucketTime.get() !== null
         ? candleDimOpacity
         : 1;
     return candleDimFadeMs > 0
@@ -1891,33 +2132,36 @@ function ChartCandleLayer({ model }: { model: LiveChartModel }) {
   }, [
     focusOtherCandles,
     scrubActive,
-    scrubCandle,
+    currentFocusBucketTime,
     candleDimOpacity,
     candleDimFadeMs,
   ]);
   const focusedCandleOpacity = useDerivedValue(() => {
-    const currentCandle = scrubCandle.get();
-    const focusCandle = currentCandle ?? lastScrubCandle.get();
-    if (!focusOtherCandles || !focusCandle) return 0;
+    const currentTime = currentFocusBucketTime.get();
+    const focusBucket =
+      currentTime === null ? lastFocusBucket.get() : { time: currentTime };
+    if (!focusOtherCandles || !focusBucket) return 0;
     return computeCandleFocusPassOpacity(
       scrubActive.get(),
-      currentCandle !== null,
+      currentTime !== null,
       inactiveCandleOpacity.get(),
     );
   }, [
     focusOtherCandles,
     scrubActive,
-    scrubCandle,
-    lastScrubCandle,
+    currentFocusBucketTime,
+    lastFocusBucket,
     inactiveCandleOpacity,
   ]);
   const focusedCandleClip = useDerivedValue(() => {
     if (!focusOtherCandles) {
       return HIDDEN_CANDLE_FOCUS_CLIP;
     }
-    const focusCandle = scrubCandle.get() ?? lastScrubCandle.get();
+    const currentTime = currentFocusBucketTime.get();
+    const focusBucket =
+      currentTime === null ? lastFocusBucket.get() : { time: currentTime };
     return computeCandleFocusClip(
-      focusCandle,
+      focusBucket,
       effectivePadding,
       engine.canvasWidth.get(),
       engine.canvasHeight.get(),
@@ -1927,8 +2171,8 @@ function ChartCandleLayer({ model }: { model: LiveChartModel }) {
     );
   }, [
     focusOtherCandles,
-    scrubCandle,
-    lastScrubCandle,
+    currentFocusBucketTime,
+    lastFocusBucket,
     effectivePadding,
     engine.canvasWidth,
     engine.canvasHeight,
@@ -1940,6 +2184,16 @@ function ChartCandleLayer({ model }: { model: LiveChartModel }) {
   return (
     <Group opacity={seriesOpacity}>
       <Group opacity={candleGroupOpacity}>
+        {candleGapsCfg && (
+          <ChartCandleGapLayer
+            model={model}
+            config={candleGapsCfg}
+            focusOtherCandles={focusOtherCandles}
+            inactiveOpacity={inactiveCandleOpacity}
+            focusedOpacity={focusedCandleOpacity}
+            focusedClip={focusedCandleClip}
+          />
+        )}
         {focusOtherCandles ? (
           <>
             <Group opacity={inactiveCandleOpacity}>
@@ -2022,11 +2276,13 @@ function ChartStack({
     thresholdMarkerVisible,
     thresholdBadgeVisible,
     thresholdMarkerValue,
+    thresholdCustomBadge,
     thresholdSeriesPts,
     formatValue,
     lineGroupOpacity,
     seriesOpacity,
     linePath,
+    lineGapsCfg,
     lineIsLinear,
     strokeWidth,
     lineProp,
@@ -2171,6 +2427,7 @@ function ChartStack({
               />
             ) : null}
           </Path>
+          {lineGapsCfg && <ChartLineGapLayer model={model} />}
         </Group>
       </Group>
 
@@ -2246,7 +2503,7 @@ function ChartStack({
 
       {/* Threshold label badge — on top of the line/dot/markers so it's never
           painted over (the dashed marker line itself stays behind the line, above). */}
-      {thresholdCfg?.line && (
+      {thresholdCfg?.line && thresholdCustomBadge == null && (
         <ThresholdBadgeOverlay
           engine={engine}
           padding={effectivePadding}
@@ -2300,15 +2557,27 @@ function ChartTradeStreamLayer({
     tradeStream,
     tradeStreamResolved,
     effectivePadding,
+    volumeBandHeight,
     palette,
     skiaFont,
     reveal,
     isStatic,
   } = model;
+  // `effectivePadding.bottom` includes the volume reservation so candle prices
+  // stop above the bars. The trade tape should still enter at the chart's true
+  // lower edge (the volume baseline / x-axis), so remove that reservation for
+  // this overlay's coordinate space only.
+  const tradeStreamPadding =
+    volumeBandHeight > 0
+      ? {
+          ...effectivePadding,
+          bottom: effectivePadding.bottom - volumeBandHeight,
+        }
+      : effectivePadding;
   const tradeMarkers = useTradeStream(
     engine,
     tradeStream!,
-    effectivePadding,
+    tradeStreamPadding,
     !isStatic,
     !isStatic,
   );
@@ -2317,7 +2586,7 @@ function ChartTradeStreamLayer({
       <TradeStreamOverlay
         markers={tradeMarkers}
         palette={palette}
-        padding={effectivePadding}
+        padding={tradeStreamPadding}
         font={skiaFont}
         opacity={reveal.dotOpacity}
         labelOffsetX={tradeStreamResolved!.labelOffsetX}
@@ -2755,6 +3024,10 @@ function ChartView({
     formatValue,
     topLabelCfg,
     bottomLabelCfg,
+    thresholdCfg,
+    thresholdMarkerLineY,
+    thresholdBadgeVisible,
+    thresholdCustomBadge,
     markersActive,
     renderMarker,
     renderTooltip,
@@ -2868,6 +3141,19 @@ function ChartView({
           />
         )}
 
+        {/* Custom threshold badge — a native view positioned from the same live
+            value/Y SharedValues as the built-in Skia badge. */}
+        {thresholdCustomBadge && thresholdCfg?.line && (
+          <CustomThresholdBadgeOverlay
+            element={thresholdCustomBadge}
+            engine={engine}
+            padding={effectivePadding}
+            y={thresholdMarkerLineY}
+            visible={thresholdBadgeVisible}
+            position={thresholdCfg.line.labelPosition}
+          />
+        )}
+
         {/* Custom-rendered markers — RN views floated over the canvas (non-Skia),
             pinned to each marker's live position. Sibling of <Canvas>. Wrapped in
             a box-none fade layer so `scrub.hideOverlaysOnScrub` hides them with the
@@ -2890,6 +3176,7 @@ function ChartView({
             scrubTime={crosshair.scrubTime}
             scrubActive={crosshair.scrubActive}
             scrubCandle={crosshair.scrubCandle}
+            scrubGap={crosshair.scrubGap}
             tooltipLayout={crosshair.tooltipLayout}
             engine={engine}
             padding={effectivePadding}
@@ -2911,13 +3198,23 @@ function ChartView({
   );
 }
 
-export function LiveChart(props: LiveChartProps) {
-  const model = useLiveChartController(props);
-  if (model.yAxisCfg) {
-    return <ChartWithYAxis model={model} />;
-  }
-  if (model.degenCfg) {
-    return <ChartWithDegen model={model} yAxisEntries={null} />;
-  }
-  return <ChartView model={model} yAxisEntries={null} degen={null} />;
-}
+export const LiveChart = forwardRef<LiveChartHandle, LiveChartProps>(
+  function LiveChart(props, ref) {
+    const model = useLiveChartController(props);
+    const { viewEnd, viewWindow } = model.engine;
+    useImperativeHandle(
+      ref,
+      () => ({
+        resetZoom: () => scheduleOnUI(resetPinchZoom, { viewEnd, viewWindow }),
+      }),
+      [viewEnd, viewWindow],
+    );
+    if (model.yAxisCfg) {
+      return <ChartWithYAxis model={model} />;
+    }
+    if (model.degenCfg) {
+      return <ChartWithDegen model={model} yAxisEntries={null} />;
+    }
+    return <ChartView model={model} yAxisEntries={null} degen={null} />;
+  },
+);