@wick-charts/vue 0.3.6 → 0.4.0

package/dist/index.d.ts

@@ -151,6 +151,28 @@ declare type __VLS_Props_3 = {
             intervals: number;
         };
     };
+    /**
+     * Viewport-level streaming behavior. Captured at mount only — changing
+     * this prop after the chart is created is ignored.
+     */
+    viewport?: {
+        /**
+         * Width of the visible window in data bars, set on the first data load
+         * to `maxVisibleBars * dataInterval`. While the dataset is smaller than
+         * this width, streaming ticks render into the empty right-side gap and
+         * the viewport stays put; once the data reaches the right edge, the
+         * viewport pans forward to keep the latest bar pinned (tail-scroll).
+         * Default: 200.
+         */
+        maxVisibleBars?: number;
+        /**
+         * Initial visible range applied before the first paint with data. Same
+         * shape as the imperative `chart.setVisibleRange` — pass a bar count
+         * (e.g. `35`), an explicit `{from, to}` window, or `{from, bars}` for
+         * a warm-up pair. Captured at mount.
+         */
+        initialRange?: VisibleRangeSpec;
+    };
     /** Show the chart background gradient. Defaults to true. */
     gradient?: boolean;
     /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
@@ -166,16 +188,15 @@ declare type __VLS_Props_3 = {
      */
     headerLayout?: 'overlay' | 'inline';
     /**
-     * Chart-level animation configuration. See `AnimationsConfig` for the full shape.
+     * Animation control. `true` / omitted uses built-in defaults; `false`
+     * disables every category. Per-series options on `<LineSeries>` /
+     * `<CandlestickSeries>` / `<BarSeries>` override these chart-level
+     * defaults unless the category here is explicitly `false`.
      *
-     * Two layers — chart-level (this prop) sets defaults for every series; per-series
-     * options on `<LineSeries>`/`<CandlestickSeries>`/`<BarSeries>` override that
-     * default for that one series.
-     *
-     * Shorthands: `true` / omitted — built-in defaults; `false` — disables every
-     * animation category; `{ points: false }` / `{ viewport: false }` disables a
-     * category. Updating this prop calls `chart.setAnimations(...)` so the new
-     * durations take effect on the next animation / render.
+     * **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.
      */
     animations?: boolean | AnimationsConfig;
     /**
@@ -465,114 +486,230 @@ declare type __VLS_WithTemplateSlots_8<T, S> = T & {
 export declare const andromeda: ThemePreset;
 
 /**
- * Chart-level animation configuration. Two independent domains so per-series
- * defaults can't bleed into viewport-interaction timings.
- *
- * **Two layers — chart-level vs per-series.** The same data-animation knobs
- * live on both layers; remember which is which:
+ * Animation behavior knobs grouped by surface:
  *
- * | Field | Chart-level (here) | Per-series option |
- * | ----- | ------------------ | ----------------- |
- * | Entry duration | {@link AnimationsConfig.points}`.enterMs` | `<XSeries options={{ entryMs }}>` (canonical name; `enterMs` is a `@deprecated` alias) |
- * | Live smoothing | `points.smoothMs` | `options={{ smoothMs }}` |
- * | Line pulse period | `points.pulseMs` | `<LineSeries options={{ pulseMs }}>` |
+ * - `axis.y` — Y bound chase: pluggable curve, expand/contract/gesture
+ *   settle times.
+ * - `axis.x` — X viewport: streaming settle + gesture override.
+ * - `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.
  *
- * Resolution: per-series option **wins** (it's the override). The chart-
- * level field acts as the default for every series that didn't set its own
- * override — *except* when the chart-level category is explicitly `false`,
- * which is a hard disable that overrides per-series too.
+ * Top-level `false` disables every animation category. `axis: false`
+ * disables both axes and ticks. `axis.y: false` / `axis.x: false` disables
+ * that axis only. Series-type-level `false` (`series: { line: false }`)
+ * disables that type only.
  *
- * - `points` — applied to data: entrance tween, live-tracking smoothing of
- *   the last candle/bar/line value, line pulse cadence.
- * - `viewport` — applied to viewport interactions: post-gesture rebound,
- *   Y-axis range chase, optional per-event ease for pan/zoom. Has no
- *   per-series equivalent — these are chart-level only.
- *
- * All settling animations share a 250 ms default so the X re-fit, Y range
- * update, and last-bar live-track all settle on the same frame on a
- * streaming tick. Pulse cycle period (600 ms) and `inputResponseMs` (0,
- * opt-in) keep their own values.
+ * The per-series numeric fields (`entry` / `smooth` / `pulse`) also exist
+ * on individual series options (`<XSeries options={{ entryMs }}>`). The
+ * chart-level field acts as the default for any series that hasn't set its
+ * own override; an explicit `series.<type>: false` (or top-level `false`)
+ * is a hard disable that overrides per-series.
  */
 declare interface AnimationsConfig {
     /**
-     * Data-series animations. `false` disables every point animation (entrance,
-     * live-smoothing, pulse) across every series — overrides any per-series
-     * option set on the same fields. An object overrides individual categories;
-     * omitted fields fall back to the built-in defaults.
-     *
-     * Per-series options (`<LineSeries options={{ entryMs, smoothMs, pulseMs }}>`)
-     * win over chart-level numeric values. The chart-level field becomes the
-     * default for series that don't set their own.
+     * Axis-level animation. `false` collapses both axes and ticks to instant.
      */
-    points?: false | {
+    axis?: false | {
         /**
-         * Per-point entrance duration (ms). Default: 250.
-         * Per-series equivalent: `<XSeries options={{ entryMs }}>` (note the
-         * `y` — chart-level uses `enterMs`, per-series uses `entryMs` for
-         * historical reasons; both refer to the same animation). `false` /
-         * `0` disables.
+         * Y bound chase. `false` snaps Y instantly.
          */
-        enterMs?: AnimationTime;
+        y?: false | {
+            /** Y curve. See {@link hermite}, {@link spring}, {@link snap}. */
+            curve?: TransitionFactory<YRange>;
+            /**
+             * Outward settle time — bound expanding to a new extreme.
+             *
+             * @default {@link DEFAULT_Y_SETTLE_MS}
+             */
+            settle?: AnimationTime;
+            /**
+             * Inward (contraction) settle — applied when a bound recedes
+             * after an extreme leaves the window (the "sticky-Y" hold).
+             *
+             * - `{ min, max }` — **dynamic**: the contract duration scales
+             *   with the contraction magnitude, from `min` (a tiny recede)
+             *   up to `max` (a full-range contraction). Big outliers ease
+             *   off slowly while small receders finish quickly, so the axis
+             *   doesn't crawl for seconds over a few pixels. Either side
+             *   falls back to its default when omitted.
+             * - a scalar `AnimationTime` — **fixed**: `min === max`, every
+             *   contraction takes the same time regardless of size (the
+             *   legacy sticky feel). `false` snaps contractions instantly.
+             *
+             * @default `{ min:` {@link DEFAULT_Y_STICKY_MIN_MS}`, max:` {@link DEFAULT_Y_STICKY_MAX_MS}` }`
+             */
+            sticky?: AnimationTime | {
+                min?: AnimationTime;
+                max?: AnimationTime;
+            };
+            /**
+             * One-shot override during a user gesture (pan/zoom). Shorter
+             * than `sticky` so contractions during interaction converge in
+             * ~one frame per wheel tick.
+             *
+             * @default {@link DEFAULT_Y_GESTURE_MS}
+             */
+            gesture?: AnimationTime;
+        };
         /**
-         * Live-value chase duration (ms) for the displayed last point on
-         * `updateData` ticks. Animator-driven cubic ease — after this many ms
-         * with no new updates, the displayed value reaches exactly the
-         * actual last value. Default: 250. Per-series equivalent:
-         * `options={{ smoothMs }}`. `false` / `0` snaps.
+         * X viewport. `false` snaps X instantly. The default critically-
+         * damped spring carries velocity across retargets so wheel-zoom
+         * sequences feel continuous and stream ticks blend smoothly into
+         * gesture motion.
          */
-        smoothMs?: AnimationTime;
+        x?: false | {
+            /** X curve. See {@link spring}, {@link snap}. */
+            curve?: TransitionFactory<VisibleRange>;
+            /**
+             * Streaming settle time. Spring reaches ~99% of the target
+             * after this many ms. Used for streaming retargets; the
+             * streaming-cadence EMA tunes the effective value upward when
+             * data arrives slower than the baseline.
+             *
+             * @default {@link DEFAULT_X_SETTLE_MS}
+             */
+            settle?: AnimationTime;
+            /**
+             * One-shot override applied to user pan/zoom commits and to
+             * programmatic `fitContent`.
+             *
+             * @default {@link DEFAULT_X_GESTURE_MS}
+             */
+            gesture?: AnimationTime;
+        };
         /**
-         * Pulse cycle period (ms) for the line last-point halo — periodic,
-         * not a one-shot transition. Default: 600. Per-series equivalent:
-         * `<LineSeries options={{ pulseMs }}>`. `false` / `0` disables.
+         * Axis tick label cross-fade. `false` makes tick relabel instant.
+         *
+         * @default {@link DEFAULT_TICKS_MS}
          */
-        pulseMs?: AnimationTime;
+        ticks?: AnimationTime;
     };
     /**
-     * Viewport interaction animations. `false` disables both rebound and Y-axis
-     * smoothing — viewport changes snap instantly.
+     * Series-visibility toggle duration. Drives BOTH the renderer's alpha
+     * cross-fade and the engine's Y re-fit ease, so the two animations land
+     * on the same frame. `false` makes `setSeriesVisible` instant.
+     *
+     * @default {@link DEFAULT_TOGGLE_MS}
      */
-    viewport?: false | {
-        /** Rebound (snap-back) duration after pan/zoom overshoot (ms). Default: 350. */
-        reboundMs?: AnimationTime;
+    toggle?: AnimationTime;
+    /**
+     * Per-series-type data animations. `false` disables every per-point
+     * animation across every series. Setting a single type to `false`
+     * (`series: { line: false }`) disables that type only.
+     *
+     * Per-series options (`<LineSeries options={{ entryMs, smoothMs, pulseMs }}>`)
+     * win over chart-level numeric values. The chart-level field becomes the
+     * default for series that don't set their own.
+     */
+    series?: false | {
         /**
-         * Y-axis range transition duration in wall-clock milliseconds. The Y
-         * min and max each ride their own {@link Animator} that retargets on
-         * data updates and eases toward the new bound over this many ms.
-         * Default `250` (shares the lockstep-arrival budget with viewport and
-         * live-track). Inward contraction always eases. Outward expansion
-         * eases when the per-point entrance is enabled (the entering candle's
-         * fade masks the brief overshoot); when entrance is hard-disabled
-         * (`points.enterMs === 0`), Y bounds snap outward to keep new
-         * highs/lows from clipping at the canvas edge. `false` / `0` snaps
-         * the Y range instantly on every update.
+         * Line-series tweens. `false` disables all line animations
+         * (entrance, live-smoothing, pulse).
          */
-        yAxisMs?: AnimationTime;
+        line?: false | {
+            /**
+             * Per-point entrance duration. `false` disables the entrance
+             * (equivalent to `entryAnimation: 'none'`).
+             *
+             * @default {@link DEFAULT_LINE_ENTRY}
+             */
+            entry?: AnimationTime;
+            /**
+             * Last-value chase duration on `updateLastPoint`. `false` /
+             * `0` snaps to the target instantly.
+             *
+             * @default {@link DEFAULT_LINE_SMOOTH}
+             */
+            smooth?: AnimationTime;
+            /**
+             * Halo cycle period at the line tail. Periodic loop, not a
+             * one-shot. `false` / `0` turns the halo off entirely (drawing
+             * and animation loop).
+             *
+             * @default {@link DEFAULT_LINE_PULSE}
+             */
+            pulse?: AnimationTime;
+        };
         /**
-         * Per-event ease applied to user pan/zoom commits. Logical state
-         * advances synchronously (gesture math, edge detection, autoscroll
-         * all read the committed target); the visual range eases over this
-         * duration so back-to-back wheel/trackpad events interpolate
-         * smoothly through the same animator.
-         *
-         * Default `0` (instant-apply, matches the long-standing pre-Phase-5
-         * behaviour). Opt in via `inputResponseMs: 60` for an eased pan/zoom
-         * feel — the default is conservative because the animated visual
-         * range diverges from the committed target until the ease completes,
-         * and existing consumers reading `chart.getVisibleRange()`
-         * synchronously after a wheel/pan expect the new value.
+         * Candlestick tweens. `false` disables candle entrance + OHLC chase.
+         */
+        candlestick?: false | {
+            /**
+             * Per-candle entrance duration. `false` disables the entrance
+             * (equivalent to `entryAnimation: 'none'`).
+             *
+             * @default {@link DEFAULT_CANDLESTICK_ENTRY}
+             */
+            entry?: AnimationTime;
+            /**
+             * Live OHLC chase duration on `updateLastPoint`. `false` / `0`
+             * snaps to the target instantly.
+             *
+             * @default {@link DEFAULT_CANDLESTICK_SMOOTH}
+             */
+            smooth?: AnimationTime;
+        };
+        /**
+         * Bar-series tweens. `false` disables bar entrance + value chase.
          */
-        inputResponseMs?: AnimationTime;
+        bar?: false | {
+            /**
+             * Per-bar entrance duration. `false` disables the entrance
+             * (equivalent to `entryAnimation: 'none'`).
+             *
+             * @default {@link DEFAULT_BAR_ENTRY}
+             */
+            entry?: AnimationTime;
+            /**
+             * Live value chase duration on `updateLastPoint`. `false` /
+             * `0` snaps to the target instantly.
+             *
+             * @default {@link DEFAULT_BAR_SMOOTH}
+             */
+            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?: false | {
+            /**
+             * Slice grow-in duration on first paint.
+             *
+             * @default {@link DEFAULT_PIE_ENTRY}
+             */
+            entry?: AnimationTime;
+            /**
+             * Slice resize duration when data changes.
+             *
+             * @default {@link DEFAULT_PIE_UPDATE}
+             */
+            update?: AnimationTime;
+        };
     };
 }
 
-/** Options passed when creating a new {@link ChartInstance}. */
 /**
- * Time-value or boolean used throughout the animation API. `false` disables
- * the category; a number configures its duration/time-constant in milliseconds
- * (`0` also disables, useful when the caller wants a number shape).
+ * Per-frame engine snapshot — same shape returned by the legacy
+ * `AnimationEngine.tick()` so existing consumers (chart render loop,
+ * `chart.getAnimationState()` public API, series overlay hooks) keep working.
  */
-declare type AnimationTime = number | false;
+declare interface AnimationState {
+    readonly xRange: XRange;
+    readonly yRange: YRange;
+    readonly animating: boolean;
+}
+
+/**
+ * Public animation-time input. Accepts:
+ *  - `number` — already milliseconds (`250`)
+ *  - `string` in `<n>ms` or `<n>s` form (`"250ms"`, `"1s"`, `"2.5s"`)
+ *  - `false` — disable (equivalent to `0`)
+ */
+declare type AnimationTime = Milliseconds | string | false;
 
 /**
  * Build a 2-stop candle-body gradient around a single hex color — a lightened
@@ -621,6 +758,51 @@ export declare interface AxisConfig {
     x?: XAxisConfig;
 }
 
+declare class AxisTickTracker {
+    #private;
+    constructor(opts?: AxisTickTrackerOptions);
+    /**
+     * Record the latest tick set. Diffs against the current set and either
+     * starts a `0 → 1` fade-in for new values or a `1 → 0` fade-out for
+     * dropped ones. Idempotent on element-wise equal arrays.
+     *
+     * Callers must invoke {@link tick} every frame to advance the animators —
+     * `snapshot()` reads the current state but does not advance time.
+     */
+    setCurrentTicks(next: readonly number[]): void;
+    /**
+     * Advance each tracked animator against `now`. Animators that settle
+     * at zero are dropped from the map; non-zero settled animators stay so
+     * a subsequent re-entering tick can pick them up without a flicker.
+     * Returns `true` while any animator is still in flight.
+     */
+    tick(now: number): boolean;
+    /**
+     * Build a renderer-ready snapshot from the tracker's own animator state.
+     * No external opacity map is consulted — `setCurrentTicks` + `tick(now)`
+     * are the only inputs.
+     */
+    snapshot(): TickTrackerSnapshot;
+    getCurrentTicks(): readonly number[];
+    getPreviousTicks(): readonly number[];
+    /**
+     * Reconfigure the cross-fade duration. Chart calls this after resolving
+     * `animations.axis.ticks` so the tracker honors the user's config
+     * without plumbing options through the scale constructors.
+     */
+    setFadeMs(ms: number): void;
+    /** Whether subsequent tick-set changes should fade-in or snap. */
+    markArmed(): void;
+    get isArmed(): boolean;
+    /** Drop all tracked ticks. Use after dataset swap so stale values don't linger. */
+    reset(): void;
+}
+
+declare interface AxisTickTrackerOptions {
+    /** Cross-fade duration in ms once {@link markArmed} has flipped. Defaults to {@link DEFAULT_TICKS_MS}. */
+    fadeMs?: number;
+}
+
 export declare const ayuMirage: ThemePreset;
 
 /**
@@ -653,8 +835,6 @@ export declare interface BarSeriesOptions {
      * @see entryMs — cross-linked duration for this animation.
      */
     entryAnimation?: BarEntryAnimation;
-    /** @deprecated Use {@link entryAnimation} instead. */
-    enterAnimation?: BarEntryAnimation;
     /**
      * Per-bar entrance duration in milliseconds. Default: `250`.
      *
@@ -662,24 +842,19 @@ export declare interface BarSeriesOptions {
      * // Override for one series:
      * <BarSeries options={{ entryMs: 600 }} data={data} />
      *
-     * // Or set the default for every series at once:
-     * <ChartContainer animations={{ points: { enterMs: 600 } }}>
+     * // Or set the default for every bar series at once:
+     * <ChartContainer animations={{ series: { bar: { entry: 600 } } }}>
      *   <BarSeries data={data} />
      * </ChartContainer>
      * ```
      *
-     * Note: chart-level uses `enterMs`, per-series uses `entryMs` — same
-     * animation, two names for historical reasons.
-     *
      * `false` or `0` disables the entrance (equivalent to
-     * `entryAnimation: 'none'`). A chart-level `animations.points: false` is a
-     * hard disable that wins over this field.
+     * `entryAnimation: 'none'`). A chart-level `animations.series.bar: false`
+     * is a hard disable that wins over this field.
      *
      * @see BarSeriesOptions.entryAnimation
      */
     entryMs?: number | false;
-    /** @deprecated Use {@link entryMs} instead. */
-    enterMs?: number | false;
     /**
      * How long the displayed bar value takes to catch up to the actual one
      * on every `updateLastPoint`. Default: `250` ms.
@@ -689,21 +864,18 @@ export declare interface BarSeriesOptions {
      * <BarSeries options={{ smoothMs: 100 }} data={data} />
      *
      * // Chart-level default:
-     * <ChartContainer animations={{ points: { smoothMs: 100 } }}>
+     * <ChartContainer animations={{ series: { bar: { smooth: 100 } } }}>
      *   <BarSeries data={data} />
      * </ChartContainer>
      * ```
      *
      * `0` or `false` snaps the displayed value to the target on every tick
-     * (no smoothing). A chart-level `animations.points: false` is a hard
+     * (no smoothing). A chart-level `animations.series.bar: false` is a hard
      * disable that wins over this field.
      */
     smoothMs?: number | false;
 }
 
-/** @deprecated Use {@link StackingMode} instead. */
-export declare type BarStacking = StackingMode;
-
 /**
  * Snapshot every visible series / layer at `time`. Used by hover overlays
  * (`InfoBar` in hover mode, `Tooltip`). Hidden series and hidden layers are
@@ -791,8 +963,6 @@ export declare interface CandlestickSeriesOptions {
      * @see entryMs — cross-linked duration for this animation.
      */
     entryAnimation?: CandlestickEntryAnimation;
-    /** @deprecated Use {@link entryAnimation} instead. */
-    enterAnimation?: CandlestickEntryAnimation;
     /**
      * Per-candle entrance duration in milliseconds. Default: `250`.
      *
@@ -800,24 +970,20 @@ export declare interface CandlestickSeriesOptions {
      * // Override for one series:
      * <CandlestickSeries options={{ entryMs: 600 }} data={data} />
      *
-     * // Or set the default for every series at once:
-     * <ChartContainer animations={{ points: { enterMs: 600 } }}>
+     * // Or set the default for every candlestick series at once:
+     * <ChartContainer animations={{ series: { candlestick: { entry: 600 } } }}>
      *   <CandlestickSeries data={data} />
      * </ChartContainer>
      * ```
      *
-     * Note: chart-level uses `enterMs`, per-series uses `entryMs` — same
-     * animation, two names for historical reasons.
-     *
      * `false` or `0` disables the entrance (equivalent to
-     * `entryAnimation: 'none'`). A chart-level `animations.points: false` is a
-     * hard disable that wins over this field.
+     * `entryAnimation: 'none'`). A chart-level
+     * `animations.series.candlestick: false` is a hard disable that wins over
+     * this field.
      *
      * @see CandlestickSeriesOptions.entryAnimation
      */
     entryMs?: number | false;
-    /** @deprecated Use {@link entryMs} instead. */
-    enterMs?: number | false;
     /**
      * How long the displayed OHLC takes to catch up to the actual last value
      * on every `updateLastPoint`. Default: `250` ms.
@@ -827,14 +993,14 @@ export declare interface CandlestickSeriesOptions {
      * <CandlestickSeries options={{ smoothMs: 100 }} data={data} />
      *
      * // Chart-level default:
-     * <ChartContainer animations={{ points: { smoothMs: 100 } }}>
+     * <ChartContainer animations={{ series: { candlestick: { smooth: 100 } } }}>
      *   <CandlestickSeries data={data} />
      * </ChartContainer>
      * ```
      *
      * `0` or `false` snaps the displayed value to the target on every tick
-     * (no smoothing). A chart-level `animations.points: false` is a hard
-     * disable that wins over this field.
+     * (no smoothing). A chart-level `animations.series.candlestick: false` is
+     * a hard disable that wins over this field.
      */
     smoothMs?: number | false;
 }
@@ -857,41 +1023,58 @@ declare interface ChartEvents {
      * subscribe to this instead of stacking multiple listeners.
      */
     overlayChange: () => void;
+    /**
+     * Fired once per main-layer frame *while* an axis tick is still in the
+     * middle of its fade-in/out animation. DOM axis components (`<TimeAxis>`,
+     * `<YAxis>`) listen to this to re-read the per-tick opacity from
+     * `timeScale.tickTracker` / `yScale.tickTracker` so the DOM labels and
+     * canvas grid lines fade in lockstep. Stops firing as soon as every
+     * tracked tick has reached its target opacity.
+     */
+    tickFrame: () => void;
 }
 
 /**
  * Core chart controller. Manages series, viewport, scales, and rendering.
  * Create one per chart container and call {@link destroy} on unmount.
  */
-export declare class ChartInstance extends EventEmitter<ChartEvents> {
+export declare class ChartInstance extends EventEmitter<ChartEvents> implements PanZoomTarget {
     #private;
     /** Maps time values to horizontal pixel coordinates. */
-    readonly timeScale: TimeScale;
+    readonly timeScale: XScale;
     /** Maps price/value to vertical pixel coordinates. */
     readonly yScale: YScale;
     get yAxisWidth(): number;
     get xAxisHeight(): number;
     constructor(container: HTMLElement, options?: ChartOptions);
-    /** Add a candlestick (OHLC) series and return its unique ID. */
-    addCandlestickSeries(options?: Partial<CandlestickSeriesOptions & {
+    /**
+     * Add a series of the given `type` and return its unique ID. `options` is
+     * typed per `type` via the overloads. `layers` (line/bar) and `id` are
+     * consumed here; everything else is forwarded to the renderer.
+     */
+    addSeries(type: 'candlestick', options?: Partial<CandlestickSeriesOptions & {
         id?: string;
     }>): string;
-    /** Add a line series and return its unique ID. */
-    addLineSeries(options?: Partial<LineSeriesOptions & {
+    addSeries(type: 'line', options?: Partial<LineSeriesOptions & {
         layers?: number;
         id?: string;
     }>): string;
-    /** Add a bar series and return its unique ID. */
-    addBarSeries(options?: Partial<BarSeriesOptions & {
+    addSeries(type: 'bar', options?: Partial<BarSeriesOptions & {
         layers?: number;
         id?: string;
     }>): string;
-    /** Add a pie/donut series. Set `innerRadiusRatio > 0` for donut. */
-    addPieSeries(options?: Partial<PieSeriesOptions & {
+    addSeries(type: 'pie', options?: Partial<PieSeriesOptions & {
         id?: string;
     }>): string;
     /** Remove a series by ID and clean up its resources. */
     removeSeries(id: string): void;
+    /**
+     * Read-only snapshot of the chart's X / Y viewport animation. The same
+     * shape (`xRange`, `yRange`, `animating`) every frame — call this inside
+     * the current render pass rather than caching the reference, as the
+     * underlying animator mutates between frames.
+     */
+    getAnimationState(): AnimationState;
     /**
      * Replace all data for a series.
      *
@@ -906,6 +1089,20 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
     appendData(id: string, point: OHLCInput | TimePointInput, layerIndex?: number): void;
     /** Update the last data point of a series in place (e.g. live candle update). */
     updateData(id: string, point: OHLCInput | TimePointInput, layerIndex?: number): void;
+    /**
+     * Keep only the most recent `count` points of a series — drop the oldest
+     * tail when the series exceeds the cap. Smooth Y-range chase (no snap):
+     * unlike {@link setSeriesData}, this does NOT set the bulk-replace snap
+     * flag, so streaming windows can roll without per-tick Y jitter.
+     *
+     * Idempotent: a no-op when the series is already at or below `count`.
+     * Use after {@link appendData} in a rolling-window stream:
+     * ```ts
+     * chart.appendData('feed', point);
+     * chart.keepLast('feed', 100);
+     * ```
+     */
+    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;
     /**
@@ -913,37 +1110,71 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
      * inside `fn` still flush the batch so counters don't leak across calls.
      */
     batch(fn: () => void): void;
-    /** Show or hide a series. Hidden series are not rendered and excluded from Y-range. */
+    /** Show or hide a series. The series cross-fades over
+     *  `animations.toggle`; the Y range re-fits on the same schedule
+     *  (one-shot duration override) so the fade and the axis adjustment
+     *  finish on the same frame. Hidden series are excluded from Y-range
+     *  computation immediately so the axis can start moving while the line
+     *  fades out in parallel.
+     */
     setSeriesVisible(seriesId: string, visible: boolean): void;
+    /**
+     * Whether streaming ticks slide the visible range to track the data tail.
+     * Flipped off by a pan that pushes the tail off screen; re-engaged when
+     * a follow-up pan brings the tail back into the destination window or
+     * when {@link fitContent} / {@link setVisibleRange} commits a range
+     * containing the tail.
+     */
+    getAutoScroll(): boolean;
     isSeriesVisible(seriesId: string): boolean;
-    /** Show or hide a specific layer within a multi-layer series. */
+    /**
+     * Show or hide a specific layer within a multi-layer series.
+     *
+     * Symmetric with {@link setSeriesVisible}: drives both the renderer's
+     * per-layer alpha fade and the engine's Y re-fit through `toggleMs` so the
+     * line fade and the axis adjustment finish on the same frame. Hidden layers
+     * are excluded from Y-range computation immediately (via the renderer's
+     * `getValueRange` reading `store.isVisible()`); the alpha fade keeps the
+     * layer's geometry on screen until the engine's Y ease settles.
+     */
     setLayerVisible(seriesId: string, layerIndex: number, visible: boolean): void;
     isLayerVisible(seriesId: string, layerIndex: number): boolean;
     /** Auto-fit the viewport to show all data across every series. */
     fitContent(): void;
-    getVisibleRange(): VisibleRange;
+    getVisibleRange(): XRange;
     /**
      * Return the full span of registered data, or `null` before any data has
-     * arrived. `{ from: dataStart, to: dataEnd }` mirrors the viewport's own
+     * arrived. `{ from: dataStart, to: dataEnd }` mirrors the chart's own
      * tracking and is cheaper than recomputing from series stores.
      */
-    getDataRange(): VisibleRange | null;
+    getDataRange(): XRange | null;
     /**
-     * Imperatively set the visible time range.
+     * Imperatively set the visible time range. Three forms:
      *
-     * Two forms:
-     * - `{ from, to }` — explicit millisecond range. Cancels any in-flight
-     *   animation and applies immediately. Auto-scroll stays on only if the
-     *   tail is inside the new range (mirrors pan semantics).
-     * - `number N` — shorthand for "show the last N bars from the tail".
-     *   Resolved against the current data bounds and data interval; keeps
-     *   auto-scroll on so streaming ticks continue to track the tail.
-     *   No-op if data hasn't loaded yet.
+     * - `number N` — show the last N bars from the data tail (anchor right).
+     *   Resolved against current data bounds and data interval; keeps
+     *   auto-scroll on. No-op if data hasn't loaded yet.
+     * - `{ from, to }` — explicit time range. `from`/`to` accept either
+     *   epoch milliseconds or `Date`. Cancels any in-flight animation and
+     *   applies immediately. Auto-scroll stays on only if the tail is
+     *   inside the new range (mirrors pan semantics).
+     * - `{ from, bars }` — anchor the visible window at `from` and extend
+     *   right by `bars` data intervals. Useful for warm-up windows where
+     *   seed points sit on the left and a stream fills the gap on the
+     *   right. `from` accepts a `Date` too.
      *
      * Typical use: on mount, zoom to the last N bars while keeping the full
      * buffer available for pan-back history inspection.
-     */
-    setVisibleRange(range: VisibleRange | number): void;
+     *
+     * `opts.gesture` (explicit `{ from, to }` form only) eases X and Y on the
+     * same fast, velocity-matched profile a user pan/zoom uses instead of the
+     * default programmatic settle (snap X, sticky-Y ease). Use it for
+     * multi-chart sync so a synced pane tracks the originating gesture in
+     * lockstep rather than lagging behind on the long sticky contract.
+     */
+    setVisibleRange(spec: VisibleRangeSpec, opts?: {
+        gesture?: boolean;
+    }): void;
     getYRange(): YRange;
     getCrosshairPosition(): CrosshairPosition | null;
     /**
@@ -999,11 +1230,6 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
         color: string;
     }[] | null;
     getSeriesIds(): string[];
-    /**
-     * Type of a registered series, or `null` for unknown ids. `'pie'` for
-     * `PieRenderer`; everything else is a time-series (`'time'`).
-     */
-    getSeriesType(seriesId: string): 'pie' | 'time' | null;
     /**
      * Filter `getSeriesIds()` by renderer type. `'pie'` returns pie series,
      * `'time'` returns line/bar/candlestick.
@@ -1082,25 +1308,6 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
      * a wrapper re-applies padding reactively (e.g. in response to a Title /
      * InfoBar ResizeObserver).
      */
-    /**
-     * Replace the chart-level animation configuration at runtime. Updates the
-     * resolved durations and propagates them to every dependent subsystem:
-     *
-     * - viewport: reboundMs (next rebound), inputResponseMs (next pan/zoom).
-     * - per-frame: yAxisMs (next render).
-     * - existing series: only the **hard-disable** signal (0 / false) is pushed
-     *   into renderers — that's the documented contract on
-     *   {@link AnimationsConfig.points}, "chart-level `false` wins over per-
-     *   series". Numeric chart-level changes update the default for *new*
-     *   series but leave existing per-series overrides intact, which avoids
-     *   silently clobbering custom values on every prop update from a React
-     *   wrapper.
-     *
-     * In-flight animations are NOT cancelled — the new durations apply to the
-     * next animation that fires. To force-snap the current animation, call
-     * the relevant API explicitly (e.g. `setRange`) afterwards.
-     */
-    setAnimations(animations: ChartOptions['animations']): void;
     setPadding(padding: ChartOptions['padding']): void;
     /** Show or hide the background grid. Takes effect on the next render frame. */
     setGrid(grid: {
@@ -1118,9 +1325,13 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
     setEdgeState(side: EdgeSide, state: EdgeState): void;
     /** Read the current host-declared state for a given edge. */
     getEdgeState(side: EdgeSide): EdgeState;
-    /** Notify chart that a YLabel is present (affects right padding). */
-    setYLabel(has: boolean): void;
-    private updateViewportPadding;
+    /**
+     * 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.
+     */
+    setYLabel(_has: boolean): void;
     /** Tear down the chart: cancel animations, remove listeners, and detach the canvas. */
     destroy(): void;
     /** The attached performance monitor, or `null` when instrumentation is disabled. */
@@ -1130,39 +1341,42 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
     private onDataChanged;
     private updateDataInterval;
     /**
-     * Sample data inside `targetVisible` and return the unbounded [min, max] of
-     * the visible series, or `null` when nothing is in view. Bounds are NOT
-     * applied here — the caller composes them via {@link resolveBound}.
+     * Shift the visible time range by `timeDelta` ms. Hard-clamped so at
+     * least one data point stays on screen — no rubber-band, no overshoot.
+     * A pan that moves the viewport off the live-tail position flips
+     * autoscroll off. Fires `edgeReached` whenever the clamp trims the
+     * gesture (i.e., the user pushed past the boundary), so consumers can
+     * trigger history loads. Forwards the committed target to the engine
+     * as a gesture for visual easing. Public so consumers can drive pan
+     * programmatically.
+     */
+    pan(timeDelta: number, chartWidth?: number): void;
+    /**
+     * Zoom around a time anchor. `factor < 1` zooms in, `> 1` zooms out.
+     * In historical mode the window anchors to `centerTime` (cursor-driven).
+     * Zoom-out is hard-capped at the padded data span. Forwards the committed
+     * target to the engine as a gesture for visual easing. Public so consumers
+     * can drive zoom programmatically.
      *
-     * `targetVisible` is the X *destination* (logicalRange), not the animating
-     * current. Sampling against a moving X would make Y chase a definition of
-     * "in view" that shifts every frame; passing the destination explicitly
-     * keeps Y on a stable target so X and Y converge together.
+     * Sticky-follow: while `#autoScroll` is on, the new window is repositioned
+     * so its right edge sits at `dataEnd + paddingRight` (follow position).
+     * Span (zoom level) from `computeZoom` is preserved; only the position
+     * is locked to the tail. This avoids the next-tick `computeStreamingTarget`
+     * offset clamp (which would otherwise slide X left to the follow position
+     * and produce a visible jump). Cursor-anchored zoom is intentionally
+     * sacrificed in follow-live mode — pan first to inspect history.
      */
-    private computeTargetYRange;
-    private updateYRange;
-    /** Resolve an {@link AxisBound} to a concrete numeric value. */
-    private resolveBound;
+    zoomAt(centerTime: number, factor: number, chartWidth?: number): void;
     /**
      * Lightweight scale sync: updates timeScale/yScale from current viewport state
      * without advancing the Y smoothing animation. Called from the viewport 'change'
-     * handler so DOM axis components always read fresh coordinates on re-render.
+     * handler, so DOM axis components always read fresh coordinates on re-render.
      */
     private syncScales;
-    private updateScales;
     /** Expensive: background, grid, all series. Only on data/viewport/resize change. */
     private renderMain;
     /** Cheap overlay: crosshair, nearest-point dots, pulse animation, edge indicator. */
     private renderOverlay;
-    private drawEdgeIndicators;
-    /**
-     * Pick the boundary time to anchor the edge indicator at. Prefer the
-     * cached value emitted by the most recent `edgeReached` — that's the
-     * *exact* point the user overshot. Fall back to the current data edge
-     * when no gesture has fired yet (host might invoke `setEdgeState`
-     * directly on mount to show a "no-data" marker from the start).
-     */
-    private resolveEdgeBoundary;
 }
 
 /** Layout metrics describing the chart area, Y axis, and time axis sizes. */
@@ -1172,6 +1386,7 @@ export declare interface ChartLayout {
     xAxisHeight: number;
 }
 
+/** Options passed when creating a new ChartInstance. */
 export declare interface ChartOptions {
     theme?: ChartTheme;
     axis?: AxisConfig;
@@ -1182,12 +1397,35 @@ export declare interface ChartOptions {
     padding?: {
         top?: number;
         bottom?: number;
-        right?: number | {
-            intervals: number;
-        };
-        left?: number | {
-            intervals: number;
-        };
+        right?: HorizontalPadding;
+        left?: HorizontalPadding;
+    };
+    /**
+     * Viewport-level streaming behavior.
+     */
+    viewport?: {
+        /**
+         * Maximum number of data bars (candles/points) the viewport will fit
+         * before it stops growing and switches to tail-scroll. While the data
+         * span is below this threshold, streaming ticks expand the right edge
+         * to absorb new points; once the span exceeds it, the visible window
+         * holds at this width and slides forward as new data arrives.
+         * Default: 200. Values below 2 are clamped.
+         */
+        maxVisibleBars?: number;
+        /**
+         * Initial visible range applied **before** the first paint after data
+         * arrives. Same shape as `ChartInstance.setVisibleRange` (a bar count,
+         * an explicit `{from, to}` window, or a `{from, bars}` warm-up pair).
+         * Calling `setVisibleRange` after mount via `useEffect` runs post-paint
+         * and visually re-zooms the chart on the next frame; this option folds
+         * the same intent into the first render so the very first paint
+         * already shows the requested window.
+         *
+         * One-shot — consumed by the first `onDataChanged` call that has data,
+         * then cleared. Subsequent `setSeriesData` calls don't re-apply it.
+         */
+        initialRange?: VisibleRangeSpec;
     };
     /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
     interactive?: boolean;
@@ -1196,17 +1434,16 @@ export declare interface ChartOptions {
         visible: boolean;
     };
     /**
-     * Animation control. Split into `points` (data-series animations) and
-     * `viewport` (pan/zoom rebound + Y-axis smoothing). See
-     * {@link AnimationsConfig} for the full shape and defaults.
+     * Animation control. Grouped as `axis: { y, x, ticks }` (axis-side
+     * behaviour), `toggle` (series visibility — alpha + Y refit), and
+     * `series.{line,candlestick,bar,pie}` (per-series-type data tweens).
+     * See {@link AnimationsConfig} for the full shape and defaults.
      *
      * Shorthands:
      * - `animations: true` (or omitted) uses built-in defaults.
      * - `animations: false` disables every animation category.
-     * - `animations: { points: false }` disables all data-series animations.
-     * - `animations: { viewport: false }` disables rebound + Y-axis smoothing.
      *
-     * Per-series options (`enterMs`, `smoothMs`, etc.) override chart-level
+     * Per-series options (`entryMs`, `smoothMs`, etc.) override chart-level
      * defaults unless the category is explicitly `false` — then the chart-
      * level gate wins.
      */
@@ -1215,7 +1452,7 @@ export declare interface ChartOptions {
      * Invoked after the user releases a pan/zoom gesture that pulled the
      * viewport past a data edge by more than 10% of the visible range. Hosts
      * typically respond by prefetching more history and calling
-     * {@link ChartInstance.setEdgeState} to show a spinner or "no more data"
+     * `ChartInstance.setEdgeState` to show a spinner or "no more data"
      * indicator at the corresponding edge.
      */
     onEdgeReached?: (info: EdgeReachedInfo) => void;
@@ -1447,15 +1684,6 @@ export declare interface CrosshairPosition {
     y: number;
 }
 
-/**
- * @deprecated Use a named preset instead — `catppuccin.theme` is the new
- * default dark palette, and `dracula`, `nightOwl`, `oneDarkPro`, `gruvbox`,
- * `monokaiPro`, `materialPalenight`, or `panda` cover the rest of the
- * dark spectrum. `darkTheme` is kept as an alias for the previous default
- * and will be removed in a future major release.
- */
-export declare const darkTheme: ChartTheme;
-
 export declare function detectInterval(times: number[]): number;
 
 export declare const dracula: ThemePreset;
@@ -1528,6 +1756,11 @@ export declare const handwritten: ThemePreset;
 
 export declare const highContrast: ThemePreset;
 
+/** Horizontal padding expressed as a fixed pixel offset or a number of data intervals. */
+declare type HorizontalPadding = number | {
+    intervals: number;
+};
+
 /** Shape returned by {@link SeriesRenderer.getHoverInfo} / per-slice entries of {@link SeriesRenderer.getSliceInfo}. */
 export declare interface HoverInfo {
     label: string;
@@ -1589,18 +1822,6 @@ declare type LegendMode = 'toggle' | 'isolate' | 'solo';
 
 export declare const lightPink: ThemePreset;
 
-/**
- * @deprecated Use a named light preset instead — `quietLight`, `githubLight`,
- * `solarizedLight`, `minimalLight`, `peachCream`, `sandDune`, `lightPink`,
- * `lavenderMist`, `mintBreeze`, `rosePineDawn`, or `handwritten`. `lightTheme`
- * is kept as an alias for the previous default and will be removed in a
- * future major release.
- */
-export declare const lightTheme: ChartTheme;
-
-/** @deprecated Use {@link TimePoint} instead. */
-export declare type LineData = TimePoint;
-
 /**
  * Entrance animation styles for new line points.
  * - `'none'` — new segments appear instantly.
@@ -1638,14 +1859,14 @@ export declare interface LineSeriesOptions {
      * <LineSeries options={{ pulseMs: 1200 }} data={data} />
      *
      * // Chart-level default:
-     * <ChartContainer animations={{ points: { pulseMs: 1200 } }}>
+     * <ChartContainer animations={{ series: { line: { pulse: 1200 } } }}>
      *   <LineSeries data={data} />
      * </ChartContainer>
      * ```
      *
      * `false` or `0` turns the halo off entirely (drawing and animation loop).
-     * A chart-level `animations.points: false` is a hard disable that wins
-     * over this field.
+     * A chart-level `animations.series.line: false` is a hard disable that
+     * wins over this field.
      */
     pulseMs?: number | false;
     /** Stacking mode. Default: 'off'. */
@@ -1658,8 +1879,6 @@ export declare interface LineSeriesOptions {
      * @see entryMs — cross-linked duration for this animation.
      */
     entryAnimation?: LineEntryAnimation;
-    /** @deprecated Use {@link entryAnimation} instead. */
-    enterAnimation?: LineEntryAnimation;
     /**
      * Per-point entrance duration in milliseconds. Default: `250`.
      *
@@ -1667,24 +1886,19 @@ export declare interface LineSeriesOptions {
      * // Override for one series:
      * <LineSeries options={{ entryMs: 600 }} data={data} />
      *
-     * // Or set the default for every series at once:
-     * <ChartContainer animations={{ points: { enterMs: 600 } }}>
+     * // Or set the default for every line series at once:
+     * <ChartContainer animations={{ series: { line: { entry: 600 } } }}>
      *   <LineSeries data={data} />
      * </ChartContainer>
      * ```
      *
-     * Note: chart-level uses `enterMs`, per-series uses `entryMs` — same
-     * animation, two names for historical reasons.
-     *
      * `false` or `0` disables the entrance (equivalent to
-     * `entryAnimation: 'none'`). A chart-level `animations.points: false` is a
-     * hard disable that wins over this field.
+     * `entryAnimation: 'none'`). A chart-level `animations.series.line: false`
+     * is a hard disable that wins over this field.
      *
      * @see LineSeriesOptions.entryAnimation
      */
     entryMs?: number | false;
-    /** @deprecated Use {@link entryMs} instead. */
-    enterMs?: number | false;
     /**
      * How long the displayed last value takes to catch up to the actual one
      * on every `updateLastPoint`. Default: `250` ms.
@@ -1694,13 +1908,13 @@ export declare interface LineSeriesOptions {
      * <LineSeries options={{ smoothMs: 100 }} data={data} />
      *
      * // Chart-level default:
-     * <ChartContainer animations={{ points: { smoothMs: 100 } }}>
+     * <ChartContainer animations={{ series: { line: { smooth: 100 } } }}>
      *   <LineSeries data={data} />
      * </ChartContainer>
      * ```
      *
      * `0` or `false` snaps the displayed value to the target on every tick
-     * (no smoothing). A chart-level `animations.points: false` is a hard
+     * (no smoothing). A chart-level `animations.series.line: false` is a hard
      * disable that wins over this field.
      */
     smoothMs?: number | false;
@@ -1710,6 +1924,15 @@ declare type Listener = (...args: any[]) => void;
 
 export declare const materialPalenight: ThemePreset;
 
+/**
+ * Time helpers for the animation config surface. The public config accepts
+ * three shapes: a number (already milliseconds), a string with an explicit
+ * unit (`"250ms"`, `"1s"`, `"2.5s"`), or `false` to disable. The resolver
+ * parses each input once at chart construction; the hot render path then
+ * only ever sees numbers.
+ */
+declare type Milliseconds = number;
+
 export declare const minimalLight: ThemePreset;
 
 export declare const mintBreeze: ThemePreset;
@@ -1827,6 +2050,25 @@ export declare const oneDarkPro: ThemePreset;
 
 export declare const panda: ThemePreset;
 
+/**
+ * Narrow interface the interaction handlers expect from their host. Lets
+ * `InteractionHandler` / `PanHandler` / `ZoomHandler` drive pan / zoom
+ * without depending on the full ChartInstance surface.
+ */
+declare interface PanZoomTarget {
+    /**
+     * Shift the visible time range by `timeDelta` ms. `chartWidth` is used
+     * by pixel-padding resolution; passing the current canvas width yields
+     * correct rubber-band clamps.
+     */
+    pan(timeDelta: number, chartWidth?: number): void;
+    /**
+     * Zoom around a time anchor. `factor < 1` zooms in, `> 1` zooms out.
+     * `chartWidth` participates in soft-bound math the same way as in `pan`.
+     */
+    zoomAt(centerTime: number, factor: number, chartWidth?: number): void;
+}
+
 export declare const peachCream: ThemePreset;
 
 /**
@@ -1909,8 +2151,6 @@ declare interface PerfStats {
     mainRendersPerSec: number;
     /** Same as {@link mainRendersPerSec} but for the overlay (crosshair + pulse) layer. */
     overlayRendersPerSec: number;
-    /** @deprecated Alias for {@link mainRendersPerSec}. Kept for older consumers. */
-    fps: number;
     mainFrameMs: FrameTimingSample;
     overlayFrameMs: FrameTimingSample;
     /** Total frames recorded per layer. Lets consumers distinguish "no data yet" from "drew once and ms is 0". */
@@ -1972,13 +2212,6 @@ declare interface PieLabelsOptions {
      * expressed as a multiplier of {@link fontSize}. Default: 1.8.
      */
     labelGap?: number;
-    /**
-     * @deprecated No effect in the radial per-slice layout. A label's X is
-     * pinned to its slice midangle, so forcing the "other" side would flip
-     * text direction without moving the label and push text across the pie.
-     * Kept in the option surface for backwards compatibility.
-     */
-    balanceSides?: boolean;
 }
 
 export declare const PieLegend: __VLS_WithTemplateSlots_4<typeof __VLS_component_4, __VLS_TemplateResult_4["slots"]>;
@@ -2096,6 +2329,30 @@ export declare function resolveAxisTextColor(theme: ChartTheme, axis?: 'x' | 'y'
  */
 export declare function resolveCandlestickBodyColor(body: string | [string, string]): string;
 
+/**
+ * Per-call settle times supplied by the engine to {@link Transition.retarget}.
+ * The engine owns all durations and pushes them per call; the curves carry
+ * no baseline of their own.
+ *
+ * X transitions use only `expandMs` (single direction). Y transitions use
+ * both `expandMs` (outward — new extreme enters window) and `contractMs`
+ * (inward — extreme leaves; the sticky-Y mechanism).
+ */
+declare interface RetargetOptions {
+    /** Optional wall clock. Defaults to `performance.now()`. */
+    now?: number;
+    /**
+     * Settle time (ms) for *outward* motion — bound reaching a new extreme.
+     * Also used by X (single-direction) as the spring's settle time.
+     */
+    expandMs?: number;
+    /**
+     * Settle time (ms) for *inward* motion — bound contracting after an
+     * extreme leaves the window. Y-only; X transitions ignore this field.
+     */
+    contractMs?: number;
+}
+
 export declare const rosePineDawn: ThemePreset;
 
 export declare const sandDune: ThemePreset;
@@ -2195,7 +2452,39 @@ export declare interface ThemePreset {
     backgroundSize?: string;
 }
 
-export declare const TimeAxis: DefineComponent<__VLS_Props_12, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_12> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+/**
+ * Per-axis tick-set holder with self-managed fade.
+ *
+ * Each tick value gets its own {@link Animator}: entering ticks ramp `0 → 1`,
+ * exiting ticks ramp `1 → 0` and are removed once they settle at zero.
+ * Callers drive the clock with {@link tick} once per frame, then read the
+ * current opacity table via {@link snapshot}.
+ *
+ * Pre-arming (initial mount, dataset swap) the tracker uses duration `0` so
+ * the very first nice-tick sets snap into place without an opening fade —
+ * transient tick churn during layout settling should not look animated.
+ */
+declare interface TickEntry {
+    /** Tick value (time or price). */
+    readonly value: number;
+    /** Current opacity in [0, 1]. */
+    readonly opacity: number;
+}
+
+declare interface TickTrackerSnapshot {
+    /**
+     * Every tick the tracker still considers alive — current ones at their
+     * resolved opacity (1.0 once any pending fade-in settles) and fading-out
+     * ones above 0.
+     */
+    readonly entries: readonly TickEntry[];
+    /** True while at least one entry hasn't reached its target opacity. */
+    readonly isAnimating: boolean;
+}
+
+export declare const TimeAxis: DefineComponent<__VLS_Props_12, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_12> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+containerRef: HTMLDivElement;
+}, HTMLDivElement>;
 
 /** A single time-value data point for line and bar series. Time is a timestamp in milliseconds. */
 export declare interface TimePoint {
@@ -2208,57 +2497,6 @@ export declare type TimePointInput = Omit<TimePoint, 'time'> & {
     time: TimeValue;
 };
 
-declare class TimeScale {
-    private from;
-    private to;
-    private width;
-    private pixelRatio;
-    private dataInterval;
-    private labelCountHintValue;
-    private minSpacingValue;
-    private resolvedInterval;
-    private lastInterval;
-    /**
-     * "want" (desired interval post-floor) at the time lastInterval was snapped.
-     * Hysteresis band anchors to this so micro range drift back across a tier
-     * boundary doesn't flip the label density — mirrors YScale, see there for
-     * the full reasoning.
-     */
-    private lastWant;
-    /** Identifies the dataInterval bucket whose tier list drove lastInterval. */
-    private lastBucketKey;
-    private get labelCountHint();
-    private get minLabelSpacing();
-    update(range: VisibleRange, mediaWidth: number, pixelRatio: number, dataInterval?: number): void;
-    setLabelCount(n: number | null | undefined): void;
-    setMinSpacing(px: number | null | undefined): void;
-    private resetHysteresis;
-    timeToX(time: number): number;
-    timeToBitmapX(time: number): number;
-    xToTime(x: number): number;
-    pixelDeltaToTimeDelta(pixelDelta: number): number;
-    barWidthMedia(dataInterval: number): number;
-    barWidthBitmap(dataInterval: number): number;
-    /**
-     * Evenly spaced "nice" tick times. Resolution uses the cached
-     * `dataInterval` set by `update()`; callers that bypass `update()` can
-     * still pass it here for back-compat.
-     */
-    niceTickValues(dataInterval: number): {
-        ticks: number[];
-        tickInterval: number;
-    };
-    getRange(): VisibleRange;
-    getMediaWidth(): number;
-    /**
-     * Resolve the next tick interval. Walks `niceTimeIntervals(dataInterval)`
-     * looking for the smallest tier ≥ desired spacing; retains the previous
-     * tier inside a ratio band so micro pan/zoom doesn't flip label density.
-     */
-    private resolveInterval;
-    private countTicks;
-}
-
 /**
  * Accepted time input: a timestamp in **milliseconds** (like `Date.now()`) or a `Date` object.
  * `Date` values are converted to milliseconds internally via `Date.getTime()`.
@@ -2309,6 +2547,57 @@ export declare interface TooltipPositionArgs {
     offsetY?: number;
 }
 
+/**
+ * Smoothing-curve contract. Implementations (`YRangeHermite`, `YRangeSpring`,
+ * `RangeSnap` for Y; `VisibleRangeSpring`, `RangeSnap` for X) drive a value
+ * of type `T` from one snapshot to the next while maintaining `current` /
+ * `target` / velocity continuity.
+ *
+ * Parametric over `T` so X and Y share the same interface — Y uses
+ * `Transition<YRange>` (default), X uses `Transition<VisibleRange>`.
+ *
+ * This is the single public customization point for the chart's curves.
+ * Other animation math (entry tweens, pulse, axis tick fade) stays
+ * engine-fixed.
+ */
+declare interface Transition<T> {
+    /** Current sampled position. Read by renderers on every frame. */
+    readonly current: T;
+    /** Active retarget destination. May equal `current` after settle. */
+    readonly target: T;
+    /** True while position has not yet converged to `target`. */
+    readonly animating: boolean;
+    /**
+     * Begin a new transition toward `value`. Existing velocity is carried
+     * over (no reset twitch). The engine supplies the active settle times
+     * via `opts.expandMs` (and `opts.contractMs` for Y).
+     */
+    retarget(value: T, opts?: RetargetOptions): void;
+    /** Land at `value` instantly. Velocity resets to zero. */
+    snap(value: T, opts?: {
+        now?: number;
+    }): void;
+    /** Advance to `now`. Returns `true` while still perceptibly moving. */
+    tick(now: number): boolean;
+}
+
+/**
+ * Context handed to a {@link TransitionFactory} at chart construction.
+ * 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> {
+    initial: T;
+}
+
+/**
+ * Factory function returning a fresh {@link Transition}. Pass one as
+ * `animations.axis.y.curve` (or `animations.axis.x.curve`) to plug a custom
+ * 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>;
+
 /** Font family and base font size used across the chart. */
 export declare interface Typography {
     /** CSS `font-family` stack applied to all text rendered by the chart. */
@@ -2356,11 +2645,26 @@ export declare function useYRange(chart: ChartInstance): Ref<YRange>;
 /** Signature for a value-to-string formatter (YAxis, YLabel, Pie, Sparkline, NumberFlow). */
 export declare type ValueFormatter = (value: number) => string;
 
-/** Time range (timestamps in milliseconds) of the currently visible portion of the chart. */
-export declare interface VisibleRange {
-    from: number;
-    to: number;
-}
+/** @deprecated Use {@link XRange} instead. Visible time range of the chart. */
+export declare type VisibleRange = XRange;
+
+/**
+ * Argument accepted by {@link Chart.setVisibleRange}. Three forms:
+ *
+ * - `number N` — show the last N bars from the data tail (anchor right).
+ * - `{ from, to }` — explicit time range; `from`/`to` accept either epoch
+ *   milliseconds or `Date`, normalised to ms internally.
+ * - `{ from, bars }` — anchor the visible window at `from` and extend
+ *   right by `bars` data intervals. Useful for "show N bars starting
+ *   here" patterns (warm-up windows for streaming charts, etc.).
+ */
+declare type VisibleRangeSpec = number | {
+    from: TimeValue;
+    to: TimeValue;
+} | {
+    from: TimeValue;
+    bars: number;
+};
 
 /** Configuration for the X (time) axis. */
 export declare interface XAxisConfig {
@@ -2370,7 +2674,72 @@ export declare interface XAxisConfig {
     visible?: boolean;
 }
 
-export declare const YAxis: DefineComponent<__VLS_Props_15, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_15> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+/** Time range (timestamps in milliseconds) of the currently visible portion of the chart. */
+declare interface XRange {
+    from: number;
+    to: number;
+}
+
+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
+     * identical on both surfaces.
+     */
+    readonly tickTracker: AxisTickTracker;
+    private from;
+    private to;
+    private width;
+    private pixelRatio;
+    private dataInterval;
+    private labelCountHintValue;
+    private minSpacingValue;
+    private resolvedInterval;
+    private lastInterval;
+    /**
+     * "want" (desired interval post-floor) at the time lastInterval was snapped.
+     * Hysteresis band anchors to this so micro range drift back across a tier
+     * boundary doesn't flip the label density — mirrors YScale, see there for
+     * the full reasoning.
+     */
+    private lastWant;
+    /** Identifies the dataInterval bucket whose tier list drove lastInterval. */
+    private lastBucketKey;
+    private get labelCountHint();
+    private get minLabelSpacing();
+    update(range: XRange, mediaWidth: number, pixelRatio: number, dataInterval?: number): void;
+    setLabelCount(n: number | null | undefined): void;
+    setMinSpacing(px: number | null | undefined): void;
+    private resetHysteresis;
+    timeToX(time: number): number;
+    timeToBitmapX(time: number): number;
+    xToTime(x: number): number;
+    pixelDeltaToTimeDelta(pixelDelta: number): number;
+    barWidthMedia(dataInterval: number): number;
+    barWidthBitmap(dataInterval: number): number;
+    /**
+     * Evenly spaced "nice" tick times. Resolution uses the cached
+     * `dataInterval` set by `update()`; callers that bypass `update()` can
+     * still pass it here for back-compat.
+     */
+    niceTickValues(dataInterval: number): {
+        ticks: number[];
+        tickInterval: number;
+    };
+    getRange(): XRange;
+    getMediaWidth(): number;
+    /**
+     * Resolve the next tick interval. Walks `niceTimeIntervals(dataInterval)`
+     * looking for the smallest tier ≥ desired spacing; retains the previous
+     * tier inside a ratio band so micro pan/zoom doesn't flip label density.
+     */
+    private resolveInterval;
+    private countTicks;
+}
+
+export declare const YAxis: DefineComponent<__VLS_Props_15, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_15> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+containerRef: HTMLDivElement;
+}, HTMLDivElement>;
 
 /** Configuration for the Y axis. */
 export declare interface YAxisConfig {
@@ -2389,7 +2758,10 @@ export declare const YLabel: __VLS_WithTemplateSlots_8<typeof __VLS_component_8,
 /** Direction of the current value vs. previous close. Drives the badge color in the default UI. */
 declare type YLabelDirection = 'up' | 'down' | 'neutral';
 
-/** Min/max value range for the Y axis. */
+/** Value range covered by the chart's Y axis at a given frame. Animated as a
+ *  single struct so the upper and lower bounds always move in lockstep — no
+ *  half-tween states where the visible domain is wider on one side than the
+ *  other for a frame. */
 export declare interface YRange {
     min: number;
     max: number;
@@ -2400,6 +2772,8 @@ export declare interface YRange {
  * Also provides tick generation and value formatting for the Y axis.
  */
 declare class YScale {
+    /** Shared fade state for Y ticks; see {@link TimeScale.tickTracker}. */
+    readonly tickTracker: AxisTickTracker;
     private min;
     private max;
     private height;