@wick-charts/vue 0.1.2 → 0.2.1

package/dist/index.d.ts

@@ -9,59 +9,142 @@ declare const __VLS_component: DefineComponent<__VLS_Props_3, {}, {}, {}, {}, Co
 theme: ChartTheme;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {
 containerRef: HTMLDivElement;
+topOverlayRef: HTMLDivElement;
+titleAnchor: HTMLDivElement;
+infoBarAnchor: HTMLDivElement;
+legendRightAnchor: HTMLDivElement;
+legendAnchor: HTMLDivElement;
 }, HTMLDivElement>;
 
+declare const __VLS_component_2: DefineComponent<__VLS_Props_6, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_6> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+declare const __VLS_component_3: DefineComponent<__VLS_Props_7, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_7> & Readonly<{}>, {
+position: "bottom" | "right";
+mode: LegendMode;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+declare const __VLS_component_4: DefineComponent<__VLS_Props_9, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_9> & Readonly<{}>, {
+format: ValueFormatter;
+mode: PieLegendMode;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+declare const __VLS_component_5: DefineComponent<__VLS_Props_10, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_10> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+containerRef: HTMLDivElement;
+}, any>;
+
+declare const __VLS_component_6: DefineComponent<__VLS_Props_11, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_11> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+declare const __VLS_component_7: DefineComponent<__VLS_Props_12, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_12> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+containerRef: HTMLDivElement;
+}, any>;
+
+declare const __VLS_component_8: DefineComponent<    {}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+
+declare const __VLS_component_9: DefineComponent<__VLS_Props_14, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_14> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
 declare type __VLS_Props = {
     data: TimePoint[][];
     options?: Partial<BarSeriesOptions>;
-    label?: string;
+    /** Stable series ID — same value across remounts. */
+    id?: string;
 };
 
 declare type __VLS_Props_10 = {
-    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;
+};
+
+declare type __VLS_Props_11 = {
+    sub?: string;
+};
+
+declare type __VLS_Props_12 = {
+    sort?: SnapshotSort;
+    format?: TooltipFormatter;
+};
+
+declare type __VLS_Props_13 = {
+    /** Custom tick-label formatter. Overrides the built-in range-adaptive default. */
+    format?: ValueFormatter;
+};
+
+declare type __VLS_Props_14 = {
+    /**
+     * 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.
+     */
+    seriesId?: string;
     color?: string;
+    /** Custom formatter; routed through NumberFlow's `formatter` so the digit animation still plays. */
+    format?: ValueFormatter;
 };
 
 declare type __VLS_Props_2 = {
     data: OHLCInput[];
     options?: Partial<CandlestickSeriesOptions>;
+    /** Stable series ID — same value across remounts. */
+    id?: string;
 };
 
 declare type __VLS_Props_3 = {
     theme?: ChartTheme;
     axis?: AxisConfig;
+    /** Background grid configuration. Default: `{ visible: true }`. */
+    grid?: {
+        visible: boolean;
+    };
 };
 
 declare type __VLS_Props_4 = {
     data: TimePoint[][];
     options?: Partial<LineSeriesOptions>;
-    label?: string;
+    /** Stable series ID — same value across remounts. */
+    id?: string;
 };
 
 declare type __VLS_Props_5 = {
     data: PieSliceData[];
     options?: Partial<PieSeriesOptions>;
+    /** Stable series ID — same value across remounts. */
+    id?: string;
 };
 
 declare type __VLS_Props_6 = {
-    value: number;
-    format?: Intl.NumberFormatOptions;
-    locale?: string;
-    spinDuration?: number;
+    sort?: SnapshotSort;
+    format?: TooltipFormatter;
 };
 
 declare type __VLS_Props_7 = {
-    seriesId: string;
-    format?: 'value' | 'percent';
+    items?: LegendItemOverride[];
+    position?: 'bottom' | 'right';
+    /** `'isolate'` shows only the clicked item; `'solo'` is a @deprecated alias. */
+    mode?: LegendMode;
 };
 
 declare type __VLS_Props_8 = {
-    seriesId: string;
+    value: number;
+    /** Value-to-string formatter. Defaults to the current locale's `Intl.NumberFormat`. */
+    format?: (value: number) => string;
+    locale?: string;
+    spinDuration?: number;
 };
 
 declare type __VLS_Props_9 = {
+    /**
+     * Owning series id. **Optional** — when omitted, the first visible pie
+     * series is picked.
+     */
     seriesId?: string;
-    sort?: TooltipSort;
+    /** 'value' shows only the value, 'percent' only the percent, 'both' shows both. Default: 'both'. */
+    mode?: PieLegendMode;
+    /** Custom formatter for the absolute slice value. */
+    format?: ValueFormatter;
 };
 
 declare function __VLS_template(): {
@@ -71,20 +154,297 @@ declare function __VLS_template(): {
     };
     refs: {
         containerRef: HTMLDivElement;
+        topOverlayRef: HTMLDivElement;
+        titleAnchor: HTMLDivElement;
+        infoBarAnchor: HTMLDivElement;
+        legendRightAnchor: HTMLDivElement;
+        legendAnchor: HTMLDivElement;
     };
     rootEl: HTMLDivElement;
 };
 
+declare function __VLS_template_2(): {
+    attrs: Partial<{}>;
+    slots: Readonly<{
+        default?(ctx: {
+            snapshots: readonly SeriesSnapshot[];
+            time: number;
+            isHover: boolean;
+        }): unknown;
+    }> & {
+        default?(ctx: {
+            snapshots: readonly SeriesSnapshot[];
+            time: number;
+            isHover: boolean;
+        }): unknown;
+    };
+    refs: {};
+    rootEl: any;
+};
+
+declare function __VLS_template_3(): {
+    attrs: Partial<{}>;
+    slots: Readonly<{
+        default?(ctx: {
+            items: readonly LegendItem[];
+        }): unknown;
+    }> & {
+        default?(ctx: {
+            items: readonly LegendItem[];
+        }): unknown;
+    };
+    refs: {};
+    rootEl: any;
+};
+
+declare function __VLS_template_4(): {
+    attrs: Partial<{}>;
+    slots: Readonly<{
+        default?(ctx: {
+            slices: readonly SliceInfo[];
+            mode: PieLegendMode;
+            format: ValueFormatter;
+        }): unknown;
+    }> & {
+        default?(ctx: {
+            slices: readonly SliceInfo[];
+            mode: PieLegendMode;
+            format: ValueFormatter;
+        }): unknown;
+    };
+    refs: {};
+    rootEl: any;
+};
+
+declare function __VLS_template_5(): {
+    attrs: Partial<{}>;
+    slots: Readonly<{
+        default?(ctx: {
+            info: HoverInfo;
+            format: ValueFormatter;
+        }): unknown;
+    }> & {
+        default?(ctx: {
+            info: HoverInfo;
+            format: ValueFormatter;
+        }): unknown;
+    };
+    refs: {
+        containerRef: HTMLDivElement;
+    };
+    rootEl: any;
+};
+
+declare function __VLS_template_6(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+
+declare function __VLS_template_7(): {
+    attrs: Partial<{}>;
+    slots: Readonly<{
+        default?(ctx: {
+            snapshots: readonly SeriesSnapshot[];
+            time: number;
+        }): unknown;
+    }> & {
+        default?(ctx: {
+            snapshots: readonly SeriesSnapshot[];
+            time: number;
+        }): unknown;
+    };
+    refs: {
+        containerRef: HTMLDivElement;
+    };
+    rootEl: any;
+};
+
+declare function __VLS_template_8(): {
+    attrs: Partial<{}>;
+    slots: Readonly<{
+        default?(ctx: {
+            snapshots: readonly SeriesSnapshot[];
+            time: number;
+            isHover: boolean;
+        }): unknown;
+    }> & {
+        default?(ctx: {
+            snapshots: readonly SeriesSnapshot[];
+            time: number;
+            isHover: boolean;
+        }): unknown;
+    };
+    refs: {};
+    rootEl: any;
+};
+
+declare function __VLS_template_9(): {
+    attrs: Partial<{}>;
+    slots: Readonly<{
+        default?(ctx: {
+            value: number;
+            y: number;
+            bgColor: string;
+            isLive: boolean;
+            direction: YLabelDirection;
+            format: ValueFormatter;
+        }): unknown;
+    }> & {
+        default?(ctx: {
+            value: number;
+            y: number;
+            bgColor: string;
+            isLive: boolean;
+            direction: YLabelDirection;
+            format: ValueFormatter;
+        }): unknown;
+    };
+    refs: {};
+    rootEl: any;
+};
+
 declare type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
 
+declare type __VLS_TemplateResult_2 = ReturnType<typeof __VLS_template_2>;
+
+declare type __VLS_TemplateResult_3 = ReturnType<typeof __VLS_template_3>;
+
+declare type __VLS_TemplateResult_4 = ReturnType<typeof __VLS_template_4>;
+
+declare type __VLS_TemplateResult_5 = ReturnType<typeof __VLS_template_5>;
+
+declare type __VLS_TemplateResult_6 = ReturnType<typeof __VLS_template_6>;
+
+declare type __VLS_TemplateResult_7 = ReturnType<typeof __VLS_template_7>;
+
+declare type __VLS_TemplateResult_8 = ReturnType<typeof __VLS_template_8>;
+
+declare type __VLS_TemplateResult_9 = ReturnType<typeof __VLS_template_9>;
+
 declare type __VLS_WithTemplateSlots<T, S> = T & {
     new (): {
         $slots: S;
     };
 };
 
+declare type __VLS_WithTemplateSlots_2<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+declare type __VLS_WithTemplateSlots_3<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+declare type __VLS_WithTemplateSlots_4<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+declare type __VLS_WithTemplateSlots_5<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+declare type __VLS_WithTemplateSlots_6<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+declare type __VLS_WithTemplateSlots_7<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+declare type __VLS_WithTemplateSlots_8<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+declare type __VLS_WithTemplateSlots_9<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
 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.
  *
@@ -103,11 +463,17 @@ export declare interface AxisConfig {
 
 export declare const ayuMirage: ThemePreset;
 
-export declare const BarSeries: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
-seriesId: (id: string) => any;
-}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
-onSeriesId?: ((id: string) => any) | undefined;
-}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+/**
+ * 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 const BarSeries: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** Visual options for a bar series. */
 export declare interface BarSeriesOptions {
@@ -118,19 +484,100 @@ 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;
 }
 
 /** @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 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 const CandlestickSeries: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
-seriesId: (id: string) => any;
-}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{
-onSeriesId?: ((id: string) => any) | undefined;
-}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const CandlestickSeries: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** Visual options for a candlestick series. */
 export declare interface CandlestickSeriesOptions {
@@ -143,7 +590,42 @@ 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;
 }
 
 export declare const catppuccin: ThemePreset;
@@ -156,6 +638,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;
 }
 
 /**
@@ -180,44 +670,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;
@@ -227,6 +711,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. */
@@ -239,57 +739,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 /
+     * TooltipLegend 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. */
@@ -303,8 +875,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. */
@@ -314,7 +895,6 @@ export declare interface ChartLayout {
     xAxisHeight: number;
 }
 
-/** Options passed when creating a new {@link ChartInstance}. */
 export declare interface ChartOptions {
     theme?: ChartTheme;
     axis?: AxisConfig;
@@ -334,8 +914,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;
+    });
 }
 
 /**
@@ -399,6 +1021,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.
@@ -425,6 +1049,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;
@@ -433,10 +1078,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;
@@ -445,8 +1117,65 @@ 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;
+}
+
+export declare const InfoBar: __VLS_WithTemplateSlots_2<typeof __VLS_component_2, __VLS_TemplateResult_2["slots"]>;
+
 export declare const lavenderMist: ThemePreset;
 
+export declare const Legend: __VLS_WithTemplateSlots_3<typeof __VLS_component_3, __VLS_TemplateResult_3["slots"]>;
+
+/**
+ * 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. The
+ * canonical {@link LegendItem} (re-exported from `@wick-charts/core`) carries
+ * the full identity + closures; those aren't meaningful for a pre-baked,
+ * non-interactive legend.
+ */
+declare interface LegendItemOverride {
+    label: string;
+    color: string;
+}
+
+declare type LegendMode = 'toggle' | 'isolate' | 'solo';
+
 export declare const lightPink: ThemePreset;
 
 export declare const lightTheme: ChartTheme;
@@ -454,11 +1183,15 @@ export declare const lightTheme: ChartTheme;
 /** @deprecated Use {@link TimePoint} instead. */
 export declare type LineData = TimePoint;
 
-export declare const LineSeries: DefineComponent<__VLS_Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
-seriesId: (id: string) => any;
-}, string, PublicProps, Readonly<__VLS_Props_4> & Readonly<{
-onSeriesId?: ((id: string) => any) | undefined;
-}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+/**
+ * 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 const LineSeries: DefineComponent<__VLS_Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_4> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** Visual options for a line series. */
 export declare interface LineSeriesOptions {
@@ -466,13 +1199,59 @@ 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 type Listener = (...args: any[]) => void;
@@ -490,7 +1269,7 @@ export declare const nightOwl: ThemePreset;
 /** Convert a {@link TimeValue} (number ms or Date) to a millisecond timestamp. */
 export declare function normalizeTime(t: TimeValue): number;
 
-export declare const NumberFlow: DefineComponent<__VLS_Props_6, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_6> & Readonly<{}>, {
+export declare const NumberFlow: DefineComponent<__VLS_Props_8, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_8> & Readonly<{}>, {
 locale: string;
 spinDuration: number;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLSpanElement>;
@@ -516,30 +1295,216 @@ export declare const panda: ThemePreset;
 
 export declare const peachCream: ThemePreset;
 
-export declare const PieLegend: DefineComponent<__VLS_Props_7, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_7> & Readonly<{}>, {
-format: "value" | "percent";
-}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+/**
+ * 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 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 const PieLegend: __VLS_WithTemplateSlots_4<typeof __VLS_component_4, __VLS_TemplateResult_4["slots"]>;
+
+declare type PieLegendMode = 'value' | 'percent' | 'both';
 
-export declare const PieSeries: DefineComponent<__VLS_Props_5, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
-seriesId: (id: string) => any;
-}, string, PublicProps, Readonly<__VLS_Props_5> & Readonly<{
-onSeriesId?: ((id: string) => any) | undefined;
-}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const PieSeries: DefineComponent<__VLS_Props_5, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_5> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** 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;
+    };
 }
 
 /** Optional min/max constraints for the Y axis. Omit a side for automatic scaling. */
@@ -551,7 +1516,7 @@ export declare interface PieSliceData {
     color?: string;
 }
 
-export declare const PieTooltip: DefineComponent<__VLS_Props_8, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_8> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const PieTooltip: __VLS_WithTemplateSlots_5<typeof __VLS_component_5, __VLS_TemplateResult_5["slots"]>;
 
 export declare const quietLight: ThemePreset;
 
@@ -567,6 +1532,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';
 
@@ -576,6 +1567,11 @@ 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;
 
 /** Stacking mode for bar/line series: off (overlap), normal (stacked), percent (100% stacked). */
@@ -615,9 +1611,6 @@ export declare interface ThemePreset {
     backgroundSize?: string;
 }
 
-/** All built-in themes keyed by display name */
-export declare const themes: Record<string, ThemePreset>;
-
 export declare const TimeAxis: DefineComponent<    {}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, HTMLDivElement>;
 
 /** A single time-value data point for line and bar series. Time is a timestamp in milliseconds. */
@@ -636,19 +1629,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;
 }
 
 /**
@@ -657,11 +1681,51 @@ declare class TimeScale {
  */
 export declare type TimeValue = number | Date;
 
-export declare const Tooltip: DefineComponent<__VLS_Props_9, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_9> & Readonly<{}>, {
-sort: TooltipSort;
-}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const Title: __VLS_WithTemplateSlots_6<typeof __VLS_component_6, __VLS_TemplateResult_6["slots"]>;
+
+export declare const Tooltip: __VLS_WithTemplateSlots_7<typeof __VLS_component_7, __VLS_TemplateResult_7["slots"]>;
+
+/** Fields surfaced to a `Tooltip` / `TooltipLegend` 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 const TooltipLegend: __VLS_WithTemplateSlots_8<typeof __VLS_component_8, __VLS_TemplateResult_8["slots"]>;
+
+export declare interface TooltipPosition {
+    left: number;
+    top: number;
+}
 
-declare type TooltipSort = 'none' | 'asc' | 'desc';
+/**
+ * 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;
+}
 
 /** Font family and size tokens used across the chart. */
 export declare interface Typography {
@@ -689,6 +1753,28 @@ export declare function useVisibleRange(chart: ChartInstance): Ref<VisibleRange>
 
 export declare function useYRange(chart: ChartInstance): Ref<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/TooltipLegend/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;
@@ -697,17 +1783,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 const YAxis: DefineComponent<    {}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, HTMLDivElement>;
+export declare const YAxis: DefineComponent<__VLS_Props_13, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_13> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
 
 /** 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;
@@ -717,7 +1803,10 @@ export declare interface YAxisConfig {
     visible?: boolean;
 }
 
-export declare const YLabel: DefineComponent<__VLS_Props_10, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_10> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const YLabel: __VLS_WithTemplateSlots_9<typeof __VLS_component_9, __VLS_TemplateResult_9["slots"]>;
+
+/** Direction of the current value vs. previous close. Drives the badge color in the default UI. */
+declare type YLabelDirection = 'up' | 'down' | 'neutral';
 
 /** Min/max value range for the Y axis. */
 export declare interface YRange {
@@ -734,20 +1823,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 { }