react-native-livechart 4.16.0 → 4.18.0

package/src/components/MarkerOverlay.tsx

@@ -388,7 +388,11 @@ export function MarkerOverlay({
         lineData: lineData?.get(),
         lineLinear,
       });
-      clusterMarkers(ms, buf, { config: cluster });
+      clusterMarkers(ms, buf, {
+        config: cluster,
+        minY: 0,
+        maxY: engine.canvasHeight.get(),
+      });
       const atlasFrames = atlasFrameRef.current!;
       atlasFrames.tick = !atlasFrames.tick;
       const frame = atlasFrames.tick ? atlasFrames.a : atlasFrames.b;

package/src/core/liveChartEngineTick.ts

@@ -371,7 +371,11 @@ export function tickLiveChartEngineFrame(
         : 1;
     if (yScale !== 1) {
       const scaledMid = (tMin + tMax) / 2;
-      const scaledHalf = ((tMax - tMin) / 2) * yScale;
+      let scaledHalf = ((tMax - tMin) / 2) * yScale;
+      // On non-negative charts, cap the zoom-out at the point where the floor
+      // reaches 0. Letting it grow and clamping min afterwards keeps only the
+      // top expanding, which pins the data to the bottom of the plot.
+      if (input.nonNegative && scaledHalf > scaledMid) scaledHalf = scaledMid;
       const scaledMin = scaledMid - scaledHalf;
       const scaledMax = scaledMid + scaledHalf;
       // Reject multiplication overflow and subnormal scales that round the two

package/src/core/liveChartSeriesEngineTick.ts

@@ -305,7 +305,11 @@ export function tickLiveChartSeriesEngineFrame(
         : 1;
     if (yScale !== 1) {
       const scaledMid = (tMin + tMax) / 2;
-      const scaledHalf = ((tMax - tMin) / 2) * yScale;
+      let scaledHalf = ((tMax - tMin) / 2) * yScale;
+      // On non-negative charts, cap the zoom-out at the point where the floor
+      // reaches 0. Letting it grow and clamping min afterwards keeps only the
+      // top expanding, which pins the data to the bottom of the plot.
+      if (input.nonNegative && scaledHalf > scaledMid) scaledHalf = scaledMid;
       const scaledMin = scaledMid - scaledHalf;
       const scaledMax = scaledMid + scaledHalf;
       if (

package/src/core/resolveConfig.ts

@@ -192,6 +192,8 @@ export interface ResolvedScrubConfig {
   hideOverlaysOnScrub: boolean;
   /** Reject outside plain-scrub starts and clamp active scrub X to the plot. */
   clampToPlot: boolean;
+  /** Candle mode: quantize the scrub X to the hovered candle's center. */
+  snapToCandles: boolean;
 }
 
 export interface ResolvedPerSeriesTooltipConfig {
@@ -582,6 +584,18 @@ export function resolveOverscroll(
   return v < MAX_OVERSCROLL ? v : MAX_OVERSCROLL;
 }
 
+/**
+ * Resolves `timeScroll.fling`: `false` disables release inertia so the window
+ * stops dead where the finger lifts. Booleans / omitted keep the default (on).
+ * See {@link TimeScrollConfig}.
+ */
+export function resolveFling(
+  prop: boolean | TimeScrollConfig | undefined,
+): boolean {
+  if (prop == null || typeof prop === "boolean") return true;
+  return prop.fling ?? true;
+}
+
 /**
  * Resolved transition durations. `undefined` for a field means "use the
  * component's built-in default" (so we don't duplicate the default constants
@@ -722,6 +736,7 @@ const SCRUB_DEFAULTS: ResolvedScrubConfig = {
   panGestureDelay: 0,
   hideOverlaysOnScrub: false,
   clampToPlot: false,
+  snapToCandles: false,
 };
 
 const PER_SERIES_TOOLTIP_DEFAULTS: ResolvedPerSeriesTooltipConfig = {
@@ -875,6 +890,7 @@ export function resolveMarkerCluster(
       overlap: clamp01(prop.overlap ?? MARKER_CLUSTER_OVERLAP),
       gap: MARKER_CLUSTER_GAP,
       maxBeforeGroup: prop.maxBeforeGroup ?? MARKER_CLUSTER_MAX_BEFORE_GROUP,
+      maxVisible: prop.maxVisible ?? Number.MAX_SAFE_INTEGER,
       groupBadge: prop.groupBadge ?? "count",
       showGroupCount: prop.showGroupCount ?? false,
     };
@@ -885,6 +901,7 @@ export function resolveMarkerCluster(
     overlap: MARKER_CLUSTER_OVERLAP,
     gap: MARKER_CLUSTER_GAP,
     maxBeforeGroup: MARKER_CLUSTER_MAX_BEFORE_GROUP,
+    maxVisible: Number.MAX_SAFE_INTEGER,
     groupBadge: "count",
     showGroupCount: false,
   };
@@ -1188,6 +1205,7 @@ export interface ResolvedDotConfig {
   ring: ResolvedDotRingConfig | null;
   show: boolean;
   color: string | undefined;
+  trackWhileParked: boolean;
 }
 
 const DOT_DEFAULTS: ResolvedDotConfig = {
@@ -1195,6 +1213,7 @@ const DOT_DEFAULTS: ResolvedDotConfig = {
   ring: RING_DEFAULTS,
   show: true,
   color: undefined,
+  trackWhileParked: false,
 };
 
 /**
@@ -1214,6 +1233,7 @@ export function resolveDot(
     ring: resolveDotRing(prop.ring),
     show: prop.show ?? DOT_DEFAULTS.show,
     color: prop.color,
+    trackWhileParked: prop.trackWhileParked ?? DOT_DEFAULTS.trackWhileParked,
   };
 }
 

package/src/core/useLiveChartEngine.ts

@@ -5,7 +5,7 @@
  *
  * @see https://github.com/benjitaylor/liveline
  */
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import {
   cancelAnimation,
   Easing,
@@ -497,7 +497,11 @@ export function useLiveChartEngine(
   // Compare against the previous key (not a "first render" flag) so React 18
   // StrictMode's double-invoked mount effect can't fire a spurious snap.
   const lastSnapKey = useRef(config.snapKey);
-  useEffect(() => {
+  // Layout effect, not passive: a passive effect runs after the commit has
+  // painted, so the frame between them draws the new data/candleWidth against
+  // the OLD framing (a one-frame squeeze on a timeframe switch). Flipping the
+  // flag before paint lets the first frame with the new props consume the snap.
+  useLayoutEffect(() => {
     if (config.snapKey === lastSnapKey.current) return;
     lastSnapKey.current = config.snapKey;
     snapSV.set(true);

package/src/core/useLiveChartSeriesEngine.ts

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from "react";
+import { useLayoutEffect, useRef, useState } from "react";
 import {
   cancelAnimation,
   Easing,
@@ -343,7 +343,9 @@ export function useLiveChartSeriesEngine(
   // changes, consumed + cleared by the next frame (mirrors useLiveChartEngine).
   const snapSV = useSharedValue(false);
   const lastSnapKey = useRef(config.snapKey);
-  useEffect(() => {
+  // Layout effect so the snap flag lands before the commit paints — a passive
+  // effect leaves one frame of new data in the old framing (mirrors useLiveChartEngine).
+  useLayoutEffect(() => {
     if (config.snapKey === lastSnapKey.current) return;
     lastSnapKey.current = config.snapKey;
     snapSV.set(true);

package/src/draw/line.ts

@@ -27,8 +27,8 @@ export const DEFAULT_PADDING: ChartPadding = {
  * The pill body starts `tl` px to the right of the gutter left edge (= dot x),
  * so the tail spans the gap between the dot and the pill body.
  *
- * When `showTail` is false the tail spike is omitted and only the round cap
- * radius is returned, letting callers shrink the right gutter.
+ * When `showTail` is false there is no tail geometry at all, so the pill body
+ * starts flush at the gutter left edge (+ dotGap) and no cap inset is reserved.
  */
 export function badgeTailAndCap(
   fontSize: number,
@@ -36,8 +36,9 @@ export function badgeTailAndCap(
   badge: BadgeMetrics = BADGE_METRICS_DEFAULTS,
 ): number {
   "worklet";
+  if (!showTail) return 0;
   const pillH = fontSize + badge.padY * 2;
-  return (showTail ? badge.tailLength : 0) + pillH / 2;
+  return badge.tailLength + pillH / 2;
 }
 
 /**

package/src/hooks/crosshairShared.ts

@@ -4,6 +4,7 @@ import type { DerivedValue, SharedValue } from "react-native-reanimated";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import { type ChartPadding } from "../draw/line";
 import { interpolateAtTime } from "../math/interpolate";
+import { pickCandleAtTime } from "../math/pickCandle";
 import type { CandlePoint } from "../types";
 
 const TOOLTIP_PAD_X = 8;
@@ -290,6 +291,36 @@ export function computeScrubTime(
   return winStart + fraction * windowSecs;
 }
 
+/**
+ * Quantizes a scrub X to the center of the candle whose time bucket contains
+ * it (`scrub.snapToCandles`) — the inverse of {@link computeScrubTime}
+ * followed by the forward mapping of the picked candle's center. Returns the
+ * raw X unchanged when the position falls in a gap between candles or when
+ * the plot has no horizontal extent / time window yet.
+ */
+export function snapScrubXToCandleCenter(
+  x: number,
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  candleWidthSecs: number,
+  padding: ChartPadding,
+  canvasWidth: number,
+  timestamp: number,
+  windowSecs: number,
+): number {
+  "worklet";
+  const chartW = canvasWidth - padding.left - padding.right;
+  if (chartW <= 0 || windowSecs <= 0) return x;
+  const winStart = timestamp - windowSecs;
+  const t = winStart + ((x - padding.left) / chartW) * windowSecs;
+  const candle = pickCandleAtTime(candles, liveCandle, t, candleWidthSecs);
+  if (!candle) return x;
+  return (
+    padding.left +
+    ((candle.time + candleWidthSecs / 2 - winStart) / windowSecs) * chartW
+  );
+}
+
 /**
  * Crosshair opacity: fades 1→0 over `fadeDistance` px as the crosshair
  * approaches the live dot at the right chart edge. A zero distance removes

package/src/hooks/resolveChartLayout.ts

@@ -46,7 +46,10 @@ export interface ChartLayoutConfig {
    * is not clipped. An explicit `insetsOverride` on a side wins over this floor.
    */
   pulse?: { maxRadius: number; strokeWidth: number } | null;
-  /** When false and badge uses the right gutter, omit BADGE_TAIL_LEN from the right padding. */
+  /**
+   * When false and the badge uses the right gutter, omit the tail and
+   * round-cap inset from the right padding.
+   */
   badgeShowTail?: boolean;
   /** Multi-series dot radius — used to add spacing between dots and Y-axis labels. */
   multiSeriesDotRadius?: number;
@@ -117,7 +120,16 @@ export function resolveChartLayout(
     );
   }
 
-  if (config.pulse && config.yAxis && config.insetsOverride?.right == null) {
+  // A right-gutter badge uses its pill layout instead of the bare centered label
+  // column, so the bare-axis pulse/label floor must not override badge sizing.
+  // The badge renders above the pulse; the general outlet floor below still
+  // prevents canvas-edge clipping.
+  if (
+    config.pulse &&
+    config.yAxis &&
+    !badgeUsesRightGutter &&
+    config.insetsOverride?.right == null
+  ) {
     const outlet = pulseRadialOutset(
       config.pulse.maxRadius,
       config.pulse.strokeWidth,

package/src/hooks/useCandlePaths.ts

@@ -17,33 +17,25 @@ import { usePathBuilder } from "./usePathBuilder";
 const CANDLE_WIDTH_LERP_SPEED = 0.08;
 
 /**
- * Candle paths (up/down bodies + up/down wicks). Each is built into a reused
- * `Skia.PathBuilder` and finalized with `detach()` each frame — a fresh
- * immutable `SkPath`, so Skia repaints without a per-curve ping-pong and no
- * mutable `SkPath` is retained across frames.
+ * Bridges the `candleWidth` prop to the UI thread and eases the displayed
+ * width toward it each frame. Must be called from the chart's OUTER component
+ * (the controller), not from inside the Skia canvas: canvas children render
+ * through Skia's own reconciler one commit behind the outer tree, so a width
+ * bridged in there lands one frame after the engine's framing targets — a
+ * timeframe switch then draws one frame of new data at the old width. See #176.
  */
-export function useCandlePaths(
-  engine: SingleEngineState,
-  padding: ChartPadding,
-  candles: SharedValue<CandlePoint[]> | undefined,
-  liveCandle: SharedValue<CandlePoint | null> | undefined,
+export function useCandleWidthLerp(
   candleWidthSecs: number,
-  active: boolean,
-  candleMetrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
-  /** Reserved volume-band height (px). `0` = no volume bars. */
-  volumeBandHeight = 0,
-  /** Corner radius (px) of the volume bars. */
-  volumeRadius = 0,
-  /** Static charts run no loops: register without starting. Default `true`. */
-  autostart = true,
   /**
    * Per-frame lerp speed (0–1) for the candle-body width as it eases toward
    * `candleWidthSecs`. `1` snaps in one frame (no "fat → thin" slide on a
    * timeframe / bucket change); `undefined` uses {@link CANDLE_WIDTH_LERP_SPEED}.
    * Resolved from `transitions.candleLerpSpeed`. See #176.
    */
-  candleLerpSpeed?: number,
-) {
+  candleLerpSpeed: number | undefined,
+  /** Static charts run no loops: register without starting. */
+  autostart: boolean,
+): SharedValue<number> {
   const targetCandleWidth = useDerivedValue(() => candleWidthSecs);
   const displayCandleWidth = useSharedValue(candleWidthSecs);
   // `transitions.candleLerpSpeed` overrides the built-in speed (0–1, already
@@ -54,16 +46,8 @@ export function useCandlePaths(
     () => candleLerpSpeed ?? CANDLE_WIDTH_LERP_SPEED,
   );
 
-  const upBodiesBuilder = usePathBuilder();
-  const downBodiesBuilder = usePathBuilder();
-  const upWicksBuilder = usePathBuilder();
-  const downWicksBuilder = usePathBuilder();
-  const upBarsBuilder = usePathBuilder();
-  const downBarsBuilder = usePathBuilder();
-
   useFrameCallback((frameInfo) => {
     "worklet";
-    if (!active) return;
     const dt = frameInfo.timeSincePreviousFrame ?? MS_PER_FRAME_60FPS;
     displayCandleWidth.set(
       lerp(
@@ -75,6 +59,36 @@ export function useCandlePaths(
     );
   }, autostart);
 
+  return displayCandleWidth;
+}
+
+/**
+ * Candle paths (up/down bodies + up/down wicks). Each is built into a reused
+ * `Skia.PathBuilder` and finalized with `detach()` each frame — a fresh
+ * immutable `SkPath`, so Skia repaints without a per-curve ping-pong and no
+ * mutable `SkPath` is retained across frames.
+ */
+export function useCandlePaths(
+  engine: SingleEngineState,
+  padding: ChartPadding,
+  candles: SharedValue<CandlePoint[]> | undefined,
+  liveCandle: SharedValue<CandlePoint | null> | undefined,
+  /** Displayed bucket width from {@link useCandleWidthLerp} (outer component). */
+  displayCandleWidth: SharedValue<number>,
+  active: boolean,
+  candleMetrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
+  /** Reserved volume-band height (px). `0` = no volume bars. */
+  volumeBandHeight = 0,
+  /** Corner radius (px) of the volume bars. */
+  volumeRadius = 0,
+) {
+  const upBodiesBuilder = usePathBuilder();
+  const downBodiesBuilder = usePathBuilder();
+  const upWicksBuilder = usePathBuilder();
+  const downWicksBuilder = usePathBuilder();
+  const upBarsBuilder = usePathBuilder();
+  const downBarsBuilder = usePathBuilder();
+
   /* istanbul ignore next -- worklet */
   const geometry = useDerivedValue(() => {
     if (!active || !candles) return { bodies: [], wicks: [] };

package/src/hooks/useChartReveal.ts

@@ -51,8 +51,9 @@ export interface ChartRevealState {
 /**
  * Drives loading / empty / live visibility.
  *
- * Chart is fully revealed only when `!loading && hasData`. `morphT` animates
- * between 0 and 1 when that condition changes. `isEmpty` is derived as
+ * Chart is fully revealed only when `!loading && hasData`. Data appearing
+ * grows `morphT` from 0 to 1; data disappearing snaps it to 0 so stale paths
+ * never visibly flatten over a loading or empty shell. `isEmpty` is derived as
  * `!loading && !hasData` for the empty overlay label.
  */
 export function useChartReveal(
@@ -87,11 +88,18 @@ export function useChartReveal(
         return;
       }
       if (prev !== chartVisible) {
+        // Collapse (live → loading/empty) snaps: the data is already gone, so
+        // animating would draw the stale line morphing flat over the loading
+        // shell.
+        if (!chartVisible) {
+          morphT.set(0);
+          return;
+        }
         // 0ms → withTiming resolves on the next frame (effectively a snap), so an
         // explicit `transitions={{ reveal: 0 }}` / `transitions={false}` removes
         // the grow-in without a special-case branch.
         morphT.set(
-          withTiming(chartVisible ? 1 : 0, {
+          withTiming(1, {
             duration: revealDuration,
             easing: Easing.out(Easing.cubic),
           }),

package/src/hooks/useCrosshair.ts

@@ -37,6 +37,7 @@ import {
   SCRUB_ACTIVATE_X_PX,
   SCRUB_FAIL_Y_PX,
   snapPrice,
+  snapScrubXToCandleCenter,
   startPlainScrub,
   type CrosshairState,
   updatePlainScrub,
@@ -157,6 +158,12 @@ export function useCrosshair(
    * Default `false`.
    */
   clampToPlot = false,
+  /**
+   * Candle mode: quantize the plain-scrub X to the hovered candle's center
+   * before it enters `scrubX` (`scrub.snapToCandles`). No-op in line mode.
+   * Default `false`.
+   */
+  snapToCandles = false,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -519,6 +526,26 @@ export function useCrosshair(
       ? SCRUB_ACTION_PRESS_HOLD_MS
       : panGestureDelay;
 
+  // `scrub.snapToCandles`: quantize the scrub X to the hovered candle's center
+  // before it enters `scrubX`, so the crosshair — and everything derived from
+  // it (time, tooltip, dim edge) — jumps candle-to-candle instead of gliding.
+  // Line mode and gaps between candles pass the raw X through.
+  /* istanbul ignore next -- worklet, called only from UI-thread gesture handlers */
+  const snapCandleX = (x: number): number => {
+    "worklet";
+    if (!snapToCandles || !isCandleMode || !candlesSV) return x;
+    return snapScrubXToCandleCenter(
+      x,
+      candlesSV.get(),
+      liveCandleSV?.get() ?? null,
+      candleWidthSecs,
+      padding,
+      engine.canvasWidth.get(),
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+    );
+  };
+
   let gesture = Gesture.Pan()
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
@@ -618,7 +645,7 @@ export function useCrosshair(
         // guard needed. (Plain-scrub counterpart of the scrub-action tap defer.)
         if (deferTapHit !== undefined && deferTapHit(e.x, e.y)) return;
         startPlainScrub(
-          e.x,
+          snapCandleX(e.x),
           padding,
           engine.canvasWidth.get(),
           clampPlainScrubToPlot,
@@ -653,7 +680,7 @@ export function useCrosshair(
           return;
         }
         updatePlainScrub(
-          e.x,
+          snapCandleX(e.x),
           padding,
           engine.canvasWidth.get(),
           clampPlainScrubToPlot,

package/src/hooks/useLiveDot.ts

@@ -1,5 +1,8 @@
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
-import type { SingleEngineState } from "../core/useLiveChartEngine";
+import type {
+  ChartEngineScroll,
+  SingleEngineState,
+} from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 
 /**
@@ -10,17 +13,39 @@ import type { ChartPadding } from "../draw/line";
  * With `followViewEdge` + `edgeValue`, the dot (and the value line that shares
  * `dotY`) tracks the visible window's right-edge price while scrolled back, so it
  * stays aligned with a `followViewEdge` badge instead of marking the live value.
+ *
+ * With `trackWhileParked` (`dot.trackWhileParked`), the dot instead tracks the
+ * **true live point's x** while scrolled back / overscrolled (`viewEnd`
+ * frozen), and hides once the live point leaves the visible window.
+ * `followViewEdge` wins when both are set — an edge-pinned dot must stay
+ * aligned with its badge.
  */
 export function useLiveDot(
-  engine: SingleEngineState,
+  engine: SingleEngineState & ChartEngineScroll,
   padding: ChartPadding,
   edgeValue?: SharedValue<number>,
   followViewEdge = false,
+  trackWhileParked = false,
 ) {
   const dotX = useDerivedValue(() => {
     const w = engine.canvasWidth.value;
     if (w === 0) return -100;
-    return w - padding.right;
+    const right = w - padding.right;
+    // While parked (scrolled back / overscrolled) the live point is not at the
+    // plot edge — track its real x so a pan doesn't lose the dot, and hide it
+    // only once the point leaves the window.
+    if (trackWhileParked && !followViewEdge && engine.viewEnd.value != null) {
+      const data = engine.data.value;
+      const last = data[data.length - 1];
+      const win = engine.displayWindow.value;
+      const chartW = w - padding.left - padding.right;
+      if (!last || win <= 0 || chartW <= 0) return -100;
+      const x =
+        padding.left +
+        ((last.time - (engine.timestamp.value - win)) / win) * chartW;
+      return x < padding.left || x > right ? -100 : x;
+    }
+    return right;
   });
 
   const dotY = useDerivedValue(() => {

package/src/hooks/useMarkers.ts

@@ -28,6 +28,7 @@ const ANCHORED_CLUSTER: ResolvedMarkerCluster = {
   overlap: 0.75,
   gap: 2,
   maxBeforeGroup: 5,
+  maxVisible: Number.MAX_SAFE_INTEGER,
   groupBadge: "count",
   showGroupCount: false,
 };
@@ -101,7 +102,11 @@ export function useMarkers(
         lineData: lineData?.get(),
         lineLinear,
       });
-      clusterMarkers(markers.get(), buf, { config: cluster });
+      clusterMarkers(markers.get(), buf, {
+        config: cluster,
+        minY: 0,
+        maxY: engine.canvasHeight.get(),
+      });
       projected.set(buf);
     },
     autostart,

package/src/hooks/usePanScroll.ts

@@ -81,6 +81,13 @@ export interface UsePanScrollOptions {
    * `timeScroll.overscroll` (see `resolveOverscroll`).
    */
   overscroll?: number;
+  /**
+   * Fling inertia on release: a fast drag keeps scrolling and decays to a stop.
+   * `false` stops the window dead where the finger lifts (a release near the
+   * live edge still re-attaches to live). Resolved from `timeScroll.fling`
+   * (see `resolveFling`). Default `true`.
+   */
+  fling?: boolean;
 }
 
 /**
@@ -218,6 +225,7 @@ export function usePanScroll({
   scrollActive,
   scrubActive,
   overscroll = 0,
+  fling = true,
 }: UsePanScrollOptions): ReturnType<typeof Gesture.Pan> {
   const { viewEnd, liveEdge, displayWindow, canvasWidth, canvasHeight } = engine;
   const padLeft = padding.left;
@@ -307,7 +315,10 @@ export function usePanScroll({
       // 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);
+      // `fling: false` → zero velocity: the decay resolves immediately where
+      // the finger lifted, and the completion callback below still re-attaches
+      // to live when the release lands inside the snap zone.
+      const velocity = fling ? flingVelocity(e.velocityX, chartW, win) : 0;
       cancelAnimation(viewEnd);
       viewEnd.set(
         withDecay({ velocity, clamp: [lo, hi] }, (finished) => {

package/src/index.ts

@@ -33,6 +33,7 @@ export { usePriceY, useTimeX } from "./hooks/useChartOverlayContext";
 
 export type {
   AreaDotsConfig,
+  AxisAutoHideConfig,
   AxisLabelConfig,
   BadgeConfig,
   BadgeMetrics,

package/src/math/markerCluster.ts

@@ -20,6 +20,9 @@ export interface ResolvedMarkerCluster {
   gap: number;
   /** Collapse a co-located run to a single count badge once it exceeds this many. */
   maxBeforeGroup: number;
+  /** Cap a `"vertical"` column at this many glyphs: the newest overflow is
+   *  hidden instead of the column growing unbounded. */
+  maxVisible: number;
   /** What a collapsed group draws: `"count"` = the round count badge (default);
    *  `"marker"` = the representative marker's own glyph; a {@link MarkerGroupBadge}
    *  = a dedicated badge (custom image/icon) independent of the members. */
@@ -31,6 +34,12 @@ export interface ResolvedMarkerCluster {
 
 export interface ClusterMarkersOpts {
   config: ResolvedMarkerCluster;
+  /** Canvas-space y bounds (typically `0` / canvas height). When set, a
+   *  `"vertical"` column is additionally capped where the next glyph would
+   *  cross a bound, so a tall stack can't climb off the chart when its anchor
+   *  is already near the edge. The base slot always draws. */
+  minY?: number;
+  maxY?: number;
 }
 
 /** Glyph box used when `marker.size` is unset — mirrors `markerAtlas.DEFAULT_ICON_SIZE`. */
@@ -131,9 +140,28 @@ function layoutBucket(
     // AWAY from the line in the side direction (above → up, below → down,
     // center → up from the line). `j` runs in time order, so the newest sits
     // furthest out — and, drawn last in array order, paints over the one below it.
+    //
+    // `maxVisible` caps the column: the oldest glyphs keep their slots and the
+    // newest overflow is simply hidden.
     const dir = side === "below" ? 1 : -1;
+    let cap = opts.config.maxVisible;
+    // Bounds clamp: slot j sits at `base + dir * j * step`; keep only slots
+    // whose glyph box stays inside [minY, maxY].
+    if (opts.minY !== undefined && opts.maxY !== undefined && step > 0) {
+      const base = anchorY + sideDy;
+      const room = dir === -1 ? base - h / 2 - opts.minY : opts.maxY - h / 2 - base;
+      const fit = 1 + Math.floor(room / step);
+      if (fit < cap) cap = Math.max(1, fit);
+    }
     for (let j = 0; j < count; j++) {
       const p = proj[idx[s + j]];
+      if (j >= cap) {
+        p.hidden = true;
+        p.isGrouped = false;
+        p.groupCount = 0;
+        p.groupRep = -1;
+        continue;
+      }
       p.x = anchorX;
       p.y = anchorY + sideDy + dir * j * step;
       p.hidden = false;