react-native-livechart 3.12.0 → 4.1.0

package/src/core/resolveConfig.ts

@@ -14,6 +14,7 @@ import type {
   LineStyleConfig,
   LiveChartMetrics,
   LiveChartMetricsOverride,
+  MarkerClusterConfig,
   DotConfig,
   DotRingConfig,
   MultiSeriesDotConfig,
@@ -28,12 +29,15 @@ import type {
   ThresholdLineConfig,
   TradeEvent,
   ValueLineConfig,
+  VolumeConfig,
   XAxisConfig,
   YAxisConfig,
+  ZoomConfig,
 } from "../types";
 
 import type { ComponentType, ReactElement } from "react";
 import type { SharedValue } from "react-native-reanimated";
+import type { ResolvedMarkerCluster } from "../math/markerCluster";
 import {
   BADGE_METRICS_DEFAULTS,
   CANDLE_METRICS_DEFAULTS,
@@ -57,10 +61,41 @@ export interface ResolvedBadgeConfig {
   tail: boolean;
   position: "right" | "left";
   background: string | undefined;
+  /** undefined → capsule (pillHeight / 2) at render time */
+  radius: number | undefined;
+  /** undefined → no border */
+  borderColor: string | undefined;
+  borderWidth: number;
+  /** undefined → variant/theme text color at render time */
+  textColor: string | undefined;
+  fontSize: number | undefined;
+  fontFamily: string | undefined;
+  fontWeight: FontWeight | undefined;
+  offsetX: number;
+  offsetY: number;
+  /** Track the visible window's right-edge price while scrolled back. */
+  followViewEdge: boolean;
 }
 
 export interface ResolvedYAxisConfig {
   minGap: number;
+  /** Fixed label count (≥ 2), or 0 for the dynamic nice-interval grid. */
+  count: number;
+  /** Float the axis over a full-width plot (no reserved right gutter). */
+  float: boolean;
+}
+
+export interface ResolvedVolumeConfig {
+  /** undefined → use palette.candleUp at render time. */
+  upColor: string | undefined;
+  /** undefined → use palette.candleDown at render time. */
+  downColor: string | undefined;
+  /** Reserved band height (px) — the tallest a bar can be. */
+  maxHeight: number;
+  /** Corner radius (px) of bar tops. */
+  radius: number;
+  /** Opacity (0..1) applied to the whole band. */
+  opacity: number;
 }
 
 /** Resolved straight-line styling (connector, etc.). `color: undefined` → caller default. */
@@ -119,7 +154,7 @@ export interface ResolvedScrubConfig {
   /** Tooltip pill corner radius in px. */
   tooltipBorderRadius: number;
   /** Where the tooltip pill sits relative to the scrub line. */
-  tooltipPlacement: "side" | "top" | "bottom";
+  tooltipPlacement: "side" | "top" | "bottom" | "point";
   /** Gap (px) between the tooltip and the plot edge it's pinned to. */
   tooltipMargin: number;
   /** Show the value row in the default tooltip body. */
@@ -146,6 +181,8 @@ export interface ResolvedScrubActionConfig {
   /** undefined → no rounding */
   snap: number | undefined;
   dismissOnTapOutside: boolean;
+  /** Clear the reticle once the action badge fires onScrubAction. */
+  dismissOnAction: boolean;
 }
 
 export interface ResolvedGradientConfig {
@@ -336,6 +373,16 @@ const BADGE_DEFAULTS: ResolvedBadgeConfig = {
   tail: true,
   position: "right",
   background: undefined,
+  radius: undefined,
+  borderColor: undefined,
+  borderWidth: 1,
+  textColor: undefined,
+  fontSize: undefined,
+  fontFamily: undefined,
+  fontWeight: undefined,
+  offsetX: 0,
+  offsetY: 0,
+  followViewEdge: false,
 };
 
 /**
@@ -350,16 +397,63 @@ export function resolveBadge(
 
 const Y_AXIS_DEFAULTS: ResolvedYAxisConfig = {
   minGap: 36,
+  count: 0,
+  float: false,
 };
 
 /**
  * Resolves `yAxis` prop to a fully-typed config or null (disabled).
  * `true` → defaults, object → merged with defaults, falsy → null.
+ * `count` is normalized to a non-negative integer (the grid math clamps the
+ * upper bound to the label pool size).
  */
 export function resolveYAxis(
   prop: boolean | YAxisConfig | undefined,
 ): ResolvedYAxisConfig | null {
-  return resolveToggle(prop, Y_AXIS_DEFAULTS, false);
+  const resolved = resolveToggle(prop, Y_AXIS_DEFAULTS, false);
+  if (resolved === null) return null;
+  return { ...resolved, count: Math.max(0, Math.floor(resolved.count)) };
+}
+
+const VOLUME_DEFAULTS: ResolvedVolumeConfig = {
+  upColor: undefined,
+  downColor: undefined,
+  maxHeight: 48,
+  radius: 2,
+  opacity: 0.6,
+};
+
+/**
+ * Resolves the `volume` prop to a fully-typed config or null (disabled).
+ * `true` → defaults, object → merged with defaults, falsy → null. Colors left
+ * `undefined` fall back to the candle palette at render time.
+ */
+export function resolveVolume(
+  prop: boolean | VolumeConfig | undefined,
+): ResolvedVolumeConfig | null {
+  return resolveToggle(prop, VOLUME_DEFAULTS, false);
+}
+
+export interface ResolvedZoomConfig {
+  /** Tightest window (max zoom-in), seconds. `undefined` → `timeWindow / 8`. */
+  minTimeWindow: number | undefined;
+  /** Widest window (max zoom-out), seconds. `undefined` → full data span. */
+  maxTimeWindow: number | undefined;
+}
+
+const ZOOM_DEFAULTS: ResolvedZoomConfig = {
+  minTimeWindow: undefined,
+  maxTimeWindow: undefined,
+};
+
+/**
+ * Resolves the `zoom` prop to a config or null (disabled). `true` → defaults
+ * (bounds derived at gesture time), object → merged, falsy → null.
+ */
+export function resolveZoom(
+  prop: boolean | ZoomConfig | undefined,
+): ResolvedZoomConfig | null {
+  return resolveToggle(prop, ZOOM_DEFAULTS, false);
 }
 
 const AXIS_LABEL_DEFAULTS: ResolvedAxisLabelConfig = {
@@ -484,6 +578,7 @@ const SCRUB_ACTION_DEFAULTS: ResolvedScrubActionConfig = {
   timeBadge: false,
   snap: undefined,
   dismissOnTapOutside: false,
+  dismissOnAction: false,
 };
 
 /**
@@ -496,6 +591,42 @@ export function resolveScrubAction(
   return resolveToggle(prop, SCRUB_ACTION_DEFAULTS, false);
 }
 
+/** Spacing + collapse-threshold defaults for `markerCluster: "stacked"`. */
+const MARKER_CLUSTER_GAP = 2;
+const MARKER_CLUSTER_MAX_BEFORE_GROUP = 5;
+const MARKER_CLUSTER_OVERLAP = 0.75;
+
+/**
+ * Resolves the `markerCluster` prop (a `"anchored"`/`"stacked"` shorthand or a
+ * {@link MarkerClusterConfig} object) to a full config. Always returns a config
+ * (never null) — `"anchored"` (the default) is a valid mode the cluster pass
+ * treats as "side offsets only, no bucketing". The object form implies
+ * `"stacked"` unless `mode` is set.
+ */
+export function resolveMarkerCluster(
+  prop: "anchored" | "stacked" | MarkerClusterConfig | undefined,
+): ResolvedMarkerCluster {
+  if (typeof prop === "object") {
+    return {
+      mode: prop.mode ?? "stacked",
+      overlap: clamp01(prop.overlap ?? MARKER_CLUSTER_OVERLAP),
+      gap: MARKER_CLUSTER_GAP,
+      maxBeforeGroup: prop.maxBeforeGroup ?? MARKER_CLUSTER_MAX_BEFORE_GROUP,
+    };
+  }
+  return {
+    mode: prop === "stacked" ? "stacked" : "anchored",
+    overlap: MARKER_CLUSTER_OVERLAP,
+    gap: MARKER_CLUSTER_GAP,
+    maxBeforeGroup: MARKER_CLUSTER_MAX_BEFORE_GROUP,
+  };
+}
+
+/** Clamp to [0, 0.95] so a glyph never fully covers its neighbor (overlap 1). */
+function clamp01(v: number): number {
+  return v < 0 ? 0 : v > 0.95 ? 0.95 : v;
+}
+
 const GRADIENT_DEFAULTS: ResolvedGradientConfig = {
   topOpacity: undefined,
   bottomOpacity: undefined,

package/src/core/useLiveChartEngine.ts

@@ -5,7 +5,7 @@
  *
  * @see https://github.com/benjitaylor/liveline
  */
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import {
   useAnimatedReaction,
   useDerivedValue,
@@ -27,6 +27,13 @@ export interface EngineConfig {
   exaggerate?: boolean;
   referenceValue?: number;
   referenceValues?: number[];
+  /**
+   * Live, per-frame Y values to fold into the axis-range fit on top of the static
+   * {@link referenceValues} — used so a *dragging* reference line expands the range
+   * and the axis follows the finger smoothly (the committed values already sit in
+   * `referenceValues`). Read on the UI thread each frame; omit for non-draggable charts.
+   */
+  liveReferenceValues?: SharedValue<number[]>;
   nonNegative?: boolean;
   maxValue?: number;
   nowOverride?: number;
@@ -50,12 +57,14 @@ export interface ChartEngineLayout {
   /** Animating window (lerps toward {@link timeWindow}); use for positioning. */
   displayWindow: SharedValue<number>;
   /**
-   * The target window from props — the exact value `displayWindow` eases toward.
-   * Tick *selection* (which X-axis labels exist) must read this, not
-   * `displayWindow`: the lerp is asymptotic and never reaches the target, so it
-   * settles just above or just below it depending on the prior window. Bucketing
-   * that off-by-epsilon value (e.g. via `niceTimeInterval`) would otherwise make
-   * the tick cadence depend on where you came from. See issue #126.
+   * The *effective* target window — the value `displayWindow` eases toward: the
+   * pinch-zoom override ({@link ChartEngineScroll.viewWindow}) when active, else
+   * the `timeWindow` prop. Tick *selection* (which X-axis labels exist) must read
+   * this, not `displayWindow`: the lerp is asymptotic and never reaches the
+   * target, so it settles just above or just below it depending on the prior
+   * window. Bucketing that off-by-epsilon value (e.g. via `niceTimeInterval`)
+   * would otherwise make the tick cadence depend on where you came from. See
+   * issue #126.
    */
   timeWindow: SharedValue<number>;
   canvasWidth: SharedValue<number>;
@@ -76,6 +85,42 @@ export interface ChartEngineExtrema {
   extremaMaxTime: SharedValue<number>;
 }
 
+/**
+ * Time-scroll state: lets a pan gesture freeze the window at an absolute time
+ * and resume following the live edge. Returned by both engines (intersected onto
+ * the state) but kept off {@link ChartEngineLayout} so overlay components — which
+ * only read the layout — don't have to carry it.
+ */
+export interface ChartEngineScroll {
+  /**
+   * Absolute right-edge time (unix seconds) to freeze at, or `null` to follow
+   * the live edge. Written by the pan-scroll gesture; read by the engine tick.
+   */
+  viewEnd: SharedValue<number | null>;
+  /**
+   * The right-edge time the engine would use if following live — advances each
+   * frame even while {@link ChartEngineLayout.timestamp} is frozen by a pan.
+   */
+  liveEdge: SharedValue<number>;
+  /**
+   * Absolute visible-window width (seconds) to freeze at, or `null` to follow
+   * the configured `timeWindow`. Written by the pinch-zoom gesture; the
+   * symmetric counterpart of {@link viewEnd} (width vs. right edge). Folded into
+   * {@link ChartEngineLayout.timeWindow}, so downstream selection/positioning
+   * picks up the zoom for free.
+   */
+  viewWindow: SharedValue<number | null>;
+}
+
+/** Single-series only: smoothed price at the visible window's right edge. */
+export interface ChartEngineEdge {
+  /**
+   * Smoothed value at the window's right edge — the live value while following,
+   * the price at `viewEnd` while scrolled back. For a `followViewEdge` badge.
+   */
+  edgeValue: SharedValue<number>;
+}
+
 export interface SingleEngineState extends ChartEngineLayout, ChartEngineExtrema {
   data: SharedValue<LiveChartPoint[]>;
   value: SharedValue<number>;
@@ -119,6 +164,14 @@ export interface EngineFrameRefs {
   nowOverrideSV?: SharedValue<number | undefined>;
   windowBufferSV?: SharedValue<number>;
   pausedSV: SharedValue<boolean>;
+  /** Pan-scroll right-edge override (null = follow live). Optional for callers/tests. */
+  viewEndSV?: SharedValue<number | null>;
+  /** Pinch-zoom window-width override (null = follow timeWindow). Optional for callers/tests. */
+  viewWindowSV?: SharedValue<number | null>;
+  /** Receives the computed live edge each frame. Optional for callers/tests. */
+  liveEdgeSV?: SharedValue<number>;
+  /** Receives the smoothed right-edge value each frame. Optional for callers/tests. */
+  edgeValueSV?: SharedValue<number>;
   modeSV: SharedValue<"line" | "candle">;
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
@@ -144,6 +197,8 @@ export function applyLiveChartEngineFrame(
     displayMax: sv.displayMax.value,
     displayWindow: sv.displayWindow.value,
     timestamp: sv.timestamp.value,
+    liveEdge: sv.liveEdgeSV?.value ?? 0,
+    edgeValue: sv.edgeValueSV?.value ?? 0,
     extremaMinValue: sv.extremaMinValue.value,
     extremaMaxValue: sv.extremaMaxValue.value,
     extremaMinTime: sv.extremaMinTime.value,
@@ -167,6 +222,8 @@ export function applyLiveChartEngineFrame(
     points: sv.data.value,
     nowSeconds: Date.now() / 1000,
     paused: sv.pausedSV.value,
+    viewEnd: sv.viewEndSV?.value,
+    viewWindow: sv.viewWindowSV?.value,
     mode: sv.modeSV.value,
     candles: sv.candles?.value,
     liveCandle: sv.liveCandle?.value,
@@ -176,15 +233,34 @@ export function applyLiveChartEngineFrame(
   sv.displayMax.value = state.displayMax;
   sv.displayWindow.value = state.displayWindow;
   sv.timestamp.value = state.timestamp;
+  if (sv.liveEdgeSV) sv.liveEdgeSV.value = state.liveEdge;
+  if (sv.edgeValueSV) sv.edgeValueSV.value = state.edgeValue;
   sv.extremaMinValue.value = state.extremaMinValue;
   sv.extremaMaxValue.value = state.extremaMaxValue;
   sv.extremaMinTime.value = state.extremaMinTime;
   sv.extremaMaxTime.value = state.extremaMaxTime;
 }
 
-export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
-  // Low-frequency config → UI thread via useDerivedValue
-  const timeWindow = useDerivedValue(() => config.timeWindow);
+export function useLiveChartEngine(
+  config: EngineConfig,
+): SingleEngineState & ChartEngineScroll & ChartEngineEdge {
+  // Pinch-zoom window-width override (null = follow the configured window).
+  // Declared first so `timeWindow` below can fold it in. Defaults to null so
+  // charts without `zoom` behave exactly as before.
+  const viewWindow = useSharedValue<number | null>(null);
+  // A change to the `timeWindow` prop (a range / timeframe selector) is an explicit
+  // request to set the window, so it clears any active pinch-zoom override —
+  // otherwise the override below (`viewWindow ?? config.timeWindow`) would shadow
+  // the new prop forever, and prop-driven window changes would silently no-op.
+  useEffect(() => {
+    viewWindow.set(null);
+  }, [config.timeWindow, viewWindow]);
+
+  // Low-frequency config → UI thread via useDerivedValue. `timeWindow` is the
+  // *effective* target window: the zoom override when set, else the prop. Both
+  // the tick's window lerp and the X-axis tick selection read it, so zoom flows
+  // downstream for free (mirrors how viewEnd drives `timestamp`).
+  const timeWindow = useDerivedValue(() => viewWindow.value ?? config.timeWindow);
   // Static charts snap to their target in one tick (smoothing=1), so the single
   // settle reaction below produces the final state with no per-frame easing.
   const smoothing = useDerivedValue(() =>
@@ -193,7 +269,15 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   const adaptiveSpeedBoostSV = useDerivedValue(() => config.adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
   const referenceValue = useDerivedValue(() => config.referenceValue);
-  const referenceValues = useDerivedValue(() => config.referenceValues);
+  // Captured directly (not via `config.`) so Reanimated tracks the SharedValue and
+  // the merge re-runs each frame while a line is dragged; stable when idle.
+  const liveReferenceValuesSV = config.liveReferenceValues;
+  const referenceValues = useDerivedValue(() => {
+    const base = config.referenceValues;
+    const live = liveReferenceValuesSV?.value;
+    if (!live || live.length === 0) return base;
+    return base && base.length > 0 ? base.concat(live) : live;
+  });
   const nonNegativeSV = useDerivedValue(() => config.nonNegative ?? false);
   const maxValueSV = useDerivedValue(() => config.maxValue);
   const nowOverrideSV = useDerivedValue(() => config.nowOverride);
@@ -212,6 +296,14 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   const [initialTimestamp] = useState(() => Date.now() / 1000);
   const timestamp = useSharedValue(initialTimestamp);
 
+  // Pan-scroll state. `viewEnd` null = follow live; a number freezes the right
+  // edge at that absolute time. `liveEdge` mirrors the would-be-live timestamp
+  // each frame so the gesture can clamp / detect catch-up. Both default to
+  // "following" so charts without `timeScroll` behave exactly as before.
+  const viewEnd = useSharedValue<number | null>(null);
+  const liveEdge = useSharedValue(initialTimestamp);
+  const edgeValue = useSharedValue(0);
+
   // Live data extrema (value + time of the visible high / low). NaN until the
   // first tick finds data — the extrema label stays hidden until then.
   const extremaMinValue = useSharedValue(NaN);
@@ -250,6 +342,10 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
     nowOverrideSV,
     windowBufferSV,
     pausedSV,
+    viewEndSV: viewEnd,
+    viewWindowSV: viewWindow,
+    liveEdgeSV: liveEdge,
+    edgeValueSV: edgeValue,
     modeSV,
     candles,
     liveCandle,
@@ -307,6 +403,10 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
     canvasWidth,
     canvasHeight,
     timestamp,
+    viewEnd,
+    viewWindow,
+    liveEdge,
+    edgeValue,
     extremaMinValue,
     extremaMaxValue,
     extremaMinTime,

package/src/core/useLiveChartSeriesEngine.ts

@@ -8,7 +8,7 @@ import {
 import { MS_PER_FRAME_60FPS } from "../constants";
 import type { LiveChartPoint, SeriesConfig } from "../types";
 import { tickLiveChartSeriesEngineFrame } from "./liveChartSeriesEngineTick";
-import type { MultiEngineState } from "./useLiveChartEngine";
+import type { ChartEngineScroll, MultiEngineState } from "./useLiveChartEngine";
 
 export interface MultiSeriesEngineConfig {
   series: SharedValue<SeriesConfig[]>;
@@ -47,6 +47,12 @@ export interface MultiEngineFrameRefs {
   nowOverrideSV?: SharedValue<number | undefined>;
   windowBufferSV?: SharedValue<number>;
   pausedSV: SharedValue<boolean>;
+  /** Pan-scroll right-edge override (null = follow live). Optional for callers/tests. */
+  viewEndSV?: SharedValue<number | null>;
+  /** Pinch-zoom window-width override (null = follow timeWindow). Optional for callers/tests. */
+  viewWindowSV?: SharedValue<number | null>;
+  /** Receives the computed live edge each frame. Optional for callers/tests. */
+  liveEdgeSV?: SharedValue<number>;
   extremaMinValue: SharedValue<number>;
   extremaMaxValue: SharedValue<number>;
   extremaMinTime: SharedValue<number>;
@@ -105,6 +111,7 @@ export function applyLiveChartSeriesEngineFrame(
     displayMax: sv.displayMax.value,
     displayWindow: sv.displayWindow.value,
     timestamp: sv.timestamp.value,
+    liveEdge: sv.liveEdgeSV?.value ?? 0,
     displayValues,
     opacities,
     extremaMinValue: sv.extremaMinValue.value,
@@ -129,11 +136,14 @@ export function applyLiveChartSeriesEngineFrame(
     series: seriesSnap,
     nowSeconds: Date.now() / 1000,
     paused: sv.pausedSV.value,
+    viewEnd: sv.viewEndSV?.value,
+    viewWindow: sv.viewWindowSV?.value,
   });
   sv.displayMin.value = state.displayMin;
   sv.displayMax.value = state.displayMax;
   sv.displayWindow.value = state.displayWindow;
   sv.timestamp.value = state.timestamp;
+  if (sv.liveEdgeSV) sv.liveEdgeSV.value = state.liveEdge;
   sv.displaySeriesValues.value = state.displayValues;
   sv.seriesOpacities.value = state.opacities;
   sv.extremaMinValue.value = state.extremaMinValue;
@@ -148,8 +158,11 @@ export function applyLiveChartSeriesEngineFrame(
  */
 export function useLiveChartSeriesEngine(
   config: MultiSeriesEngineConfig,
-): MultiEngineState {
-  const timeWindow = useDerivedValue(() => config.timeWindow);
+): MultiEngineState & ChartEngineScroll {
+  // Pinch-zoom window-width override (null = follow the configured window).
+  // Declared first so `timeWindow` folds it in — see useLiveChartEngine.
+  const viewWindow = useSharedValue<number | null>(null);
+  const timeWindow = useDerivedValue(() => viewWindow.value ?? config.timeWindow);
   const smoothing = useDerivedValue(() => config.smoothing);
   const adaptiveSpeedBoostSV = useDerivedValue(() => config.adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
@@ -170,6 +183,10 @@ export function useLiveChartSeriesEngine(
   const [initialTimestamp] = useState(() => Date.now() / 1000);
   const timestamp = useSharedValue(initialTimestamp);
 
+  // Pan-scroll state (see useLiveChartEngine). Defaults to following live.
+  const viewEnd = useSharedValue<number | null>(null);
+  const liveEdge = useSharedValue(initialTimestamp);
+
   const displaySeriesValues = useSharedValue<number[]>([]);
   const seriesOpacities = useSharedValue<number[]>([]);
 
@@ -217,6 +234,9 @@ export function useLiveChartSeriesEngine(
         nowOverrideSV,
         windowBufferSV,
         pausedSV,
+        viewEndSV: viewEnd,
+        viewWindowSV: viewWindow,
+        liveEdgeSV: liveEdge,
         extremaMinValue,
         extremaMaxValue,
         extremaMinTime,
@@ -237,6 +257,9 @@ export function useLiveChartSeriesEngine(
     canvasWidth,
     canvasHeight,
     timestamp,
+    viewEnd,
+    viewWindow,
+    liveEdge,
     series,
     displaySeriesValues,
     seriesOpacities,

package/src/draw/grid.ts

@@ -1,4 +1,4 @@
-import { GRID_METRICS_DEFAULTS } from "../constants";
+import { GRID_METRICS_DEFAULTS, MAX_Y_LABELS } from "../constants";
 import { lerp } from "../math/lerp";
 import type { GridMetrics } from "../types";
 
@@ -8,6 +8,43 @@ export interface YAxisEntry {
   alpha: number;
 }
 
+/**
+ * Fixed-count Y-axis: place exactly `count` price labels evenly **in pixels**
+ * across the plot band — top = `displayMax`, bottom = `displayMin`. Values track
+ * the live range each frame (no nice-number rounding), so the label count stays
+ * constant while data streams in.
+ *
+ * `minGap` is a floor: the count drops to what fits when the plot is too short
+ * to space `count` labels at least `minGap` px apart. Clamped to
+ * `[2, MAX_Y_LABELS]`. Every entry is fully opaque — there's no per-line fade
+ * because the count (and thus each line's pixel slot) doesn't change.
+ */
+export function fixedGridEntries(
+  displayMax: number,
+  valRange: number,
+  chartH: number,
+  padTop: number,
+  count: number,
+  minGap: number,
+  formatValue: (v: number) => string,
+): YAxisEntry[] {
+  "worklet";
+  // minGap floor: at most `floor(chartH / minGap)` gaps fit ⇒ that many + 1 labels.
+  const maxFit = Math.floor(chartH / minGap) + 1;
+  let n = Math.min(count, maxFit, MAX_Y_LABELS);
+  if (n < 2) n = 2;
+
+  const stepPx = chartH / (n - 1);
+  const stepVal = valRange / (n - 1);
+  const entries: YAxisEntry[] = [];
+  for (let i = 0; i < n; i++) {
+    const y = padTop + i * stepPx;
+    const val = displayMax - i * stepVal;
+    entries.push({ y, label: formatValue(val), alpha: 1 });
+  }
+  return entries;
+}
+
 /**
  * Pick a nice Y-axis interval using TradingView's cycling divisor approach.
  * Hysteresis: once chosen, sticks until pixel spacing falls outside [0.5x, 4x] of minGap.
@@ -94,6 +131,7 @@ export function computeGridEntries(
   dt: number,
   minGap = 36,
   grid: GridMetrics = GRID_METRICS_DEFAULTS,
+  count = 0,
 ): { entries: YAxisEntry[]; interval: number } {
   "worklet";
   const chartH = canvasHeight - padTop - padBottom;
@@ -102,6 +140,25 @@ export function computeGridEntries(
   const valRange = displayMax - displayMin;
   if (valRange <= 0) return { entries: [], interval: prevInterval };
 
+  // Fixed-count mode bypasses nice-interval picking and per-line fading. Leave
+  // `prevInterval`/`labelAlphas` untouched so toggling back to the dynamic grid
+  // resumes cleanly. Needs at least 2 labels (a high/low pair) to be meaningful;
+  // count of 0 or 1 falls through to the dynamic nice-interval grid.
+  if (count >= 2) {
+    return {
+      entries: fixedGridEntries(
+        displayMax,
+        valRange,
+        chartH,
+        padTop,
+        count,
+        minGap,
+        formatValue,
+      ),
+      interval: prevInterval,
+    };
+  }
+
   const pxPerUnit = chartH / valRange;
 
   const coarse = pickInterval(valRange, pxPerUnit, minGap, prevInterval);
@@ -114,7 +171,19 @@ export function computeGridEntries(
   // Phase 1: compute target alpha for every grid line
   const targets: Record<number, number> = {};
   const first = Math.ceil(displayMin / fine) * fine;
-  for (let val = first; val <= displayMax; val += fine) {
+  // Guard against a non-advancing loop. On a near-flat (but not bit-identical)
+  // range, `fine` can drop below ulp(val), so `val += fine === val` and the loop
+  // never terminates — freezing the UI thread, since this runs in a worklet every
+  // frame. `stepResolves` skips the degenerate range (also catches fine === 0);
+  // MAX_GRID_LINES is a hard backstop in case the step stalls mid-loop (real
+  // grids only have a handful of lines, so it never bites normal data).
+  const stepResolves = first + fine !== first;
+  const MAX_GRID_LINES = 1000;
+  for (
+    let val = first, lineCount = 0;
+    stepResolves && val <= displayMax && lineCount < MAX_GRID_LINES;
+    val += fine, lineCount++
+  ) {
     const y = gridValueToY(val, displayMax, valRange, padTop, chartH);
     /* istanbul ignore next -- y stays in chart band for v in [first, displayMax] with consistent toY */
     if (y < padTop - 2 || y > canvasHeight - padBottom + 2) continue;