react-native-livechart 3.12.0 → 4.0.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,39 @@ 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;
+  /** 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 +152,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. */
@@ -336,6 +369,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,6 +393,7 @@ export function resolveBadge(
 
 const Y_AXIS_DEFAULTS: ResolvedYAxisConfig = {
   minGap: 36,
+  float: false,
 };
 
 /**
@@ -362,6 +406,47 @@ export function resolveYAxis(
   return resolveToggle(prop, Y_AXIS_DEFAULTS, false);
 }
 
+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 = {
   format: undefined,
   color: undefined,
@@ -496,6 +581,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

@@ -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,27 @@ 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);
+
+  // 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 +262,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 +289,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 +335,10 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
     nowOverrideSV,
     windowBufferSV,
     pausedSV,
+    viewEndSV: viewEnd,
+    viewWindowSV: viewWindow,
+    liveEdgeSV: liveEdge,
+    edgeValueSV: edgeValue,
     modeSV,
     candles,
     liveCandle,
@@ -307,6 +396,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

@@ -114,7 +114,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;

package/src/draw/markerAtlas.ts

@@ -21,11 +21,42 @@ const PILL_TEXT_COLOR = "#ffffff";
 /** Anti-alias breathing room baked around every cell so sprites don't clip. */
 const CELL_MARGIN = 2;
 
-/** Default glyph color per kind when `marker.color` is unset. */
+/** Glyphs composed into a collapsed-cluster count badge (digits only; capped "99"). */
+const GROUP_CHARS = "0123456789";
+/** Padding (px) between the digits and the inner circle edge. */
+const BADGE_PAD = 2;
+/** Background-colored halo ring around the badge — matches the icon-pill border. */
+const BADGE_BORDER = 2;
+/** Count-badge digits render at this fraction of the chart font, so two digits fit
+ *  a small round badge. Shared with the overlay's per-frame digit layout. */
+export const BADGE_TEXT_SCALE = 0.75;
+
+/** Atlas cell sig for one count-badge glyph (`0`-`9`), drawn white. */
+export function groupGlyphSig(ch: string): string {
+  "worklet";
+  return `gd\x1f${ch}`;
+}
+
+/** Atlas cell sig for the round count-badge background (one fixed circle per color). */
+export function groupBgSig(color: string): string {
+  "worklet";
+  return `gbg\x1f${color}`;
+}
+
+/** Text shown in a collapsed-cluster count badge — exact up to `"99"`, capped there
+ *  so it always fits the fixed round badge (≤ 2 digits). */
+export function groupCountText(count: number): string {
+  "worklet";
+  return count > 99 ? "99" : `${count}`;
+}
+
+/** Default glyph color per kind when `marker.color` is unset. Worklet-safe so the
+ *  per-frame overlay worklet can resolve a collapsed cluster's badge color. */
 export function defaultMarkerColor(
   kind: MarkerKind,
   palette: LiveChartPalette,
 ): string {
+  "worklet";
   switch (kind) {
     case "trade":
       return palette.line;
@@ -93,9 +124,13 @@ export interface MarkerAtlas {
    * hi-res cell back to its logical on-canvas size. See `buildMarkerAtlas`.
    */
   scale: number;
+  /** Logical ink width (px) of each count-badge digit `"0"`–`"9"`, for laying them
+   *  out proportionally (so narrow digits like `1` don't leave gaps). Empty when
+   *  the atlas carries no group cells (clustering off). */
+  digitWidths: Record<string, number>;
 }
 
-const EMPTY_ATLAS: MarkerAtlas = { image: null, cells: {}, scale: 1 };
+const EMPTY_ATLAS: MarkerAtlas = { image: null, cells: {}, scale: 1, digitWidths: {} };
 
 function fillPaint(color: string): SkPaint {
   const p = Skia.Paint();
@@ -260,6 +295,51 @@ function cellSpec(m: Marker, palette: LiveChartPalette, font: SkFont): CellSpec
   };
 }
 
+/** One count-badge glyph (`0`-`9` / `+`) in white, on a uniform-width box so the
+ *  digits lay out tabular. `uw`/`gh` are the shared logical glyph metrics. */
+function groupGlyphCellSpec(
+  ch: string,
+  uw: number,
+  gh: number,
+  font: SkFont,
+): CellSpec {
+  const b = font.measureText(ch);
+  const dx = b.x + b.width / 2;
+  const dy = b.y + b.height / 2;
+  const m2 = CELL_MARGIN * 2;
+  return {
+    w: uw + m2,
+    h: gh + m2,
+    draw: (canvas, cx, cy) =>
+      canvas.drawText(ch, cx - dx, cy - dy, fillPaint(PILL_TEXT_COLOR), font),
+  };
+}
+
+/** Round count-badge background — a single fixed-size circle (independent of digit
+ *  count) with a background-colored halo ring like the icon pills. Sized to fit the
+ *  scaled two-digit text, so the badge stays small, round, and never changes size.
+ *  `uw`/`gh` are the shared (full-size) glyph metrics; the text is drawn scaled. */
+function groupBgCellSpec(
+  color: string,
+  bgColor: string,
+  uw: number,
+  gh: number,
+): CellSpec {
+  const m2 = CELL_MARGIN * 2;
+  // Inner circle fits a centered two-digit string at BADGE_TEXT_SCALE plus padding.
+  const innerR = Math.ceil(Math.max(2 * uw, gh) * BADGE_TEXT_SCALE) / 2 + BADGE_PAD;
+  const outerR = innerR + BADGE_BORDER;
+  const diameter = 2 * outerR;
+  return {
+    w: diameter + m2,
+    h: diameter + m2,
+    draw: (canvas, cx, cy) => {
+      canvas.drawCircle(cx, cy, outerR, fillPaint(bgColor)); // halo ring
+      canvas.drawCircle(cx, cy, innerR, fillPaint(color)); // colored badge
+    },
+  };
+}
+
 /**
  * Rasterize every distinct marker appearance into a single packed atlas image,
  * once per appearance-set change (NOT per frame). The per-frame worklet then
@@ -279,6 +359,9 @@ export function buildMarkerAtlas(
   palette: LiveChartPalette,
   font: SkFont,
   scale = 1,
+  /** Also bake count-badge cells (digits + per-color backgrounds) for
+   *  `markerCluster: "stacked"` collapse. Off by default — no atlas bloat. */
+  withGroups = false,
 ): MarkerAtlas {
   const seen = new Set<string>();
   const specs: { sig: string; spec: CellSpec }[] = [];
@@ -290,6 +373,37 @@ export function buildMarkerAtlas(
     seen.add(sig);
     specs.push({ sig, spec: cellSpec(m, palette, font) });
   }
+
+  // Count-badge cells: 10 uniform white digit cells shared across colors, plus one
+  // fixed round background per cluster color. A collapsed group composes its number
+  // (centered, ≤ 2 digits) over the circle in the same `drawAtlas`.
+  const digitWidths: Record<string, number> = {};
+  if (withGroups && specs.length > 0) {
+    let uw = 1;
+    let gh = 1;
+    for (const ch of GROUP_CHARS) {
+      const b = font.measureText(ch);
+      digitWidths[ch] = Math.max(1, Math.ceil(b.width));
+      if (b.width > uw) uw = b.width;
+      if (b.height > gh) gh = b.height;
+    }
+    uw = Math.ceil(uw);
+    gh = Math.ceil(gh);
+    for (const ch of GROUP_CHARS) {
+      specs.push({ sig: groupGlyphSig(ch), spec: groupGlyphCellSpec(ch, uw, gh, font) });
+    }
+    const bgColor = `rgb(${palette.bgRgb[0]}, ${palette.bgRgb[1]}, ${palette.bgRgb[2]})`;
+    const colors = new Set<string>();
+    for (let i = 0; i < markers.length; i++) {
+      const m = markers[i];
+      if (isConnectorMarker(m)) continue;
+      colors.add(m.color ?? defaultMarkerColor(m.kind, palette));
+    }
+    for (const color of colors) {
+      specs.push({ sig: groupBgSig(color), spec: groupBgCellSpec(color, bgColor, uw, gh) });
+    }
+  }
+
   if (specs.length === 0) return EMPTY_ATLAS;
 
   let totalW = 0;
@@ -326,5 +440,5 @@ export function buildMarkerAtlas(
   }
   const picture = recorder.finishRecordingAsPicture();
   const image = drawAsImageFromPicture(picture, { width: texW, height: texH });
-  return { image, cells, scale };
+  return { image, cells, scale, digitWidths };
 }