@wick-charts/react 0.1.2 → 0.2.2

package/dist/index.d.ts

@@ -5,6 +5,70 @@ import { ReactNode } from 'react';
 
 export declare const andromeda: ThemePreset;
 
+/**
+ * Chart-level animation configuration. Split into two independent domains so
+ * per-series defaults can't bleed into viewport-interaction timings:
+ *
+ * - `points` — animations applied to data: per-series entrance tween, live-
+ *   tracking smoothing of the last candle/bar/line value, pulse cadence.
+ *   These values act as defaults for each series. Per-series options always
+ *   win unless the chart-level category is explicitly `false`, in which case
+ *   the whole category is forced off.
+ *
+ * - `viewport` — animations applied to viewport interactions: post-gesture
+ *   rebound duration and Y-axis range smoothing.
+ *
+ * User-initiated pan/zoom (wheel, drag, touch) always applies instantly. The
+ * latency of an exponential chase reads as laggy in practice. API-driven
+ * transitions (`fitToData`, `scrollToEnd`) and post-gesture rebound still
+ * tween via their own fixed-duration ease-out.
+ */
+declare interface AnimationsConfig {
+    /**
+     * Data-series animations. `false` disables every point animation (entrance,
+     * live-smoothing, pulse) across every series. An object overrides individual
+     * categories; omitted fields fall back to the built-in defaults.
+     */
+    points?: false | {
+        /** Per-point entrance duration (ms). `false`/`0` disables. Default: 400. */
+        enterMs?: AnimationTime;
+        /**
+         * Exponential-smoothing time constant (ms) for live last-value chase.
+         * `false`/`0` disables smoothing — the last point snaps to the target.
+         * Default: 70 ms (equivalent to the legacy `liveSmoothRate = 14`).
+         */
+        smoothMs?: AnimationTime;
+        /** Pulse cycle period (ms) for the line last-point halo. Default: 600. */
+        pulseMs?: AnimationTime;
+    };
+    /**
+     * Viewport interaction animations. `false` disables both rebound and Y-axis
+     * smoothing — viewport changes snap instantly.
+     */
+    viewport?: false | {
+        /** Rebound (snap-back) duration after pan/zoom overshoot (ms). Default: 350. */
+        reboundMs?: AnimationTime;
+        /**
+         * Y-axis range transition scale. **Frame-count-based, calibrated at
+         * 60 Hz — not wall-clock ms.** Each render frame closes
+         * `min(1, 16 / yAxisMs)` of the remaining gap. Default 80 ≈ the
+         * legacy 0.2-per-frame closure. `false` / `0` snaps the Y range
+         * instantly. Unlike `smoothMs` / `entryMs` / `reboundMs`, the
+         * perceptual duration scales with frame time on refresh rates far
+         * from 60 Hz.
+         */
+        yAxisMs?: AnimationTime;
+    };
+}
+
+/** Options passed when creating a new {@link ChartInstance}. */
+/**
+ * Time-value or boolean used throughout the animation API. `false` disables
+ * the category; a number configures its duration/time-constant in milliseconds
+ * (`0` also disables, useful when the caller wants a number shape).
+ */
+declare type AnimationTime = number | false;
+
 /**
  * Defines a bound for the Y axis.
  *
@@ -23,7 +87,17 @@ export declare interface AxisConfig {
 
 export declare const ayuMirage: ThemePreset;
 
-export declare function BarSeries({ data, options, label, id: idProp, onSeriesId }: BarSeriesProps): null;
+/**
+ * Entrance animation styles for bars.
+ * - `'none'` — no animation.
+ * - `'fade'` — opacity 0→1.
+ * - `'grow'` — height grows from baseline.
+ * - `'slide'` — translates in from the right with a fade.
+ * - `'fade-grow'` *(default)* — fade + grow combined.
+ */
+declare type BarEntryAnimation = 'none' | 'fade' | 'grow' | 'slide' | 'fade-grow';
+
+export declare function BarSeries({ data, options, id: idProp }: BarSeriesProps): null;
 
 /** Visual options for a bar series. */
 export declare interface BarSeriesOptions {
@@ -34,27 +108,108 @@ export declare interface BarSeriesOptions {
     barWidthRatio: number;
     /** Stacking mode. Default: 'off'. */
     stacking: StackingMode;
+    /**
+     * Entrance animation style for newly appended bars. Style is specific to
+     * the bar series; there is no chart-level override for style — only for
+     * duration. Default: `'fade-grow'`.
+     *
+     * @see entryMs — cross-linked duration for this animation.
+     */
+    entryAnimation?: BarEntryAnimation;
+    /** @deprecated Use {@link entryAnimation} instead. */
+    enterAnimation?: BarEntryAnimation;
+    /**
+     * Entrance animation duration in milliseconds. `false` or `0` disables the
+     * per-bar entrance (equivalent to `entryAnimation: 'none'`). Omit to inherit
+     * from {@link AnimationsConfig.points}.`entryMs` (default 400).
+     *
+     * When `animations.points.entryMs` is `false` at the chart level, the
+     * entrance is forced off regardless of this field.
+     *
+     * @see BarSeriesOptions.entryAnimation
+     */
+    entryMs?: number | false;
+    /** @deprecated Use {@link entryMs} instead. */
+    enterMs?: number | false;
+    /**
+     * Exponential-smoothing time constant (ms) for live-tracking the last
+     * bar's value under `updateLastPoint`. `0` or `false` snaps directly to the
+     * target (no smoothing). Omit to inherit from
+     * {@link AnimationsConfig.points}.`smoothMs` (default 70 ms).
+     *
+     * When `animations.points.smoothMs` is `false` at the chart level, smoothing
+     * is forced off regardless of this field.
+     */
+    smoothMs?: number | false;
 }
 
 declare interface BarSeriesProps {
     /** Array of datasets — one per layer. A single-layer bar chart uses `[data]`. */
     data: TimePoint[][];
     options?: Partial<BarSeriesOptions>;
-    /** Display label shown in the tooltip. */
-    label?: string;
-    /** Stable series ID. Prefer this over `onSeriesId` — same value across remounts. */
+    /** Stable series ID — same value across remounts. */
     id?: string;
-    /** @deprecated Use the `id` prop instead. */
-    onSeriesId?: (id: string) => void;
 }
 
 /** @deprecated Use {@link StackingMode} instead. */
 export declare type BarStacking = StackingMode;
 
-/** Lookup a theme by name (defaults to "One Dark Pro") */
-export declare function buildTheme(themeName: string): ChartTheme;
+/**
+ * Snapshot every visible series / layer at `time`. Used by hover overlays
+ * (`InfoBar` in hover mode, `Tooltip`). Hidden series and hidden layers are
+ * skipped automatically — the returned array reflects what the chart would
+ * actually be drawing.
+ *
+ * The result is cached per `(chart, cacheKey)` slot; as long as
+ * `chart.getOverlayVersion()` hasn't changed and `time`/`sort` match the
+ * cached call, the **same reference** is returned. This makes
+ * `React.memo((a, b) => a.snapshots === b.snapshots)` skip renders on
+ * crosshair moves that stay within one data point.
+ */
+export declare function buildHoverSnapshots(chart: ChartInstance, args: BuildHoverSnapshotsArgs): readonly SeriesSnapshot[];
 
-export declare function CandlestickSeries({ data, options, id: idProp, onSeriesId }: CandlestickSeriesProps): null;
+export declare interface BuildHoverSnapshotsArgs {
+    /** Timestamp to resolve each series at. Typically `crosshair.time`. */
+    time: number;
+    /** Sort the output by numeric value. Default: `'none'`. */
+    sort?: SnapshotSort;
+    /**
+     * Cache bucket key. Distinct buckets (e.g. `'tooltip'`, `'infobar-hover'`)
+     * let separate overlays cache independently so they don't invalidate each
+     * other on every call.
+     */
+    cacheKey: string;
+}
+
+/**
+ * Snapshot every visible series / layer at its own last point. For
+ * multi-layer renderers each layer contributes its own `time`, so ragged
+ * streams (layer 1 newer than layer 0) show correctly instead of stalling
+ * at the primary layer's timestamp.
+ *
+ * Cached by `(chart, cacheKey)` + `sort`, invalidated on
+ * `chart.getOverlayVersion()` bump. `time` is not an input, so the slot is
+ * stored with `time: null`.
+ */
+export declare function buildLastSnapshots(chart: ChartInstance, args: BuildLastSnapshotsArgs): readonly SeriesSnapshot[];
+
+export declare interface BuildLastSnapshotsArgs {
+    sort?: SnapshotSort;
+    cacheKey: string;
+}
+
+/**
+ * Entrance animation styles for candlesticks (shown when a new candle appears via `appendData`).
+ * - `'none'` — no animation.
+ * - `'fade'` — opacity 0→1.
+ * - `'unfold'` — body scales from the open line outward.
+ * - `'slide'` — translates in from the right with a fade.
+ * - `'fade-unfold'` *(default)* — fade + unfold combined; the default because a lone fade is
+ *   hard to notice in streaming demos, while the body-unfold gives a clear visual anchor.
+ */
+declare type CandlestickEntryAnimation = 'none' | 'fade' | 'unfold' | 'slide' | 'fade-unfold';
+
+export declare function CandlestickSeries({ data, options, id: idProp }: CandlestickSeriesProps): null;
 
 /** Visual options for a candlestick series. */
 export declare interface CandlestickSeriesOptions {
@@ -67,16 +222,49 @@ export declare interface CandlestickSeriesOptions {
     /** Width of candle body as a fraction of the available bar slot (0-1). */
     bodyWidthRatio: number;
     /** Apply a subtle vertical gradient to candle bodies. Default: true. */
+    bodyGradient?: boolean;
+    /** @deprecated Use {@link bodyGradient} instead. */
     candleGradient?: boolean;
+    /**
+     * Entrance animation style for newly appended candles. Style is specific to
+     * the candlestick; there is no chart-level override for style — only for
+     * duration. Default: `'unfold'`.
+     *
+     * @see entryMs — cross-linked duration for this animation.
+     */
+    entryAnimation?: CandlestickEntryAnimation;
+    /** @deprecated Use {@link entryAnimation} instead. */
+    enterAnimation?: CandlestickEntryAnimation;
+    /**
+     * Entrance animation duration in milliseconds. `false` or `0` disables the
+     * per-candle entrance (equivalent to `entryAnimation: 'none'`). Omit to
+     * inherit from {@link AnimationsConfig.points}.`entryMs` (default 400).
+     *
+     * When `animations.points.entryMs` is `false` at the chart level, the
+     * entrance is forced off regardless of this field.
+     *
+     * @see CandlestickSeriesOptions.entryAnimation
+     */
+    entryMs?: number | false;
+    /** @deprecated Use {@link entryMs} instead. */
+    enterMs?: number | false;
+    /**
+     * Exponential-smoothing time constant (ms) for live-tracking the last
+     * candle's O/H/L/C under `updateLastPoint`. `0` or `false` snaps directly
+     * to the target (no smoothing). Omit to inherit from
+     * {@link AnimationsConfig.points}.`smoothMs` (default 70 ms).
+     *
+     * When `animations.points.smoothMs` is `false` at the chart level, smoothing
+     * is forced off regardless of this field.
+     */
+    smoothMs?: number | false;
 }
 
 declare interface CandlestickSeriesProps {
     data: OHLCInput[];
     options?: Partial<CandlestickSeriesOptions>;
-    /** Stable series ID. Prefer this over `onSeriesId` — same value across remounts. */
+    /** Stable series ID — same value across remounts. */
     id?: string;
-    /** @deprecated Use the `id` prop instead. */
-    onSeriesId?: (id: string) => void;
 }
 
 export declare const catppuccin: ThemePreset;
@@ -84,9 +272,16 @@ export declare const catppuccin: ThemePreset;
 /**
  * Top-level React wrapper that creates a {@link ChartInstance} and provides it to children via context.
  * Owns the DOM container and canvas lifecycle; renders children as an overlay layer.
- * Detects `<Legend>` children and renders them outside the chart area.
+ *
+ * Detects `<Title>`, `<InfoBar>`, and `<Legend>` children and positions them as:
+ *   - Title + InfoBar — absolutely-positioned *overlays* stacked at the top of the canvas
+ *     block, so the canvas (and therefore the grid) fills the full container height. The stacked
+ *     height is measured and fed back into `chart.setPadding({ top })` so series data stays below
+ *     them.
+ *   - Legend — flex sibling at the bottom (or right, when `position="right"`), so its height is
+ *     reserved by browser layout.
  */
-export declare function ChartContainer({ children, theme, axis, padding, gradient, interactive, grid, style, className }: ChartContainerProps): JSX_2.Element;
+export declare function ChartContainer({ children, theme, axis, padding, gradient, interactive, grid, headerLayout, perf, style, className, }: ChartContainerProps): JSX_2.Element;
 
 /** Props for the {@link ChartContainer} component. */
 declare interface ChartContainerProps {
@@ -115,8 +310,29 @@ declare interface ChartContainerProps {
     gradient?: boolean;
     /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
     interactive?: boolean;
-    /** Show the background grid. Defaults to true. */
-    grid?: boolean;
+    /** Background grid configuration. Default: `{ visible: true }`. */
+    grid?: {
+        visible: boolean;
+    };
+    /**
+     * How `<Title>` and `<InfoBar>` are positioned relative to the canvas.
+     * - `'overlay'` (default): absolute overlays on top of the canvas — the grid
+     *   and Y-axis labels render full-height behind the header strip.
+     * - `'inline'`: flex siblings above the canvas — the canvas (and grid) are
+     *   shifted down by the measured header height, so nothing renders behind
+     *   the title. The chart background still spans the full container.
+     */
+    headerLayout?: 'overlay' | 'inline';
+    /**
+     * Enable runtime performance instrumentation. Off by default.
+     *
+     * - `true` — attach a {@link PerfMonitor} and render a visible HUD overlay on this chart.
+     * - `{ hud: true, windowMs, maxSamples, ... }` — same, with monitor options.
+     * - `{ hud: false, monitor }` — attach to an existing monitor without rendering the HUD.
+     *
+     * Only read at mount; changing this prop after the chart is created is ignored.
+     */
+    perf?: PerfOption;
     style?: CSSProperties;
     className?: string;
 }
@@ -127,6 +343,14 @@ declare interface ChartEvents {
     viewportChange: () => void;
     dataUpdate: () => void;
     seriesChange: () => void;
+    /**
+     * Fired whenever any state that affects **overlay components** (InfoBar,
+     * Tooltip, Legend, YLabel, PieLegend, PieTooltip) changes. Superset of
+     * `dataUpdate` and `seriesChange` — also fires on visibility toggles,
+     * series option changes, and theme swaps. Overlay components should
+     * subscribe to this instead of stacking multiple listeners.
+     */
+    overlayChange: () => void;
 }
 
 /**
@@ -151,44 +375,38 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
         layers?: number;
         id?: string;
     }>): string;
-    /** @deprecated Pass options as first argument: `addLineSeries({ layers: N, ...options })` */
-    addLineSeries(layerCount: number, options?: Partial<LineSeriesOptions>): string;
-    /** Set data for a specific layer within a line series. */
-    setLineLayerData(id: string, layerIndex: number, data: TimePoint[]): void;
     /** Add a bar series and return its unique ID. */
     addBarSeries(options?: Partial<BarSeriesOptions & {
         layers?: number;
         id?: string;
     }>): string;
-    /** @deprecated Pass options as first argument: `addBarSeries({ layers: N, ...options })` */
-    addBarSeries(layerCount: number, options?: Partial<BarSeriesOptions>): string;
-    /** Set data for a specific layer within a bar series. */
-    setBarLayerData(id: string, layerIndex: number, data: TimePoint[]): void;
     /** Add a pie/donut series. Set `innerRadiusRatio > 0` for donut. */
     addPieSeries(options?: Partial<PieSeriesOptions & {
         id?: string;
     }>): string;
-    /** Set data for a pie/donut series. */
-    setPieData(id: string, data: PieSliceData[]): void;
     /** Remove a series by ID and clean up its resources. */
     removeSeries(id: string): void;
-    /** Replace all data for a series (batch load). Accepts `Date` objects for time fields. */
-    setSeriesData(id: string, data: OHLCInput[] | TimePointInput[]): void;
+    /**
+     * Replace all data for a series.
+     *
+     * - Single-layer series (candlestick, single-layer line/bar, pie): pass `data` directly.
+     * - Multi-layer series (line/bar with multiple layers): pass `layerIndex` to target a specific layer.
+     *
+     * For line/bar accepts `TimePointInput[]` (time may be `Date`); for candlestick accepts `OHLCInput[]`;
+     * for pie accepts `PieSliceData[]`. Time fields are normalized internally.
+     */
+    setSeriesData(id: string, data: unknown, layerIndex?: number): void;
     /** Append a new data point to the end of a series (real-time tick). */
-    appendData(id: string, point: OHLCInput | TimePointInput): void;
+    appendData(id: string, point: OHLCInput | TimePointInput, layerIndex?: number): void;
     /** Update the last data point of a series in place (e.g. live candle update). */
-    updateData(id: string, point: OHLCInput | TimePointInput): void;
+    updateData(id: string, point: OHLCInput | TimePointInput, layerIndex?: number): void;
     /** Update visual options (color, width, etc.) for an existing series. */
     updateSeriesOptions(id: string, options: Partial<CandlestickSeriesOptions> | Partial<LineSeriesOptions> | Partial<BarSeriesOptions> | Partial<PieSeriesOptions>): void;
     /**
-     * Batch multiple updates: suppress recomputes until `fn` returns.
-     * Equivalent to `beginUpdate()` / `endUpdate()` but safer (always calls endUpdate even on throw).
+     * Batch multiple updates: suppress recomputes until `fn` returns. Exceptions
+     * inside `fn` still flush the batch so counters don't leak across calls.
      */
     batch(fn: () => void): void;
-    /** @deprecated Use {@link batch} instead. */
-    beginUpdate(): void;
-    /** @deprecated Use {@link batch} instead. */
-    endUpdate(): void;
     /** Show or hide a series. Hidden series are not rendered and excluded from Y-range. */
     setSeriesVisible(seriesId: string, visible: boolean): void;
     isSeriesVisible(seriesId: string): boolean;
@@ -198,6 +416,22 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
     /** Auto-fit the viewport to show all data across every series. */
     fitContent(): void;
     getVisibleRange(): VisibleRange;
+    /**
+     * Imperatively set the visible time range.
+     *
+     * Two forms:
+     * - `{ from, to }` — explicit millisecond range. Cancels any in-flight
+     *   animation and applies immediately. Auto-scroll stays on only if the
+     *   tail is inside the new range (mirrors pan semantics).
+     * - `number N` — shorthand for "show the last N bars from the tail".
+     *   Resolved against the current data bounds and data interval; keeps
+     *   auto-scroll on so streaming ticks continue to track the tail.
+     *   No-op if data hasn't loaded yet.
+     *
+     * Typical use: on mount, zoom to the last N bars while keeping the full
+     * buffer available for pan-back history inspection.
+     */
+    setVisibleRange(range: VisibleRange | number): void;
     getYRange(): YRange;
     getCrosshairPosition(): CrosshairPosition | null;
     /** Get the last visible value and whether the absolute last point is on screen. */
@@ -210,57 +444,129 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
     getLastData(seriesId: string): OHLCData | TimePoint | null;
     /** Find the data point closest to the given timestamp within one data interval. */
     getDataAtTime(seriesId: string, time: number): OHLCData | TimePoint | null;
-    /** Get all layers' data at a given time for multi-layer series (Bar/Line with stacking). */
+    /**
+     * Get all layers' data at a given time for multi-layer series (Bar/Line
+     * with stacking). Each entry carries the owning `layerIndex` and the
+     * snapped sample time — callers must not derive layer identity from the
+     * array index, because hidden layers are filtered out.
+     */
     getLayerSnapshots(seriesId: string, time: number): {
+        layerIndex: number;
+        time: number;
         value: number;
         color: string;
     }[] | null;
     getSeriesIds(): string[];
+    /**
+     * Type of a registered series, or `null` for unknown ids. `'pie'` for
+     * `PieRenderer`; everything else is a time-series (`'time'`).
+     */
+    getSeriesType(seriesId: string): 'pie' | 'time' | null;
+    /**
+     * Filter `getSeriesIds()` by renderer type. `'pie'` returns pie series,
+     * `'time'` returns line/bar/candlestick.
+     *
+     * - `opts.visibleOnly` — exclude series with `isSeriesVisible=false`; for
+     *   multi-layer series also exclude when every layer is hidden.
+     * - `opts.singleLayerOnly` — exclude series with more than one layer.
+     *   Useful for YLabel fallback priority (stick to a single line first).
+     */
+    getSeriesIdsByType(type: 'pie' | 'time', opts?: {
+        visibleOnly?: boolean;
+        singleLayerOnly?: boolean;
+    }): string[];
+    /**
+     * Cumulative top last-value for stacked series — the point a YLabel badge
+     * anchors to on the rendered stack head. Falls back to `getLastValue` for
+     * series without stacked concepts (Candlestick, single-layer Line/Bar).
+     * Returns `null` for unknown ids or empty series.
+     */
+    getStackedLastValue(seriesId: string): {
+        value: number;
+        isLive: boolean;
+    } | null;
+    /**
+     * Per-layer last snapshots with each layer's own `time`. Returns `null`
+     * for single-layer renderers or when no visible layer has data. Used by
+     * overlay components that must display every layer in last-mode even
+     * when layers advance at different rates (ragged streams).
+     */
+    getLayerLastSnapshots(seriesId: string): {
+        layerIndex: number;
+        time: number;
+        value: number;
+        color: string;
+    }[] | null;
     /** Get the primary display color for a series. */
     getSeriesColor(seriesId: string): string | null;
     getSeriesLabel(seriesId: string): string | undefined;
-    /** Get per-layer colors for a series. Returns null for non-bar/line series (e.g. candlestick, pie). */
+    /** Get per-layer colors for a series. Returns null for single-layer non-bar/line series. */
     getSeriesLayers(seriesId: string): {
         color: string;
     }[] | null;
-    /** Get all pie slices with computed colors and percentages. Returns null for non-pie series. */
-    getPieSlices(seriesId: string): {
-        label: string;
-        value: number;
-        percent: number;
-        color: string;
-    }[] | null;
-    /** Get the hovered pie slice info (label, value, percentage, color). Returns null if no hover. */
-    getPieHoverInfo(seriesId: string): {
-        label: string;
-        value: number;
-        percent: number;
-        color: string;
-    } | null;
-    /** Apply a new theme and update candlestick series colors. Line series keep their individual colors. */
+    /** Get all slices with computed colors and percentages. Returns null for series without slice data (e.g. candlestick, line, bar). */
+    getSliceInfo(seriesId: string): SliceInfo[] | null;
+    /** Get hover info (label/value/percent/color) for the currently hovered element, or null. */
+    getHoverInfo(seriesId: string): HoverInfo | null;
+    /** Apply a new theme and update series colors where appropriate. */
     setTheme(theme: ChartTheme): void;
     getTheme(): ChartTheme;
     /** Update axis configuration and re-render. */
     setAxis(config: AxisConfig): void;
+    /**
+     * Apply label-density knobs driven by `<YAxis labelCount=… minLabelSpacing=…>`
+     * — kept separate from {@link setAxis} so component props don't force a
+     * Y-animation reset. Triggers a viewportChange + repaint so static charts
+     * react without waiting for pan/zoom.
+     */
+    setYAxisLabelDensity(params: {
+        labelCount?: number | null;
+        minLabelSpacing?: number | null;
+    }): void;
+    /** Label-density knobs for the time axis — mirror of {@link setYAxisLabelDensity}. */
+    setTimeAxisLabelDensity(params: {
+        labelCount?: number | null;
+        minLabelSpacing?: number | null;
+    }): void;
     getMediaSize(): Size;
     /** Returns layout metrics for the chart area, Y axis, and time axis. */
     getLayout(): ChartLayout;
     getDataInterval(): number;
-    /** Update viewport padding at runtime. Refits the visible range to current data bounds. */
+    /**
+     * Update viewport padding at runtime. Refits the visible time range to
+     * current data bounds **only when horizontal padding (left/right) changes**
+     * — vertical padding only affects the Y-range computation, so touching it
+     * shouldn't reset the user's zoom / auto-scroll state. This matters when
+     * a wrapper re-applies padding reactively (e.g. in response to a Title /
+     * InfoBar ResizeObserver).
+     */
     setPadding(padding: ChartOptions['padding']): void;
     /** Show or hide the background grid. Takes effect on the next render frame. */
-    setGrid(grid: boolean): void;
+    setGrid(grid: {
+        visible: boolean;
+    }): void;
+    /**
+     * Set the visual state for one side of the chart. Typically called in
+     * response to the `onEdgeReached` callback:
+     *   - `loading` while a history fetch is in flight,
+     *   - `no-data` once the fetch confirmed there's nothing more,
+     *   - `idle` when the host no longer wants any edge affordance.
+     * The state persists until replaced. `has-more` is accepted for API
+     * symmetry and currently renders identically to `idle`.
+     */
+    setEdgeState(side: EdgeSide, state: EdgeState): void;
+    /** Read the current host-declared state for a given edge. */
+    getEdgeState(side: EdgeSide): EdgeState;
     /** Notify chart that a YLabel is present (affects right padding). */
     setYLabel(has: boolean): void;
-    private updatePieHover;
     private updateViewportPadding;
     /** Tear down the chart: cancel animations, remove listeners, and detach the canvas. */
     destroy(): void;
+    /** The attached performance monitor, or `null` when instrumentation is disabled. */
+    getPerfMonitor(): PerfMonitor | null;
     /** Compute the earliest and latest timestamps across all series. */
     private getDataBounds;
     private onDataChanged;
-    /** Check whether the last data point of any series falls within the visible time range. */
-    private isLastPointVisible;
     private updateDataInterval;
     private updateYRange;
     /** Resolve an {@link AxisBound} to a concrete numeric value. */
@@ -274,8 +580,17 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
     private updateScales;
     /** Expensive: background, grid, all series. Only on data/viewport/resize change. */
     private renderMain;
-    /** Cheap overlay: crosshair, nearest-point dots, pulse animation. */
+    /** Cheap overlay: crosshair, nearest-point dots, pulse animation, edge indicator. */
     private renderOverlay;
+    private drawEdgeIndicators;
+    /**
+     * Pick the boundary time to anchor the edge indicator at. Prefer the
+     * cached value emitted by the most recent `edgeReached` — that's the
+     * *exact* point the user overshot. Fall back to the current data edge
+     * when no gesture has fired yet (host might invoke `setEdgeState`
+     * directly on mount to show a "no-data" marker from the start).
+     */
+    private resolveEdgeBoundary;
 }
 
 /** Layout metrics describing the chart area, Y axis, and time axis sizes. */
@@ -285,7 +600,6 @@ export declare interface ChartLayout {
     xAxisHeight: number;
 }
 
-/** Options passed when creating a new {@link ChartInstance}. */
 export declare interface ChartOptions {
     theme?: ChartTheme;
     axis?: AxisConfig;
@@ -305,8 +619,50 @@ export declare interface ChartOptions {
     };
     /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
     interactive?: boolean;
-    /** Show the background grid. Defaults to true. */
-    grid?: boolean;
+    /** Background grid configuration. Default: `{ visible: true }`. */
+    grid?: {
+        visible: boolean;
+    };
+    /**
+     * Animation control. Split into `points` (data-series animations) and
+     * `viewport` (pan/zoom rebound + Y-axis smoothing). See
+     * {@link AnimationsConfig} for the full shape and defaults.
+     *
+     * Shorthands:
+     * - `animations: true` (or omitted) uses built-in defaults.
+     * - `animations: false` disables every animation category.
+     * - `animations: { points: false }` disables all data-series animations.
+     * - `animations: { viewport: false }` disables rebound + Y-axis smoothing.
+     *
+     * Per-series options (`enterMs`, `smoothMs`, etc.) override chart-level
+     * defaults unless the category is explicitly `false` — then the chart-
+     * level gate wins.
+     */
+    animations?: boolean | AnimationsConfig;
+    /**
+     * Invoked after the user releases a pan/zoom gesture that pulled the
+     * viewport past a data edge by more than 10% of the visible range. Hosts
+     * typically respond by prefetching more history and calling
+     * {@link ChartInstance.setEdgeState} to show a spinner or "no more data"
+     * indicator at the corresponding edge.
+     */
+    onEdgeReached?: (info: EdgeReachedInfo) => void;
+    /**
+     * Runtime performance instrumentation. Opt-in — absent by default so the
+     * hot render path stays free of timing/counting overhead.
+     *
+     * - `false` / omitted — no instrumentation, no HUD, byte-identical to a perf-free build.
+     * - `true` — create an internal {@link PerfMonitor} and mount a visible HUD overlay.
+     * - `{ hud: true, ...options }` — same, with monitor options forwarded.
+     * - `{ hud: false, ...options }` — instrument but do not render a HUD (useful when
+     *   the host app consumes stats via `monitor.onFrame` and renders its own UI).
+     * - `PerfMonitor` instance — attach to a pre-constructed monitor. Useful when several
+     *   charts share one telemetry sink. HUD defaults to off in this mode.
+     */
+    perf?: boolean | PerfMonitor | (PerfMonitorOptions & {
+        hud?: boolean;
+        monitor?: PerfMonitor;
+    });
 }
 
 /**
@@ -370,6 +726,8 @@ export declare interface ChartTheme {
     };
 }
 
+export declare function computeTooltipPosition(args: TooltipPositionArgs): TooltipPosition;
+
 /**
  * Build a complete {@link ThemePreset} from a partial config.
  * Only `background` is required — everything else is derived from it.
@@ -396,6 +754,27 @@ export declare function detectInterval(times: number[]): number;
 
 export declare const dracula: ThemePreset;
 
+/** Payload for {@link ChartOptions.onEdgeReached}. */
+declare interface EdgeReachedInfo {
+    side: EdgeSide;
+    /** Time units the user pulled past the soft bound. */
+    overshoot: number;
+    /** Soft-bound timestamp that was crossed (dataStart - leftPad or dataEnd + rightPad). */
+    boundaryTime: number;
+}
+
+/** Which data side the user pulled past during a gesture. */
+declare type EdgeSide = 'left' | 'right';
+
+/**
+ * Host-controlled visual state for a chart edge:
+ * - `idle`: nothing rendered (default).
+ * - `loading`: a subtle spinner appears in the overshoot area.
+ * - `no-data`: a dashed boundary line + "No more data" label appears at the data edge.
+ * - `has-more`: reserved — currently behaves like `idle`. Use when more data exists but is not being fetched.
+ */
+declare type EdgeState = 'idle' | 'loading' | 'no-data' | 'has-more';
+
 declare class EventEmitter<Events = Record<string, Listener>> {
     private listeners;
     on<K extends string & keyof Events>(event: K, listener: Events[K] & Listener): void;
@@ -404,10 +783,37 @@ declare class EventEmitter<Events = Record<string, Listener>> {
     removeAllListeners(): void;
 }
 
+/**
+ * Compact notation for large magnitudes (K / M / B / T) with adaptive
+ * precision for values below 1. Default decimal count for the compact
+ * suffixes can be overridden via `opts.decimals`.
+ */
+export declare function formatCompact(v: number, opts?: {
+    decimals?: number;
+}): string;
+
 export declare function formatDate(timestamp: number): string;
 
+/**
+ * Full-precision display that adapts decimal count to the value's magnitude.
+ * No K/M/B compression — callers wanting a short label should use
+ * `formatCompact` instead.
+ */
+export declare function formatPriceAdaptive(v: number): string;
+
 export declare function formatTime(timestamp: number, interval: number): string;
 
+declare type FrameKind = 'main' | 'overlay';
+
+declare interface FrameTimingSample {
+    /** Wall-clock ms for the most recent frame. */
+    last: number;
+    /** Median frame time over the rolling window. */
+    p50: number;
+    /** Tail frame time (worst 5%) — useful for spotting stutter. */
+    p95: number;
+}
+
 export declare const githubLight: ThemePreset;
 
 export declare const gruvbox: ThemePreset;
@@ -416,26 +822,129 @@ export declare const handwritten: ThemePreset;
 
 export declare const highContrast: ThemePreset;
 
+/** Shape returned by {@link SeriesRenderer.getHoverInfo} / per-slice entries of {@link SeriesRenderer.getSliceInfo}. */
+export declare interface HoverInfo {
+    label: string;
+    value: number;
+    percent: number;
+    color: string;
+}
+
+/**
+ * Compact OHLC/series info bar rendered as a flex row above the chart canvas.
+ * Pairs with {@link Tooltip} (which then only renders its floating near-cursor part).
+ *
+ * Pass a render-prop child for a custom layout — the built-in UI is used when
+ * {@link children} is omitted.
+ */
+export declare function InfoBar({ sort, format, children }: InfoBarProps): JSX_2.Element | null;
+
+/** Props for the {@link InfoBar} component. */
+export declare interface InfoBarProps {
+    /** Sort order for line values (default: 'none'). */
+    sort?: TooltipSort;
+    /**
+     * Custom formatter for every displayed number in the default UI. Called per
+     * cell with the field hint (`'open' | 'high' | 'low' | 'close' | 'volume' | 'value'`).
+     * Defaults: adaptive precision for ohlc/value, compact (K/M/B/T) for volume.
+     * Ignored when {@link children} is a render-prop.
+     */
+    format?: TooltipFormatter;
+    /**
+     * Render-prop escape hatch. Receives the computed snapshots and replaces the
+     * entire built-in layout. Filter, reorder, or re-style rows here without
+     * re-implementing any data wiring.
+     */
+    children?: (ctx: InfoBarRenderContext) => ReactNode;
+}
+
+/** Context passed to the {@link InfoBar} render-prop. */
+export declare interface InfoBarRenderContext {
+    readonly snapshots: readonly SeriesSnapshot[];
+    /** Timestamp displayed. In hover mode it's the crosshair time; in last-mode it's the newest point. */
+    readonly time: number;
+    /** `true` while the user's pointer is over the chart (hover mode). */
+    readonly isHover: boolean;
+}
+
 export declare const lavenderMist: ThemePreset;
 
-export declare function Legend({ items, position, mode }: LegendProps): JSX_2.Element | null;
+export declare function Legend({ items, position, mode, children }: LegendProps): JSX_2.Element | null;
 
+/**
+ * Canonical legend item — the unit every framework Legend passes to its
+ * scoped slot (and the shape the built-in default UI consumes).
+ *
+ * Each item is **self-contained**: it carries its own identity and
+ * pre-bound `toggle` / `isolate` closures, so slot code can freely sort,
+ * filter, or remap items without risking a click on one row mutating the
+ * wrong series.
+ *
+ * - `id` — row key for list rendering (React `key`, Vue `:key`,
+ *   Svelte `each … (key)`). Guaranteed unique within the array.
+ * - `seriesId` — owning series id, **never includes a layer suffix**.
+ *   Use this for filtering/grouping; not unique across multi-layer rows.
+ * - `layerIndex` — layer within a multi-layer series; `undefined` for
+ *   single-layer rows.
+ * - `isDisabled` — current toggled-off state, derived from
+ *   `isSeriesVisible` / `isLayerVisible` plus local isolate-state in the
+ *   Legend component.
+ */
 export declare interface LegendItem {
+    readonly id: string;
+    readonly seriesId: string;
+    readonly layerIndex?: number;
+    readonly label: string;
+    readonly color: string;
+    readonly isDisabled: boolean;
+    /** Toggle just this item's visibility. */
+    readonly toggle: () => void;
+    /** Show only this item; calling again reveals everything (isolate/unisolate). */
+    readonly isolate: () => void;
+}
+
+/**
+ * Minimal visual shape the {@link LegendProps.items} override accepts — just
+ * the pieces the built-in swatch/label UI needs. The canonical
+ * {@link LegendItem} (re-exported from `@wick-charts/core`) carries full
+ * identity plus `toggle`/`isolate` closures; those aren't meaningful when a
+ * consumer hands in a pre-baked, non-interactive legend.
+ */
+export declare interface LegendItemOverride {
     label: string;
     color: string;
 }
 
+/**
+ * Legend interaction mode.
+ * - `'toggle'` — click toggles the clicked item on/off (default).
+ * - `'isolate'` — click shows only that item; click again shows all.
+ * - `'solo'` — **@deprecated** alias for `'isolate'`, kept for back-compat.
+ */
+declare type LegendMode = 'toggle' | 'isolate' | 'solo';
+
 export declare interface LegendProps {
-    /** Override auto-detected items. When omitted, derived from series layers. */
-    items?: LegendItem[];
+    /**
+     * Static override for auto-detected items. Renders a non-interactive legend
+     * with just swatch + label. Ignored when {@link children} is a render-prop.
+     */
+    items?: LegendItemOverride[];
     /** Layout position. Default: 'bottom'. */
     position?: 'bottom' | 'right';
+    /** Click behavior for the built-in UI. Default: `'toggle'`. Ignored when {@link children} is provided. */
+    mode?: LegendMode;
     /**
-     * Click behavior:
-     * - `'toggle'` — click toggles individual items on/off (default)
-     * - `'solo'` — click shows only that item; click again shows all
+     * Render-prop escape hatch. Receives the computed `items` (each carrying
+     * its own `toggle()` / `isolate()` closures) and fully replaces the
+     * built-in flex row / column. Callers can filter, reorder, and re-style
+     * without reimplementing visibility wiring.
      */
-    mode?: 'toggle' | 'solo';
+    children?: (ctx: LegendRenderContext) => ReactNode;
+}
+
+/** Context passed to the {@link Legend} render-prop. */
+declare interface LegendRenderContext {
+    readonly items: readonly LegendItem[];
 }
 
 export declare const lightPink: ThemePreset;
@@ -445,7 +954,15 @@ export declare const lightTheme: ChartTheme;
 /** @deprecated Use {@link TimePoint} instead. */
 export declare type LineData = TimePoint;
 
-export declare function LineSeries({ data, options, label, id: idProp, onSeriesId }: LineSeriesProps): null;
+/**
+ * Entrance animation styles for new line points.
+ * - `'none'` — new segments appear instantly.
+ * - `'grow'` *(default)* — trailing segment reveals left-to-right.
+ * - `'fade'` — geometry fixed; trailing segment strokes in with alpha 0→1.
+ */
+declare type LineEntryAnimation = 'none' | 'grow' | 'fade';
+
+export declare function LineSeries({ data, options, id: idProp }: LineSeriesProps): null;
 
 /** Visual options for a line series. */
 export declare interface LineSeriesOptions {
@@ -453,24 +970,67 @@ export declare interface LineSeriesOptions {
     label?: string;
     /** One color per layer. */
     colors: string[];
-    lineWidth: number;
-    /** Whether to render a gradient area fill below the line (or between stacked layers). */
-    areaFill: boolean;
-    /** Whether to show an animated pulsing dot at the last data point. */
+    /** Stroke width in CSS pixels. Default: 1. `0` hides the line stroke. */
+    strokeWidth: number;
+    /** Area-fill configuration. Default: `{ visible: true }`. */
+    area: {
+        visible: boolean;
+    };
+    /**
+     * Whether to show an animated pulsing dot at the last data point.
+     */
     pulse: boolean;
+    /**
+     * Pulse cycle period in milliseconds. `false`/`0` disables the halo (both
+     * the drawing and the associated animation loop). Omit to inherit from
+     * {@link AnimationsConfig.points}.`pulseMs` (default 600 ms). When
+     * `animations.points.pulseMs` is `false` at the chart level the pulse is
+     * forced off regardless of this field.
+     */
+    pulseMs?: number | false;
     /** Stacking mode. Default: 'off'. */
     stacking: StackingMode;
+    /**
+     * Entrance animation style for new points. Style is specific to the line
+     * series; there is no chart-level override for style — only for duration.
+     * Default: `'grow'`.
+     *
+     * @see entryMs — cross-linked duration for this animation.
+     */
+    entryAnimation?: LineEntryAnimation;
+    /** @deprecated Use {@link entryAnimation} instead. */
+    enterAnimation?: LineEntryAnimation;
+    /**
+     * Entrance animation duration in milliseconds. `false` or `0` disables the
+     * per-point entrance (equivalent to `entryAnimation: 'none'`). Omit to
+     * inherit from {@link AnimationsConfig.points}.`entryMs` (default 400).
+     *
+     * When `animations.points.entryMs` is `false` at the chart level, the
+     * entrance is forced off regardless of this field.
+     *
+     * @see LineSeriesOptions.entryAnimation
+     */
+    entryMs?: number | false;
+    /** @deprecated Use {@link entryMs} instead. */
+    enterMs?: number | false;
+    /**
+     * Exponential-smoothing time constant (ms) for live-tracking the last
+     * point's value under `updateLastPoint`. `0` or `false` snaps directly to
+     * the target (no smoothing). Omit to inherit from
+     * {@link AnimationsConfig.points}.`smoothMs` (default 70 ms).
+     *
+     * When `animations.points.smoothMs` is `false` at the chart level, smoothing
+     * is forced off regardless of this field.
+     */
+    smoothMs?: number | false;
 }
 
 declare interface LineSeriesProps {
     /** Array of datasets — one per layer. A single line uses `[data]`. */
     data: TimePoint[][];
     options?: Partial<LineSeriesOptions>;
-    label?: string;
-    /** Stable series ID. Prefer this over `onSeriesId` — same value across remounts. */
+    /** Stable series ID — same value across remounts. */
     id?: string;
-    /** @deprecated Use the `id` prop instead. */
-    onSeriesId?: (id: string) => void;
 }
 
 declare type Listener = (...args: any[]) => void;
@@ -492,7 +1052,16 @@ export declare function NumberFlow({ value, format, locale, spinDuration, classN
 
 declare interface NumberFlowProps {
     value: number;
-    format?: Intl.NumberFormatOptions;
+    /**
+     * Value-to-string formatter. Defaults to the current locale's
+     * `Intl.NumberFormat` when omitted. Pass the shared `formatCompact` /
+     * `formatPriceAdaptive` helpers or your own function to customize.
+     *
+     * `Intl.NumberFormatOptions` is also accepted (legacy) — it's routed
+     * through the built-in `Intl.NumberFormat` for back-compat with callers
+     * from before this prop was a function.
+     */
+    format?: ((value: number) => string) | Intl.NumberFormatOptions;
     locale?: string;
     spinDuration?: number;
     className?: string;
@@ -520,42 +1089,267 @@ export declare const panda: ThemePreset;
 
 export declare const peachCream: ThemePreset;
 
-export declare function PieLegend({ seriesId, format }: PieLegendProps): JSX_2.Element | null;
+/**
+ * Collects per-frame timing, draw-call counts, per-series render ms, and heap
+ * usage. All collection sites short-circuit to no-ops when no monitor is
+ * attached to the chart, so the zero-perf path remains byte-identical to a
+ * monitorless build.
+ *
+ * Not thread-safe (there are no threads) — a single chart writes to a single
+ * monitor. Multiple charts may share a monitor, but `perSeries` keys must be
+ * unique across charts or samples will collide.
+ */
+declare class PerfMonitor {
+    /** Draw-call tally map for the main layer. Mutated in place by the counting context; cleared at the start of each frame. */
+    readonly drawCallsMain: Map<string, number>;
+    /** Draw-call tally map for the overlay layer. Same contract as `drawCallsMain`. */
+    readonly drawCallsOverlay: Map<string, number>;
+    private readonly mainMs;
+    private readonly overlayMs;
+    private readonly mainStamps;
+    private readonly overlayStamps;
+    private readonly perSeriesMs;
+    private readonly perSeriesStamps;
+    private readonly listeners;
+    private readonly windowMs;
+    private readonly maxSamples;
+    private readonly heapInterval;
+    private heapCounter;
+    private heapMb;
+    private mainFrameCount;
+    private overlayFrameCount;
+    /** Most recent frame timestamp across either layer — anchor for age-based trimming. */
+    private lastStamp;
+    constructor(options?: PerfMonitorOptions);
+    /** Clear the draw-call tally for the given layer. Call at the start of each frame. */
+    resetDrawCalls(kind: FrameKind): void;
+    /** Record a completed frame's wall-clock duration and emit stats to subscribers. */
+    recordFrame(kind: FrameKind, ms: number, timestamp: number): void;
+    /** Record one series renderer's time slice inside the main pass. Called from inside `renderMain`, so the enclosing `recordFrame('main', …)` trim takes care of age. */
+    recordSeries(id: string, ms: number, timestamp?: number): void;
+    /** Drop samples older than `windowMs` behind the newest recorded stamp, and enforce the hard per-layer cap. */
+    private trimAll;
+    /** Subscribe to per-frame stat snapshots. Returns an unsubscribe function. */
+    onFrame(cb: (stats: PerfStats) => void): () => void;
+    /** Snapshot current stats. Safe to call outside frames. */
+    getStats(): PerfStats;
+    destroy(): void;
+    private sampleHeap;
+}
+
+declare interface PerfMonitorOptions {
+    /**
+     * Age of the rolling window in milliseconds. Samples older than this are
+     * dropped from FPS / percentile calculations. Defaults to 5000 (5 seconds).
+     *
+     * Tradeoff: smaller windows react faster to load changes but are noisier;
+     * larger windows smooth spikes but lag. 5 s is a balance — it's long
+     * enough that p95 is meaningful and short enough that numbers visibly
+     * settle when you stop interacting.
+     */
+    windowMs?: number;
+    /**
+     * Hard cap on retained samples per layer. Belt-and-suspenders against a
+     * runaway high-FPS layer growing the buffer unbounded. Defaults to 2000.
+     */
+    maxSamples?: number;
+    /** Sample `performance.memory` every Nth main frame. Defaults to 30 (~0.5s at 60fps). */
+    heapSampleEveryNFrames?: number;
+}
+
+declare type PerfOption = NonNullable<ChartOptions['perf']>;
+
+declare interface PerfStats {
+    /**
+     * Main-layer renders per second, derived from the interval between recent main
+     * frames. Charts render on demand (data change, pan, zoom, resize, streaming
+     * tick), so `0` during an idle chart is normal — not a stutter. `0` until two
+     * frames have been recorded.
+     */
+    mainRendersPerSec: number;
+    /** Same as {@link mainRendersPerSec} but for the overlay (crosshair + pulse) layer. */
+    overlayRendersPerSec: number;
+    /** @deprecated Alias for {@link mainRendersPerSec}. Kept for older consumers. */
+    fps: number;
+    mainFrameMs: FrameTimingSample;
+    overlayFrameMs: FrameTimingSample;
+    /** Total frames recorded per layer. Lets consumers distinguish "no data yet" from "drew once and ms is 0". */
+    frameCount: {
+        main: number;
+        overlay: number;
+    };
+    drawCalls: {
+        main: Record<string, number>;
+        overlay: Record<string, number>;
+    };
+    perSeries: Record<string, FrameTimingSample>;
+    /** `null` on browsers without `performance.memory` (Firefox, Safari). */
+    heapMb: number | null;
+}
+
+/**
+ * How per-slice labels are drawn on a pie/donut.
+ *
+ * - `'outside'` (default) — a short leader line runs from the slice edge to a
+ *   text block outside the pie. Reserves horizontal space so the pie shrinks
+ *   to fit. Matches the canonical infographic look.
+ * - `'inside'` — text sits on the slice. Auto-skipped when the measured text
+ *   won't fit the slice chord at the label radius.
+ * - `'none'` — the renderer draws no labels (PieLegend / PieTooltip still work).
+ */
+declare interface PieLabelsOptions {
+    /** Default: `'outside'`. */
+    mode?: 'inside' | 'outside' | 'none';
+    /** What to display per label. Default: `'both'` (e.g. `"BTC  42%"`). */
+    content?: 'percent' | 'label' | 'both';
+    /** Font size in CSS pixels. Default: 11. */
+    fontSize?: number;
+    /**
+     * Slices narrower than this (in degrees) get no on-pie label. Default: 2.5°
+     * (≈ 0.7% of the pie). Raise when many tiny slices would crowd the
+     * de-cluster pass into unreadable overlaps.
+     */
+    minSliceAngle?: number;
+    /** Leader-line radial segment length in CSS pixels. Default: 12. */
+    elbowLen?: number;
+    /** Gap between leader line and text in CSS pixels. Default: 6. */
+    legPad?: number;
+    /**
+     * Radial distance in CSS pixels from the pie's outer edge to the natural
+     * label anchor point. The label then extends horizontally outward by
+     * {@link railWidth} before the text starts. Clamped internally against
+     * {@link elbowLen}. Default: 14.
+     */
+    distance?: number;
+    /**
+     * Horizontal length of the final leader-line segment in CSS pixels — the
+     * straight tail that runs from the radial elbow out to the text anchor.
+     * Higher values give a longer visible "rail" before the label. Default: 16.
+     */
+    railWidth?: number;
+    /**
+     * Minimum vertical gap between adjacent outside labels on the same side,
+     * expressed as a multiplier of {@link fontSize}. Default: 1.8.
+     */
+    labelGap?: number;
+    /**
+     * @deprecated No effect in the radial per-slice layout. A label's X is
+     * pinned to its slice midangle, so forcing the "other" side would flip
+     * text direction without moving the label and push text across the pie.
+     * Kept in the option surface for backwards compatibility.
+     */
+    balanceSides?: boolean;
+}
+
+export declare function PieLegend({ seriesId, mode: modeProp, format, position, children }: PieLegendProps): JSX_2.Element | null;
 
-export declare type PieLegendFormat = 'value' | 'percent';
+/**
+ * Legend row content.
+ *
+ * - `'value'` — only the absolute value (e.g. `25`).
+ * - `'percent'` — only the percentage (e.g. `25.0%`).
+ * - `'both'` (default) — value + percent side-by-side; value is bold, percent dimmed.
+ */
+export declare type PieLegendMode = 'value' | 'percent' | 'both';
+
+/**
+ * Where the legend sits relative to the pie canvas.
+ *
+ * - `'bottom'` (default) — flex sibling below the canvas. Matches the time-series `<Legend>` layout.
+ * - `'right'` — flex sibling on the right of the canvas.
+ * - `'overlay'` — absolute overlay on top of the canvas. Back-compat escape hatch for callers
+ *   that were relying on the old positioning; stacks with any `<Title>` at the top-left and can
+ *   collide with it, so use sparingly.
+ */
+export declare type PieLegendPosition = 'bottom' | 'right' | 'overlay';
 
 export declare interface PieLegendProps {
-    seriesId: string;
-    /** Display format: 'value' shows absolute + percent, 'percent' shows only percent. Default: 'value'. */
-    format?: PieLegendFormat;
+    /**
+     * Owning series id. **Optional** — when omitted, the first visible pie
+     * series is picked.
+     */
+    seriesId?: string;
+    /** Default: `'both'`. See {@link PieLegendMode}. */
+    mode?: PieLegendMode;
+    /** Custom formatter for the absolute slice value. Default: shared `formatCompact`. */
+    format?: ValueFormatter;
+    /** Layout placement. Default: `'bottom'`. See {@link PieLegendPosition}. */
+    position?: PieLegendPosition;
+    /** Render-prop escape hatch. Receives slices + mode + format, replaces default UI. */
+    children?: (ctx: PieLegendRenderContext) => ReactNode;
+}
+
+/** Context passed to the {@link PieLegend} render-prop. */
+export declare interface PieLegendRenderContext {
+    readonly slices: readonly SliceInfo[];
+    readonly mode: PieLegendMode;
+    readonly format: ValueFormatter;
 }
 
 /** Pie chart series. Set `options.innerRadiusRatio` > 0 for donut. */
-export declare function PieSeries({ data, options, id: idProp, onSeriesId }: PieSeriesProps): null;
+export declare function PieSeries({ data, options, id: idProp }: PieSeriesProps): null;
 
 /** Visual options for a pie/donut series. `innerRadiusRatio > 0` makes it a donut. */
 export declare interface PieSeriesOptions {
     /** Palette fallback (defaults to theme.seriesColors). */
     colors?: string[];
-    /** 0 = pie, 0.6 = donut. Fraction of outer radius used as inner hole. */
+    /** 0 = pie, 0.6 = donut. Fraction of the outer radius used as an inner hole. */
     innerRadiusRatio: number;
-    /** Gap between slices in radians (default 0.02). */
+    /** Gap between slices in degrees. Default: 1.15° (≈ 0.02 rad). */
     padAngle: number;
-    /** Slice border color (default transparent). */
-    strokeColor: string;
-    /** Slice border width (default 0). */
-    strokeWidth: number;
-    /** Display label shown in tooltip. */
+    /** Display the label shown in the tooltip. */
     label?: string;
+    /** Per-slice label rendering on the pie itself. See {@link PieLabelsOptions}. */
+    sliceLabels?: PieLabelsOptions;
+    /**
+     * When `true`, enables pie motion effects: the outside-label entrance
+     * draw-in on mount / data swap, and the hover-explode slice offset.
+     * Default: `false` — labels paint fully on the first frame and hovered
+     * slices stay in place (hover feedback is left to the tooltip / legend /
+     * cursor). Enable for presentations where the motion adds narrative
+     * value.
+     */
+    animate?: boolean;
+    /**
+     * Ambient *outer* drop-shadow behind each slice. Adds lift for flat
+     * dashboards. Omit / `false` to disable (default). `true` uses soft
+     * defaults; pass an object to tune individually.
+     */
+    shadow?: boolean | {
+        /** Shadow color. Default: `rgba(0, 0, 0, 0.22)`. */
+        color?: string;
+        /** Blur radius in CSS pixels. Default: 24. */
+        blur?: number;
+        /** Horizontal offset in CSS pixels. Default: 0. */
+        offsetX?: number;
+        /** Vertical offset in CSS pixels. Default: 10. */
+        offsetY?: number;
+    };
+    /**
+     * Inner rim darkening — a dark band near each slice's outer edge that
+     * gives the pie an "inset" / pressed look. Implemented by extending the
+     * per-slice radial gradient with a dark edge stop, so it pairs naturally
+     * with the existing depth gradient. Omit / `false` to disable (default).
+     */
+    innerShadow?: boolean | {
+        /**
+         * Rim color. Default: `rgba(0, 0, 0, 0.1)` (blended over the slice
+         * color). Accepts any CSS color.
+         */
+        color?: string;
+        /**
+         * Fraction of the slice's radial span covered by the darkened band
+         * (0..1). Default: 0.3 — darkening starts at 70% of the radius.
+         */
+        depth?: number;
+    };
 }
 
 declare interface PieSeriesProps {
     data: PieSliceData[];
     options?: Partial<PieSeriesOptions>;
-    /** Stable series ID. Prefer this over `onSeriesId` — same value across remounts. */
+    /** Stable series ID — same value across remounts. */
     id?: string;
-    /** @deprecated Use the `id` prop instead. */
-    onSeriesId?: (id: string) => void;
 }
 
 /** Optional min/max constraints for the Y axis. Omit a side for automatic scaling. */
@@ -568,10 +1362,24 @@ export declare interface PieSliceData {
 }
 
 /** Tooltip for pie/donut charts. Shows hovered slice label, value, and percentage. */
-export declare function PieTooltip({ seriesId }: PieTooltipProps): JSX_2.Element | null;
+export declare function PieTooltip({ seriesId, format, children }: PieTooltipProps): JSX_2.Element | null;
 
 declare interface PieTooltipProps {
-    seriesId: string;
+    /**
+     * Owning series id. **Optional** — when omitted, the first visible pie
+     * series is picked.
+     */
+    seriesId?: string;
+    /** Custom formatter for the slice value. Default: shared `formatCompact`. */
+    format?: ValueFormatter;
+    /** Render-prop escape hatch — receives hover info + format, replaces default UI. */
+    children?: (ctx: PieTooltipRenderContext) => ReactNode;
+}
+
+/** Context passed to the {@link PieTooltip} render-prop. */
+declare interface PieTooltipRenderContext {
+    readonly info: HoverInfo;
+    readonly format: ValueFormatter;
 }
 
 export declare const quietLight: ThemePreset;
@@ -588,6 +1396,32 @@ export declare const rosePineDawn: ThemePreset;
 
 export declare const sandDune: ThemePreset;
 
+/**
+ * Frozen, per-row snapshot of a series at a single point in time. The shape
+ * `buildHoverSnapshots` / `buildLastSnapshots` return to overlay slot
+ * consumers.
+ *
+ * **Two identities, one snapshot:**
+ * - `id` is the **row key** — guaranteed unique within the returned array,
+ *   safe for React `key`, Vue `:key`, Svelte `each … (key)`. For single-layer
+ *   series this equals the `seriesId`; for multi-layer series it's
+ *   `${seriesId}_layer${layerIndex}`.
+ * - `seriesId` is the **owning series identity** — never carries a layer
+ *   suffix, not unique across multi-layer rows. Use it for filtering or
+ *   grouping (e.g. `snapshots.filter(s => s.seriesId === 'btc')`).
+ *
+ * `data` is a shallow clone, frozen along with the snapshot itself — a slot
+ * consumer cannot accidentally mutate the chart's internal store.
+ */
+export declare interface SeriesSnapshot {
+    readonly id: string;
+    readonly seriesId: string;
+    readonly layerIndex?: number;
+    readonly label?: string;
+    readonly data: Readonly<OHLCData> | Readonly<TimePoint>;
+    readonly color: string;
+}
+
 /** Supported primary series types. */
 export declare type SeriesType = 'candlestick' | 'line' | 'bar' | 'pie';
 
@@ -597,9 +1431,14 @@ declare interface Size {
     height: number;
 }
 
+export declare type SliceInfo = HoverInfo;
+
+/** Sort order applied to a snapshot list by the helper. */
+export declare type SnapshotSort = 'none' | 'asc' | 'desc';
+
 export declare const solarizedLight: ThemePreset;
 
-export declare function Sparkline({ data, theme, variant, valuePosition, formatValue, label, sublabel, color, negativeColor, areaFill, width, height, lineWidth, gradient, style, }: SparklineProps): JSX_2.Element;
+export declare function Sparkline({ data, theme, variant, valuePosition, formatValue, label, sublabel, color, negativeColor, area, areaFill, width, height, strokeWidth, gradient, style, }: SparklineProps): JSX_2.Element;
 
 export declare interface SparklineProps {
     data: TimePoint[];
@@ -619,13 +1458,17 @@ export declare interface SparklineProps {
     /** Secondary color for negative bars */
     negativeColor?: string;
     /** Show area fill under line */
+    area?: {
+        visible: boolean;
+    };
+    /** @deprecated Use {@link area} instead. */
     areaFill?: boolean;
     /** Chart width (default: 140) */
     width?: number;
     /** Overall height (default: 48) */
     height?: number;
-    /** Line width (default: 1.5) */
-    lineWidth?: number;
+    /** Stroke width in CSS pixels (default: 1.5) */
+    strokeWidth?: number;
     /** Show chart background gradient (default: true) */
     gradient?: boolean;
     /** Container style override */
@@ -675,13 +1518,17 @@ export declare interface ThemePreset {
 
 export declare const ThemeProvider: Provider<ChartTheme | null>;
 
-/** All built-in themes keyed by display name */
-export declare const themes: Record<string, ThemePreset>;
-
-declare function TimeAxis(): JSX_2.Element;
+declare function TimeAxis({ labelCount, minLabelSpacing }?: TimeAxisProps): JSX_2.Element;
 export { TimeAxis }
 export { TimeAxis as XAxis }
 
+declare interface TimeAxisProps {
+    /** Desired number of labels (≥ 2). Overrides chart-level `axis.x.labelCount`. */
+    labelCount?: number;
+    /** Minimum pixel gap between adjacent labels (hard floor). Overrides chart-level. */
+    minLabelSpacing?: number;
+}
+
 /** A single time-value data point for line and bar series. Time is a timestamp in milliseconds. */
 export declare interface TimePoint {
     time: number;
@@ -698,19 +1545,50 @@ declare class TimeScale {
     private to;
     private width;
     private pixelRatio;
-    update(range: VisibleRange, mediaWidth: number, pixelRatio: number): void;
+    private dataInterval;
+    private labelCountHintValue;
+    private minSpacingValue;
+    private resolvedInterval;
+    private lastInterval;
+    /**
+     * "want" (desired interval post-floor) at the time lastInterval was snapped.
+     * Hysteresis band anchors to this so micro range drift back across a tier
+     * boundary doesn't flip the label density — mirrors YScale, see there for
+     * the full reasoning.
+     */
+    private lastWant;
+    /** Identifies the dataInterval bucket whose tier list drove lastInterval. */
+    private lastBucketKey;
+    private get labelCountHint();
+    private get minLabelSpacing();
+    update(range: VisibleRange, mediaWidth: number, pixelRatio: number, dataInterval?: number): void;
+    setLabelCount(n: number | null | undefined): void;
+    setMinSpacing(px: number | null | undefined): void;
+    private resetHysteresis;
     timeToX(time: number): number;
     timeToBitmapX(time: number): number;
     xToTime(x: number): number;
     pixelDeltaToTimeDelta(pixelDelta: number): number;
     barWidthMedia(dataInterval: number): number;
     barWidthBitmap(dataInterval: number): number;
+    /**
+     * Evenly spaced "nice" tick times. Resolution uses the cached
+     * `dataInterval` set by `update()`; callers that bypass `update()` can
+     * still pass it here for back-compat.
+     */
     niceTickValues(dataInterval: number): {
         ticks: number[];
         tickInterval: number;
     };
     getRange(): VisibleRange;
     getMediaWidth(): number;
+    /**
+     * Resolve the next tick interval. Walks `niceTimeIntervals(dataInterval)`
+     * looking for the smallest tier ≥ desired spacing; retains the previous
+     * tier inside a ratio band so micro pan/zoom doesn't flip label density.
+     */
+    private resolveInterval;
+    private countTicks;
 }
 
 /**
@@ -720,25 +1598,116 @@ declare class TimeScale {
 export declare type TimeValue = number | Date;
 
 /**
- * Two-part tooltip:
- * 1. Compact legend always visible in top-left
- * 2. Floating glass tooltip near cursor on hover
+ * Chart title / subtitle bar rendered as a flex row above the chart canvas
+ * (above {@link InfoBar} when both are present). Hoisted out of the
+ * overlay layer by {@link ChartContainer}, so browser flex layout reserves
+ * its height and ResizeObserver drives a Y-range recompute.
+ *
+ * Place it at the top of a chart's children — its slot in the DOM is
+ * determined by `ChartContainer`, not by source order:
+ * ```tsx
+ * <ChartContainer>
+ *   <Title sub="Live Candlestick">BTC/USD</Title>
+ *   <InfoBar />
+ *   <CandlestickSeries data={data} />
+ *   ...
+ * </ChartContainer>
+ * ```
+ */
+export declare function Title({ children, sub, style }: TitleProps): JSX_2.Element;
+
+/** Props for the {@link Title} component. */
+export declare interface TitleProps {
+    /** Primary label (e.g. "BTC/USD"). */
+    children?: ReactNode;
+    /**
+     * Secondary label rendered in a muted colour next to the primary one (e.g.
+     * "Live Candlestick", "1m", series count).
+     */
+    sub?: ReactNode;
+    /** Extra styles merged onto the flex row. */
+    style?: CSSProperties;
+}
+
+/**
+ * Floating near-cursor glass tooltip that appears while hovering the chart.
+ *
+ * Hover-only: without a crosshair position, the component renders `null`.
+ * The companion {@link InfoBar} shows last-known values when no hover is active.
  */
-export declare function Tooltip({ seriesId, sort, showLegend, legend }: TooltipProps): JSX_2.Element | null;
+export declare function Tooltip({ sort, format, children }: TooltipProps): JSX_2.Element | null;
+
+/** Fields surfaced to a `Tooltip` / `InfoBar` formatter. */
+export declare type TooltipField = 'open' | 'high' | 'low' | 'close' | 'volume' | 'value';
+
+/** Signature for the tooltip formatter — single prop, field hint. */
+export declare type TooltipFormatter = (value: number, field: TooltipField) => string;
+
+export declare interface TooltipPosition {
+    left: number;
+    top: number;
+}
+
+/**
+ * Pure positioning for a floating tooltip. Flip the tooltip to the other
+ * side of the cursor when the preferred side would overflow, then clamp
+ * into `[0, chart - size]` so the flipped side can't spill past the
+ * opposite edge either.
+ *
+ * Works for time-series tooltips anchoring to the crosshair and pie
+ * tooltips anchoring to a slice centroid alike — pass the chart bounds
+ * that match the overlay container (media size minus axis gutters for
+ * time-series, full media size for pie).
+ */
+export declare interface TooltipPositionArgs {
+    /** Cursor or anchor x in CSS pixels, relative to the chart area origin. */
+    x: number;
+    /** Cursor or anchor y in CSS pixels, relative to the chart area origin. */
+    y: number;
+    /** Plot-area width in CSS pixels. */
+    chartWidth: number;
+    /** Plot-area height in CSS pixels. */
+    chartHeight: number;
+    /** Tooltip box width in CSS pixels. */
+    tooltipWidth: number;
+    /** Tooltip box height in CSS pixels. */
+    tooltipHeight: number;
+    /** Gap between anchor and tooltip. Defaults to 16. */
+    offsetX?: number;
+    offsetY?: number;
+}
 
 /**
  * Props for the {@link Tooltip} component.
- * By default shows all series. Use `seriesId` to show one, or `sort` to order values.
+ * Renders the built-in floating glass panel by default. Pass a render-prop
+ * child to replace its *contents* — the positioned container (with flip/clamp)
+ * stays.
  */
-declare interface TooltipProps {
-    /** Show only this series. When omitted, show all series. */
-    seriesId?: string;
-    /** Sort order for line values when showing all series (default: 'none'). */
+export declare interface TooltipProps {
+    /** Sort order for line values (default: 'none'). */
     sort?: TooltipSort;
-    /** Show the compact legend strip in the top-left corner (default: true). */
-    showLegend?: boolean;
-    /** @deprecated Use `showLegend` instead. */
-    legend?: boolean;
+    /**
+     * Custom formatter for every displayed number in the default UI. Called per
+     * row with the field hint (`'open' | 'high' | 'low' | 'close' | 'volume' | 'value'`).
+     * Defaults: adaptive precision for ohlc/value, compact (K/M/B/T) for volume.
+     * Ignored when {@link children} is a render-prop.
+     */
+    format?: TooltipFormatter;
+    /**
+     * Render-prop escape hatch. Receives the hover snapshots and replaces the
+     * built-in panel contents. The floating container (positioning, blur glass,
+     * clamping) is preserved — use
+     * [`computeTooltipPosition`](../../core/src/tooltip-position.ts) directly if
+     * you need your own container.
+     */
+    children?: (ctx: TooltipRenderContext) => ReactNode;
+}
+
+/** Context passed to the {@link Tooltip} render-prop. */
+export declare interface TooltipRenderContext {
+    readonly snapshots: readonly SeriesSnapshot[];
+    /** Crosshair timestamp — the tooltip is hover-only, so this is always a real hover time. */
+    readonly time: number;
 }
 
 /** Sort order for multi-series tooltip values. */
@@ -771,6 +1740,28 @@ export declare function useVisibleRange(chart: ChartInstance): VisibleRange;
 
 export declare function useYRange(chart: ChartInstance): YRange;
 
+/**
+ * Default value formatters used across the chart library.
+ *
+ * Two shapes are exposed:
+ *   - `formatCompact` — compact K/M/B/T suffixes for large magnitudes, adaptive
+ *     precision for values < 1. Intended for axis labels, legends, pie slices.
+ *   - `formatPriceAdaptive` — full-precision display that scales decimal count
+ *     to the magnitude. Intended for tooltip rows where users want to read the
+ *     exact number.
+ *
+ * Both handle the full range of JS numbers the library is likely to see:
+ *   - 0, ±Infinity, NaN
+ *   - BTC-style sub-cent prices (0.00001234 → "0.00001234", not "1.234e-5")
+ *   - trillion-scale values (5.4e12 → "5.40T")
+ *   - Number.MAX_SAFE_INTEGER falls back to scientific notation (>= 1e15)
+ *
+ * Consumers can import these directly, or swap them in per-component via the
+ * `format` prop on Tooltip/InfoBar/YAxis/etc. (see framework wrappers).
+ */
+/** Signature for a value-to-string formatter (YAxis, YLabel, Pie, Sparkline, NumberFlow). */
+export declare type ValueFormatter = (value: number) => string;
+
 /** Time range (timestamps in milliseconds) of the currently visible portion of the chart. */
 export declare interface VisibleRange {
     from: number;
@@ -779,17 +1770,17 @@ export declare interface VisibleRange {
 
 /** Configuration for the X (time) axis. */
 export declare interface XAxisConfig {
-    /** Height in pixels. Default: 30. */
+    /** Height in CSS pixels. Default: 30. */
     height?: number;
     /** Whether the axis is visible. Default: true. When false, height is treated as 0. */
     visible?: boolean;
 }
 
-export declare function YAxis(): JSX_2.Element;
+export declare function YAxis({ format, labelCount, minLabelSpacing }?: YAxisProps): JSX_2.Element;
 
 /** Configuration for the Y axis. */
 export declare interface YAxisConfig {
-    /** Width in pixels. Default: 55. */
+    /** Width in CSS pixels. Default: 55. */
     width?: number;
     /** Minimum bound. Default: 'auto'. */
     min?: AxisBound;
@@ -799,12 +1790,59 @@ export declare interface YAxisConfig {
     visible?: boolean;
 }
 
-export declare function YLabel({ seriesId, color }: YLabelProps): JSX_2.Element | null;
+export declare interface YAxisProps {
+    /**
+     * Custom tick-label formatter. When supplied, overrides the built-in
+     * range-adaptive formatter for this axis.
+     */
+    format?: ValueFormatter;
+    /**
+     * Desired number of labels (≥ 2). Overrides any chart-level `axis.y.labelCount`.
+     * Realized count may differ ±1 after the 1-2-5 snap.
+     */
+    labelCount?: number;
+    /** Minimum pixel gap between adjacent labels (hard floor). Overrides chart-level. */
+    minLabelSpacing?: number;
+}
+
+export declare function YLabel({ seriesId, color, format, children }: YLabelProps): JSX_2.Element | null;
+
+/** Direction of the current value vs. previous close. Drives the badge color in the default UI. */
+declare type YLabelDirection = 'up' | 'down' | 'neutral';
 
 declare interface YLabelProps {
-    seriesId: string;
+    /**
+     * Owning series id. **Optional** — when omitted, the first visible
+     * single-layer time series is picked, falling back to the first visible
+     * multi-layer time series. `null` (no compatible series) renders nothing.
+     */
+    seriesId?: string;
     /** Override badge color (e.g. line color). If not set, uses up/down/neutral from theme. */
     color?: string;
+    /**
+     * Custom formatter. Routed through NumberFlow as its `format` prop so the
+     * digit-by-digit animation still plays on the output string — NumberFlow
+     * animates whichever characters the formatter returns.
+     */
+    format?: ValueFormatter;
+    /**
+     * Render-prop escape hatch. Receives the resolved value, pixel position, and
+     * direction metadata. Replaces the built-in badge + dashed line entirely.
+     */
+    children?: (ctx: YLabelRenderContext) => ReactNode;
+}
+
+/** Context passed to the {@link YLabel} render-prop. */
+declare interface YLabelRenderContext {
+    readonly value: number;
+    /** Pixel Y of the badge anchor (already account for current viewport). */
+    readonly y: number;
+    /** Final background color chosen by the built-in UI — handy if you want to match the dashed line accent. */
+    readonly bgColor: string;
+    /** `true` while the chart is tracking a live last point (still mutating). */
+    readonly isLive: boolean;
+    readonly direction: YLabelDirection;
+    readonly format: ValueFormatter;
 }
 
 /** Min/max value range for the Y axis. */
@@ -822,20 +1860,69 @@ declare class YScale {
     private max;
     private height;
     private pixelRatio;
+    private labelCountHintValue;
+    private minSpacingValue;
+    /** Cached {1,2,5}×10^k interval resolved at update-time; null when degenerate. */
+    private resolvedInterval;
+    /** Previous resolved interval — drives the ratio-band hysteresis. */
+    private lastInterval;
+    /**
+     * rawInterval at the moment `lastInterval` was snapped. Anchoring the
+     * hysteresis band to *raw-at-snap* (not `lastInterval`) is what creates
+     * naturally asymmetric tier hysteresis: after an escalation the band
+     * starts just above the tier boundary, so live range drift back across
+     * the boundary doesn't instantly flip back.
+     */
+    private lastRawInterval;
+    /** Custom formatter (driven by `<YAxis format=…>`). */
+    private customFormat;
+    private get labelCountHint();
+    private get minLabelSpacing();
     /** Recalculate the scale with a new Y range, chart height, and device pixel ratio. */
     update(range: YRange, mediaHeight: number, pixelRatio: number): void;
+    /** Desired label count. Invalid values (NaN, <2, Infinity) clear the hint. */
+    setLabelCount(n: number | null | undefined): void;
+    /** Minimum pixel gap between adjacent labels. */
+    setMinSpacing(px: number | null | undefined): void;
+    private resetHysteresis;
+    /** Install (or clear) a custom formatter. */
+    setFormat(fn: ValueFormatter | null): void;
+    /** Read back the currently installed formatter — null when the built-in is active. */
+    getFormat(): ValueFormatter | null;
     /** Convert a value to a Y position in CSS (media) pixels. */
     valueToY(value: number): number;
     /** Convert a value to a Y position in physical (bitmap) pixels. */
     valueToBitmapY(value: number): number;
     /** Convert a Y position in CSS pixels back to a value. */
     yToValue(y: number): number;
-    /** Generate evenly spaced "nice" tick values that fit the current range and chart height. */
+    /**
+     * Generate evenly spaced "nice" tick values for the current range and
+     * chart height. Pure read — resolution happens in `update()`.
+     */
     niceTickValues(): number[];
     getRange(): YRange;
     getMediaHeight(): number;
-    /** Format a value for display, adapting decimal places to the visible range magnitude. */
+    /**
+     * Format a tick value for display. When a custom formatter is installed
+     * (via {@link setFormat} or the `format` prop on `<YAxis>`), it wins;
+     * otherwise decimals are driven by the resolved tick interval — so
+     * ticks at step 100 never render as "42000.0" just because the visible
+     * range happens to be < 1000.
+     */
     formatY(value: number): string;
+    /**
+     * Resolve the interval to a {1,2,5}×10^k tick size that satisfies the pixel
+     * floor and (optionally) targets `labelCountHint` labels.
+     *
+     * Hysteresis: the band [0.8×, 1.25×] is anchored to **rawInterval at last
+     * snap**, not to `lastInterval`. After an escalation (e.g. 100 → 200),
+     * `lastRawInterval` sits just past the tier boundary, so typical live
+     * range drift back across the boundary stays inside the band and does
+     * *not* de-escalate. This prevents the 2-tier flicker users see when new
+     * candles nudge the Y range across a raw-interval threshold.
+     */
+    private resolveInterval;
+    private countTicks;
 }
 
 export { }