react-native-livechart 3.12.0 → 4.0.0

package/src/types.ts

@@ -79,6 +79,15 @@ export interface ReferenceLine {
   strokeWidth?: number;
   /** Dash pattern as `[dashLength, gapLength]` in pixels (line stroke + band border). */
   intervals?: [number, number];
+  /**
+   * Span the **full chart width** — edge to edge through the Y-axis gutter, not
+   * clipped at the plot's right edge — so the line/band visually connects to its
+   * value on the axis (like a price tag). Only the line/band extends; any
+   * `label`/`badge` stays anchored inside the plot. For a Form-A line with a
+   * `badge`, the full-width line replaces the dashed connector. No effect on a
+   * vertical time band. Default `false` (stops at the plot edge). Form A / B.
+   */
+  fullWidth?: boolean;
   /** Line / band color override. Defaults to palette `refLine`. */
   color?: string;
   /** Fill opacity for a value / time band (0–1). Default `0.16`. */
@@ -126,6 +135,86 @@ export interface ReferenceLine {
   badgeBorderColor?: string;
   /** Badge pill corner radius in pixels. Default `5`. (Fallback for `badge.radius`.) */
   badgeRadius?: number;
+
+  // ── Draggable (Form A only) ───────────────────────────────────────────────
+  /**
+   * Make this Form-A line **draggable** along the Y-axis — grab its handle / badge
+   * and drag to set a new value (a working-order price, alert level, or target).
+   * The line tracks the finger on the UI thread; {@link onChange} / {@link onCommit}
+   * report the value to JS. The line is *uncontrolled* by default (it stays where
+   * you drop it); pair `onCommit` with writing the value back into `value` to make
+   * it controlled. No effect on bands / time bands. Default `false`.
+   */
+  draggable?: boolean;
+  /**
+   * Snap the dragged value to this increment (e.g. `0.01` for cents, `0.5` for a
+   * tick size) so drops land on round levels. Omit for free dragging. Applies only
+   * while {@link draggable}.
+   */
+  snap?: number;
+  /**
+   * Hard-clamp the draggable value to `[min, max]` in Y-axis units — the line
+   * can't be dragged past either end. Omit for unbounded (clamped only to the
+   * visible range). Reaching a bound fires {@link onDragOut}. Applies only while
+   * {@link draggable}.
+   */
+  bounds?: [number, number];
+  /**
+   * Fired on the JS thread *while* dragging, each time the (snapped, clamped)
+   * value changes. De-duplicated to value changes — not every frame. Form-A
+   * draggable only.
+   */
+  onChange?: (value: number) => void;
+  /**
+   * Fired once on the JS thread when the drag ends (finger up), with the final
+   * (snapped, clamped) value. Pair with a controlled `value` to persist the move.
+   * Form-A draggable only.
+   */
+  onCommit?: (value: number) => void;
+  /**
+   * Fired on the JS thread when the line's value crosses **into** its watched
+   * interval — the visible Y-range, or {@link bounds} when set. Triggers from
+   * dragging *or* the axis rescaling under a fixed value (e.g. a target scrolling
+   * back into view). Edge-triggered: once per crossing. Form-A only.
+   */
+  onDragIn?: (value: number) => void;
+  /**
+   * Fired on the JS thread when the line's value crosses **out of** its watched
+   * interval (the visible Y-range, or {@link bounds}) — dragged/scrolled off-screen
+   * or pinned at a bound. Edge-triggered: once per crossing. Form-A only.
+   */
+  onDragOut?: (value: number) => void;
+}
+
+/**
+ * Shared **style & shape** knobs for every badge pill — the value `badge`
+ * ({@link BadgeConfig}), reference-line badges ({@link ReferenceLineBadgeConfig}),
+ * and the grouping count pill. Each badge interface extends this and adds its own
+ * anchor (`position`) / content fields. Unset values fall back to that badge's own
+ * defaults (documented on each interface). One source of truth so every badge is
+ * configured identically.
+ */
+export interface BadgeStyleConfig {
+  /** Pill background color. */
+  background?: string;
+  /** Pill border color. */
+  borderColor?: string;
+  /** Border stroke width in pixels. Default `1`. */
+  borderWidth?: number;
+  /** Pill corner radius in pixels. */
+  radius?: number;
+  /** Label / icon text color override. */
+  textColor?: string;
+  /** Badge font size in pixels. Falls back to the chart `font`. */
+  fontSize?: number;
+  /** Badge font family. Falls back to the chart `font`. */
+  fontFamily?: string;
+  /** Badge font weight. Falls back to the chart `font`. */
+  fontWeight?: FontWeight;
+  /** Nudge the whole badge horizontally from its anchor, in pixels. Default `0`. */
+  offsetX?: number;
+  /** Nudge the whole badge vertically from its anchor, in pixels. Default `0`. */
+  offsetY?: number;
 }
 
 /**
@@ -133,10 +222,20 @@ export interface ReferenceLine {
  * price alert, or target tag. The badge sits at the line's value (pinned to
  * `position`) with a dashed connector to the opposite edge, and pins to the
  * nearest edge with a chevron once the value scrolls off-screen.
+ *
+ * Extends {@link BadgeStyleConfig} for the style/shape knobs. Their reference-line
+ * fallbacks: `background` → `badgeBackground` → theme `tooltipBg`; `borderColor` →
+ * `badgeBorderColor` → the line `color`; `radius` → `badgeRadius` → `5`; `textColor`
+ * → `labelColor` → the line `color` → theme `refLabel`; the `font*` knobs → the
+ * chart `font`.
  */
-export interface ReferenceLineBadgeConfig {
-  /** Which plot edge the badge pins to. Default `"left"`. */
-  position?: "left" | "right";
+export interface ReferenceLineBadgeConfig extends BadgeStyleConfig {
+  /**
+   * Where the badge pins horizontally. `"left"` / `"right"` pin to that plot edge
+   * with a dashed connector running to the opposite edge; `"center"` floats the
+   * pill centered in the plot at the line's value (no connector). Default `"left"`.
+   */
+  position?: "left" | "center" | "right";
   /**
    * Leading glyph drawn in the badge — rendered with the chart font, so pass an
    * emoji-capable font (via the chart `font` prop) for emoji. Like `Marker.icon`.
@@ -147,12 +246,71 @@ export interface ReferenceLineBadgeConfig {
    * Default `true`. Set `false` for an **icon-only** badge.
    */
   text?: boolean;
-  /** Pill background. Falls back to `badgeBackground`, then theme `tooltipBg`. */
-  background?: string;
-  /** Pill border color. Falls back to `badgeBorderColor`, then the line `color`. */
-  borderColor?: string;
-  /** Pill corner radius in pixels. Falls back to `badgeRadius`, then `5`. */
+}
+
+/**
+ * Context passed to a custom {@link LiveChartProps.renderReferenceLine}. The chart
+ * floats the element you return over the canvas and pins it to the line's value on
+ * the UI thread (vertically centered on the line, horizontally at the badge /
+ * label position) — so it tracks the rescaling axis and any drag smoothly without
+ * JS re-renders, just like {@link TooltipRenderProps}. Replaces the built-in pill
+ * badge / gutter label for that line; return `null`/`undefined` to keep the
+ * built-in. Bind the SharedValues to animated text (e.g. an animated `TextInput`)
+ * for the value to update on the UI thread too.
+ */
+export interface ReferenceLineRenderProps {
+  /** The reference line being rendered. */
+  line: ReferenceLine;
+  /** Its index in the `referenceLines` array. */
+  index: number;
+  /** Live Y-axis value of the line — tracks dragging when {@link ReferenceLine.draggable}. */
+  value: SharedValue<number>;
+  /** The value formatted with the chart's `formatValue` (computed UI-side). */
+  valueStr: SharedValue<string>;
+  /** Canvas Y pixel of the line, recomputed each frame (`-1` when not laid out). */
+  y: SharedValue<number>;
+  /** Whether the value currently sits within the visible plot range. */
+  inRange: SharedValue<boolean>;
+  /**
+   * Which visible edge the value is pinned to when off-screen: `"above"` (past the
+   * top), `"below"` (past the bottom), or `"in"`. Use it to flip a directional
+   * chevron on a custom off-axis handle.
+   */
+  edge: SharedValue<"above" | "in" | "below">;
+  /** Whether this line is currently being dragged. */
+  dragging: SharedValue<boolean>;
+}
+
+/**
+ * Grouping behavior for reference lines (single-series). When enabled, Form-A
+ * lines whose handles fall within {@link ReferenceLineGroupingConfig.radius} px of
+ * each other collapse into a single count handle, so a cluster of nearby orders /
+ * alerts reads as one tag instead of an unreadable pile. Pass `true` for defaults
+ * or an object to tune the proximity radius.
+ */
+export interface ReferenceLineGroupingConfig {
+  /**
+   * Collapse lines whose value-Y positions are within this many px of each other.
+   * Default `18`.
+   */
   radius?: number;
+  /**
+   * Styling for the collapsed **count pill** — the same style/shape config as a
+   * reference-line badge ({@link ReferenceLineBadgeConfig}): `position`
+   * (`"left"` / `"center"` / `"right"`), `icon` (a leading glyph before the count),
+   * `background`, `borderColor`, `borderWidth`, `radius` (corner radius),
+   * `textColor`, `fontSize` / `fontFamily` / `fontWeight`, and `offsetX` / `offsetY`.
+   * Omit for the theme defaults (left-pinned, `tooltipBg` fill, `refLine` border,
+   * `refLabel` text). The badge's `text: false` hides the count for an icon-only pill.
+   */
+  badge?: ReferenceLineBadgeConfig;
+  /**
+   * Format the collapsed count for the pill label, e.g. `n => \`×${n}\`` or
+   * `n => \`${n} orders\``. Default `String(n)` (the bare count). **Must be a
+   * worklet** (add the `"worklet"` directive) — it runs on the UI thread each
+   * frame, like the chart's `formatValue`. A plain JS closure throws.
+   */
+  format?: (count: number) => string;
 }
 
 /**
@@ -356,22 +514,67 @@ export interface AreaDotsConfig {
   opacity?: number;
 }
 
-/** Value badge pill configuration. */
-export interface BadgeConfig {
+/**
+ * Value badge pill configuration. Extends {@link BadgeStyleConfig} for the
+ * style/shape knobs (`background`, `borderColor` / `borderWidth`, `radius`,
+ * `textColor`, `font*`, `offsetX/Y`). Value-badge specifics: `radius` defaults to a
+ * full capsule (clamped to `[0, pillHeight / 2]`); `borderColor` unset → no border;
+ * `textColor` unset → the `variant` / theme rule.
+ */
+export interface BadgeConfig extends BadgeStyleConfig {
   /** Visual style of the badge pill. Default `"default"`. */
   variant?: BadgeVariant;
   /** Show the pointed tail toward the live dot. Default `true`. */
   tail?: boolean;
-  /** Badge background color override. */
-  background?: string;
   /** Which side of the chart the badge appears on. Default `"right"`. */
   position?: "right" | "left";
+  /**
+   * When the chart is scrolled back (see `timeScroll`), move the live-price
+   * indicators — the badge, the value line, and the live dot — to the price at
+   * the visible window's right edge instead of the live price, so they track the
+   * last visible price as you pan. Default `false`.
+   *
+   * @experimental
+   */
+  followViewEdge?: boolean;
+}
+
+/**
+ * Volume-bar configuration (candle mode only — see {@link LiveChartProps.volume}).
+ * Bars are drawn in a reserved band below the candles; the candle/price plot
+ * shrinks by {@link maxHeight} to make room (the x-axis stays at the bottom).
+ * Each bar's height is its candle's `volume` normalized to the largest visible
+ * volume, so the tallest visible bar fills the band.
+ */
+export interface VolumeConfig {
+  /** Bar color for up (close ≥ open) candles. Default: `palette.candleUp`. */
+  upColor?: string;
+  /** Bar color for down (close < open) candles. Default: `palette.candleDown`. */
+  downColor?: string;
+  /**
+   * Height (px) of the reserved band — the tallest a bar can be. Reserved out of
+   * the plot below the candles. Default `48`.
+   */
+  maxHeight?: number;
+  /** Corner radius (px) of bar tops. `0` = sharp. Default `2`. */
+  radius?: number;
+  /** Opacity (0..1) applied to the whole band. Default `0.6`. */
+  opacity?: number;
 }
 
 /** Y-axis grid configuration. */
 export interface YAxisConfig {
   /** Minimum pixel gap between grid lines. Default `36`. */
   minGap?: number;
+  /**
+   * Float the price axis over a full-width plot instead of reserving a right
+   * gutter for it. The line/candles run all the way to the right edge, and the
+   * price labels (and the live-value badge) float on top — so the chart isn't
+   * cut off short of the edge, especially while time-scrolling. Default `false`.
+   *
+   * @experimental
+   */
+  float?: boolean;
 }
 
 /**
@@ -480,11 +683,13 @@ export interface ScrubConfig {
    * Where the tooltip pill sits relative to the vertical scrub line.
    * `"side"` (default) offsets it to the right of the line and flips left near
    * the right edge. `"top"` / `"bottom"` center it horizontally over the line,
-   * clamped into the plot and pinned to the plot's top or bottom. This also
-   * drives a custom {@link LiveChartProps.renderTooltip} so it gets the same
-   * placement for free.
+   * clamped into the plot and pinned to the plot's top or bottom. `"point"`
+   * centers it over the line and floats it just above the scrub dot, flipping
+   * below the dot when there isn't room above (single-series line mode; candle
+   * mode keeps its top-pinned OHLC stack). This also drives a custom
+   * {@link LiveChartProps.renderTooltip} so it gets the same placement for free.
    */
-  tooltipPlacement?: "side" | "top" | "bottom";
+  tooltipPlacement?: "side" | "top" | "bottom" | "point";
   /**
    * Gap in px between the tooltip and the plot edge it's pinned to — the top for
    * `"side"`/`"top"`, the bottom for `"bottom"`. Applies to the built-in pill and
@@ -626,6 +831,92 @@ export interface TooltipRenderProps {
   candle: SharedValue<CandlePoint | null>;
 }
 
+/** Inner plot rectangle in canvas pixels (a snapshot field of {@link ChartScale}). */
+export interface ChartPlotRect {
+  /** Inner plot left edge (`padding.left`). */
+  left: number;
+  /** Inner plot top edge (`padding.top`). */
+  top: number;
+  /** Inner plot right edge (`canvasWidth - padding.right`). */
+  right: number;
+  /** Inner plot bottom edge (`canvasHeight - padding.bottom`). */
+  bottom: number;
+  /** Full canvas width. */
+  width: number;
+  /** Full canvas height. */
+  height: number;
+}
+
+/**
+ * A snapshot of the chart's live scale — the value range, time window, and plot
+ * rect at one frame. Carried by {@link ChartOverlayContext.scale} (a `SharedValue`
+ * recomputed each frame) and consumed by the pure mapping functions. Reading
+ * `scale.get()` inside your worklet is what subscribes the overlay to per-frame
+ * updates, so it tracks the chart as it scrolls and rescales.
+ */
+export interface ChartScale {
+  /** Live Y-axis lower bound (price at the plot bottom). */
+  min: number;
+  /** Live Y-axis upper bound (price at the plot top). */
+  max: number;
+  /** Visible time window in seconds. */
+  window: number;
+  /** Right-edge timestamp (unix seconds) — "now". */
+  now: number;
+  /** Inner plot rectangle in canvas px. */
+  plot: ChartPlotRect;
+}
+
+/**
+ * The price↔pixel / time↔pixel bridge handed to a custom
+ * {@link LiveChartProps.renderOverlay}.
+ *
+ * **Easiest path — the `usePriceY` / `useTimeX` hooks.** They project a price / time
+ * to a `SharedValue<number>` that tracks the live axis for you; just read it in
+ * your `useAnimatedStyle` like any SharedValue:
+ *
+ * ```tsx
+ * function PriceLevel({ ctx, price }) {
+ *   const y = usePriceY(ctx, price); // reactive — tracks the rescaling axis
+ *   const style = useAnimatedStyle(() => ({ transform: [{ translateY: y.get() }] }));
+ *   return <Animated.View style={style} />;
+ * }
+ * ```
+ *
+ * **Manual path — {@link scale} + the pure mappings.** For one-off math (e.g. a
+ * gesture handler) or when you want everything in one worklet, read `scale.get()`
+ * inside your worklet — that read subscribes it to the per-frame scale — then pass
+ * the snapshot to the pure mappings (`priceToY` / `yToPrice` / `timeToX` /
+ * `xToTime`). The mappings do **not** read `scale` themselves, so they only reflect
+ * the chart live when you feed them `scale.get()`:
+ *
+ * ```tsx
+ * const style = useAnimatedStyle(() => {
+ *   const s = scale.get();          // subscribe to the live scale
+ *   const y = priceToY(142.5, s);   // project a price to its pixel
+ *   return { transform: [{ translateY: y }] };
+ * });
+ * ```
+ */
+export interface ChartOverlayContext {
+  /**
+   * The live {@link ChartScale} snapshot, recomputed each frame. Read `.get()`
+   * inside your worklet to subscribe it to chart updates.
+   */
+  scale: SharedValue<ChartScale>;
+  /** Maps a price (Y-axis value) → canvas Y px for a {@link ChartScale}. Worklet. -1 when not laid out. */
+  priceToY: (price: number, scale: ChartScale) => number;
+  /**
+   * Inverse of {@link priceToY}: canvas Y px → price. Worklet. Clamps to the
+   * visible range; `null` when not laid out.
+   */
+  yToPrice: (y: number, scale: ChartScale) => number | null;
+  /** Maps a unix-seconds timestamp → canvas X px for a {@link ChartScale}. Worklet. -1 when not laid out. */
+  timeToX: (time: number, scale: ChartScale) => number;
+  /** Inverse of {@link timeToX}: canvas X px → unix-seconds timestamp. Worklet. */
+  xToTime: (x: number, scale: ChartScale) => number;
+}
+
 /** Outer ring drawn around the built-in selection dot (the subtle halo). */
 export interface SelectionDotRingConfig {
   /** Ring color. Defaults to the dot color. */
@@ -783,14 +1074,60 @@ export interface Marker {
   pill?: boolean;
   /** Icon / image box size in px (icon font size or image width+height). Default `16`. */
   size?: number;
-  /** Pass-through payload surfaced on `onMarkerHover`. */
+  /**
+   * Sit the glyph above / below its anchor instead of centered on it. Default
+   * `"center"` (on the line/value, today's behavior). Also the stack direction
+   * when `markerCluster: "stacked"` — e.g. buys `"below"`, sells `"above"`.
+   */
+  side?: MarkerSide;
+  /** Pass-through payload surfaced on `onMarkerPress`. */
   data?: unknown;
 }
 
-/** Payload for `onMarkerHover` — the marker and its screen position. */
-export interface MarkerHoverEvent {
+/** Where a marker glyph sits relative to its anchor (and the stack direction). */
+export type MarkerSide = "above" | "below" | "center";
+
+/**
+ * Object form of {@link LiveChartProps.markerCluster} for tuning the stacked
+ * collision behavior. Passing this object implies `mode: "stacked"` unless you
+ * set `mode` explicitly.
+ */
+export interface MarkerClusterConfig {
+  /** Defaults to `"stacked"` when this object form is used. */
+  mode?: "anchored" | "stacked";
+  /**
+   * How much adjacent co-located glyphs overlap when fanned, `0` (just touching)
+   * to `1` (fully stacked). Default `0.75`. The on-screen overlap is approximate
+   * (the fan step is estimated from the glyph size, not its exact pixels).
+   */
+  overlap?: number;
+  /** Collapse a co-located run to a single count badge once it exceeds this many.
+   *  Default `5`. */
+  maxBeforeGroup?: number;
+}
+
+/** Context passed to `renderMarker` alongside the marker (cluster / position state). */
+export interface MarkerRenderContext {
+  /** Index of the marker in the `markers` array. */
+  index: number;
+  /** `true` when this marker is the representative of a collapsed cluster. */
+  isGrouped: boolean;
+  /** Number of markers in the collapsed cluster (`0` when not grouped). */
+  groupCount: number;
+  /** Resolved side the glyph is drawn on. */
+  side: MarkerSide;
+}
+
+/** Payload for `onMarkerPress` — the marker and its screen position. */
+export interface MarkerPressEvent {
   marker: Marker;
   point: { x: number; y: number };
+  /** Index of the pressed marker in the `markers` array. */
+  index: number;
+  /** `true` when the press landed on a collapsed cluster (count badge). */
+  isGrouped: boolean;
+  /** The cluster's markers when `isGrouped`, so the consumer can list them. */
+  members?: Marker[];
 }
 
 /** Particle burst + screen shake on momentum swings ("degen mode"). */
@@ -1001,6 +1338,13 @@ export interface CandlePoint {
   low: number;
   /** Closing price. */
   close: number;
+  /**
+   * Traded volume in the bucket. Drives the optional volume bars
+   * (see {@link LiveChartProps.volume}); bar heights are normalized to the
+   * largest visible volume, so only relative values matter. Omitted candles
+   * contribute no bar. Ignored when `volume` is off or in line mode.
+   */
+  volume?: number;
 }
 
 // ── Metrics (sizing & motion tokens) ─────────────────────────────────────────
@@ -1048,6 +1392,10 @@ export interface CandleMetrics {
   maxBodyPx: number;
   /** Body width as a fraction of the per-candle slot width (0–1). Default `0.8`. */
   bodyWidthRatio: number;
+  /** Corner radius (px) of candle bodies. `0` = sharp corners. Default `0`. */
+  bodyRadius: number;
+  /** Wick (high–low line) stroke width in px. Default `1`. */
+  wickWidth: number;
 }
 
 /** Grid-line and axis-label fade animation speeds. */
@@ -1091,6 +1439,61 @@ export interface LiveChartMetricsOverride {
 
 // ── Component Props ──────────────────────────────────────────────────────────
 
+/**
+ * Time-scroll activation (see {@link LiveChartCoreProps.timeScroll}).
+ *
+ * @experimental Prototype — gesture model and API may change.
+ */
+export interface TimeScrollConfig {
+  /**
+   * Which gesture pans the timeline:
+   *  - `"holdToScrub"` (default) — a one-finger drag anywhere scrolls; scrub
+   *    moves to press-and-hold (Rainbow-style). See {@link scrubHoldMs} for the
+   *    hold duration.
+   *  - `"axisDrag"` — a one-finger drag starting in the bottom X-axis band
+   *    ("grab the time ruler"); the plot area stays free for one-finger scrub.
+   */
+  gesture?: "holdToScrub" | "axisDrag";
+  /**
+   * `holdToScrub` only: press-and-hold duration (ms) before scrub engages, so a
+   * quicker one-finger drag scrolls instead. Higher = more deliberate scrub and
+   * fewer accidental scrubs while scrolling. Falls back to `scrub.panGestureDelay`
+   * if set, otherwise `500`.
+   */
+  scrubHoldMs?: number;
+}
+
+/**
+ * Pinch-to-zoom the visible time window (see {@link LiveChartCoreProps.zoom}).
+ *
+ * @experimental Prototype — gesture model and API may change.
+ */
+export interface ZoomConfig {
+  /**
+   * Tightest visible window in seconds (max zoom-in). Default `timeWindow / 8`.
+   */
+  minTimeWindow?: number;
+  /**
+   * Widest visible window in seconds (max zoom-out). Defaults to the full data
+   * span (you can zoom out to all retained history), never below `timeWindow`.
+   */
+  maxTimeWindow?: number;
+}
+
+/**
+ * The visible time range reported by {@link LiveChartCoreProps.onVisibleRangeChange}.
+ *
+ * @experimental
+ */
+export interface VisibleRange {
+  /** Left-edge time of the visible window (unix seconds). */
+  startSec: number;
+  /** Right-edge time of the visible window (unix seconds). */
+  endSec: number;
+  /** True when the window is at the live edge (not scrolled back / paused). */
+  following: boolean;
+}
+
 /** Props shared between `LiveChart` and `LiveChartSeries`. */
 export interface LiveChartCoreProps {
   /** Color scheme. Default `"dark"`. */
@@ -1168,9 +1571,19 @@ export interface LiveChartCoreProps {
    */
   markers?: SharedValue<Marker[]>;
   /** Fires when a marker is tapped; `null` when a tap misses every marker. */
-  onMarkerHover?: (event: MarkerHoverEvent | null) => void;
+  onMarkerPress?: (event: MarkerPressEvent | null) => void;
   /** Tap hit-test radius in px. Default `16` (≈ 44px touch target with the glyph). */
   markerHitRadius?: number;
+  /**
+   * Collision handling for co-located markers. `"anchored"` (default) keeps
+   * today's behavior — glyphs draw at their anchor and overlap. `"stacked"` fans
+   * co-located markers apart horizontally (overlapping, left-over-right) along
+   * their {@link Marker.side}, collapsing a cluster into a single count-badge
+   * marker once it exceeds {@link MarkerClusterConfig.maxBeforeGroup}. Grouping is
+   * recomputed per frame, so a cluster fans back out as you zoom/scroll in. Pass a
+   * {@link MarkerClusterConfig} object to tune the `overlap` and group threshold.
+   */
+  markerCluster?: "anchored" | "stacked" | MarkerClusterConfig;
   /**
    * Render a marker as a custom **React Native** element instead of a built-in
    * Skia glyph — e.g. an `expo-blur` glass badge or any non-Skia view that the
@@ -1183,8 +1596,15 @@ export interface LiveChartCoreProps {
    * each custom marker is its own animated view + projection, whereas built-in
    * glyphs batch into a single draw call. Custom-rendered markers skip the atlas
    * glyph entirely (no double-draw).
+   *
+   * The second argument carries cluster / position state (see
+   * {@link MarkerRenderContext}) — e.g. render a distinct collapsed look when
+   * `ctx.isGrouped` (showing `ctx.groupCount`).
    */
-  renderMarker?: (marker: Marker) => ReactElement | null | undefined;
+  renderMarker?: (
+    marker: Marker,
+    ctx: MarkerRenderContext,
+  ) => ReactElement | null | undefined;
   /**
    * Render a fully custom scrub tooltip as a **React Native** element instead of
    * the built-in pill — the same idea as `renderMarker`. The chart floats the
@@ -1226,6 +1646,31 @@ export interface LiveChartCoreProps {
    * and `timeWindow = maxT - minT` to fill the canvas edge-to-edge with historical data.
    */
   nowOverride?: number;
+  /**
+   * Enable horizontal time-scrolling: drag (or fling) to pan back through history.
+   * The chart stops auto-scrolling while panned and resumes once you reach the
+   * live edge again. One-finger plot-area scrub is unchanged. Requires retained
+   * history in `data` / `candles` to scroll into.
+   *
+   * `true` uses the default drag-to-scroll gesture (`"holdToScrub"`); pass a
+   * {@link TimeScrollConfig} to pick the activation (`"holdToScrub"` or
+   * `"axisDrag"`). Default `false`.
+   *
+   * @experimental Prototype — gesture model and API may change.
+   */
+  timeScroll?: boolean | TimeScrollConfig;
+  /**
+   * Pinch-to-zoom the visible time window. Two-finger pinch in/out narrows or
+   * widens the window, anchored at the focal point between your fingers. Composes
+   * with `timeScroll` (zoom level and scroll position are independent). Seed extra
+   * history in `data` / `candles` to have room to zoom out into.
+   *
+   * `true` uses sensible default bounds; pass a {@link ZoomConfig} to set
+   * `minTimeWindow` / `maxTimeWindow`. Default `false`.
+   *
+   * @experimental Prototype — gesture model and API may change.
+   */
+  zoom?: boolean | ZoomConfig;
   /** Accessibility label for the chart container. */
   accessibilityLabel?: string;
   /** Accessibility role for the chart container. Default `"image"`. */
@@ -1242,6 +1687,22 @@ export interface LiveChartCoreProps {
   onGestureStart?: () => void;
   /** Called once when the user stops scrubbing/panning the chart. */
   onGestureEnd?: () => void;
+  /**
+   * Called as the visible time window changes (throttled to ~1 Hz), with the
+   * window's edges in unix seconds and whether the chart is at the live edge.
+   * Useful for paging data sources alongside `timeScroll` / `zoom`.
+   *
+   * @experimental
+   */
+  onVisibleRangeChange?: (range: VisibleRange) => void;
+  /**
+   * Called once when the visible window's left edge comes within one
+   * window-width of the earliest retained data — the cue to lazily load older
+   * history. Re-arms after the edge moves back out.
+   *
+   * @experimental
+   */
+  onReachStart?: () => void;
   /**
    * Fade out chart content on the left (destination-out style). `true` = defaults, `false` = off,
    * or pass `LeftEdgeFadeConfig`. Default `true`.
@@ -1324,6 +1785,19 @@ export interface LiveChartProps extends LiveChartCoreProps {
    *  in a list. Pulse/scrub/degen and the entry animation are disabled. Frame the data
    *  with `timeWindow` + `nowOverride` (see the historical-data-fill pattern). */
   static?: boolean;
+  /**
+   * Render a custom overlay floated over the chart canvas, handed a price↔pixel /
+   * time↔pixel {@link ChartOverlayContext} so it can track the auto-rescaling axis
+   * on the UI thread. Return any React Native view tree (e.g. order / avg-entry /
+   * liquidation price tags) and position its pieces with the context's worklet
+   * mappings inside `useAnimatedStyle`; return `null`/`undefined` for no overlay.
+   *
+   * The returned tree is mounted as an RN sibling of the `<Canvas>` (like
+   * `renderMarker` / `renderTooltip`), full-bleed with `pointerEvents="box-none"`
+   * so empty areas still scrub while an interactive leaf can receive touches.
+   * Single-series only.
+   */
+  renderOverlay?: (ctx: ChartOverlayContext) => ReactElement | null | undefined;
   /** Called when the user scrubs the crosshair. `null` when scrub ends. */
   onScrub?: (point: ScrubPoint | null) => void;
   /**
@@ -1349,6 +1823,36 @@ export interface LiveChartProps extends LiveChartCoreProps {
    * routed here, not to reticle placement). Single-series only.
    */
   onReferenceLinePress?: (line: ReferenceLine, index: number) => void;
+  /**
+   * Render a reference line's tag as a custom **React Native** element instead of
+   * the built-in Skia pill / gutter label — the same model as `renderMarker` /
+   * `renderTooltip`. The chart floats the returned element over the canvas and
+   * pins it to the line's value on the UI thread (see {@link ReferenceLineRenderProps}),
+   * so it tracks the rescaling axis and any drag without JS re-renders. Called per
+   * Form-A line; return `null`/`undefined` to keep that line's built-in tag. Works
+   * with `badge: false` too (replace the plain gutter label). Single-series only.
+   */
+  renderReferenceLine?: (
+    ctx: ReferenceLineRenderProps,
+  ) => ReactElement | null | undefined;
+  /**
+   * Collapse Form-A reference lines whose handles sit near the same value into a
+   * single count handle (e.g. a stack of working orders at adjacent prices reads
+   * as one "×3" tag). `true` = defaults, `false`/omitted = off, or pass a
+   * {@link ReferenceLineGroupingConfig} to tune the proximity radius. Lines a
+   * {@link LiveChartProps.renderReferenceLine} owns are excluded (their custom tag
+   * draws itself), so the count reflects only collapsed built-in tags. Single-series
+   * only. Default off.
+   */
+  referenceLineGrouping?: boolean | ReferenceLineGroupingConfig;
+  /**
+   * Volume bars below the candles (candle mode only). `true` = defaults,
+   * `false`/omitted = off, or pass a {@link VolumeConfig} for colors, band
+   * height, rounding, and opacity. The candle/price plot shrinks by the band
+   * height to make room; the x-axis stays pinned to the bottom. Reads each
+   * candle's `CandlePoint.volume`. Ignored in line mode. Default off.
+   */
+  volume?: boolean | VolumeConfig;
   /**
    * Called on the JS thread when degen chart shake starts (momentum swing with shake enabled).
    * Not called when `degen` is off or `DegenOptions.shake` is `false`.