react-native-livechart 3.12.0 → 4.1.0

package/dist/types.d.ts

@@ -56,6 +56,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`. */
@@ -103,16 +112,103 @@ export interface ReferenceLine {
     badgeBorderColor?: string;
     /** Badge pill corner radius in pixels. Default `5`. (Fallback for `badge.radius`.) */
     badgeRadius?: number;
+    /**
+     * 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;
 }
 /**
  * Pill-badge presentation for a Form-A {@link ReferenceLine} — a working order,
  * 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`.
@@ -123,12 +219,69 @@ 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;
 }
 /**
  * A time-range segment of the chart — e.g. a pre-market / regular / after-hours
@@ -318,21 +471,77 @@ export interface AreaDotsConfig {
     /** Overall opacity (0..1) applied to the whole field. Default `1`. */
     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;
+    /**
+     * Show a fixed number of price labels instead of the dynamic nice-interval
+     * grid. When set (≥ 2), exactly `count` labels are spaced evenly **in pixels**
+     * across the plot — top label = current high, bottom = current low — so the
+     * count never changes as data streams in. Values are not rounded to "nice"
+     * numbers; they track the live range each frame.
+     *
+     * `minGap` still acts as a floor: if `count` labels won't fit at least
+     * `minGap` px apart, the count is reduced to what fits. Clamped to at most 15
+     * (the label pool size). Omit (or `0`) for the default dynamic grid.
+     */
+    count?: 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;
 }
 /**
  * Axis edge label — the value floated at the plot's top or bottom edge
@@ -438,11 +647,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
@@ -504,6 +715,13 @@ export interface ScrubActionConfig {
      * instead of moving it. Default `false` (an empty-plot tap re-places the reticle).
      */
     dismissOnTapOutside?: boolean;
+    /**
+     * Dismiss the reticle once the action badge is pressed (and
+     * {@link LiveChartProps.onScrubAction} fires), so no crosshair lingers after the
+     * action — e.g. clear the order reticle once the order has been placed. Default
+     * `false` (the reticle stays until tapped away).
+     */
+    dismissOnAction?: boolean;
 }
 /**
  * Payload for {@link LiveChartProps.onScrubAction} — the chosen price **level**
@@ -579,6 +797,89 @@ 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. */
@@ -728,16 +1029,59 @@ 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"). */
 export interface DegenOptions {
@@ -935,6 +1279,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;
 }
 /**
  * Spatial sizing & motion tokens — the geometry/timing analogue of
@@ -977,6 +1328,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. */
 export interface GridMetrics {
@@ -1013,6 +1368,58 @@ export interface LiveChartMetricsOverride {
     motion?: Partial<MotionMetrics>;
     emptyState?: Partial<EmptyStateMetrics>;
 }
+/**
+ * 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"`. */
@@ -1090,9 +1497,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
@@ -1105,8 +1522,12 @@ 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
@@ -1148,6 +1569,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"`. */
@@ -1164,6 +1610,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`.
@@ -1241,6 +1703,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;
     /**
@@ -1266,6 +1741,34 @@ 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`.