@wick-charts/vue 0.4.2 → 0.5.0

package/dist/index.d.ts

@@ -26,32 +26,45 @@ position: "bottom" | "right";
 mode: LegendMode;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
-declare const __VLS_component_4: DefineComponent<__VLS_Props_10, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_10> & Readonly<{}>, {
+declare const __VLS_component_4: DefineComponent<__VLS_Props_11, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_11> & Readonly<{}>, {
 position: PieLegendPosition;
 format: ValueFormatter;
 mode: PieLegendMode;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
-declare const __VLS_component_5: DefineComponent<__VLS_Props_11, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_11> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+declare const __VLS_component_5: DefineComponent<__VLS_Props_12, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_12> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 containerRef: HTMLDivElement;
 }, any>;
 
-declare const __VLS_component_6: DefineComponent<__VLS_Props_13, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_13> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, 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_7: DefineComponent<__VLS_Props_14, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_14> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+declare const __VLS_component_7: DefineComponent<__VLS_Props_17, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_17> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 containerRef: HTMLDivElement;
 }, any>;
 
-declare const __VLS_component_8: DefineComponent<__VLS_Props_16, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_16> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+declare const __VLS_component_8: DefineComponent<__VLS_Props_19, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_19> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 declare type __VLS_Props = {
-    data: TimePoint[][];
+    /** Flat `TimePoint[]`, `TimePoint[][]`, or named `{ label, color?, data }` layers. Time accepts ms or `Date`. */
+    data: MultiLayerData;
     options?: Partial<BarSeriesOptions>;
     /** Stable series ID — same value across remounts. */
     id?: string;
 };
 
 declare type __VLS_Props_10 = {
+    value: number;
+    /**
+     * Value-to-string formatter. Defaults to the current locale's
+     * `Intl.NumberFormat` when omitted. `Intl.NumberFormatOptions` is also
+     * accepted (legacy) — routed through the built-in `Intl.NumberFormat`.
+     */
+    format?: ((value: number) => string) | Intl.NumberFormatOptions;
+    locale?: string;
+    spinDuration?: number;
+};
+
+declare type __VLS_Props_11 = {
     /**
      * Owning series id. **Optional** — when omitted, the first visible pie
      * series is picked.
@@ -65,7 +78,7 @@ declare type __VLS_Props_10 = {
     position?: PieLegendPosition;
 };
 
-declare type __VLS_Props_11 = {
+declare type __VLS_Props_12 = {
     /**
      * Owning series id. **Optional** — when omitted, the first visible pie
      * series is picked.
@@ -75,14 +88,42 @@ declare type __VLS_Props_11 = {
     format?: ValueFormatter;
 };
 
-declare type __VLS_Props_12 = {
+declare type __VLS_Props_13 = {
+    /** 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. */
+    color?: string;
+    /** Optional text label drawn in a pill at the line's near end. */
+    label?: string;
+    /** Dash style. Default: `'dashed'`. */
+    style?: ReferenceLineStyle;
+    /** Stroke width in CSS pixels. Default: `1`. */
+    width?: number;
+};
+
+declare type __VLS_Props_14 = {
     /** 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_13 = {
+declare type __VLS_Props_15 = {
+    /** 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. */
+    label?: string;
+    /** Edge-line and label-pill accent. Default: the theme's muted axis text color. */
+    color?: string;
+};
+
+declare type __VLS_Props_16 = {
     /**
      * @deprecated Use the named `sub` slot instead — it accepts arbitrary
      * inline markup (icons, badges, formatted text) to mirror React's
@@ -96,12 +137,12 @@ declare type __VLS_Props_13 = {
     sub?: string;
 };
 
-declare type __VLS_Props_14 = {
+declare type __VLS_Props_17 = {
     sort?: SnapshotSort;
     format?: TooltipFormatter;
 };
 
-declare type __VLS_Props_15 = {
+declare type __VLS_Props_18 = {
     /** Custom tick-label formatter. Overrides the built-in range-adaptive default. */
     format?: ValueFormatter;
     /**
@@ -113,7 +154,7 @@ declare type __VLS_Props_15 = {
     minLabelSpacing?: number;
 };
 
-declare type __VLS_Props_16 = {
+declare type __VLS_Props_19 = {
     /**
      * Owning series id. **Optional** — when omitted, the first visible
      * single-layer time series is picked, falling back to the first visible
@@ -126,7 +167,8 @@ declare type __VLS_Props_16 = {
 };
 
 declare type __VLS_Props_2 = {
-    data: OHLCInput[];
+    /** Flat `OHLCInput[]`, or `{ label, data }` to name the stream. */
+    data: CandlestickData;
     options?: Partial<CandlestickSeriesOptions>;
     /** Stable series ID — same value across remounts. */
     id?: string;
@@ -214,7 +256,8 @@ declare type __VLS_Props_3 = {
 };
 
 declare type __VLS_Props_4 = {
-    data: TimePoint[][];
+    /** 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;
@@ -240,21 +283,26 @@ declare type __VLS_Props_7 = {
 };
 
 declare type __VLS_Props_8 = {
-    data: NavigatorData;
-    /** Strip height in CSS pixels. Defaults to `theme.navigator.height` (60). */
-    height?: number;
+    /** 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 = {
-    value: number;
-    /**
-     * Value-to-string formatter. Defaults to the current locale's
-     * `Intl.NumberFormat` when omitted. `Intl.NumberFormatOptions` is also
-     * accepted (legacy) — routed through the built-in `Intl.NumberFormat`.
-     */
-    format?: ((value: number) => string) | Intl.NumberFormatOptions;
-    locale?: string;
-    spinDuration?: number;
+    data: NavigatorData;
+    /** Strip height in CSS pixels. Defaults to `theme.navigator.height` (60). */
+    height?: number;
 };
 
 declare function __VLS_template(): {
@@ -852,12 +900,12 @@ 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>;
 
+/** Series definition for `chart.addSeries` — keeps the chart renderer-agnostic
+ *  so hosts that never render bars don't bundle this module. */
+export declare const BarSeriesDef: SeriesDefinition<BarSeriesOptions>;
+
 /** Visual options for a bar series. */
 export declare interface BarSeriesOptions {
-    /** Display label shown in the tooltip (e.g. "Volume"). */
-    label?: string;
-    /** One color per layer. */
-    colors: string[];
     /** Width of each bar as a fraction of the available bar slot (0–1). `1` = bars touch; `0.6` = roughly 60 % of the slot. Default: 0.7. */
     barWidthRatio: number;
     /** Stacking mode. Default: 'off'. */
@@ -938,6 +986,180 @@ export declare interface BarSeriesOptions {
     projectedFrom?: number;
 }
 
+/**
+ * Members shared by every series renderer, regardless of whether it owns a
+ * time axis. Chart dispatches these uniformly; type-specific behavior is
+ * opted into via the optional members below.
+ *
+ * Single-layer renderers (Candlestick, Pie) default most layer methods to no-ops.
+ * 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).
+ */
+declare interface BaseSeriesRenderer {
+    /** Paint the series on the main layer. */
+    render(ctx: SeriesRenderContext): void;
+    /**
+     * Replace the series' data. For multi-layer renderers (Line, Bar), `layerIndex`
+     * selects which internal store to target; defaults to 0.
+     */
+    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;
+    /** Replace the last point in place (live candle update). Optional. */
+    updateLastPoint?(point: unknown, layerIndex?: number): void;
+    /**
+     * Keep only the last `count` points; drop the oldest. No-op when the series
+     * is already at or below the cap. Smooth Y-range update — does NOT trigger
+     * the snap that {@link setData} forces.
+     */
+    keepLast?(count: number, layerIndex?: number): void;
+    /** Number of visual layers the renderer owns. Default: 1. */
+    getLayerCount(): number;
+    /** Show/hide a layer. No-op for single-layer renderers. */
+    setLayerVisible(index: number, visible: boolean): void;
+    /** Current visibility of a layer. */
+    isLayerVisible(index: number): boolean;
+    /** Per-layer colors. Single-layer renderers return `[primary]`. */
+    getLayerColors(): string[];
+    /**
+     * Set per-layer color overrides carried in `data` (sparse — `undefined` keeps
+     * the theme base). Only multi-layer (line / bar) renderers implement it.
+     */
+    setColorOverrides?(overrides: (ValueColor | undefined)[]): void;
+    /** Apply a new theme. Each renderer decides what that means for itself. */
+    applyTheme(theme: ChartTheme, prevTheme: ChartTheme): void;
+    /**
+     * Shallow-merge new visual options into the renderer's configuration.
+     * Each renderer narrows the parameter in its concrete signature.
+     */
+    updateOptions(options: any): void;
+    /**
+     * Hit-test a bitmap-space coordinate; return the hovered index or -1. Optional.
+     * `padding` is in **bitmap pixels** (already scaled by `verticalPixelRatio`)
+     * so its values align with the `bx`/`by`/`bitmapWidth`/`bitmapHeight` arguments
+     * — the hit area then matches the painted geometry exactly.
+     */
+    hitTest?(bx: number, by: number, bitmapWidth: number, bitmapHeight: number, padding?: RenderPadding): number;
+    /** Set the currently hovered index. Returns true if the value changed. Optional. */
+    setHoverIndex?(index: number): boolean;
+    /** Get info about the currently hovered element, or null. Optional. */
+    getHoverInfo?(theme: ChartTheme): HoverInfo | null;
+    /** Pie-style breakdown of all elements. Optional. */
+    getSliceInfo?(theme: ChartTheme): SliceInfo[] | null;
+    /** Last data value for the series, or null if empty. Optional. */
+    getLastValue?(): number | null;
+    /** Nearest data point to a given time, or null. Optional. */
+    getDataAtTime?(time: number, interval: number): TimePoint | OHLCData | null;
+    /**
+     * For multi-layer renderers: nearest data point per visible layer at `time`.
+     * Each entry carries the owning `layerIndex` (so filtered hidden layers
+     * don't shift the caller's identity mapping) and the **resolved sample
+     * time** of the snapped point (not the query time). Used by Chart for
+     * tooltips/legends.
+     * Returns null for single-layer renderers or when no visible layer has data.
+     */
+    getLayerSnapshots?(time: number, interval: number): {
+        layerIndex: number;
+        time: number;
+        value: number;
+        color: string;
+    }[] | null;
+    /**
+     * Stacked last value — cumulative top of the rendered stack for multi-layer
+     * renderers. Falls back to `getLastValue()` behavior for single-layer
+     * renderers (or when no layer is visible). Chart uses this to anchor a
+     * `<YLabel />` at the same point the canvas paints the stack head.
+     */
+    getStackedLastValue?(): {
+        value: number;
+        isLive: boolean;
+    } | null;
+    /**
+     * Per-layer last snapshots, each with its own `time`. Useful for ragged
+     * multi-layer series where layers advance independently — last-mode
+     * overlays need to show each layer at its true last time, not at the
+     * primary layer's time.
+     * Returns null for single-layer renderers or when no visible layer has data.
+     */
+    getLayerLastSnapshots?(): {
+        layerIndex: number;
+        time: number;
+        value: number;
+        color: string;
+    }[] | null;
+    /** Total data points across all owned stores. Used by Chart for batch-load detection. */
+    getTotalLength?(): number;
+    /**
+     * Abort in-flight entrance animations (per-point/per-bar intros). Called
+     * when the user pans or zooms — continuing to tween bar fills while the
+     * chart is being dragged reads as flicker.
+     *
+     * Live-tracking smoothing (the halo/last-value lerp) is NOT cancelled here;
+     * that motion is subtle and shouldn't jump when the viewport moves.
+     */
+    cancelEntranceAnimations?(): void;
+    /**
+     * Start a series-level alpha cross-fade. Chart calls this on
+     * `setSeriesVisible` so the show/hide animation lives next to the geometry
+     * that owns it. `target` is the destination opacity in `[0, 1]` and
+     * `durationMs <= 0` snaps. Optional — renderers that don't need a fade
+     * (e.g. pie) leave it unimplemented; the chart falls back to a binary
+     * visibility flag.
+     */
+    setAlpha?(target: number, durationMs: number): void;
+    /** Current series-level opacity in `[0, 1]`. Chart applies it as `globalAlpha` during render. */
+    getAlpha?(): number;
+    /**
+     * Start a per-layer alpha cross-fade. Chart calls this on `setLayerVisible`
+     * so the toggled layer fades over the same `toggleMs` window the engine
+     * uses to ease the Y axis. Renderers that don't support per-layer alpha
+     * (single-store: candlestick, pie) leave it unimplemented; the chart
+     * skips the call and the layer toggles binary.
+     */
+    setLayerAlpha?(index: number, target: number, durationMs: number): void;
+    /** Current per-layer opacity in `[0, 1]`. Multiplied into `globalAlpha` by the renderer at draw time. */
+    getLayerAlpha?(index: number): number;
+    /** True while the renderer has an active animation (Chart polls per frame). */
+    readonly needsAnimation?: boolean;
+    /**
+     * Optional overlay hook. Chart invokes this during the overlay pass so each
+     * renderer can paint type-specific overlays (crosshair dots, pulse dots).
+     */
+    drawOverlay?(ctx: OverlayRenderContext): void;
+    /** True when the renderer wants the overlay layer to keep ticking (pulse animations, etc.). */
+    readonly overlayNeedsAnimation?: boolean;
+    /**
+     * True if the renderer has overlay content (e.g. pulse dots) whose positions fall within
+     * [from, to]. Chart uses this to stop scheduling overlay frames when animated content is
+     * fully off-screen. Default when omitted: assume visible (safe, may waste CPU).
+     */
+    hasOverlayContentInRange?(from: number, to: number): boolean;
+    /**
+     * Subscribe to data-changed notifications (any internal store update).
+     * Returns an unsubscribe function.
+     */
+    onDataChanged?(listener: () => void): () => void;
+    /** Tear down listeners and any owned resources. */
+    dispose(): void;
+}
+
+declare interface BitmapCoordinateSpace {
+    context: CanvasRenderingContext2D;
+    bitmapSize: {
+        width: number;
+        height: number;
+    };
+    mediaSize: {
+        width: number;
+        height: number;
+    };
+    horizontalPixelRatio: number;
+    verticalPixelRatio: number;
+}
+
 /**
  * Snapshot every visible series / layer at `time`. Used by hover overlays
  * (`InfoBar` in hover mode, `Tooltip`). Hidden series and hidden layers are
@@ -1016,6 +1238,12 @@ export declare interface CandlePaintArgs {
 /** Paints one candle body. Owns its fill. Never re-creates the gradient. */
 export declare type CandlePainter = (env: PaintEnv, args: CandlePaintArgs) => void;
 
+/**
+ * `data` shape for a candlestick series — a flat `OHLCInput[]` stream, or a
+ * `SeriesLayer<OHLCInput>` that names it for the tooltip / info bar / legend.
+ */
+declare type CandlestickData = OHLCInput[] | SeriesLayer<OHLCInput>;
+
 /**
  * `body` shape encodes the fill mode: a single color renders flat; a
  * `[top, bottom]` tuple renders a 2-stop vertical gradient. Use
@@ -1041,10 +1269,12 @@ declare type CandlestickEntryAnimation = 'none' | 'fade' | 'unfold' | 'slide' |
 
 export declare const CandlestickSeries: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{}>, {}, {}, {}, {}, 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. */
+export declare const CandlestickSeriesDef: SeriesDefinition<CandlestickSeriesOptions>;
+
 /** Visual options for a candlestick series. */
 export declare interface CandlestickSeriesOptions {
-    /** Display label shown in the tooltip. */
-    label?: string;
     /** Colours for bullish candles (close ≥ open). */
     up: CandlestickDirectionColors;
     /** Colours for bearish candles (close < open). */
@@ -1162,26 +1392,95 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
     get xAxisHeight(): number;
     constructor(container: HTMLElement, options?: ChartOptions);
     /**
-     * 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.
+     * Add a series and return its unique ID. `options` is typed per series via
+     * the overloads. `layers` (line/bar) and `id` are consumed here; everything
+     * else is forwarded to the renderer.
+     *
+     * Preferred form: pass a {@link SeriesDefinition}
+     * (`chart.addSeries(LineSeriesDef, …)`) — the chart stays renderer-agnostic
+     * and bundlers drop the series types a host never imports. The string form
+     * resolves through the registry and requires a one-time
+     * `registerBuiltinSeries()` call at startup.
      */
     addSeries(type: 'candlestick', options?: Partial<CandlestickSeriesOptions & {
         id?: string;
+        label?: string;
     }>): string;
     addSeries(type: 'line', options?: Partial<LineSeriesOptions & {
         layers?: number;
         id?: string;
+        label?: string;
+        labels?: (string | undefined)[];
     }>): string;
     addSeries(type: 'bar', options?: Partial<BarSeriesOptions & {
         layers?: number;
         id?: string;
+        label?: string;
+        labels?: (string | undefined)[];
     }>): string;
     addSeries(type: 'pie', options?: Partial<PieSeriesOptions & {
         id?: string;
+        label?: string;
     }>): string;
+    addSeries<O>(def: SeriesDefinition<O>, options?: Partial<O> & {
+        layers?: number;
+        id?: string;
+        label?: string;
+        labels?: (string | undefined)[];
+    }): string;
     /** Remove a series by ID and clean up its resources. */
     removeSeries(id: string): void;
+    /**
+     * Pin a point annotation to `time` (X) and `value` (Y), or to a series via
+     * `seriesId` (Y snaps to the nearest data point at `time`). Returns the marker
+     * id for later {@link updateMarker} / {@link removeMarker}.
+     *
+     * Markers render on the overlay layer and stay out of the series model — they
+     * are excluded from tooltips, the legend, and the Y-range autoscale, and never
+     * appear in series queries.
+     */
+    addMarker(config: MarkerConfig): string;
+    /** Replace a marker's config in place. No-op when the id is unknown. */
+    updateMarker(id: string, config: MarkerConfig): void;
+    /** Remove a marker by id. No-op when the id is unknown. */
+    removeMarker(id: string): void;
+    /** Read-only snapshot of the registered markers (normalized). Mutate via add / update / removeMarker. */
+    getMarkers(): readonly Readonly<MarkerEntry>[];
+    /**
+     * Shade the time interval `[from, to]` with a translucent vertical band —
+     * an anomaly window, a maintenance window, a highlighted session. Omit `to`
+     * (or pass `'now'`) for an open-ended band that extends to the right edge of
+     * the plot — the "still firing" case. Returns the region id for later
+     * {@link updateRegion} / {@link removeRegion}.
+     *
+     * Regions render on the main layer *behind* the series and stay out of the
+     * series model — they never affect the Y-range autoscale, tooltips, or the
+     * legend.
+     */
+    addRegion(config: TimeRegionConfig): string;
+    /** Replace a region's config in place. No-op when the id is unknown. */
+    updateRegion(id: string, config: TimeRegionConfig): void;
+    /** Remove a region by id. No-op when the id is unknown. */
+    removeRegion(id: string): void;
+    /** Read-only snapshot of the registered regions (normalized). Mutate via add / update / removeRegion. */
+    getRegions(): readonly Readonly<RegionEntry>[];
+    /**
+     * Draw a reference line across the plot — a horizontal threshold / baseline
+     * pinned to a `value`, or a vertical event boundary pinned to a `time`
+     * (mutually exclusive). Returns the line id for later {@link updateLine} /
+     * {@link removeLine}.
+     *
+     * Lines render on the overlay layer *above* the series and stay out of the
+     * series model — they never affect the Y-range autoscale, tooltips, or the
+     * legend.
+     */
+    addLine(config: ReferenceLineConfig): string;
+    /** Replace a reference line's config in place. No-op when the id is unknown. */
+    updateLine(id: string, config: ReferenceLineConfig): void;
+    /** Remove a reference line by id. No-op when the id is unknown. */
+    removeLine(id: string): void;
+    /** Read-only snapshot of the registered reference lines (normalized). Mutate via add / update / removeLine. */
+    getLines(): readonly Readonly<LineEntry>[];
     /**
      * Read-only snapshot of the chart's X / Y viewport animation. The same
      * shape (`xRange`, `yRange`, `animating`) every frame — call this inside
@@ -1381,7 +1680,25 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
     }[] | null;
     /** Get the primary display color for a series. */
     getSeriesColor(seriesId: string): string | null;
+    /** The series' primary name (first layer). Used for single-layer overlays. */
     getSeriesLabel(seriesId: string): string | undefined;
+    /** The display name of one layer, or `undefined` when that layer is unnamed. */
+    getLayerLabel(seriesId: string, layerIndex: number): string | undefined;
+    /**
+     * Set every layer's display name at once (index = layer). Drives the tooltip,
+     * legend, and info bar. Called by the framework wrappers as the carried
+     * per-layer labels in `data` change. No-ops (and skips the overlay bump) when
+     * the labels are unchanged, so it's safe to call on every data tick.
+     */
+    setSeriesLabels(seriesId: string, labels: (string | undefined)[]): void;
+    /**
+     * Set the per-layer color overrides carried in `data` (sparse — `undefined`
+     * leaves that layer on the theme base). A {@link ValueColor} per layer: a
+     * string (uniform) or a function of value (per bar / per segment). Handed to
+     * the renderer, which keeps them separate from the theme base so a theme swap
+     * preserves them. Called by the framework wrappers; no-ops when unchanged.
+     */
+    setLayerColors(seriesId: string, overrides: (ValueColor | undefined)[]): void;
     /** Get per-layer colors for a series. Returns null for single-layer non-bar/line series. */
     getSeriesLayers(seriesId: string): {
         color: string;
@@ -1572,20 +1889,17 @@ export declare interface ChartOptions {
     onEdgeReached?: (info: EdgeReachedInfo) => void;
     /**
      * Runtime performance instrumentation. Opt-in — absent by default so the
-     * hot render path stays free of timing/counting overhead.
+     * hot render path stays free of timing/counting overhead, and so bundles
+     * without instrumentation carry no perf code at all (the chart never
+     * imports it; whatever you pass here is what ships).
      *
-     * - `false` / omitted — no instrumentation, no HUD, byte-identical to a perf-free build.
-     * - `true` — create an internal {@link PerfMonitor} and mount a visible HUD overlay.
-     * - `{ hud: true, ...options }` — same, with monitor options forwarded.
-     * - `{ hud: false, ...options }` — instrument but do not render a HUD (useful when
-     *   the host app consumes stats via `monitor.onFrame` and renders its own UI).
-     * - `PerfMonitor` instance — attach to a pre-constructed monitor. Useful when several
-     *   charts share one telemetry sink. HUD defaults to off in this mode.
+     * - omitted — no instrumentation, no HUD.
+     * - `perfHud()` — monitor + visible HUD overlay (replaces the old `perf: true`).
+     * - `PerfMonitor` instance — instrument without a HUD; useful when the host
+     *   consumes stats via `monitor.onFrame` and renders its own UI, or when
+     *   several charts share one telemetry sink.
      */
-    perf?: boolean | PerfMonitor | (PerfMonitorOptions & {
-        hud?: boolean;
-        monitor?: PerfMonitor;
-    });
+    perf?: PerfMonitor | PerfConfig;
 }
 
 /**
@@ -1643,6 +1957,35 @@ export declare interface ChartTheme {
     };
     /** Color palette for multi-series charts (stacked bars, overlays). */
     seriesColors: string[];
+    /**
+     * Default single-layer bar color. A {@link ValueColor}: a string for a uniform
+     * bar, or a function of the bar's value for sign / threshold coloring.
+     * {@link createTheme} defaults it to a sign function (candlestick up / down
+     * body), which is how bars get green-up / red-down without any option.
+     *
+     * Optional so hand-built theme literals keep compiling — the bar renderer
+     * falls back to {@link ChartTheme.seriesColors}`[0]`. A function value makes
+     * the theme non-JSON-serializable; that is an accepted trade-off (the theme
+     * editor simply omits it).
+     */
+    bar?: {
+        /** Default fill — a string (uniform) or a value-fn (e.g. sign-based up/down). */
+        color: ValueColor;
+    };
+    /**
+     * Pie / donut specific colors. Optional so hand-built theme literals that
+     * predate the field keep compiling — renderers fall back to
+     * {@link ChartTheme.axis} `textColor` (the same muted tone
+     * {@link createTheme} derives by default).
+     */
+    pie?: {
+        /**
+         * Fill of the synthetic "Other" slice produced by small-slice grouping.
+         * Deliberately muted: a vivid palette color would give the aggregate the
+         * same visual weight as a real category.
+         */
+        otherColor: string;
+    };
     /** Bollinger band / envelope fill colors. */
     bands: {
         /** Fill for the upper band region (above the middle band). */
@@ -1964,6 +2307,17 @@ declare type LegendMode = 'toggle' | 'isolate' | 'solo';
 
 export declare const lightPink: ThemePreset;
 
+/** Internal bookkeeping for a registered reference line. `coord` is a Y value (horizontal) or normalized epoch ms (vertical). */
+declare interface LineEntry {
+    id: string;
+    orientation: ReferenceLineOrientation;
+    coord: number;
+    color?: string;
+    label?: string;
+    style: ReferenceLineStyle;
+    width: number;
+}
+
 /**
  * Entrance animation styles for new line points.
  * - `'none'` — new segments appear instantly.
@@ -2013,12 +2367,12 @@ declare interface LinePoint {
 
 export declare const LineSeries: DefineComponent<__VLS_Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_4> & Readonly<{}>, {}, {}, {}, {}, 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. */
+export declare const LineSeriesDef: SeriesDefinition<LineSeriesOptions>;
+
 /** Visual options for a line series. */
 export declare interface LineSeriesOptions {
-    /** Display label shown in the tooltip (e.g. "BTC", "Revenue"). */
-    label?: string;
-    /** One color per layer. */
-    colors: string[];
     /** Stroke width in CSS pixels. Default: 1. `0` hides the line stroke. */
     strokeWidth: number;
     /** Area-fill configuration. Default: `{ visible: true }`. */
@@ -2119,10 +2473,75 @@ export declare interface LineSeriesOptions {
      * to `'straight'`.
      */
     linePainter?: LinePainter;
+    /**
+     * Threshold coloring. Paints the stroke and the area fill one color below a Y
+     * `value` and another above it, with the switch pinned to that value's pixel
+     * row — a vertical canvas gradient, so it tracks the Y-axis as it autoscales.
+     * Use it to make a series visibly "go critical" past a limit: the line runs
+     * calm below the level and hot above it.
+     *
+     * Positional, so it is independent of (and overrides) the per-layer
+     * `data.color` for the stroke and fill. Applies to unstacked lines only.
+     *
+     * ```
+     * <LineSeries data={data} options={{ threshold: { value: 70, above: '#f0556a' } }} />
+     * ```
+     */
+    threshold?: {
+        /** Y data value where the color switches. */
+        value: number;
+        /** Color above the threshold (toward the top of the plot). */
+        above: string;
+        /** Color below the threshold. Default: the series' resolved color. */
+        below?: 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>;
+
+/**
+ * A point annotation pinned to a `time` (X) and a `value` (Y) — "anomaly opened
+ * here", "deploy happened here". Markers live outside the series model, so they
+ * are excluded from tooltips, the legend, and the Y-range autoscale, and never
+ * pollute series queries. Drawn on the overlay layer, clipped to the plot area.
+ */
+export declare interface MarkerConfig {
+    /** X anchor — epoch ms or a `Date`. Normalized on the way in. */
+    time: TimeValue;
+    /**
+     * Y anchor as a data value. Omit and set {@link MarkerConfig.seriesId} to snap
+     * the marker to that series' nearest data point 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'`. */
+    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;
+}
+
+/** Internal bookkeeping for a registered marker. `time` is normalized to epoch ms; `shape`/`pulse` carry resolved defaults. */
+declare interface MarkerEntry {
+    id: string;
+    time: number;
+    value?: number;
+    seriesId?: string;
+    shape: MarkerShape;
+    pulse: boolean;
+    label?: string;
+    color?: string;
+}
+
+/** Glyph drawn at the marker anchor. Arrows point their tip *at* the anchor point. */
+export declare type MarkerShape = 'dot' | 'circle' | 'arrow-up' | 'arrow-down';
+
 export declare const materialPalenight: ThemePreset;
 
 /**
@@ -2140,7 +2559,19 @@ export declare const mintBreeze: ThemePreset;
 
 export declare const monokaiPro: ThemePreset;
 
-declare const Navigator_2: DefineComponent<__VLS_Props_8, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_8> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+/**
+ * Omnivorous `data` shape for line and bar series. Accepts, interchangeably:
+ * - `TimePointInput[]` — one auto-named layer (the common single-series case);
+ * - `TimePointInput[][]` — N auto-named layers;
+ * - `SeriesLayer<TimePointInput>` — one named/colored layer;
+ * - an array mixing raw `TimePointInput[]` layers and named `SeriesLayer`s.
+ *
+ * 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>>;
+
+declare const Navigator_2: DefineComponent<__VLS_Props_9, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_9> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 stripRef: HTMLDivElement;
 }, any>;
 export { Navigator_2 as Navigator }
@@ -2166,9 +2597,14 @@ export declare interface NavigatorCandlePoint {
  * active zone aligns with the main chart's plot area (matches the TimeAxis).
  *
  * Event topology — navigator is a pure listener on the chart side, never emits:
- *   chart.viewportChange → reposition window DOM + redraw on next frame
+ *   chart.viewportChange → reposition window DOM on next frame (canvas untouched)
+ *   chart.tickFrame      → reposition window DOM on next frame (window glide)
  *   chart.overlayChange  → full redraw (catches data + theme swaps)
  *   ResizeObserver       → resize canvas + full redraw
+ *
+ * The canvas miniature depends only on data / theme / size, so per-frame
+ * viewport signals take the light DOM-only path — a wheel-zoom or pan never
+ * re-decimates the dataset or repaints the strip.
  */
 export declare class NavigatorController {
     #private;
@@ -2227,7 +2663,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_9, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_9> & Readonly<{}>, {
+export declare const NumberFlow: DefineComponent<__VLS_Props_10, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_10> & Readonly<{}>, {
 locale: string;
 spinDuration: number;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLSpanElement>;
@@ -2249,6 +2685,31 @@ export declare type OHLCInput = Omit<OHLCData, 'time'> & {
 
 export declare const oneDarkPro: ThemePreset;
 
+/** Overlay render state passed to {@link SeriesRenderer.drawOverlay}. */
+declare interface OverlayRenderContext {
+    scope: BitmapCoordinateSpace;
+    timeScale: XScale;
+    yScale: YScale;
+    theme: ChartTheme;
+    dataInterval: number;
+    /** Vertical padding in **CSS pixels** — see {@link RenderPadding}. */
+    padding: RenderPadding;
+    /** Current crosshair position, or null when none. */
+    crosshair: {
+        mediaX: number;
+        mediaY: number;
+        time: number;
+        y: number;
+    } | null;
+    /**
+     * Engine-owned animation state. Pulse renderers read `state.pulsePhase`
+     * here so the halo cycles off the same clock the rest of the chart uses.
+     */
+    state?: AnimationState;
+    /** The chart-side id for this series. See {@link SeriesRenderContext.seriesId}. */
+    seriesId?: string;
+}
+
 /**
  * Engine context shared by every painter. `ctx.globalAlpha` is ALREADY composed
  * (layer × series × entrance fade) by the renderer, and every geometry handed to
@@ -2287,6 +2748,39 @@ declare interface PanZoomTarget {
 
 export declare const peachCream: ThemePreset;
 
+/**
+ * Chart-ready perf configuration: a monitor plus an optional HUD mount.
+ * Produced by {@link perfHud} (or hand-assembled); passed as the chart's
+ * `perf` option. The chart itself never imports perf code — whatever the
+ * config carries is all that ships in the bundle.
+ */
+export declare interface PerfConfig {
+    /** Monitor that collects frame timing / draw calls for this chart. */
+    monitor: PerfMonitor;
+    /** Mounts the HUD overlay; the chart calls it at construction and destroys the result. */
+    hud?: (container: HTMLElement, monitor: PerfMonitor) => {
+        destroy(): void;
+    };
+    /** True when the config constructed the monitor — the chart then destroys it on teardown. */
+    ownsMonitor?: boolean;
+}
+
+/**
+ * Performance instrumentation with the visible HUD overlay — the factory
+ * replacement for the old `perf: true`:
+ *
+ * ```ts
+ * new ChartInstance(el, { perf: perfHud() });
+ * <ChartContainer perf={perfHud({ windowMs: 500 })} />
+ * perfHud(sharedMonitor) // HUD on an externally-owned monitor
+ * ```
+ *
+ * Importing this factory is what pulls the monitor + HUD code into the
+ * bundle; pass a bare `PerfMonitor` instance as `perf` for HUD-less
+ * instrumentation.
+ */
+export declare function perfHud(init?: PerfMonitorOptions | PerfMonitor): PerfConfig;
+
 /**
  * Collects per-frame timing, draw-call counts, per-series render ms, and heap
  * usage. All collection sites short-circuit to no-ops when no monitor is
@@ -2297,7 +2791,7 @@ export declare const peachCream: ThemePreset;
  * monitor. Multiple charts may share a monitor, but `perSeries` keys must be
  * unique across charts or samples will collide.
  */
-declare class PerfMonitor {
+export declare class PerfMonitor {
     /** Draw-call tally map for the main layer. Mutated in place by the counting context; cleared at the start of each frame. */
     readonly drawCallsMain: Map<string, number>;
     /** Draw-call tally map for the overlay layer. Same contract as `drawCallsMain`. */
@@ -2321,6 +2815,13 @@ declare class PerfMonitor {
     constructor(options?: PerfMonitorOptions);
     /** Clear the draw-call tally for the given layer. Call at the start of each frame. */
     resetDrawCalls(kind: FrameKind): void;
+    /**
+     * Wrap a 2D context in a draw-call-counting Proxy feeding this monitor's
+     * tally for `kind`. Lives on the monitor (rather than being imported by
+     * the chart's canvas manager) so charts without instrumentation carry no
+     * perf code at all.
+     */
+    wrapContext(ctx: CanvasRenderingContext2D, kind: FrameKind): CanvasRenderingContext2D;
     /** Record a completed frame's wall-clock duration and emit stats to subscribers. */
     recordFrame(kind: FrameKind, ms: number, timestamp: number): void;
     /** Record one series renderer's time slice inside the main pass. Called from inside `renderMain`, so the enclosing `recordFrame('main', …)` trim takes care of age. */
@@ -2335,7 +2836,7 @@ declare class PerfMonitor {
     private sampleHeap;
 }
 
-declare interface PerfMonitorOptions {
+export declare interface PerfMonitorOptions {
     /**
      * Age of the rolling window in milliseconds. Samples older than this are
      * dropped from FPS / percentile calculations. Defaults to 5000 (5 seconds).
@@ -2357,12 +2858,15 @@ declare interface PerfMonitorOptions {
 
 declare type PerfOption = NonNullable<ChartOptions['perf']>;
 
-declare interface PerfStats {
+export declare interface PerfStats {
     /**
-     * Main-layer renders per second, derived from the interval between recent main
-     * frames. Charts render on demand (data change, pan, zoom, resize, streaming
-     * tick), so `0` during an idle chart is normal — not a stutter. `0` until two
-     * frames have been recorded.
+     * Main-layer renders per second. During continuous rendering this is the
+     * rate of the trailing run of back-to-back frames (so it reflects the
+     * *current* rate immediately instead of ramping up as idle time ages out
+     * of the window); for sparse on-demand renders it is the window-wide
+     * average. Charts render on demand (data change, pan, zoom, resize,
+     * streaming tick), so `0` during an idle chart is normal — not a stutter.
+     * `0` until two frames have been recorded.
      */
     mainRendersPerSec: number;
     /** Same as {@link mainRendersPerSec} but for the overlay (crosshair + pulse) layer. */
@@ -2436,8 +2940,33 @@ declare type PieLegendMode = 'value' | 'percent' | 'both';
 
 declare type PieLegendPosition = 'bottom' | 'right' | 'overlay';
 
+/**
+ * Grouping of the smallest slices into a single synthetic "Other" slice.
+ * Enabled by default: when the data holds more than {@link maxSlices} slices,
+ * the largest `maxSlices - 1` keep their original order and the rest are
+ * summed into one "Other" slice appended at the end. The grouped slice
+ * behaves like a regular slice in labels / legend / tooltip / hit-testing.
+ */
+declare interface PieOtherOptions {
+    /** Max number of rendered slices including "Other". Default: 8. */
+    maxSlices?: number;
+    /** Label of the aggregated slice. Default: `'Other'`. */
+    label?: string;
+    /**
+     * Color override for the aggregated slice. Default: `theme.pie.otherColor`
+     * (falls back to `axis.textColor` for themes without a `pie` block) — a
+     * muted tone so the aggregate doesn't carry the same visual weight as a
+     * real category.
+     */
+    color?: string;
+}
+
 export declare const PieSeries: DefineComponent<__VLS_Props_5, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_5> & Readonly<{}>, {}, {}, {}, {}, 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. */
+export declare const PieSeriesDef: SeriesDefinition<PieSeriesOptions>;
+
 /** Visual options for a pie/donut series. `innerRadiusRatio > 0` makes it a donut. */
 export declare interface PieSeriesOptions {
     /** Palette fallback (defaults to theme.seriesColors). */
@@ -2450,6 +2979,13 @@ export declare interface PieSeriesOptions {
     label?: string;
     /** Per-slice label rendering on the pie itself. See {@link PieLabelsOptions}. */
     sliceLabels?: PieLabelsOptions;
+    /**
+     * Group the smallest slices into a single "Other" slice when the dataset
+     * exceeds `maxSlices` (default: 8 rendered slices total). On by default so
+     * dense datasets stay readable — pass `false` to always render every slice.
+     * See {@link PieOtherOptions}.
+     */
+    other?: boolean | PieOtherOptions;
     /**
      * When `true`, enables pie motion effects: the outside-label entrance
      * draw-in on mount / data swap, and the hover-explode slice offset.
@@ -2459,6 +2995,14 @@ export declare interface PieSeriesOptions {
      * value.
      */
     animate?: boolean;
+    /**
+     * 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.
+     * Set `false` for flat, solid-color slices (the material / infographic
+     * look). Orthogonal to {@link innerShadow}: an explicit `innerShadow` still
+     * paints its dark rim band even when the depth gradient is off.
+     */
+    gradient?: boolean;
     /**
      * Ambient *outer* drop-shadow behind each slice. Adds lift for flat
      * dashboards. Omit / `false` to disable (default). `true` uses soft
@@ -2494,6 +3038,11 @@ export declare interface PieSeriesOptions {
     };
 }
 
+/** A spatial renderer with no time axis (Pie). Has no time-series queries. */
+declare interface PieSeriesRenderer extends BaseSeriesRenderer {
+    readonly kind: 'pie';
+}
+
 /** Optional min/max constraints for the Y axis. Omit a side for automatic scaling. */
 /** A single slice in a pie/donut chart. */
 export declare interface PieSliceData {
@@ -2515,6 +3064,83 @@ 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>;
+
+/**
+ * A straight reference line across the plot — a horizontal threshold / baseline
+ * pinned to a `value`, or a vertical event boundary pinned to a `time`. Like
+ * markers and regions, reference lines stay out of the series model: they don't
+ * affect the Y-range autoscale, tooltips, or the legend. Drawn on the overlay
+ * layer, *above* the series and clipped to the plot area, so the line reads on
+ * top of the data the way a threshold should.
+ */
+export declare interface ReferenceLineConfig {
+    /** Horizontal line at this Y data value. Mutually exclusive with {@link time}. */
+    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. */
+    color?: string;
+    /** Optional text label drawn in a pill at the line's near end. */
+    label?: string;
+    /** Dash style. Default: `'dashed'`. */
+    style?: ReferenceLineStyle;
+    /** Stroke width in CSS pixels. Default: `1`. */
+    width?: number;
+}
+
+/** Orientation of a resolved reference line. */
+export declare type ReferenceLineOrientation = 'horizontal' | 'vertical';
+
+/** Dash pattern of a {@link ReferenceLineConfig}. */
+export declare type ReferenceLineStyle = 'solid' | 'dashed';
+
+/** Internal bookkeeping for a registered time region. `from`/`to` are normalized to epoch ms; `to: null` is open-ended. */
+declare interface RegionEntry {
+    id: string;
+    from: number;
+    to: number | null;
+    fill?: string;
+    color?: string;
+    label?: string;
+}
+
+/**
+ * Register the four 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
+ * care about size should pass definitions directly instead:
+ * `chart.addSeries(LineSeriesDef, options)`.
+ */
+export declare function registerBuiltinSeries(): void;
+
+/**
+ * Make a definition resolvable through the string form
+ * `chart.addSeries('line', …)`. The built-ins register in one call via
+ * `registerBuiltinSeries()`; hosts that pass definitions directly never
+ * need the registry.
+ */
+export declare function registerSeriesDefinition(def: SeriesDefinition): void;
+
+/**
+ * Vertical padding reserved at the top/bottom of the chart area.
+ *
+ * **Unitless on its own** — the unit is fixed by the call site:
+ *  - In {@link SeriesRenderContext} / {@link OverlayRenderContext}: **CSS pixels**
+ *    (multiply by `scope.verticalPixelRatio` to convert to bitmap pixels).
+ *  - In {@link SeriesRenderer.hitTest}: **bitmap pixels** (the chart pre-scales
+ *    so the values align with the `bx`/`by` bitmap-space pointer coords).
+ *
+ * Time-based renderers absorb this implicitly via the YScale's value range,
+ * but spatial renderers (Pie) need the raw pixel reservation to keep their
+ * layout out of the Title / InfoBar overlay regions.
+ */
+declare interface RenderPadding {
+    top: number;
+    bottom: number;
+}
+
 /**
  * Resolve the effective font size for a given axis, falling back to the
  * shared `axis.fontSize` default when no per-axis override is set.
@@ -2594,6 +3220,72 @@ export declare interface RoundedRectArgs {
 
 export declare const sandDune: ThemePreset;
 
+/** Environment the chart hands a {@link SeriesDefinition} when constructing its renderer. */
+export declare interface SeriesCreateEnv {
+    /** Active chart theme — definitions read their default colours from it. */
+    theme: ChartTheme;
+    /** Number of stacked layers requested via `layers` (`1` when omitted). */
+    layerCount: number;
+}
+
+/**
+ * A series type the chart knows how to instantiate.
+ *
+ * Pass one to `chart.addSeries(def, options)` — the chart itself stays
+ * renderer-agnostic, so bundlers only ship the series a host actually
+ * imports. The built-in definitions live next to their renderers
+ * (`CandlestickSeriesDef`, `LineSeriesDef`, `BarSeriesDef`, `PieSeriesDef`).
+ */
+export declare interface SeriesDefinition<O = Record<string, unknown>> {
+    /** Discriminator for animation defaults and string-form lookup. */
+    readonly type: SeriesType;
+    /** Construct the renderer. `options` arrives with the chart's animation defaults/overrides already merged. */
+    create(env: SeriesCreateEnv, options: Partial<O>): SeriesRenderer;
+}
+
+/**
+ * A single named (and optionally colored) layer. Carries the layer's display
+ * name and color *alongside* its data, so `Tooltip` / `Legend` show per-layer
+ * names without a separate `label` option. `color` applies to line/bar layers;
+ * a candlestick stream ignores it (candle colors come from `up` / `down`).
+ */
+declare interface SeriesLayer<T> {
+    /** Display name shown in tooltip / legend. A multi-layer series defaults each unnamed layer to `Series N`. */
+    label?: string;
+    /** Stroke + fill color for this layer; overrides the theme default. A function colors per bar / per line segment by value. Ignored by candlestick. */
+    color?: ValueColor;
+    /** The layer's points. */
+    data: T[];
+}
+
+declare interface SeriesRenderContext {
+    scope: BitmapCoordinateSpace;
+    timeScale: XScale;
+    yScale: YScale;
+    theme: ChartTheme;
+    dataInterval: number;
+    /** Vertical padding in **CSS pixels** — see {@link RenderPadding}. */
+    padding: RenderPadding;
+    /**
+     * Engine-owned animation state — pulse phase, live values, entry
+     * progress. Optional during the Phase 2 migration: renderers that
+     * haven't been ported yet keep reading their own state and ignore this.
+     */
+    state?: AnimationState;
+    /**
+     * The id under which the chart registered this series — used by
+     * stateful per-series lookups (`state.pulsePhase.get(seriesId)`,
+     * `state.seriesAlpha.get(seriesId)`).
+     */
+    seriesId?: string;
+}
+
+/**
+ * Every series renderer is one of these. Discriminated on `kind`: narrow with
+ * `kind === 'pie'` (or `!== 'pie'`) to reach the variant-specific surface.
+ */
+declare type SeriesRenderer = TimeSeriesRenderer | PieSeriesRenderer;
+
 /**
  * Frozen, per-row snapshot of a series at a single point in time. The shape
  * `buildHoverSnapshots` / `buildLastSnapshots` return to overlay slot
@@ -2667,6 +3359,8 @@ export declare interface ThemeConfig {
     };
     line?: Partial<ChartTheme['line']>;
     seriesColors?: string[];
+    bar?: Partial<NonNullable<ChartTheme['bar']>>;
+    pie?: Partial<NonNullable<ChartTheme['pie']>>;
     bands?: Partial<ChartTheme['bands']>;
     crosshair?: Partial<ChartTheme['crosshair']>;
     axis?: Partial<ChartTheme['axis']>;
@@ -2730,7 +3424,7 @@ declare interface TickTrackerSnapshot {
     readonly isAnimating: boolean;
 }
 
-export declare const TimeAxis: DefineComponent<__VLS_Props_12, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_12> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+export declare const TimeAxis: DefineComponent<__VLS_Props_14, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_14> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 containerRef: HTMLDivElement;
 }, HTMLDivElement>;
 
@@ -2745,6 +3439,67 @@ 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>;
+
+/**
+ * A translucent vertical band shading the interval `[from, to]` — Grafana's
+ * "annotation region", TradingView's highlighted session, an SRE anomaly
+ * window. Regions live outside the series model: they never affect the Y-range
+ * autoscale, tooltips, or the legend. Drawn on the main layer *behind* the
+ * series so the data reads on top of the shading, clipped to the plot area.
+ */
+export declare interface TimeRegionConfig {
+    /** Left edge — epoch ms or a `Date`. Normalized on the way in. */
+    from: TimeValue;
+    /**
+     * Right edge — epoch ms or a `Date`. Omit (or pass `'now'`) for an open-ended
+     * region that extends to the right edge of the plot — the "still firing" case.
+     */
+    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. */
+    label?: string;
+    /** Edge-line and label-pill accent. Default: the theme's muted axis text color. */
+    color?: string;
+}
+
+/**
+ * Right edge of a {@link TimeRegionConfig}. A concrete time closes the band;
+ * `'now'` (or an omitted `to`) leaves it open-ended — it extends to the right
+ * edge of the plot, the "still firing" case.
+ */
+export declare type TimeRegionEnd = TimeValue | 'now';
+
+/**
+ * A renderer with a time axis (Candlestick, Line, Bar). Owns its data and
+ * answers the time-series queries directly — Chart never reaches into a store.
+ * Multi-layer renderers (Line, Bar) aggregate across their layers internally;
+ * `getLastDataPoint` / `getSecondLastDataPoint` / `getVisibleDataPoints` are
+ * pinned to layer 0 (see {@link BaseMultiLayerSeries}).
+ */
+declare interface TimeSeriesRenderer extends BaseSeriesRenderer {
+    readonly kind: 'candlestick' | 'line' | 'bar';
+    /** Earliest/latest sample time across all owned layers, or null when empty. */
+    getTimeBounds(): {
+        first: number;
+        last: number;
+    } | null;
+    /** Last data point (layer 0 for multi-layer), or null when empty. */
+    getLastDataPoint(): OHLCData | TimePoint | null;
+    /** Second-to-last data point (layer 0 for multi-layer), or null. */
+    getSecondLastDataPoint(): OHLCData | TimePoint | null;
+    /** First `maxCount` sample times from the first populated layer — feeds interval detection. */
+    sampleTimes(maxCount: number): number[];
+    /** Visible points in `[from, to]` (layer 0 for multi-layer). */
+    getVisibleDataPoints(from: number, to: number): readonly (OHLCData | TimePoint)[];
+    /** Effective min/max for auto-range (stacked totals for multi-layer; raw min/max otherwise). */
+    getValueRange(from: number, to: number): {
+        min: number;
+        max: number;
+    } | null;
+}
+
 /**
  * Accepted time input: a timestamp in **milliseconds** (like `Date.now()`) or a `Date` object.
  * `Date` values are converted to milliseconds internally via `Date.getTime()`.
@@ -2892,6 +3647,15 @@ export declare function useVisibleRange(chart: ChartInstance): Ref<VisibleRange>
 
 export declare function useYRange(chart: ChartInstance): Ref<YRange>;
 
+/**
+ * A color, or a function of a datum's value → color. The function form is
+ * evaluated per element — per bar in a bar series, per segment in a line — so
+ * one layer can paint by sign / threshold (e.g. `v => v >= 0 ? up : down`)
+ * without any extra option. Used both for the per-layer `data` override and the
+ * theme's default bar color.
+ */
+declare type ValueColor = string | ((value: number) => string);
+
 /**
  * Default value formatters used across the chart library.
  *
@@ -3006,7 +3770,7 @@ declare class XScale {
     private countTicks;
 }
 
-export declare const YAxis: DefineComponent<__VLS_Props_15, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_15> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+export declare const YAxis: DefineComponent<__VLS_Props_18, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_18> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 containerRef: HTMLDivElement;
 }, HTMLDivElement>;