@wick-charts/vue 0.5.1 → 0.6.1

package/dist/index.d.ts

@@ -6,8 +6,15 @@ import { Ref } from 'vue';
 import { ShallowRef } from 'vue';
 
 declare const __VLS_component: DefineComponent<__VLS_Props_3, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_3> & Readonly<{}>, {
+fade: boolean | {
+top?: number;
+overlap?: number;
+right?: number;
+left?: number;
+};
 theme: ChartTheme;
 gradient: boolean;
+interactive: boolean;
 headerLayout: "overlay" | "inline";
 }, {}, {}, {}, string, ComponentProvideOptions, false, {
 titleAnchor: HTMLDivElement;
@@ -19,30 +26,30 @@ legendAnchor: HTMLDivElement;
 navigatorAnchor: 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_2: DefineComponent<__VLS_Props_8, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_8> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
-declare const __VLS_component_3: DefineComponent<__VLS_Props_7, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_7> & Readonly<{}>, {
+declare const __VLS_component_3: DefineComponent<__VLS_Props_9, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_9> & Readonly<{}>, {
 position: "bottom" | "right";
 mode: LegendMode;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
-declare const __VLS_component_4: DefineComponent<__VLS_Props_11, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_11> & Readonly<{}>, {
+declare const __VLS_component_4: DefineComponent<__VLS_Props_13, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_13> & Readonly<{}>, {
 position: PieLegendPosition;
 format: ValueFormatter;
 mode: PieLegendMode;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
-declare const __VLS_component_5: DefineComponent<__VLS_Props_12, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_12> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+declare const __VLS_component_5: DefineComponent<__VLS_Props_14, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_14> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 containerRef: HTMLDivElement;
 }, any>;
 
-declare const __VLS_component_6: DefineComponent<__VLS_Props_16, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_16> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+declare const __VLS_component_6: DefineComponent<__VLS_Props_18, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_18> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
-declare const __VLS_component_7: DefineComponent<__VLS_Props_17, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_17> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+declare const __VLS_component_7: DefineComponent<__VLS_Props_19, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_19> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 containerRef: HTMLDivElement;
 }, any>;
 
-declare const __VLS_component_8: DefineComponent<__VLS_Props_19, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_19> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+declare const __VLS_component_8: DefineComponent<__VLS_Props_21, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_21> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 declare type __VLS_Props = {
     /** Flat `TimePoint[]`, `TimePoint[][]`, or named `{ label, color?, data }` layers. Time accepts ms or `Date`. */
@@ -50,9 +57,34 @@ declare type __VLS_Props = {
     options?: Partial<BarSeriesOptions>;
     /** Stable series ID — same value across remounts. */
     id?: string;
+    /** Show/hide the series without unmounting it — excludes it from the Y-range fit and tooltip/legend. Default `true`. Live. */
+    visible?: boolean;
 };
 
 declare type __VLS_Props_10 = {
+    /** X anchor — epoch ms or a `Date`. */
+    time: TimeValue;
+    /** Y anchor as a data value. Omit and set `seriesId` to snap to that series' value at `time`. */
+    value?: number;
+    /** Snap Y to this series' value at `time` when `value` is omitted. Also the default color source. */
+    seriesId?: string;
+    /** Glyph at the anchor. Default: `'dot'`. Arrows point their tip at the anchor. */
+    shape?: MarkerShape;
+    /** Reuse the line pulse halo around the anchor. Default: `false`. */
+    pulse?: boolean;
+    /** Optional text label drawn as a callout chip whose tail points at the anchor. */
+    label?: string;
+    /** Color override. Falls back to the series color (when `seriesId` is set), then the theme line color. */
+    color?: string;
+};
+
+declare type __VLS_Props_11 = {
+    data: NavigatorData;
+    /** Strip height in CSS pixels. Defaults to `theme.navigator.height` (60). */
+    height?: number;
+};
+
+declare type __VLS_Props_12 = {
     value: number;
     /**
      * Value-to-string formatter. Defaults to the current locale's
@@ -64,7 +96,7 @@ declare type __VLS_Props_10 = {
     spinDuration?: number;
 };
 
-declare type __VLS_Props_11 = {
+declare type __VLS_Props_13 = {
     /**
      * Owning series id. **Optional** — when omitted, the first visible pie
      * series is picked.
@@ -78,7 +110,7 @@ declare type __VLS_Props_11 = {
     position?: PieLegendPosition;
 };
 
-declare type __VLS_Props_12 = {
+declare type __VLS_Props_14 = {
     /**
      * Owning series id. **Optional** — when omitted, the first visible pie
      * series is picked.
@@ -88,14 +120,14 @@ declare type __VLS_Props_12 = {
     format?: ValueFormatter;
 };
 
-declare type __VLS_Props_13 = {
+declare type __VLS_Props_15 = {
     /** Horizontal line at this Y data value. Mutually exclusive with `time`. */
     value?: number;
     /** Vertical line at this `time` (epoch ms or `Date`). Mutually exclusive with `value`. */
     time?: TimeValue;
-    /** Line and label-pill color. Default: the theme line color. */
+    /** Line and label-chip accent color. Default: the theme line color. */
     color?: string;
-    /** Optional text label drawn in a pill at the line's near end. */
+    /** Optional text label drawn in an annotation chip at the line's near end. */
     label?: string;
     /** Dash style. Default: `'dashed'`. */
     style?: ReferenceLineStyle;
@@ -103,27 +135,27 @@ declare type __VLS_Props_13 = {
     width?: number;
 };
 
-declare type __VLS_Props_14 = {
+declare type __VLS_Props_16 = {
     /** 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;
 };
 
-declare type __VLS_Props_15 = {
+declare type __VLS_Props_17 = {
     /** Left edge — epoch ms or a `Date`. */
     from: TimeValue;
     /** Right edge — epoch ms or a `Date`. Omit (or pass `'now'`) for an open-ended band to the right edge. */
     to?: TimeRegionEnd;
     /** Band fill — any CSS color, typically translucent. Default: a faint tint of `color`. */
     fill?: string;
-    /** Optional text label drawn in a pill at the top of the band. */
+    /** Optional text label drawn in an annotation chip at the top of the band. */
     label?: string;
-    /** Edge-line and label-pill accent. Default: the theme's muted axis text color. */
+    /** Edge-line and label-chip accent. Default: the theme's muted axis text color. */
     color?: string;
 };
 
-declare type __VLS_Props_16 = {
+declare type __VLS_Props_18 = {
     /**
      * @deprecated Use the named `sub` slot instead — it accepts arbitrary
      * inline markup (icons, badges, formatted text) to mirror React's
@@ -137,12 +169,22 @@ declare type __VLS_Props_16 = {
     sub?: string;
 };
 
-declare type __VLS_Props_17 = {
+declare type __VLS_Props_19 = {
     sort?: SnapshotSort;
     format?: TooltipFormatter;
 };
 
-declare type __VLS_Props_18 = {
+declare type __VLS_Props_2 = {
+    /** Flat `OHLCInput[]`, or `{ label, data }` to name the stream. */
+    data: CandlestickData;
+    options?: Partial<CandlestickSeriesOptions>;
+    /** Stable series ID — same value across remounts. */
+    id?: string;
+    /** Show/hide the series without unmounting it — excludes it from the Y-range fit and tooltip/legend. Default `true`. Live. */
+    visible?: boolean;
+};
+
+declare type __VLS_Props_20 = {
     /** Custom tick-label formatter. Overrides the built-in range-adaptive default. */
     format?: ValueFormatter;
     /**
@@ -154,7 +196,7 @@ declare type __VLS_Props_18 = {
     minLabelSpacing?: number;
 };
 
-declare type __VLS_Props_19 = {
+declare type __VLS_Props_21 = {
     /**
      * Owning series id. **Optional** — when omitted, the first visible
      * single-layer time series is picked, falling back to the first visible
@@ -164,18 +206,17 @@ declare type __VLS_Props_19 = {
     color?: string;
     /** Custom formatter; routed through NumberFlow's `formatter` so the digit animation still plays. */
     format?: ValueFormatter;
-};
-
-declare type __VLS_Props_2 = {
-    /** Flat `OHLCInput[]`, or `{ label, data }` to name the stream. */
-    data: CandlestickData;
-    options?: Partial<CandlestickSeriesOptions>;
-    /** Stable series ID — same value across remounts. */
-    id?: string;
+    /**
+     * Badge motion. `true` (default) glides + counts up + fades in with the
+     * intro; `false` snaps with no easing; an object tunes individual parts.
+     */
+    animate?: YLabelAnimate;
 };
 
 declare type __VLS_Props_3 = {
+    /** Visual theme. Live — changing this at runtime updates all themed elements. */
     theme?: ChartTheme;
+    /** Grouped axis configuration (Y/X visibility, bounds, sizing). Live. */
     axis?: AxisConfig;
     /**
      * Viewport padding. `top`/`bottom` are in pixels. `left`/`right` accept either pixels (`50`)
@@ -215,16 +256,62 @@ declare type __VLS_Props_3 = {
          */
         initialRange?: VisibleRangeSpec;
     };
-    /** Show the chart background gradient. Defaults to true. */
+    /**
+     * Controlled visible range. Same shape as the imperative
+     * `chart.setVisibleRange` — a bar count, an explicit `{from, to}` window,
+     * or `{from, bars}`. Every reference/value change applies via
+     * `chart.setVisibleRange`, so pair it with `onVisibleRangeChange` for a
+     * two-way binding; a same-value literal (compared structurally) is a
+     * no-op, so an inline object doesn't re-apply on every render.
+     *
+     * For a one-shot initial window that isn't re-applied on every prop
+     * change, use `viewport.initialRange` instead.
+     */
+    visibleRange?: VisibleRangeSpec;
+    /** Show the chart background gradient. Live. Defaults to true. */
     gradient?: boolean;
-    /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
+    /**
+     * Enable zoom, pan, and crosshair interactions. Defaults to true.
+     *
+     * Mount-only — core has no `setInteractive`, so changing this prop after
+     * mount is ignored.
+     */
     interactive?: boolean;
-    /** Background grid configuration. Default: `{ visible: true }`. */
+    /** Background grid configuration. Live. Default: `{ visible: true }`. */
     grid?: {
         visible: boolean;
     };
     /**
-     * How `<Title>` and `<InfoBar>` are positioned relative to the canvas.
+     * Soft fade-out at the top of the plot area, so series content dissolves
+     * under a floating `<Title>` / `<InfoBar>` instead of colliding with it.
+     * The mask erases canvas alpha rather than painting a cover color, so it
+     * stays correct over the default background gradient. Live.
+     *
+     * Two directions, independently controlled:
+     *
+     * **X (under the axis)** — panning content slides under the Y-axis
+     * column and dissolves instead of hard-clipping at the pane edge. **On
+     * by default** as a 60px ramp that finishes just inside the axis
+     * column, before the label glyphs; `{ right }` overrides the total
+     * ramp width in CSS px (`0` disables). `{ left }` adds the mirror zone
+     * at the left pane edge (default off).
+     *
+     * **Top (under the header)** — opt-in. `true` enables the auto zone
+     * (measured header + 24px run-out, half the header fold-in released so
+     * data rides up into the zone at rest), `{ top }` sets the zone height
+     * explicitly, and `{ overlap }` tunes how many px of the fold-in to
+     * release (0 keeps the strict fold-in). Off unless one of those is set.
+     *
+     * `false` — every mask off, strict edges everywhere.
+     */
+    fade?: boolean | {
+        top?: number;
+        overlap?: number;
+        right?: number;
+        left?: number;
+    };
+    /**
+     * How `<Title>` and `<InfoBar>` are positioned relative to the canvas. Live.
      * - `'overlay'` (default): absolute overlays on top of the canvas.
      * - `'inline'`: flex siblings above the canvas — the canvas (and grid) shift down.
      */
@@ -235,10 +322,10 @@ declare type __VLS_Props_3 = {
      * `<CandlestickSeries>` / `<BarSeries>` override these chart-level
      * defaults unless the category here is explicitly `false`.
      *
-     * **Init-only by reference identity.** A new `animations` reference
-     * recreates the underlying `ChartInstance`. Hoist the object outside
-     * the render scope — an inline literal tears the chart down on every
-     * re-render.
+     * **Init-only, but diffed by value, not reference.** A same-value
+     * inline object literal is a no-op — only a genuine change to the
+     * resolved config recreates the underlying `ChartInstance`, since the
+     * animation engine doesn't support live reconfiguration yet.
      */
     animations?: boolean | AnimationsConfig;
     /**
@@ -253,56 +340,94 @@ declare type __VLS_Props_3 = {
      * the prop identity later is ignored.
      */
     onEdgeReached?: (info: EdgeReachedInfo) => void;
+    /**
+     * Fired on a click (or tap) on the chart canvas that isn't the tail end
+     * of a pan drag. `info.spatialHit` resolves a pie/heatmap/custom-spatial
+     * series directly under the pointer; for a time-series series, resolve
+     * the point yourself from `info.time` (`chart.getDataAtTime` /
+     * `buildHoverSnapshots`). Live — the latest callback is always used.
+     */
+    onPointClick?: (info: PointClickInfo) => void;
+    /**
+     * Fired on a double-click on the chart canvas. The chart also responds
+     * by calling `fitContent()`. Live — the latest callback is always used.
+     */
+    onPointDoubleClick?: (info: PointClickInfo) => void;
+    /**
+     * Fired when the spatially-hovered series/index changes (pie, heatmap,
+     * or a custom spatial kind) — `null` when the pointer leaves every hit
+     * area. Live — the latest callback is always used.
+     */
+    onSeriesHover?: (hit: SeriesHoverInfo | null) => void;
+    /**
+     * Fired once the underlying `ChartInstance` is constructed — on mount,
+     * and again if the chart is ever rebuilt (a genuine `animations` value
+     * change). Live — the latest callback is always used for the next rebuild.
+     */
+    onReady?: (chart: ChartInstance) => void;
+    /**
+     * Fired whenever the committed visible range changes — pan, zoom,
+     * `fitContent()`, a data update that shifts the tail-scroll window, or a
+     * `visibleRange` prop change. Live — the latest callback is always used.
+     */
+    onVisibleRangeChange?: (range: VisibleRange) => void;
+    /**
+     * Fired on every crosshair move, with `null` when the pointer leaves the
+     * chart. Live — the latest callback is always used.
+     */
+    onCrosshairMove?: (position: CrosshairPosition | null) => void;
 };
 
 declare type __VLS_Props_4 = {
+    data: HeatmapCellData[];
+    options?: Partial<HeatmapSeriesOptions>;
+    /** Stable series ID — same value across remounts. */
+    id?: string;
+    /** Show/hide the series without unmounting it — excludes it from the Y-range fit and tooltip/legend. Default `true`. Live. */
+    visible?: boolean;
+};
+
+declare type __VLS_Props_5 = {
     /** Flat `TimePoint[]`, `TimePoint[][]`, or named `{ label, color?, data }` layers. Time accepts ms or `Date`. */
     data: MultiLayerData;
     options?: Partial<LineSeriesOptions>;
     /** Stable series ID — same value across remounts. */
     id?: string;
+    /** Show/hide the series without unmounting it — excludes it from the Y-range fit and tooltip/legend. Default `true`. Live. */
+    visible?: boolean;
 };
 
-declare type __VLS_Props_5 = {
+declare type __VLS_Props_6 = {
     data: PieSliceData[];
     options?: Partial<PieSeriesOptions>;
     /** Stable series ID — same value across remounts. */
     id?: string;
+    /** Show/hide the series without unmounting it — excludes it from the Y-range fit and tooltip/legend. Default `true`. Live. */
+    visible?: boolean;
 };
 
-declare type __VLS_Props_6 = {
+declare type __VLS_Props_7 = {
+    /**
+     * Owning series id. **Optional** — when omitted, the first visible heatmap
+     * series is picked.
+     */
+    seriesId?: string;
+    /** Custom formatter for the cell value. Default: plain integers, compact decimals. */
+    format?: ValueFormatter;
+};
+
+declare type __VLS_Props_8 = {
     sort?: SnapshotSort;
     format?: TooltipFormatter;
 };
 
-declare type __VLS_Props_7 = {
+declare type __VLS_Props_9 = {
     items?: LegendItemOverride[];
     position?: 'bottom' | 'right';
     /** `'isolate'` shows only the clicked item; `'solo'` is a @deprecated alias. */
     mode?: LegendMode;
-};
-
-declare type __VLS_Props_8 = {
-    /** X anchor — epoch ms or a `Date`. */
-    time: TimeValue;
-    /** Y anchor as a data value. Omit and set `seriesId` to snap to that series' value at `time`. */
-    value?: number;
-    /** Snap Y to this series' value at `time` when `value` is omitted. Also the default color source. */
-    seriesId?: string;
-    /** Glyph at the anchor. Default: `'dot'`. Arrows point their tip at the anchor. */
-    shape?: MarkerShape;
-    /** Reuse the line pulse halo around the anchor. Default: `false`. */
-    pulse?: boolean;
-    /** Optional text label drawn in a pill next to the anchor. */
-    label?: string;
-    /** Color override. Falls back to the series color (when `seriesId` is set), then the theme line color. */
-    color?: string;
-};
-
-declare type __VLS_Props_9 = {
-    data: NavigatorData;
-    /** Strip height in CSS pixels. Defaults to `theme.navigator.height` (60). */
-    height?: number;
+    /** Fired after a click changes series visibility — via the built-in UI or a custom slot calling `item.toggle()`/`isolate()` directly. */
+    onToggle?: (info: LegendToggleInfo) => void;
 };
 
 declare function __VLS_template(): {
@@ -452,6 +577,7 @@ declare function __VLS_template_8(): {
             isLive: boolean;
             direction: YLabelDirection;
             format: ValueFormatter;
+            opacity: number;
         }): unknown;
     }> & {
         default?(ctx: {
@@ -461,6 +587,7 @@ declare function __VLS_template_8(): {
             isLive: boolean;
             direction: YLabelDirection;
             format: ValueFormatter;
+            opacity: number;
         }): unknown;
     };
     refs: {};
@@ -542,7 +669,7 @@ export declare const andromeda: ThemePreset;
  * - `axis.ticks` — axis tick label cross-fade.
  * - `toggle` — series visibility (alpha fade + Y re-fit, locked to one
  *   duration so they finish on the same frame).
- * - `series.{line,candlestick,bar,pie}` — per-series-type data tweens.
+ * - `series.{line,candlestick,bar,pie,heatmap}` — per-series-type data tweens.
  *
  * Top-level `false` disables every animation category. `axis: false`
  * disables both axes and ticks. `axis.y: false` / `axis.x: false` disables
@@ -555,7 +682,7 @@ export declare const andromeda: ThemePreset;
  * own override; an explicit `series.<type>: false` (or top-level `false`)
  * is a hard disable that overrides per-series.
  */
-declare interface AnimationsConfig {
+export declare interface AnimationsConfig {
     /**
      * Axis-level animation. `false` collapses both axes and ticks to instant.
      */
@@ -664,6 +791,15 @@ declare interface AnimationsConfig {
              * @default {@link DEFAULT_LINE_ENTRY}
              */
             entry?: AnimationTime;
+            /**
+             * Initial-load reveal — the line draws itself left-to-right
+             * on the first data seed, with a glowing head riding the
+             * reveal front. The value is the per-element wave duration;
+             * the full sweep lasts ~2×. `false` / `0` disables the intro.
+             *
+             * @default {@link DEFAULT_LINE_INTRO}
+             */
+            intro?: AnimationTime;
             /**
              * Last-value chase duration on `updateLastPoint`. `false` /
              * `0` snaps to the target instantly.
@@ -691,6 +827,15 @@ declare interface AnimationsConfig {
              * @default {@link DEFAULT_CANDLESTICK_ENTRY}
              */
             entry?: AnimationTime;
+            /**
+             * Initial-load reveal — candles unfold in a left-to-right
+             * wave on the first data seed. The value is the per-candle
+             * wave duration; the full wave lasts ~2×. `false` / `0`
+             * disables the intro.
+             *
+             * @default {@link DEFAULT_CANDLESTICK_INTRO}
+             */
+            intro?: AnimationTime;
             /**
              * Live OHLC chase duration on `updateLastPoint`. `false` / `0`
              * snaps to the target instantly.
@@ -710,6 +855,15 @@ declare interface AnimationsConfig {
              * @default {@link DEFAULT_BAR_ENTRY}
              */
             entry?: AnimationTime;
+            /**
+             * Initial-load reveal — bars grow from the baseline in a
+             * left-to-right wave on the first data seed. The value is the
+             * per-bar wave duration; the full wave lasts ~2×. `false` /
+             * `0` disables the intro.
+             *
+             * @default {@link DEFAULT_BAR_INTRO}
+             */
+            intro?: AnimationTime;
             /**
              * Live value chase duration on `updateLastPoint`. `false` /
              * `0` snaps to the target instantly.
@@ -719,13 +873,15 @@ declare interface AnimationsConfig {
             smooth?: AnimationTime;
         };
         /**
-         * Pie segment entry/update tweens. Parsed at config-time; the actual
-         * wiring lands in a later phase — providing a value here today is a
-         * no-op but the shape is stable.
+         * Pie segment entry/update tweens. `false` disables the slice
+         * entry sweep (`update` is still parse-only; wiring lands in a
+         * later phase).
          */
         pie?: false | {
             /**
-             * Slice grow-in duration on first paint.
+             * Initial-load reveal — slices unfurl clockwise over this
+             * total duration on the first data seed, then the outside
+             * labels chain in. `false` / `0` disables the intro.
              *
              * @default {@link DEFAULT_PIE_ENTRY}
              */
@@ -737,6 +893,25 @@ declare interface AnimationsConfig {
              */
             update?: AnimationTime;
         };
+        /**
+         * Heatmap tweens. `false` disables the entrance wave, value tween,
+         * and hover lift.
+         */
+        heatmap?: false | {
+            /**
+             * Per-cell entrance duration — the diagonal reveal wave on
+             * first paint / grid-shape change.
+             *
+             * @default {@link DEFAULT_HEATMAP_ENTRY}
+             */
+            entry?: AnimationTime;
+            /**
+             * In-place value/color tween and hover-lift ease.
+             *
+             * @default {@link DEFAULT_HEATMAP_UPDATE}
+             */
+            update?: AnimationTime;
+        };
     };
 }
 
@@ -757,7 +932,7 @@ declare interface AnimationState {
  *  - `string` in `<n>ms` or `<n>s` form (`"250ms"`, `"1s"`, `"2.5s"`)
  *  - `false` — disable (equivalent to `0`)
  */
-declare type AnimationTime = Milliseconds | string | false;
+export declare type AnimationTime = Milliseconds | string | false;
 
 /**
  * Build a 2-stop candle-body gradient around a single hex color — a lightened
@@ -853,6 +1028,21 @@ declare interface AxisTickTrackerOptions {
 
 export declare const ayuMirage: ThemePreset;
 
+/**
+ * History back-fill: the reveal front sweeps from the data boundary into
+ * the prepended span. Meant for the `historyReveal` option, whose localized
+ * frame interprets clip coordinates in reveal space — `x = 0` at the
+ * boundary, increasing toward the older end, `width` = the prepended span's
+ * bitmap width — so the line reads as plotting itself backwards. The
+ * default `historyReveal` for the line series.
+ */
+export declare function backfillSweepIntro(): LineIntroFn;
+
+/** Declarative per-bar transform — translation and opacity only; growth is
+ *  expressed through {@link BarIntroDirectives.value} instead so stacked
+ *  columns rise as one attached unit. */
+export declare type BarElementTransform = WaveIntroTransform;
+
 /**
  * Entrance animation styles for bars.
  * - `'none'` — no animation.
@@ -861,7 +1051,7 @@ export declare const ayuMirage: ThemePreset;
  * - `'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 type BarEntryAnimation = 'none' | 'fade' | 'grow' | 'slide' | 'fade-grow';
 
 /** Post-transform bitmap rectangle a bar painter fills. */
 declare interface BarGeometry {
@@ -873,6 +1063,57 @@ declare interface BarGeometry {
     baselineY: number;
 }
 
+/** What one intro frame should look like. */
+export declare interface BarIntroDirectives {
+    /** Horizontal clip window in bitmap px applied to the whole pass.
+     *  Omitted sides default to the pane edges. */
+    clip?: {
+        fromX?: number;
+        toX?: number;
+    };
+    /** Per-value transform applied before geometry and stacking. Scaling the
+     *  value grows the bar from the baseline on every render path. */
+    value?: (args: BarIntroValueArgs) => number;
+    /** Per-bar transform applied after the geometry is resolved. */
+    element?: (el: BarIntroElement) => BarElementTransform;
+}
+
+/** Arguments handed to {@link BarIntroDirectives.element} per drawn bar. */
+export declare interface BarIntroElement extends WaveIntroElement {
+    /** Settled left edge in bitmap px. */
+    x: number;
+    /** Settled top edge in bitmap px. */
+    topY: number;
+    /** Settled bar height in bitmap px. */
+    barHeight: number;
+    /** Y the bar grows from — the zero line, or the segment's own base for
+     *  stacked bars. */
+    baselineY: number;
+    /** Bar body width in bitmap px. */
+    barWidth: number;
+}
+
+/** One frame of bar intro choreography. */
+export declare type BarIntroFn = (frame: BarIntroFrame) => BarIntroDirectives;
+
+/** Read view of one bar intro frame. */
+export declare interface BarIntroFrame extends WaveIntroFrame {
+    /** Time → bitmap X through the live time scale. */
+    timeToX(time: number): number;
+}
+
+/** Arguments handed to {@link BarIntroDirectives.value} for every rendered value. */
+export declare interface BarIntroValueArgs {
+    layerIndex: number;
+    time: number;
+    /** The value the renderer would draw without the intro (live smoothing included). */
+    value: number;
+    /** Normalized x-position across the visible window, clamped to `[0, 1]`. */
+    position: number;
+    /** Eased wave progress for this value, staggered left → right. */
+    progress: number;
+}
+
 /** Arguments handed to a {@link BarPainter} once per bar / stacked segment. */
 export declare interface BarPaintArgs {
     geom: BarGeometry;
@@ -898,7 +1139,9 @@ export declare interface BarPaintArgs {
 /** Paints one bar / stacked segment. Owns its fill — it calls `ctx.fill()`. */
 export declare type BarPainter = (env: PaintEnv, args: BarPaintArgs) => void;
 
-export declare const BarSeries: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const BarSeries: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+visible: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** Series definition for `chart.addSeries` — keeps the chart renderer-agnostic
  *  so hosts that never render bars don't bundle this module. */
@@ -938,6 +1181,63 @@ export declare interface BarSeriesOptions {
      * @see BarSeriesOptions.entryAnimation
      */
     entryMs?: number | false;
+    /**
+     * Initial-load intro animation — a `BarIntroFn`, usually one of the
+     * shipped factories: `growIntro()` (the default), `springIntro()`,
+     * `riseIntro()`, `fadeIntro()`, `wipeIntro()`. Independent of
+     * `entryAnimation` — the intro plays once on the first data seed,
+     * streaming entrances keep their own style.
+     *
+     * @see introMs — cross-linked duration for this animation.
+     */
+    introAnimation?: BarIntroFn;
+    /**
+     * Initial-load reveal duration in milliseconds. On the first data seed
+     * (empty → non-empty) bars reveal in a left-to-right wave: each bar
+     * tweens for `introMs`, starts staggered across another `introMs`, so
+     * the full wave lasts ~2×. The visual style is picked by
+     * `introAnimation`. Default: `500`.
+     *
+     * ```
+     * // Per-series override:
+     * <BarSeries options={{ introMs: 800 }} data={data} />
+     *
+     * // Chart-level default:
+     * <ChartContainer animations={{ series: { bar: { intro: 800 } } }}>
+     *   <BarSeries data={data} />
+     * </ChartContainer>
+     * ```
+     *
+     * `false` or `0` disables the intro. Bulk re-seeds of a non-empty series
+     * never replay it. Skipped entirely under `prefers-reduced-motion`.
+     */
+    introMs?: number | false;
+    /**
+     * History-prepend reveal — plays when older points land at the front of
+     * the series (the `EdgeLoader` load-more-on-scroll path). A wave sweeps
+     * from the data boundary into the new history; each bar's stagger
+     * position is `0` at the boundary and `1` at the deepest new point, so
+     * intro factories that read `el.progress` (`fadeIntro()` — the default,
+     * `riseIntro()`, `growIntro()`, `springIntro()`) work here unchanged.
+     * Clip directives are interpreted in reveal space: `x = 0` at the
+     * boundary, increasing toward the older end.
+     *
+     * The fn receives a localized frame: `range` is the prepended time span
+     * (not the visible window) and `width` is that span's bitmap width.
+     *
+     * `'none'` disables the reveal — prepended points appear instantly.
+     *
+     * @see historyRevealMs — cross-linked duration for this animation.
+     */
+    historyReveal?: BarIntroFn | 'none';
+    /**
+     * History-prepend reveal duration in milliseconds — the per-bar wave
+     * duration; the full reveal lasts ~2×. Default: `400`. `false` or `0`
+     * disables the reveal. Skipped entirely under `prefers-reduced-motion`.
+     *
+     * @see BarSeriesOptions.historyReveal
+     */
+    historyRevealMs?: number | false;
     /**
      * How long the displayed bar value takes to catch up to the actual one
      * on every `updateLastPoint`. Default: `250` ms.
@@ -995,10 +1295,11 @@ export declare interface BarSeriesOptions {
  * Multi-layer renderers (Line, Bar) override them against each internal store.
  *
  * Time-series data queries are NOT here — they live on {@link TimeSeriesRenderer}
- * as required methods, so Chart narrows via `kind !== 'pie'` and calls them
- * directly (no optional chaining).
+ * as required methods, so Chart narrows via {@link isTimeSeriesRenderer} and
+ * calls them directly (no optional chaining). Never narrow by comparing `kind`
+ * against a single spatial value — new spatial kinds slip through such guards.
  */
-declare interface BaseSeriesRenderer {
+export declare interface BaseSeriesRenderer {
     /** Paint the series on the main layer. */
     render(ctx: SeriesRenderContext): void;
     /**
@@ -1008,6 +1309,21 @@ declare interface BaseSeriesRenderer {
     setData(data: unknown, layerIndex?: number): void;
     /** Append a single point (real-time tick). Optional — not all renderers support streaming. */
     appendPoint?(point: unknown, layerIndex?: number): void;
+    /**
+     * Insert older points at the front of the series (history prepend / load-more).
+     * The suffix already on screen is untouched, so — unlike {@link setData} — this
+     * does NOT re-arm the intro, clear entrance/chase state, or force a Y snap.
+     * Optional; not all renderers support it.
+     */
+    prependPoints?(points: unknown[], layerIndex?: number): void;
+    /**
+     * Seed the placeholder shapes a loading indicator was showing at the data
+     * boundary, called by the chart right before the matching
+     * {@link prependPoints}. A history reveal that supports morphing (e.g.
+     * `skeletonMorphIntro`) grows the real elements out of these shapes; a
+     * renderer that doesn't implement this simply plays its plain reveal.
+     */
+    setHistoryHandoff?(bars: PlaceholderBar[]): void;
     /** Replace the last point in place (live candle update). Optional. */
     updateLastPoint?(point: unknown, layerIndex?: number): void;
     /**
@@ -1077,6 +1393,14 @@ declare interface BaseSeriesRenderer {
         value: number;
         isLive: boolean;
     } | null;
+    /**
+     * Stacked value at an arbitrary `time` — the cumulative stack top at that
+     * sample, mirroring {@link getStackedLastValue} but anywhere in the window
+     * (used for the YLabel intro count-up start so it shares the stack basis).
+     * Single-layer renderers return the nearest sample's value; `null` when no
+     * layer has a sample near `time`.
+     */
+    getStackedValueAtTime?(time: number, interval: number): number | null;
     /**
      * Per-layer last snapshots, each with its own `time`. Useful for ragged
      * multi-layer series where layers advance independently — last-mode
@@ -1124,6 +1448,13 @@ declare interface BaseSeriesRenderer {
     getLayerAlpha?(index: number): number;
     /** True while the renderer has an active animation (Chart polls per frame). */
     readonly needsAnimation?: boolean;
+    /**
+     * Reveal-front position in `[0, 1]` of the initial-load intro across the
+     * visible window — `1` once settled (or when the renderer has no intro).
+     * Overlays (the Y-label badge, annotations) key their own entrance off this
+     * so they reveal in step with the series draw. Omitted → treated as `1`.
+     */
+    getIntroFront?(): number;
     /**
      * Optional overlay hook. Chart invokes this during the overlay pass so each
      * renderer can paint type-specific overlays (crosshair dots, pulse dots).
@@ -1146,7 +1477,7 @@ declare interface BaseSeriesRenderer {
     dispose(): void;
 }
 
-declare interface BitmapCoordinateSpace {
+export declare interface BitmapCoordinateSpace {
     context: CanvasRenderingContext2D;
     bitmapSize: {
         width: number;
@@ -1204,6 +1535,24 @@ export declare interface BuildLastSnapshotsArgs {
     cacheKey: string;
 }
 
+/** What one element should look like this frame. Every field is optional —
+ *  an empty object renders the element settled. */
+export declare interface CandleElementTransform extends WaveIntroTransform {
+    /** Lerp factor from `anchorY` toward the settled edges: `0` = collapsed
+     *  at the anchor, `1` = settled. Applied before the offsets. */
+    unfold?: number;
+    /** Absolute top edge override in bitmap px — replaces the `unfold` math
+     *  for this frame (the offsets still apply). Lets a morph start from
+     *  arbitrary geometry instead of the anchor. */
+    topY?: number;
+    /** Absolute bottom edge override in bitmap px — see {@link topY}. */
+    bottomY?: number;
+    /** Blend of the element's fill toward the theme's muted placeholder gray
+     *  (the axis text color): `0` = the candle's own color, `1` = fully
+     *  placeholder-colored. Volume bars ignore it. */
+    tint?: number;
+}
+
 /** Post-transform bitmap rectangle a candle-body painter fills. */
 declare interface CandleGeometry {
     x: number;
@@ -1212,6 +1561,51 @@ declare interface CandleGeometry {
     height: number;
 }
 
+/** What one intro frame should look like. */
+export declare interface CandleIntroDirectives {
+    /** Horizontal clip window in bitmap px applied to the whole pass (volume
+     *  band included). Omitted sides default to the pane edges. */
+    clip?: {
+        fromX?: number;
+        toX?: number;
+    };
+    /** Per-element transform — called for every wick, body, and volume bar. */
+    element?: (el: CandleIntroElement) => CandleElementTransform;
+}
+
+/** Arguments handed to {@link CandleIntroDirectives.element} per element. */
+export declare interface CandleIntroElement extends WaveIntroElement {
+    /** Which candle element is being transformed. */
+    element: 'wick' | 'body' | 'volume';
+    /** Settled left edge in bitmap px. */
+    x: number;
+    /** Settled top edge in bitmap px. */
+    topY: number;
+    /** Settled bottom edge in bitmap px. */
+    bottomY: number;
+    /** Y the element unfolds around — the open price for wick/body, the band
+     *  baseline for volume. */
+    anchorY: number;
+    /** Element width in bitmap px. */
+    barWidth: number;
+}
+
+/** One frame of candlestick intro choreography. */
+export declare type CandleIntroFn = (frame: CandleIntroFrame) => CandleIntroDirectives;
+
+/** Read view of one candlestick intro frame. */
+export declare interface CandleIntroFrame extends WaveIntroFrame {
+    /** Time → bitmap X through the live time scale. */
+    timeToX(time: number): number;
+    /**
+     * Placeholder shapes the loading indicator was showing when this history
+     * reveal armed — present only on a history-reveal frame that followed a
+     * loading-indicator hand-off (see `skeletonMorphIntro`). Absent on
+     * initial-load intro frames and on reveals with no hand-off.
+     */
+    placeholders?: readonly MorphPlaceholder[];
+}
+
 /** Arguments handed to a {@link CandlePainter} once per candle body. */
 export declare interface CandlePaintArgs {
     geom: CandleGeometry;
@@ -1265,9 +1659,11 @@ declare interface CandlestickDirectionColors {
  * - `'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 type CandlestickEntryAnimation = 'none' | 'fade' | 'unfold' | 'slide' | 'fade-unfold';
 
-export declare const CandlestickSeries: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const CandlestickSeries: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{}>, {
+visible: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** Series definition for `chart.addSeries` — keeps the chart renderer-agnostic
  *  so hosts that never render candles don't bundle this module. */
@@ -1310,6 +1706,63 @@ export declare interface CandlestickSeriesOptions {
      * @see CandlestickSeriesOptions.entryAnimation
      */
     entryMs?: number | false;
+    /**
+     * Initial-load intro animation — a `CandleIntroFn`, usually one of the
+     * shipped factories: `candleUnfoldIntro()` (the default),
+     * `wickBodyIntro()`, `riseIntro()`, `fadeIntro()`. Independent of
+     * `entryAnimation` — the intro plays once on the first data seed,
+     * streaming entrances keep their own style.
+     *
+     * @see introMs — cross-linked duration for this animation.
+     */
+    introAnimation?: CandleIntroFn;
+    /**
+     * Initial-load reveal duration in milliseconds. On the first data seed
+     * (empty → non-empty) candles reveal in a left-to-right wave: each candle
+     * tweens for `introMs`, starts staggered across another `introMs`, so the
+     * full wave lasts ~2×. The visual style is picked by `introAnimation`.
+     * Default: `500`.
+     *
+     * ```
+     * // Per-series override:
+     * <CandlestickSeries options={{ introMs: 800 }} data={data} />
+     *
+     * // Chart-level default:
+     * <ChartContainer animations={{ series: { candlestick: { intro: 800 } } }}>
+     *   <CandlestickSeries data={data} />
+     * </ChartContainer>
+     * ```
+     *
+     * `false` or `0` disables the intro. Bulk re-seeds of a non-empty series
+     * never replay it. Skipped entirely under `prefers-reduced-motion`.
+     */
+    introMs?: number | false;
+    /**
+     * History-prepend reveal — plays when older points land at the front of
+     * the series (the `EdgeLoader` load-more-on-scroll path). A wave sweeps
+     * from the data boundary into the new history; each candle's stagger
+     * position is `0` at the boundary and `1` at the deepest new point, so
+     * intro factories that read `el.progress` (`fadeIntro()` — the default,
+     * `riseIntro()`, `candleUnfoldIntro()`, `wickBodyIntro()`) work here
+     * unchanged. Clip directives are interpreted in reveal space: `x = 0` at
+     * the boundary, increasing toward the older end.
+     *
+     * The fn receives a localized frame: `range` is the prepended time span
+     * (not the visible window) and `width` is that span's bitmap width.
+     *
+     * `'none'` disables the reveal — prepended points appear instantly.
+     *
+     * @see historyRevealMs — cross-linked duration for this animation.
+     */
+    historyReveal?: CandleIntroFn | 'none';
+    /**
+     * History-prepend reveal duration in milliseconds — the per-candle wave
+     * duration; the full reveal lasts ~2×. Default: `400`. `false` or `0`
+     * disables the reveal. Skipped entirely under `prefers-reduced-motion`.
+     *
+     * @see CandlestickSeriesOptions.historyReveal
+     */
+    historyRevealMs?: number | false;
     /**
      * How long the displayed OHLC takes to catch up to the actual last value
      * on every `updateLastPoint`. Default: `250` ms.
@@ -1349,13 +1802,36 @@ export declare interface CandlestickSeriesOptions {
     candlePainter?: CandlePainter;
 }
 
+/** Each candle unfolds from its open price in a left-to-right wave — the
+ *  default intro. Alpha rides the same progress as the unfold so a candle
+ *  still waiting for the wave front stays invisible instead of painting as
+ *  a flat, min-height line at its open price. */
+export declare function candleUnfoldIntro(): CandleIntroFn;
+
 export declare const catppuccin: ThemePreset;
 
+/**
+ * Center-out reveal: the clip window opens from the pane's horizontal
+ * center outward, a glowing head riding each front.
+ */
+export declare function centerOutIntro(): LineIntroFn;
+
 export declare const ChartContainer: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 
 /** Events emitted by {@link ChartInstance}. */
 declare interface ChartEvents {
     crosshairMove: (pos: CrosshairPosition | null) => void;
+    /** Fired on a click (or tap) on the chart canvas that isn't the tail end of a pan drag. */
+    pointClick: (info: PointClickInfo) => void;
+    /** Fired on a double-click on the chart canvas. Chart also responds by calling `fitContent()`. */
+    pointDoubleClick: (info: PointClickInfo) => void;
+    /**
+     * Fired when the spatially-hovered series/index changes (pie, heatmap, or
+     * a custom spatial kind) — `null` when the pointer leaves every hit area.
+     * Time-series series have no pixel geometry to hover this way; read
+     * `crosshairMove` + `getDataAtTime`/`buildHoverSnapshots` for those.
+     */
+    seriesHover: (hit: SeriesHoverInfo | null) => void;
     viewportChange: () => void;
     dataUpdate: () => void;
     seriesChange: () => void;
@@ -1422,6 +1898,10 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
         id?: string;
         label?: string;
     }>): string;
+    addSeries(type: 'heatmap', options?: Partial<HeatmapSeriesOptions & {
+        id?: string;
+        label?: string;
+    }>): string;
     addSeries<O>(def: SeriesDefinition<O>, options?: Partial<O> & {
         layers?: number;
         id?: string;
@@ -1488,6 +1968,14 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
      * underlying animator mutates between frames.
      */
     getAnimationState(): AnimationState;
+    /**
+     * Reveal-front position in `[0, 1]` of any in-flight initial-load intro.
+     * With a `seriesId`, that series' own front; without, the minimum across
+     * every visible time series — overlays wait for the slowest reveal. `1`
+     * whenever nothing is introing. Overlay components (the Y-label badge,
+     * annotations) read this to reveal their entrance in step with the draw.
+     */
+    getIntroFront(seriesId?: string): number;
     /**
      * Replace all data for a series.
      *
@@ -1500,6 +1988,20 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
     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, layerIndex?: number): void;
+    /**
+     * Prepend older points to the front of a series — the "load more history on
+     * scroll" path. Unlike {@link setSeriesData}, this deliberately does NOT set
+     * `#dataReplaceSnapPending`: the visible window and the data inside it don't
+     * change, so the viewport must stay put (X) and the Y axis eases if newly
+     * revealed history shifts the range — instead of the full-span re-fit and
+     * instant dual-axis snap a bulk `setSeriesData` replace would force. Routes
+     * through the streaming `onPointAppended` engine signal via `onDataChanged`.
+     *
+     * `points` must be sorted ascending and sit strictly before the current
+     * first point; the sync reconciler guarantees this before calling here.
+     * No-op if the renderer doesn't support prepend.
+     */
+    prependData(id: string, points: (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, layerIndex?: number): void;
     /**
@@ -1517,7 +2019,7 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
      */
     keepLast(id: string, count: number, 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;
+    updateSeriesOptions(id: string, options: Partial<CandlestickSeriesOptions> | Partial<LineSeriesOptions> | Partial<BarSeriesOptions> | Partial<PieSeriesOptions> | Partial<HeatmapSeriesOptions>): void;
     /**
      * Batch multiple updates: suppress recomputes until `fn` returns. Exceptions
      * inside `fn` still flush the batch so counters don't leak across calls.
@@ -1651,15 +2153,24 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
     }[] | null;
     getSeriesIds(): string[];
     /**
-     * Filter `getSeriesIds()` by renderer type. `'pie'` returns pie series,
-     * `'time'` returns line/bar/candlestick.
+     * Whether pan/zoom gestures currently apply — true when any visible series
+     * has a time axis. Part of the {@link PanZoomTarget} surface: on a
+     * spatial-only chart (pie, heatmap) the interaction layer stops capturing
+     * wheel and touch events, so the page scrolls normally under the cursor.
+     */
+    canPanZoom(): boolean;
+    /**
+     * Filter `getSeriesIds()` by renderer type. A concrete kind (`'pie'`,
+     * `'heatmap'`, a custom kind, …) returns series of that exact kind;
+     * `'time'` returns every time-axis series (line/bar/candlestick and any
+     * custom time-series kind).
      *
      * - `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?: {
+    getSeriesIdsByType(type: SeriesKind | 'time', opts?: {
         visibleOnly?: boolean;
         singleLayerOnly?: boolean;
     }): string[];
@@ -1673,6 +2184,14 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
         value: number;
         isLive: boolean;
     } | null;
+    /**
+     * Stacked value at an arbitrary `time` — the cumulative stack top at that
+     * sample, sharing a basis with {@link getStackedLastValue}. Falls back to the
+     * nearest raw sample (close / value) for renderers without a stacked concept
+     * (Candlestick, single-layer Line/Bar). Returns `null` for unknown ids or
+     * when no sample sits near `time`. Used by the YLabel intro count-up start.
+     */
+    getStackedValueAtTime(seriesId: string, time: number): number | 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
@@ -1717,6 +2236,12 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
     /** Apply a new theme and update series colors where appropriate. */
     setTheme(theme: ChartTheme): void;
     getTheme(): ChartTheme;
+    /** BCP 47 locale applied to the built-in time-axis / tooltip / crosshair formatting. */
+    setLocale(locale: string | undefined): void;
+    getLocale(): string | undefined;
+    /** IANA timezone applied to the same built-in date-time formatting. */
+    setTimeZone(timeZone: string | undefined): void;
+    getTimeZone(): string | undefined;
     /** Update axis configuration and re-render. */
     setAxis(config: AxisConfig): void;
     /**
@@ -1751,6 +2276,14 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
     setGrid(grid: {
         visible: boolean;
     }): void;
+    /**
+     * Set or clear the edge fade masks (see {@link ChartOptions.fade}).
+     * Content the main layer draws inside a zone dissolves toward that edge.
+     * `right` omitted re-arms its default (track the Y-axis width); pass
+     * `{ top: 0, right: 0, left: 0 }` to turn every mask off. Takes effect on
+     * the next render frame.
+     */
+    setFade(fade: ChartOptions['fade']): void;
     /**
      * Set the visual state for one side of the chart. Typically called in
      * response to the `onEdgeReached` callback:
@@ -1764,7 +2297,14 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
     /** Read the current host-declared state for a given edge. */
     getEdgeState(side: EdgeSide): EdgeState;
     /**
-     * Notify chart that a YLabel overlay is mounted / unmounted. Currently a
+     * Swap the painter used for a side's `loading` spinner — the same
+     * pluggable-function contract as the series intro animations. `null`
+     * (default) falls back to the built-in three-dot spinner. Takes effect
+     * immediately if that side is currently in the `loading` state.
+     */
+    setEdgeIndicator(side: EdgeSide, indicator: LoadingIndicatorFn | null): void;
+    /**
+     * Notify chart that a YLabel overlay is mounted / unmounted. Currently a
      * no-op — placeholder for the right-padding reflow that will adjust the
      * chart area to make room for the badge.
      * TODO: implement reflow.
@@ -1867,10 +2407,35 @@ export declare interface ChartOptions {
     };
     /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
     interactive?: boolean;
+    /**
+     * BCP 47 locale applied to the built-in time-axis / tooltip / crosshair
+     * date-time formatting (e.g. `'de-DE'`). Default: `'en-US'`. Live —
+     * `chart.setLocale()` updates it after construction. Ignored for a series
+     * that installs a custom formatter via `chart.timeScale.setFormat()`.
+     */
+    locale?: string;
+    /**
+     * IANA timezone applied to the same built-in date-time formatting (e.g.
+     * `'America/New_York'`). Default: the browser's local timezone. Live —
+     * `chart.setTimeZone()` updates it after construction.
+     */
+    timeZone?: string;
     /** Background grid configuration. Default: `{ visible: true }`. */
     grid?: {
         visible: boolean;
     };
+    /**
+     * Soft alpha fade applied at the edges of the plot area. Anything the main
+     * layer draws inside a zone (series, grid, time-region bands) dissolves to
+     * transparent as it approaches the edge: horizontally sliding under the
+     * Y-axis labels on the right (`right`, **on by default**), toward a
+     * floating Title / InfoBar at the top (`top`), or out the left edge
+     * (`left`). The mask *erases* pixels rather than painting a cover color,
+     * so it stays correct over any container background — including the
+     * default CSS gradient. Live — `chart.setFade()` updates it after
+     * construction.
+     */
+    fade?: FadeConfig;
     /**
      * Animation control. Grouped as `axis: { y, x, ticks }` (axis-side
      * behaviour), `toggle` (series visibility — alpha + Y refit), and
@@ -1993,6 +2558,20 @@ export declare interface ChartTheme {
          */
         otherColor: string;
     };
+    /**
+     * Heatmap sequential ramp. Optional so hand-built theme literals keep
+     * compiling — the renderer falls back to a ramp derived from
+     * {@link ChartTheme.line} `color` and the background at render time.
+     */
+    heatmap?: {
+        /**
+         * Ramp stops, low → high, interpolated perceptually. {@link createTheme}
+         * derives a two-stop single-hue ramp: a faint accent wash near the
+         * surface up to the full accent — which flips anchor automatically with
+         * theme polarity (low values sink into the background in both modes).
+         */
+        colors: string[];
+    };
     /** Bollinger band / envelope fill colors. */
     bands: {
         /** Fill for the upper band region (above the middle band). */
@@ -2163,12 +2742,38 @@ export declare interface CrosshairPosition {
 /** Path-shape selector for {@link tracePath}. */
 export declare type CurveKind = 'straight' | 'smooth' | 'stepped';
 
+/**
+ * A custom spatial renderer with no time axis — implement this (rather than
+ * {@link PieSeriesRenderer} / {@link HeatmapSeriesRenderer}, which are reserved
+ * for the built-ins) when writing a new non-time-axis series from scratch,
+ * e.g. a radar or treemap chart. Pick any `kind` that isn't a built-in one.
+ */
+export declare interface CustomSpatialSeriesRenderer extends BaseSeriesRenderer {
+    readonly kind: string;
+}
+
+/**
+ * Structural equality for plain option bags that may carry function-valued
+ * fields (e.g. `AnimationsConfig.axis.y.curve`, a transition factory).
+ * Functions (and any other non-plain value) compare by reference — only
+ * arrays and plain objects recurse. Used to tell a caller's brand-new inline
+ * object literal (same values, new reference) apart from a genuine option
+ * change, so wrappers can skip an expensive rebuild in the former case.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+
+declare const _default: DefineComponent<__VLS_Props_16, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_16> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+containerRef: HTMLDivElement;
+}, HTMLDivElement>;
+export { _default as TimeAxis }
+export { _default as XAxis }
+
 export declare function detectInterval(times: number[]): number;
 
 export declare const dracula: ThemePreset;
 
 /** Payload for {@link ChartOptions.onEdgeReached}. */
-declare interface EdgeReachedInfo {
+export declare interface EdgeReachedInfo {
     side: EdgeSide;
     /** Time units the user pulled past the soft bound. */
     overshoot: number;
@@ -2177,7 +2782,9 @@ declare interface EdgeReachedInfo {
 }
 
 /** Which data side the user pulled past during a gesture. */
-declare type EdgeSide = 'left' | 'right';
+export declare type EdgeSide = 'left' | 'right';
+
+declare type EdgeSide_2 = 'left' | 'right';
 
 /**
  * Host-controlled visual state for a chart edge:
@@ -2186,7 +2793,7 @@ declare type EdgeSide = 'left' | 'right';
  * - `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';
+export declare type EdgeState = 'idle' | 'loading' | 'no-data' | 'has-more';
 
 declare class EventEmitter<Events = Record<string, Listener>> {
     private listeners;
@@ -2196,6 +2803,33 @@ declare class EventEmitter<Events = Record<string, Listener>> {
     removeAllListeners(): void;
 }
 
+/** Shape of {@link ChartOptions.fade}. */
+declare interface FadeConfig {
+    /** Fade-zone height in CSS pixels, measured down from the top of the plot
+     *  area. `0` / omitted disables the mask. */
+    top?: number;
+    /**
+     * Total width in CSS pixels of the horizontal dissolve at the right edge.
+     * The ramp finishes just inside the Y-axis column — 12px past the pane
+     * edge, before the right-anchored label glyphs start — so content melts
+     * on approach (pan / tail-scroll exit) and is fully gone before it can
+     * cross any axis text; the rest of the width runs backward into the pane
+     * as a soft lead-in. **Defaults to a 60px ramp** — on out of the box;
+     * `0` disables. A no-op while the Y axis is hidden.
+     */
+    right?: number;
+    /** Fade-zone width in CSS pixels at the left pane edge — content panning
+     *  out to the left dissolves instead of hard-clipping at the canvas
+     *  boundary. `0` / omitted disables. */
+    left?: number;
+}
+
+/**
+ * Plain staggered fade-in, no geometry motion. Works for both bar and
+ * candlestick series.
+ */
+export declare function fadeIntro(): WaveIntroFn;
+
 /**
  * Fill a rounded rectangle with per-corner masking, using manual `arcTo` so the
  * output is deterministic and independent of `CanvasRenderingContext2D.roundRect`
@@ -2218,7 +2852,7 @@ export declare function formatCompact(v: number, opts?: {
     decimals?: number;
 }): string;
 
-export declare function formatDate(timestamp: number): string;
+export declare function formatDate(timestamp: number, opts?: TimeFormatOptions): string;
 
 /**
  * Full-precision display that adapts decimal count to the value's magnitude.
@@ -2227,7 +2861,7 @@ export declare function formatDate(timestamp: number): string;
  */
 export declare function formatPriceAdaptive(v: number): string;
 
-export declare function formatTime(timestamp: number, interval: number): string;
+export declare function formatTime(timestamp: number, interval: number, opts?: TimeFormatOptions): string;
 
 declare type FrameKind = 'main' | 'overlay';
 
@@ -2242,10 +2876,103 @@ declare interface FrameTimingSample {
 
 export declare const githubLight: ThemePreset;
 
+/** Bars fade-grow up from the baseline in a left-to-right wave — the
+ *  default intro. */
+export declare function growIntro(): BarIntroFn;
+
 export declare const gruvbox: ThemePreset;
 
 export declare const handwritten: ThemePreset;
 
+/** One cell of a heatmap matrix — a (column, row) coordinate with a magnitude. */
+export declare interface HeatmapCellData {
+    /** Column key. Column order follows first appearance unless {@link HeatmapSeriesOptions.columns} pins it. */
+    x: string;
+    /** Row key. Row order follows first appearance unless {@link HeatmapSeriesOptions.rows} pins it. */
+    y: string;
+    /** Magnitude mapped onto the sequential color ramp. */
+    value: number;
+    /** Explicit fill override for this cell. Skips the ramp entirely. */
+    color?: string;
+}
+
+/** Per-cell value labels drawn inside heatmap cells. */
+export declare interface HeatmapCellLabelsOptions {
+    /** Font size in CSS pixels. Default: 10. */
+    fontSize?: number;
+    /**
+     * Value formatter. Default: decimals adapt to the value domain — 2 for
+     * unit-scale domains (correlations), integers for wide ones, compact
+     * notation (`1.2K`) past 1000.
+     */
+    format?: (value: number) => string;
+}
+
+export declare const HeatmapSeries: DefineComponent<__VLS_Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_4> & Readonly<{}>, {
+visible: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+/** Series definition for `chart.addSeries` — keeps the chart renderer-agnostic
+ *  so hosts that never render heatmaps don't bundle this module. */
+export declare const HeatmapSeriesDef: SeriesDefinition<HeatmapSeriesOptions>;
+
+/** Visual options for a heatmap series. */
+export declare interface HeatmapSeriesOptions {
+    /**
+     * Sequential ramp stops, low → high, interpolated perceptually (OKLab).
+     * Two stops give a classic single-hue ramp; three make a diverging scale.
+     * Default: derived from the theme — a faint wash of the accent color near
+     * the surface up to the full accent (`theme.heatmap.colors` when present).
+     */
+    colors?: string[];
+    /** Domain minimum mapped to the first ramp stop. Default: the data minimum. */
+    min?: number;
+    /** Domain maximum mapped to the last ramp stop. Default: the data maximum. */
+    max?: number;
+    /** Surface gap between adjacent cells in CSS pixels. Default: 2. */
+    gap?: number;
+    /** Cell corner radius in CSS pixels. Default: 3. */
+    cornerRadius?: number;
+    /** Draw row labels (left) and column labels (bottom). Default: true. */
+    axisLabels?: boolean;
+    /** Draw the value inside each cell (auto-skipped when it doesn't fit). Default: false. */
+    cellLabels?: boolean | HeatmapCellLabelsOptions;
+    /** Explicit column order. Keys absent from the data render as empty columns. */
+    columns?: string[];
+    /** Explicit row order. Keys absent from the data render as empty rows. */
+    rows?: string[];
+    /**
+     * Entrance duration per cell in milliseconds — the diagonal reveal wave on
+     * first paint / grid-shape change. `0` paints instantly.
+     * Default: chart animation config (600).
+     */
+    entryMs?: number;
+    /**
+     * Value/color tween duration when a cell's value changes in place, and the
+     * hover-lift ease. `0` snaps. Default: chart animation config (300).
+     */
+    updateMs?: number;
+}
+
+/** A spatial matrix renderer with no time axis (Heatmap). Has no time-series queries. */
+export declare interface HeatmapSeriesRenderer extends BaseSeriesRenderer {
+    readonly kind: 'heatmap';
+}
+
+export declare const HeatmapTooltip: DefineComponent<__VLS_Props_7, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_7> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+/**
+ * Velocity-matched cubic Hermite Y transition. Direction-aware: per-call
+ * `expandMs` (outward, default 250 ms via the engine) and `contractMs`
+ * (inward, default 2500 ms — sticky-Y) are supplied through `retarget()`.
+ *
+ * Default Y transition. Bounded duration — after the supplied settle each
+ * side lands exactly at the target with zero velocity, unlike spring's
+ * asymptotic approach. Predictable for animations whose end-state matters
+ * (axis labels can settle in a known time).
+ */
+export declare function hermite(): TransitionFactory<YRange>;
+
 export declare const highContrast: ThemePreset;
 
 /** Horizontal padding expressed as a fixed pixel offset or a number of data intervals. */
@@ -2263,6 +2990,17 @@ export declare interface HoverInfo {
 
 export declare const InfoBar: __VLS_WithTemplateSlots_2<typeof __VLS_component_2, __VLS_TemplateResult_2["slots"]>;
 
+export declare function isDarkBg(bg: string): boolean;
+
+/**
+ * Narrow a renderer to the time-axis variant. A capability check, not a
+ * `kind` allowlist — any renderer implementing the required time-series
+ * queries (own a `getTimeBounds()`) counts, including custom series kinds.
+ * The chart's viewport, crosshair, interval detection, and Y autoscale all
+ * dispatch through this guard.
+ */
+export declare function isTimeSeriesRenderer(renderer: SeriesRenderer): renderer is TimeSeriesRenderer;
+
 export declare const lavenderMist: ThemePreset;
 
 export declare const Legend: __VLS_WithTemplateSlots_3<typeof __VLS_component_3, __VLS_TemplateResult_3["slots"]>;
@@ -2312,6 +3050,14 @@ declare interface LegendItemOverride {
 
 declare type LegendMode = 'toggle' | 'isolate' | 'solo';
 
+/** Payload for the `onToggle` prop — one entry per user click, regardless of built-in vs custom rendering. */
+declare interface LegendToggleInfo {
+    /** The clicked item's id (matches {@link LegendItem.id}). */
+    id: string;
+    /** Which interaction produced this change. */
+    action: 'toggle' | 'isolate' | 'unisolate';
+}
+
 export declare const lightPink: ThemePreset;
 
 /** Internal bookkeeping for a registered reference line. `coord` is a Y value (horizontal) or normalized epoch ms (vertical). */
@@ -2333,6 +3079,91 @@ declare interface LineEntry {
  */
 declare type LineEntryAnimation = 'none' | 'grow' | 'fade';
 
+/** What one intro frame should look like. Every field is optional — an empty
+ *  object renders the frame settled. */
+export declare interface LineIntroDirectives {
+    /**
+     * Horizontal clip window in bitmap pixels. Omitted sides default to the
+     * pane edges, so `{ toX }` is a left-to-right reveal and `{ fromX }` a
+     * right-to-left one.
+     */
+    clip?: {
+        fromX?: number;
+        toX?: number;
+    };
+    /**
+     * Draw a stroke-only ghost of the full line under the main pass at this
+     * alpha (the area fill is left to the main pass).
+     */
+    ghostAlpha?: number;
+    /**
+     * Head-glow anchors — the renderer draws a pulse dot per visible layer at
+     * each head's `time` (bell-faded over the intro window). Heads are
+     * skipped for stacked series, where a single layer's Y is meaningless.
+     */
+    heads?: Array<{
+        x: number;
+        time: number;
+    }>;
+    /**
+     * Per-value transform applied to every rendered value (stroke, area,
+     * stacked cumulative, trailing endpoint, overlay pulse) via the
+     * renderer's `effectiveValue` hook.
+     */
+    value?: (args: LineIntroValueArgs) => number;
+}
+
+/** One frame of intro choreography. See the module docs for the contract. */
+export declare type LineIntroFn = (frame: LineIntroFrame) => LineIntroDirectives;
+
+/** Read view of one intro frame — everything a {@link LineIntroFn} may need. */
+export declare interface LineIntroFrame {
+    /** Linear intro progress in `[0, 1]` over the whole reveal window. */
+    progress: number;
+    /** Visible time range. */
+    range: VisibleRange;
+    /**
+     * Plot-area width in bitmap pixels — the span `timeToX` maps the visible
+     * range onto (excludes the Y-axis strip sharing the canvas).
+     */
+    width: number;
+    /** Plot-area height in bitmap pixels (excludes the X-axis strip). */
+    height: number;
+    /** The series' stacking mode — path-based intros usually degrade to a plain clip when stacked. */
+    stacking: StackingMode;
+    /** Time → bitmap X through the live time scale. */
+    timeToX(time: number): number;
+    /** Bitmap X → time — the inverse of {@link timeToX}, for mapping a clip front back into the time domain. */
+    xToTime(x: number): number;
+    /** Value → bitmap Y through the live Y scale. */
+    valueToY(value: number): number;
+    /** Number of layers in the series. */
+    layerCount: number;
+    /** Visible data of one layer (memoized per frame). */
+    layerData(layerIndex: number): readonly TimePoint[];
+    /** Mean of the layer's visible finite values, or `null` for an empty/poisoned layer (memoized per frame). */
+    layerMean(layerIndex: number): number | null;
+    /**
+     * Bitmap-space polyline of the first visible layer (finite values only,
+     * memoized per frame), or `null` when no layer has two drawable points.
+     */
+    primaryPath(): ReadonlyArray<{
+        x: number;
+        y: number;
+        time: number;
+    }> | null;
+}
+
+/** Arguments handed to {@link LineIntroDirectives.value} for every rendered value. */
+export declare interface LineIntroValueArgs {
+    layerIndex: number;
+    time: number;
+    /** The value the renderer would draw without the intro (live smoothing included). */
+    value: number;
+    /** Normalized x-position of `time` across the visible range, clamped to `[0, 1]`. */
+    position: number;
+}
+
 /** Arguments handed to a {@link LinePainter} once per finite run. */
 export declare interface LinePaintArgs {
     /**
@@ -2372,7 +3203,9 @@ declare interface LinePoint {
     y: number;
 }
 
-export declare const LineSeries: DefineComponent<__VLS_Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_4> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const LineSeries: DefineComponent<__VLS_Props_5, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_5> & Readonly<{}>, {
+visible: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** Series definition for `chart.addSeries` — keeps the chart renderer-agnostic
  *  so hosts that never render lines don't bundle this module. */
@@ -2441,6 +3274,66 @@ export declare interface LineSeriesOptions {
      * @see LineSeriesOptions.entryAnimation
      */
     entryMs?: number | false;
+    /**
+     * Initial-load reveal duration in milliseconds. On the first data seed
+     * (empty → non-empty) the line draws itself left-to-right — stroke and
+     * area sweep in behind a glowing head that rides the reveal front. The
+     * full sweep lasts ~2× `introMs`. Default: `500`.
+     *
+     * ```
+     * // Per-series override:
+     * <LineSeries options={{ introMs: 800 }} data={data} />
+     *
+     * // Chart-level default:
+     * <ChartContainer animations={{ series: { line: { intro: 800 } } }}>
+     *   <LineSeries data={data} />
+     * </ChartContainer>
+     * ```
+     *
+     * `false` or `0` disables the intro. Bulk re-seeds of a non-empty series
+     * never replay it. Skipped entirely under `prefers-reduced-motion`.
+     */
+    introMs?: number | false;
+    /**
+     * Initial-load reveal choreography — a `LineIntroFn` called once per
+     * frame while the intro plays. The shipped styles are factories over the
+     * same contract: `unfoldIntro()` (the default — amplitude springs from
+     * the mean into shape), `sweepIntro()` (left-to-right draw-on with a
+     * glowing head), `traceIntro()` (faint ghost, then an ink sweep),
+     * `plotterIntro()` (head advances at constant path speed), `centerOutIntro()`
+     * (clip opens from the pane's center outward). Style is specific to the
+     * line series; there is no chart-level override for style — only for
+     * duration (`introMs`).
+     *
+     * @see LineIntroFn — the custom-fn contract (frame → directives).
+     * @see introMs — cross-linked duration for this animation.
+     */
+    introAnimation?: LineIntroFn;
+    /**
+     * History-prepend reveal — plays when older points land at the front of
+     * the series (the `EdgeLoader` load-more-on-scroll path). Default: the
+     * line back-fills itself from the data boundary into the new history
+     * behind a moving clip front (`backfillSweepIntro()`).
+     *
+     * A custom `LineIntroFn` receives a localized frame: `range` is the
+     * prepended time span with `range.to` at the data boundary (not the
+     * visible window), `width` is that span's bitmap width, and `progress`
+     * runs over the reveal. Value-transform directives are applied to the
+     * prepended points only.
+     *
+     * `'none'` disables the reveal — prepended points appear instantly.
+     *
+     * @see historyRevealMs — cross-linked duration for this animation.
+     */
+    historyReveal?: LineIntroFn | 'none';
+    /**
+     * History-prepend reveal duration in milliseconds — the full sweep lasts
+     * ~2×. Default: `400`. `false` or `0` disables the reveal. Skipped
+     * entirely under `prefers-reduced-motion`.
+     *
+     * @see LineSeriesOptions.historyReveal
+     */
+    historyRevealMs?: number | false;
     /**
      * How long the displayed last value takes to catch up to the actual one
      * on every `updateLastPoint`. Default: `250` ms.
@@ -2502,11 +3395,90 @@ export declare interface LineSeriesOptions {
         /** Color below the threshold. Default: the series' resolved color. */
         below?: string;
     };
+    /**
+     * Dot markers at each data point. Hidden by default.
+     *
+     * Dots ride the same animated geometry as the stroke (entrance unfurl,
+     * live-value smoothing, stacked cumulative), so they glide with the line
+     * instead of snapping. When the visible points sit too dense to read as
+     * discrete markers (average spacing under ~1.5 dot diameters, e.g. zoomed
+     * far out), the dots are skipped for that frame — they'd merge into a fat
+     * line and hide the stroke. Zooming back in brings them back.
+     *
+     * ```
+     * <LineSeries data={data} options={{ points: { visible: true } }} />
+     * ```
+     */
+    points?: {
+        /** Whether a dot is drawn at each data point. */
+        visible: boolean;
+        /** Dot radius in CSS pixels. Default: `3`. */
+        radius?: number;
+        /** Fill color override. Default: the layer's resolved series color. */
+        color?: string;
+    };
 }
 
 declare type Listener = (...args: any[]) => void;
 
-export declare const Marker: DefineComponent<__VLS_Props_8, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_8> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+/** Read view of one loading-indicator frame — everything a {@link LoadingIndicatorFn} may need. */
+export declare interface LoadingIndicatorArgs {
+    scope: BitmapCoordinateSpace;
+    theme: ChartTheme;
+    /**
+     * Plot-area size in CSS/media pixels (excludes the axis bands) — multiply
+     * by the scope's pixel ratios to get bitmap units.
+     */
+    chartMediaWidth: number;
+    chartMediaHeight: number;
+    /** Animation timestamp, typically `performance.now()`. */
+    now: number;
+    /**
+     * Which edge this indicator's stage is anchored to. `'left'` means the
+     * data boundary sits at local x = `chartMediaWidth` (the stage extends
+     * further away from the data as x decreases); `'right'` means the
+     * boundary sits at local x = `0`. Present only when painted by
+     * `chart.setEdgeIndicator` — absent for a hypothetical future non-edge
+     * caller.
+     */
+    side?: EdgeSide_2;
+    /**
+     * Y position (media px, within `[0, chartMediaHeight]`) of the boundary
+     * point on the chart's primary visible time series — lets an indicator
+     * start exactly where the real data leaves off. `undefined` when there's
+     * no visible time series or no data resolvable at the boundary.
+     */
+    edgeValueY?: number;
+    /**
+     * Media px between adjacent bars at the chart's current zoom level — lets
+     * an indicator size its placeholder shapes to match the real candles/bars
+     * that will render once data lands. `undefined` when not resolvable (e.g.
+     * a chart with no meaningful viewport span yet).
+     */
+    barSpacing?: number;
+    /**
+     * Kind of the primary visible time series (`'candlestick'`, `'line'`,
+     * `'bar'`, ...) — lets an indicator adapt its shape to what's actually
+     * loading instead of always drawing one fixed shape. `undefined` when
+     * unresolvable.
+     */
+    seriesKind?: SeriesKind;
+    /**
+     * Report the placeholder shapes drawn this frame. The chart snapshots the
+     * latest report and, when the fetched history lands, hands it to the
+     * series' history reveal — a morph-style reveal (`skeletonMorphIntro`)
+     * grows the real candles out of these exact placeholders instead of
+     * cross-fading. Optional both ways: an indicator that never reports (or
+     * a chart caller that doesn't collect) simply falls back to the plain
+     * reveal.
+     */
+    reportPlaceholders?(bars: PlaceholderBar[]): void;
+}
+
+/** Pure function contract for a pluggable loading indicator. */
+export declare type LoadingIndicatorFn = (args: LoadingIndicatorArgs) => void;
+
+export declare const Marker: DefineComponent<__VLS_Props_10, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_10> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /**
  * A point annotation pinned to a `time` (X) and a `value` (Y) — "anomaly opened
@@ -2528,7 +3500,12 @@ export declare interface MarkerConfig {
     shape?: MarkerShape;
     /** Reuse the line pulse halo around the anchor. Default: `false`. */
     pulse?: boolean;
-    /** Optional text label drawn in a pill next to the anchor. */
+    /**
+     * Optional text label, drawn as a callout chip whose tail points at the
+     * anchor — above it for `arrow-down` / `dot` / `circle`, below for
+     * `arrow-up`, flipping when the plot edge would cut it off. On arrow
+     * shapes the tail replaces the glyph.
+     */
     label?: string;
     /** Color override. Falls back to the series color (when `seriesId` is set), then the theme line color. */
     color?: string;
@@ -2546,7 +3523,13 @@ declare interface MarkerEntry {
     color?: string;
 }
 
-/** Glyph drawn at the marker anchor. Arrows point their tip *at* the anchor point. */
+/**
+ * Glyph drawn at the marker anchor. On a bare marker, arrows point their tip
+ * *at* the anchor point. On a labeled marker the callout tail does the
+ * pointing instead — the arrow glyph is dropped and the shape only picks the
+ * callout's side: above the anchor for `arrow-down`, below for `arrow-up`.
+ * `dot` and `circle` keep their glyph under the callout.
+ */
 export declare type MarkerShape = 'dot' | 'circle' | 'arrow-up' | 'arrow-down';
 
 export declare const materialPalenight: ThemePreset;
@@ -2564,8 +3547,37 @@ export declare const minimalLight: ThemePreset;
 
 export declare const mintBreeze: ThemePreset;
 
+/**
+ * Blend two colors perceptually (OKLab), `t` in [0, 1]. Accepts `#rgb`,
+ * `#rrggbb`, and `rgb()/rgba()` inputs; anything else (named colors,
+ * `hsl()`) falls back to a hard switch at `t = 0.5` — it never produces a
+ * NaN canvas fill. An `rgba()` input's alpha interpolates linearly alongside
+ * the OKLab channels — the result is an `rgba()` string whenever either
+ * endpoint is translucent, an opaque hex otherwise. Results are cached on a
+ * quantized `t` (1/256 steps), so per-frame per-cell sampling stays
+ * allocation-free after the first frame.
+ */
+export declare function mixColors(from: string, to: string, t: number): string;
+
 export declare const monokaiPro: ThemePreset;
 
+/**
+ * One placeholder shape a loading indicator painted at the data boundary,
+ * mapped into bitmap space — what a morph-style history reveal grows the
+ * real candles out of. Re-anchored to the boundary every frame, so the
+ * morph stays glued while the user keeps panning.
+ */
+declare interface MorphPlaceholder {
+    /** Bar center X, bitmap px. */
+    x: number;
+    /** Bar center Y, bitmap px. */
+    y: number;
+    /** Half the body height, bitmap px. */
+    halfHeight: number;
+    /** Body width, bitmap px. */
+    width: number;
+}
+
 /**
  * Omnivorous `data` shape for line and bar series. Accepts, interchangeably:
  * - `TimePointInput[]` — one auto-named layer (the common single-series case);
@@ -2576,9 +3588,9 @@ export declare const monokaiPro: ThemePreset;
  * Everything normalizes to `SeriesLayer[]` internally (see `toLayers`). Time
  * accepts epoch milliseconds or a `Date` on every point.
  */
-declare type MultiLayerData = TimePointInput[] | SeriesLayer<TimePointInput> | Array<TimePointInput[] | SeriesLayer<TimePointInput>>;
+export declare type MultiLayerData = TimePointInput[] | SeriesLayer<TimePointInput> | Array<TimePointInput[] | SeriesLayer<TimePointInput>>;
 
-declare const Navigator_2: DefineComponent<__VLS_Props_9, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_9> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+declare const Navigator_2: DefineComponent<__VLS_Props_11, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_11> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 stripRef: HTMLDivElement;
 }, any>;
 export { Navigator_2 as Navigator }
@@ -2670,7 +3682,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_10, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_10> & Readonly<{}>, {
+export declare const NumberFlow: DefineComponent<__VLS_Props_12, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_12> & Readonly<{}>, {
 locale: string;
 spinDuration: number;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLSpanElement>;
@@ -2693,7 +3705,7 @@ export declare type OHLCInput = Omit<OHLCData, 'time'> & {
 export declare const oneDarkPro: ThemePreset;
 
 /** Overlay render state passed to {@link SeriesRenderer.drawOverlay}. */
-declare interface OverlayRenderContext {
+export declare interface OverlayRenderContext {
     scope: BitmapCoordinateSpace;
     timeScale: XScale;
     yScale: YScale;
@@ -2751,8 +3763,22 @@ declare interface PanZoomTarget {
      * `chartWidth` participates in soft-bound math the same way as in `pan`.
      */
     zoomAt(centerTime: number, factor: number, chartWidth?: number): void;
+    /**
+     * Whether pan/zoom gestures currently apply to this target. A spatial-only
+     * chart (pie, heatmap) has no time axis to gesture on, so the interaction
+     * layer leaves wheel and touch events to the page — scrolling past the
+     * chart keeps working. Targets that omit the hook are always pan/zoomable.
+     */
+    canPanZoom?(): boolean;
 }
 
+/**
+ * Parse an {@link AnimationTime} to milliseconds. Invalid strings throw at
+ * config-resolution time, so a typo surfaces at startup, not silently as zero
+ * animation later. Used once per field in `resolveAnimationsConfig`.
+ */
+export declare function parseAnimationTime(value: AnimationTime): Milliseconds;
+
 export declare const peachCream: ThemePreset;
 
 /**
@@ -2968,7 +3994,9 @@ declare interface PieOtherOptions {
     color?: string;
 }
 
-export declare const PieSeries: DefineComponent<__VLS_Props_5, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_5> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const PieSeries: DefineComponent<__VLS_Props_6, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_6> & Readonly<{}>, {
+visible: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** Series definition for `chart.addSeries` — keeps the chart renderer-agnostic
  *  so hosts that never render pies don't bundle this module. */
@@ -2982,6 +4010,16 @@ export declare interface PieSeriesOptions {
     innerRadiusRatio: number;
     /** Gap between slices in degrees. Default: 1.15° (≈ 0.02 rad). */
     padAngle: number;
+    /**
+     * Rounds each slice's corners in CSS pixels — the two where the outer rim
+     * meets the straight edges, plus two more on the inner rim once
+     * `innerRadiusRatio > 0` carves out a donut hole. Default: 3 (matching the
+     * bar/candlestick families); pass 0 for sharp wedges. Thin rings and narrow
+     * slices automatically clamp the radius down to whatever they can fit
+     * without the corners overlapping, so a value that's too large for a given
+     * slice degrades gracefully instead of producing a malformed shape.
+     */
+    cornerRadius?: number;
     /** Display the label shown in the tooltip. */
     label?: string;
     /** Per-slice label rendering on the pie itself. See {@link PieLabelsOptions}. */
@@ -3002,6 +4040,27 @@ export declare interface PieSeriesOptions {
      * value.
      */
     animate?: boolean;
+    /**
+     * Initial-load reveal duration in milliseconds. On the first data seed
+     * (empty → non-empty) slices unfurl clockwise over this total duration,
+     * then the outside labels draw in. Default: `600`.
+     *
+     * ```
+     * // Per-series override:
+     * <PieSeries options={{ entryMs: 900 }} data={data} />
+     *
+     * // Chart-level default:
+     * <ChartContainer animations={{ series: { pie: { entry: 900 } } }}>
+     *   <PieSeries data={data} />
+     * </ChartContainer>
+     * ```
+     *
+     * `false` or `0` disables the intro (a chart-level
+     * `animations.series.pie: false` also force-disables it). Bulk re-seeds
+     * of a non-empty series never replay it. Skipped entirely under
+     * `prefers-reduced-motion`.
+     */
+    entryMs?: number | false;
     /**
      * Per-slice radial *depth* gradient — a subtle lightening from the slice
      * center toward its edge that gives the pie a soft 3D sheen. On by default.
@@ -3046,7 +4105,7 @@ export declare interface PieSeriesOptions {
 }
 
 /** A spatial renderer with no time axis (Pie). Has no time-series queries. */
-declare interface PieSeriesRenderer extends BaseSeriesRenderer {
+export declare interface PieSeriesRenderer extends BaseSeriesRenderer {
     readonly kind: 'pie';
 }
 
@@ -3061,6 +4120,51 @@ export declare interface PieSliceData {
 
 export declare const PieTooltip: __VLS_WithTemplateSlots_5<typeof __VLS_component_5, __VLS_TemplateResult_5["slots"]>;
 
+/**
+ * One placeholder shape a loading indicator painted, in chart-media pixels
+ * relative to the data boundary — the hand-off currency between an edge
+ * indicator and a series' history reveal. `offsetX` grows away from the
+ * data (into the overshoot zone), so the geometry stays glued to the
+ * boundary while the user keeps panning.
+ */
+declare interface PlaceholderBar {
+    /** Distance from the data boundary to the bar's center, media px, ≥ 0. */
+    offsetX: number;
+    /** Bar center Y, media px within the plot area. */
+    y: number;
+    /** Half the body height, media px. */
+    halfHeight: number;
+    /** Body width, media px. */
+    width: number;
+}
+
+/**
+ * Chart-recorder pen: the reveal front advances at constant speed along the
+ * polyline's arc length (bitmap space), so it decelerates through volatile
+ * stretches and races across flat ones. Falls back to the plain sweep for
+ * stacked series and degenerate paths.
+ */
+export declare function plotterIntro(): LineIntroFn;
+
+/**
+ * Payload for `pointClick` / `pointDoubleClick`. `spatialHit` resolves a
+ * no-time-axis series (pie, heatmap, or a custom spatial kind) directly
+ * under the pointer — for time-series series (line/bar/candlestick, or a
+ * custom time-axis kind), resolve the point yourself from `time`, e.g. via
+ * `buildHoverSnapshots(chart, { time: info.time, cacheKey: '…' })` or
+ * `chart.getDataAtTime(seriesId, info.time)`.
+ */
+export declare interface PointClickInfo {
+    mediaX: number;
+    mediaY: number;
+    time: number;
+    y: number;
+    spatialHit: {
+        seriesId: string;
+        index: number;
+    } | null;
+}
+
 export declare const quietLight: ThemePreset;
 
 /** Axis-aligned rectangle in media (CSS) coordinates. */
@@ -3071,7 +4175,7 @@ declare interface Rect {
     height: number;
 }
 
-export declare const ReferenceLine: DefineComponent<__VLS_Props_13, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_13> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const ReferenceLine: DefineComponent<__VLS_Props_15, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_15> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /**
  * A straight reference line across the plot — a horizontal threshold / baseline
@@ -3086,9 +4190,9 @@ export declare interface ReferenceLineConfig {
     value?: number;
     /** Vertical line at this `time` (epoch ms or `Date`). Mutually exclusive with {@link value}. */
     time?: TimeValue;
-    /** Line and label-pill color. Default: the theme line color. */
+    /** Line and label-chip accent color. Default: the theme line color. */
     color?: string;
-    /** Optional text label drawn in a pill at the line's near end. */
+    /** Optional text label drawn in an annotation chip at the line's near end. */
     label?: string;
     /** Dash style. Default: `'dashed'`. */
     style?: ReferenceLineStyle;
@@ -3113,7 +4217,7 @@ declare interface RegionEntry {
 }
 
 /**
- * Register the four built-in series so the string form
+ * Register the five built-in series so the string form
  * `chart.addSeries('line', …)` resolves. Call it once at startup.
  *
  * Importing this helper pulls every renderer into the bundle — hosts that
@@ -3143,7 +4247,7 @@ export declare function registerSeriesDefinition(def: SeriesDefinition): void;
  * but spatial renderers (Pie) need the raw pixel reservation to keep their
  * layout out of the Title / InfoBar overlay regions.
  */
-declare interface RenderPadding {
+export declare interface RenderPadding {
     top: number;
     bottom: number;
 }
@@ -3202,6 +4306,14 @@ declare interface RetargetOptions {
     contractMs?: number;
 }
 
+/**
+ * Elements float up into place from below, fading in along the wave.
+ * Works for both bar and candlestick series.
+ */
+export declare function riseIntro(options?: {
+    travel?: number;
+}): WaveIntroFn;
+
 export declare const rosePineDawn: ThemePreset;
 
 /** DEFAULT bar painter (registered as `'rounded'`). Trusts the engine-supplied
@@ -3225,6 +4337,13 @@ export declare interface RoundedRectArgs {
     corners: CornerMask;
 }
 
+/**
+ * Sample a multi-stop ramp at `t` in [0, 1] with perceptual interpolation
+ * between adjacent stops. A single-stop ramp returns that stop; an empty
+ * ramp returns transparent black (defensive — resolved options never allow it).
+ */
+export declare function sampleRamp(stops: readonly string[], t: number): string;
+
 export declare const sandDune: ThemePreset;
 
 /** Environment the chart hands a {@link SeriesDefinition} when constructing its renderer. */
@@ -3250,6 +4369,20 @@ export declare interface SeriesDefinition<O = Record<string, unknown>> {
     create(env: SeriesCreateEnv, options: Partial<O>): SeriesRenderer;
 }
 
+/** Which spatial series (pie, heatmap, or a custom spatial kind) is currently hovered, and its slice/cell info. */
+export declare interface SeriesHoverInfo {
+    seriesId: string;
+    index: number;
+    info: HoverInfo | null;
+}
+
+/**
+ * Discriminant for the {@link SeriesRenderer} union. Open-ended — a custom
+ * series (see {@link CustomSpatialSeriesRenderer} / {@link TimeSeriesRenderer})
+ * picks any string that isn't one of the built-ins.
+ */
+export declare type SeriesKind = 'candlestick' | 'line' | 'bar' | 'pie' | 'heatmap' | (string & {});
+
 /**
  * A single named (and optionally colored) layer. Carries the layer's display
  * name and color *alongside* its data, so `Tooltip` / `Legend` show per-layer
@@ -3265,7 +4398,7 @@ declare interface SeriesLayer<T> {
     data: T[];
 }
 
-declare interface SeriesRenderContext {
+export declare interface SeriesRenderContext {
     scope: BitmapCoordinateSpace;
     timeScale: XScale;
     yScale: YScale;
@@ -3289,9 +4422,10 @@ declare interface SeriesRenderContext {
 
 /**
  * Every series renderer is one of these. Discriminated on `kind`: narrow with
- * `kind === 'pie'` (or `!== 'pie'`) to reach the variant-specific surface.
+ * {@link isTimeSeriesRenderer} to reach the time-axis surface — spatial kinds
+ * (pie, heatmap, and any custom spatial kind) have no time-series queries.
  */
-declare type SeriesRenderer = TimeSeriesRenderer | PieSeriesRenderer;
+export declare type SeriesRenderer = TimeSeriesRenderer | PieSeriesRenderer | HeatmapSeriesRenderer | CustomSpatialSeriesRenderer;
 
 /**
  * Frozen, per-row snapshot of a series at a single point in time. The shape
@@ -3319,8 +4453,8 @@ export declare interface SeriesSnapshot {
     readonly color: string;
 }
 
-/** Supported primary series types. */
-export declare type SeriesType = 'candlestick' | 'line' | 'bar' | 'pie';
+/** Primary series types. Open-ended — a custom {@link SeriesDefinition} picks any string that isn't a built-in. */
+export declare type SeriesType = 'candlestick' | 'line' | 'bar' | 'pie' | 'heatmap' | (string & {});
 
 /** Width and height pair. */
 declare interface Size {
@@ -3328,17 +4462,97 @@ declare interface Size {
     height: number;
 }
 
+/**
+ * "Chart skeleton" — muted placeholder candle shapes with a soft shimmer
+ * band sweeping across them, the classic skeleton-screen pattern adapted for
+ * a time-series stage. The bar nearest the boundary is centered on the real
+ * {@link LoadingIndicatorArgs.edgeValueY} so it still visually picks up
+ * where the chart leaves off; the rest are honest placeholders (a gentle
+ * taper), not a prediction. Falls back to mid-height when no boundary value
+ * is resolvable (e.g. an empty chart).
+ *
+ * Placeholder size tracks {@link LoadingIndicatorArgs.barSpacing} — the
+ * chart's actual current zoom level — so bars don't visually "pop" to a
+ * different size once real data lands; when it isn't resolvable, falls back
+ * to a fixed gap. Wick stubs only draw for `seriesKind === 'candlestick'`
+ * (or when the kind isn't resolvable, since candlestick is the common case);
+ * a `'line'`/`'bar'` series gets a plain placeholder body instead, since a
+ * wick reads as OHLC-specific.
+ */
+export declare const skeletonLoadingIndicator: LoadingIndicatorFn;
+
+/**
+ * Skeleton morph: candles that land where the loading indicator's
+ * placeholder bars stood grow out of those exact shapes — geometry eases
+ * from the placeholder body to the real OHLC, fill blends from the muted
+ * placeholder gray to the candle's own color. Candles outside the
+ * placeholder zone (and any reveal with no hand-off, e.g. a custom
+ * indicator that never reports its shapes) play the `fallback` instead —
+ * `fadeIntro()` unless overridden.
+ *
+ * Meant for the `historyReveal` option, paired with an `EdgeLoader` whose
+ * indicator reports placeholders (`skeletonLoadingIndicator` does).
+ */
+export declare function skeletonMorphIntro(options?: {
+    fallback?: CandleIntroFn;
+}): CandleIntroFn;
+
 export declare type SliceInfo = HoverInfo;
 
 /** `curve: 'smooth'` — monotone cubic. The in-flight last segment stays straight
  *  while the trailing endpoint is growing so the head can't wobble / overshoot. */
 export declare const smoothCurve: LinePainter;
 
+/**
+ * Snap factory — no animation, no parameters. Generic so it works for both
+ * Y and X. Exposed so power users can opt out of axis motion without
+ * disabling other animations:
+ *
+ * ```
+ * animations: { axis: { y: { curve: snap() } } }
+ * ```
+ */
+export declare function snap<T extends YRange | VisibleRange = YRange>(): TransitionFactory<T>;
+
 /** Sort order applied to a snapshot list by the helper. */
 export declare type SnapshotSort = 'none' | 'asc' | 'desc';
 
 export declare const solarizedLight: ThemePreset;
 
+/**
+ * Critically-damped spring transition factory. Generic over the value type
+ * so the same factory works for both Y (`YRange`) and X (`VisibleRange`).
+ *
+ * The factory dispatches at construction time based on the shape of the
+ * initial value:
+ *
+ * - `{ min, max }` → {@link YRangeSpring} (direction-aware ω: expand vs
+ *   contract, used by the sticky-Y mechanism).
+ * - `{ from, to }` → {@link VisibleRangeSpring} (single ω, no direction
+ *   asymmetry — X has no analog of sticky-Y).
+ *
+ * Both implementations carry velocity through mid-flight retargets so
+ * wheel-zoom sequences and rapid streaming ticks stay continuous.
+ *
+ * Usage:
+ * ```ts
+ * animations: {
+ *   axis: {
+ *     y: { curve: spring() },
+ *     x: { curve: spring() },
+ *   },
+ * }
+ * ```
+ *
+ * The engine is the single source of truth for the per-call durations —
+ * settle times come through `RetargetOptions.expandMs` / `contractMs`.
+ */
+export declare function spring<T extends YRange | VisibleRange = YRange>(): TransitionFactory<T>;
+
+/** Bars grow from the baseline with a soft ease-out-back overshoot past
+ *  their final height before settling. */
+export declare function springIntro(): BarIntroFn;
+
 /** Stacking mode for bar/line series: off (overlap), normal (stacked), percent (100% stacked). */
 export declare type StackingMode = 'off' | 'normal' | 'percent';
 
@@ -3349,6 +4563,11 @@ export declare const steppedCurve: LinePainter;
  *  the pre-feature stroke path. */
 export declare const straightCurve: LinePainter;
 
+/** Left-to-right draw-on behind a clip edge with a glowing head. */
+export declare function sweepIntro(options?: {
+    head?: boolean;
+}): LineIntroFn;
+
 /**
  * Input config for {@link createTheme}. Mirrors the structure of {@link ChartTheme}
  * but everything is optional except `background`. Missing values are derived automatically.
@@ -3368,6 +4587,7 @@ export declare interface ThemeConfig {
     seriesColors?: string[];
     bar?: Partial<NonNullable<ChartTheme['bar']>>;
     pie?: Partial<NonNullable<ChartTheme['pie']>>;
+    heatmap?: Partial<NonNullable<ChartTheme['heatmap']>>;
     bands?: Partial<ChartTheme['bands']>;
     crosshair?: Partial<ChartTheme['crosshair']>;
     axis?: Partial<ChartTheme['axis']>;
@@ -3431,9 +4651,18 @@ declare interface TickTrackerSnapshot {
     readonly isAnimating: boolean;
 }
 
-export declare const TimeAxis: DefineComponent<__VLS_Props_14, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_14> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
-containerRef: HTMLDivElement;
-}, HTMLDivElement>;
+/** Locale / timezone override for {@link formatTime} / {@link formatDate}. Any field omitted keeps the built-in default. */
+export declare interface TimeFormatOptions {
+    /** BCP 47 locale tag (e.g. `'de-DE'`). Default: `'en-US'`. */
+    locale?: string;
+    /** IANA timezone name (e.g. `'America/New_York'`). Default: the browser's local timezone. */
+    timeZone?: string;
+    /** 12-hour clock. Default: `false` (24-hour), preserved from the original hardcoded behavior. */
+    hour12?: boolean;
+}
+
+/** Custom time-tick formatter, mirroring {@link YScale}'s `ValueFormatter` contract. */
+export declare type TimeFormatter = (timestamp: number, interval: number) => string;
 
 /** A single time-value data point for line and bar series. Time is a timestamp in milliseconds. */
 export declare interface TimePoint {
@@ -3446,7 +4675,7 @@ export declare type TimePointInput = Omit<TimePoint, 'time'> & {
     time: TimeValue;
 };
 
-export declare const TimeRegion: DefineComponent<__VLS_Props_15, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_15> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const TimeRegion: DefineComponent<__VLS_Props_17, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_17> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /**
  * A translucent vertical band shading the interval `[from, to]` — Grafana's
@@ -3465,9 +4694,9 @@ export declare interface TimeRegionConfig {
     to?: TimeRegionEnd;
     /** Band fill — any CSS color, typically translucent. Default: a faint tint of `color`. */
     fill?: string;
-    /** Optional text label drawn in a pill at the top of the band. */
+    /** Optional text label drawn in an annotation chip at the top of the band. */
     label?: string;
-    /** Edge-line and label-pill accent. Default: the theme's muted axis text color. */
+    /** Edge-line and label-chip accent. Default: the theme's muted axis text color. */
     color?: string;
 }
 
@@ -3485,8 +4714,8 @@ export declare type TimeRegionEnd = TimeValue | 'now';
  * `getLastDataPoint` / `getSecondLastDataPoint` / `getVisibleDataPoints` are
  * pinned to layer 0 (see {@link BaseMultiLayerSeries}).
  */
-declare interface TimeSeriesRenderer extends BaseSeriesRenderer {
-    readonly kind: 'candlestick' | 'line' | 'bar';
+export declare interface TimeSeriesRenderer extends BaseSeriesRenderer {
+    readonly kind: 'candlestick' | 'line' | 'bar' | (string & {});
     /** Earliest/latest sample time across all owned layers, or null when empty. */
     getTimeBounds(): {
         first: number;
@@ -3507,6 +4736,9 @@ declare interface TimeSeriesRenderer extends BaseSeriesRenderer {
     } | null;
 }
 
+/** Custom tick-value generator — replaces the built-in `niceTimeIntervals` tier resolution entirely when installed. */
+export declare type TimeTickGenerator = (range: XRange, dataInterval: number) => number[];
+
 /**
  * Accepted time input: a timestamp in **milliseconds** (like `Date.now()`) or a `Date` object.
  * `Date` values are converted to milliseconds internally via `Date.getTime()`.
@@ -3557,6 +4789,15 @@ export declare interface TooltipPositionArgs {
     offsetY?: number;
 }
 
+/**
+ * Blueprint → ink: a faint stroke-only ghost of the whole line shows from
+ * the first frame, while the full-color pass (area included) sweeps across
+ * behind the same front as `'sweep'`.
+ */
+export declare function traceIntro(options?: {
+    ghostAlpha?: number;
+}): LineIntroFn;
+
 /**
  * Emit path commands for one run of points onto `env.ctx`. Issues only
  * `moveTo` / `lineTo` / `bezierCurveTo`; it never opens or closes a path, so the
@@ -3591,7 +4832,7 @@ export declare interface TracePathArgs {
  * Other animation math (entry tweens, pulse, axis tick fade) stays
  * engine-fixed.
  */
-declare interface Transition<T> {
+export declare interface Transition<T> {
     /** Current sampled position. Read by renderers on every frame. */
     readonly current: T;
     /** Active retarget destination. May equal `current` after settle. */
@@ -3617,7 +4858,7 @@ declare interface Transition<T> {
  * Holds the initial value so the produced transition starts pinned to
  * the same value the chart will render on its first frame.
  */
-declare interface TransitionContext<T> {
+export declare interface TransitionContext<T> {
     initial: T;
 }
 
@@ -3627,7 +4868,7 @@ declare interface TransitionContext<T> {
  * smoothing strategy. Built-in factories: {@link hermite} (Y default),
  * {@link spring} (X default, also valid for Y), {@link snap} (no animation).
  */
-declare type TransitionFactory<T> = (ctx: TransitionContext<T>) => Transition<T>;
+export declare type TransitionFactory<T> = (ctx: TransitionContext<T>) => Transition<T>;
 
 /** Font family and base font size used across the chart. */
 export declare interface Typography {
@@ -3637,6 +4878,17 @@ export declare interface Typography {
     fontSize: number;
 }
 
+/**
+ * Amplitude unfold: every value lerps from its layer's visible mean toward
+ * its real value with a soft ease-out-back overshoot, staggered
+ * left-to-right by `stagger` (fraction of the window; default 0.35,
+ * clamped to `[0, 0.9]` — at 1 the rightmost points would never finish
+ * their tween and snap on settle).
+ */
+export declare function unfoldIntro(options?: {
+    stagger?: number;
+}): LineIntroFn;
+
 export declare function useChartInstance(): ChartInstance;
 
 export declare function useCrosshairPosition(chart: ChartInstance): Ref<CrosshairPosition | null>;
@@ -3685,6 +4937,9 @@ declare type ValueColor = string | ((value: number) => string);
 /** Signature for a value-to-string formatter (YAxis, YLabel, Pie, Sparkline, NumberFlow). */
 export declare type ValueFormatter = (value: number) => string;
 
+/** Custom tick-value generator — replaces the built-in {1,2,5}×10^k resolution entirely when installed. */
+export declare type ValueTickGenerator = (range: YRange) => number[];
+
 /** @deprecated Use {@link XRange} instead. Visible time range of the chart. */
 export declare type VisibleRange = XRange;
 
@@ -3698,7 +4953,7 @@ export declare type VisibleRange = XRange;
  *   right by `bars` data intervals. Useful for "show N bars starting
  *   here" patterns (warm-up windows for streaming charts, etc.).
  */
-declare type VisibleRangeSpec = number | {
+export declare type VisibleRangeSpec = number | {
     from: TimeValue;
     to: TimeValue;
 } | {
@@ -3706,6 +4961,70 @@ declare type VisibleRangeSpec = number | {
     bars: number;
 };
 
+/** Directives shape common to both series (each extends it with its own
+ *  element/value callbacks). */
+export declare interface WaveIntroDirectives {
+    /**
+     * Horizontal clip window in bitmap pixels applied to the whole series
+     * pass. Omitted sides default to the pane edges, so `{ toX }` is a
+     * left-to-right reveal.
+     */
+    clip?: {
+        fromX?: number;
+        toX?: number;
+    };
+    element?: (el: WaveIntroElement) => WaveIntroTransform;
+}
+
+/** Per-element fields common to the bar and candlestick intro contracts. */
+export declare interface WaveIntroElement {
+    /** Eased wave progress for this element, staggered left → right. */
+    progress: number;
+    /** Normalized x-position across the visible window, clamped to `[0, 1]`. */
+    position: number;
+    /** The element's time coordinate. */
+    time: number;
+}
+
+/** An intro function built only from the shared fields — assignable to both
+ *  `BarIntroFn` and `CandleIntroFn`. */
+export declare type WaveIntroFn = (frame: WaveIntroFrame) => WaveIntroDirectives;
+
+/** Frame fields common to the bar and candlestick intro contracts. */
+export declare interface WaveIntroFrame {
+    /** Linear intro progress in `[0, 1]` over the whole reveal window. */
+    progress: number;
+    /**
+     * Plot-area width in bitmap pixels — the span the time scale maps the
+     * visible range onto (excludes the Y-axis strip sharing the canvas).
+     */
+    width: number;
+    /** Plot-area height in bitmap pixels (excludes the X-axis strip). */
+    height: number;
+    /** Visible time range. */
+    range: VisibleRange;
+}
+
+/** Declarative transform understood by both series' element callbacks. */
+export declare interface WaveIntroTransform {
+    /** Horizontal translation in bitmap px. */
+    offsetX?: number;
+    /** Vertical translation in bitmap px. */
+    offsetY?: number;
+    /** Opacity multiplier in `[0, 1]`. */
+    alpha?: number;
+}
+
+/** Two-phase reveal: wicks needle out first as a skeleton, then bodies (and
+ *  volume) unfold over them from the open price. */
+export declare function wickBodyIntro(): CandleIntroFn;
+
+/**
+ * A hard reveal front sweeps left to right; elements appear fully formed
+ * behind it. Works for both bar and candlestick series.
+ */
+export declare function wipeIntro(): WaveIntroFn;
+
 /** Configuration for the X (time) axis. */
 export declare interface XAxisConfig {
     /** Height in CSS pixels. Default: 30. */
@@ -3720,7 +5039,7 @@ declare interface XRange {
     to: number;
 }
 
-declare class XScale {
+export declare class XScale {
     /**
      * Shared fade state for time ticks. Grid lines (canvas) and DOM tick labels
      * read opacity from the same tracker, so a tick fading in/out looks
@@ -3734,6 +5053,12 @@ declare class XScale {
     private dataInterval;
     private labelCountHintValue;
     private minSpacingValue;
+    /** Custom formatter (driven by `setFormat` / a future `<TimeAxis format=…>`). */
+    private customFormat;
+    /** Custom tick generator — bypasses tier resolution in `niceTickValues` when set. */
+    private customTickGenerator;
+    private localeValue;
+    private timeZoneValue;
     private resolvedInterval;
     private lastInterval;
     /**
@@ -3750,6 +5075,28 @@ declare class XScale {
     update(range: XRange, mediaWidth: number, pixelRatio: number, dataInterval?: number): void;
     setLabelCount(n: number | null | undefined): void;
     setMinSpacing(px: number | null | undefined): void;
+    /** Install (or clear) a custom tick-label formatter. */
+    setFormat(fn: TimeFormatter | null): void;
+    /** Read back the currently installed formatter — null when the built-in is active. */
+    getFormat(): TimeFormatter | null;
+    /**
+     * Install (or clear) a custom tick-value generator. When set, it replaces
+     * `niceTimeIntervals` tier resolution entirely — `niceTickValues` calls it
+     * directly with the current range and reports its own tick spacing.
+     */
+    setTickGenerator(fn: TimeTickGenerator | null): void;
+    /** BCP 47 locale applied to the built-in formatter. Ignored while a custom `setFormat` is installed. */
+    setLocale(locale: string | undefined): void;
+    getLocale(): string | undefined;
+    /** IANA timezone applied to the built-in formatter. Ignored while a custom `setFormat` is installed. */
+    setTimeZone(timeZone: string | undefined): void;
+    getTimeZone(): string | undefined;
+    /**
+     * Format a tick timestamp for display. A custom formatter (via
+     * {@link setFormat}) wins; otherwise falls back to the built-in
+     * `formatTime`, applying the installed locale/timezone.
+     */
+    formatX(timestamp: number, interval: number): string;
     private resetHysteresis;
     timeToX(time: number): number;
     timeToBitmapX(time: number): number;
@@ -3777,7 +5124,7 @@ declare class XScale {
     private countTicks;
 }
 
-export declare const YAxis: DefineComponent<__VLS_Props_18, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_18> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+export declare const YAxis: DefineComponent<__VLS_Props_20, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_20> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 containerRef: HTMLDivElement;
 }, HTMLDivElement>;
 
@@ -3795,6 +5142,23 @@ export declare interface YAxisConfig {
 
 export declare const YLabel: __VLS_WithTemplateSlots_8<typeof __VLS_component_8, __VLS_TemplateResult_8["slots"]>;
 
+/**
+ * Badge motion: `true` (default) glides + counts up + fades in with the intro;
+ * `false` snaps with no easing (the pre-animation behavior); an object tunes
+ * individual parts.
+ */
+declare type YLabelAnimate = boolean | YLabelAnimateOptions;
+
+/** Fine-grained badge motion tuning. See the framework `YLabel`'s `animate` prop. */
+declare interface YLabelAnimateOptions {
+    /** Glide the badge vertically across value jumps instead of snapping. Default `true`. */
+    glide?: boolean;
+    /** Count the value up from the first visible sample to the last during the initial reveal. Default `true`. */
+    countUp?: boolean;
+    /** Settle time (ms) for the vertical glide. Default {@link DEFAULT_SETTLE_MS}. */
+    settleMs?: number;
+}
+
 /** Direction of the current value vs. previous close. Drives the badge color in the default UI. */
 declare type YLabelDirection = 'up' | 'down' | 'neutral';
 
@@ -3811,7 +5175,7 @@ export declare interface YRange {
  * Maps values to vertical pixel positions (and vice versa).
  * Also provides tick generation and value formatting for the Y axis.
  */
-declare class YScale {
+export declare class YScale {
     /** Shared fade state for Y ticks; see {@link TimeScale.tickTracker}. */
     readonly tickTracker: AxisTickTracker;
     private min;
@@ -3834,6 +5198,8 @@ declare class YScale {
     private lastRawInterval;
     /** Custom formatter (driven by `<YAxis format=…>`). */
     private customFormat;
+    /** Custom tick generator — bypasses {1,2,5}×10^k resolution in `niceTickValues` when set. */
+    private customTickGenerator;
     private get labelCountHint();
     private get minLabelSpacing();
     /** Recalculate the scale with a new Y range, chart height, and device pixel ratio. */
@@ -3847,6 +5213,12 @@ declare class YScale {
     setFormat(fn: ValueFormatter | null): void;
     /** Read back the currently installed formatter — null when the built-in is active. */
     getFormat(): ValueFormatter | null;
+    /**
+     * Install (or clear) a custom tick-value generator. When set, it replaces
+     * {1,2,5}×10^k resolution entirely — `niceTickValues` calls it directly
+     * with the current range.
+     */
+    setTickGenerator(fn: ValueTickGenerator | null): void;
     /** 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. */