openalgo-charts 2.4.0 → 2.4.5

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+import { TradingCapabilitySource as TradingCapabilitySource$1 } from 'openalgo-charts';
+
 /** Library version string. Matches package.json (including locally prepared releases). */
-declare const VERSION = "2.4.0";
+declare const VERSION = "2.4.5";
 /** Returns the current library version. */
 declare function version(): string;
 
@@ -431,6 +433,28 @@ interface Bar {
     low: number;
     close: number;
     volume?: number;
+    /**
+     * Open interest: contracts outstanding at the end of this bar. Optional,
+     * because only a derivatives feed carries it; on a cash instrument it is
+     * absent, and absent is not zero. Zero is a real reading on a contract nobody
+     * holds.
+     *
+     * **It is a level, not a flow, and that is the whole reason it needs saying
+     * here.** Volume is a quantity traded *during* the bar, so folding five
+     * one-minute bars into a five-minute bar adds five volumes together. Open
+     * interest is a position *as at* the bar, so the same fold takes the last
+     * one and adding them would produce a number five times too large that still
+     * looks entirely plausible on a chart.
+     *
+     * Every aggregation path in this library therefore treats the two
+     * differently: `mergeBars`, the higher-timeframe fold in `securitySeries`,
+     * and the tick-to-bar builders all sum volume and carry the latest open
+     * interest. A transform that maps one source bar to one output bar passes it
+     * through; one that invents bars from price alone (Renko, Point and Figure)
+     * does not carry it at all, because a synthetic bar has no instant to be the
+     * position as at.
+     */
+    oi?: number;
     /**
      * Per-bar colour override, honoured by every Family-A renderer: candles and
      * OHLC bars take it on body, border and wick together, histogram and column
@@ -899,8 +923,10 @@ declare class SeriesMarkers implements IPrimitive {
  * Which price axis a series maps to. 'right' (default) and 'left' each draw an
  * axis and autoscale independently; '' is a hidden overlay scale (no axis, its
  * own autoscale) used to pin a volume histogram inside the price pane.
+ * `overlay:name` creates an independent hidden scale, shared only by series
+ * using that same name on this pane.
  */
-type PriceScaleId = 'right' | 'left' | '';
+type PriceScaleId = 'right' | 'left' | '' | `overlay:${string}`;
 /**
  * Value formatting for a price scale (its axis labels and crosshair tag):
  * `price` (tick-size precision), `volume` (compact 1.2K / 3.4M / 5.6B),
@@ -1338,7 +1364,7 @@ declare class Pane {
     private _rightScale;
     /** Extra scales created on demand: left axis and a hidden overlay (volume). */
     private _leftScale;
-    private _overlayScale;
+    private readonly _overlayScales;
     /**
      * Scales whose price-per-bar ratio is pinned, with the geometry the ratio was
      * last held against. A lock stores that geometry rather than a number,
@@ -1548,1344 +1574,1504 @@ declare class Pane {
 }
 
 /**
- * A grid overlay pinned to a corner of the pane rather than to bars.
- *
- * Seasonality heatmaps, performance summaries and signal scoreboards are all
- * the same shape: a small table of coloured cells that stays put while the
- * chart pans underneath. That makes this a screen-space primitive like the
- * watermark and the pane legend, not a series: it has no time anchor, takes no
- * part in autoscale, and survives a zoom untouched.
+ * Horizontal price line primitive (ARCHITECTURE.md §8). The reusable base for
+ * order/SL/TP/alert/indicator-level lines: a line across the plot plus a fixed
+ * right-axis price tag and an optional broker-style segmented pill group on the
+ * line — [badge][qty][label][✕] — with hover / dragging states (the chart
+ * passes `hoverId`/`dragId` on the render context) and a drag ghost at the
+ * pre-drag price via `setDragGhost`. Interaction semantics are unchanged from
+ * the classic tag: the ✕ hit-tests as `${id}::close`, everything else drags.
  */
 
-type TablePosition = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
-interface TableCell {
-    text: string;
-    /** Cell fill. Transparent when omitted, so the pane shows through. */
-    bgColor?: string;
-    /** Text colour. Derived from `bgColor` for contrast when omitted. */
-    textColor?: string;
-    align?: 'left' | 'center' | 'right';
-    /** Overrides the table's `fontSize` for this cell, for a heading row. */
-    fontSize?: number;
-    bold?: boolean;
-}
-interface ChartTableOptions {
-    position: TablePosition;
-    /** Gap from the pane edge, media px. */
-    margin: number;
-    /** Column width in media px. A per-column array sizes each one separately. */
-    cellWidth: number | readonly number[];
-    cellHeight: number;
-    /**
-     * Type size in media px, or `'auto'` to fit each cell: as large as its row
-     * allows, shrunk until its text also fits its column. A stretched grid with
-     * one long label would otherwise either clip that cell or be sized down as a
-     * whole to suit it.
-     */
-    fontSize: number | 'auto';
-    /** Grid line colour. Omit to draw no grid. */
-    borderColor?: string;
-    borderWidth: number;
+interface PriceLineOptions {
+    price: number;
+    color: string;
+    /** Line thickness in media px. Default 1. */
+    lineWidth?: number;
+    /** Legacy two-state dash switch, equivalent to `lineStyle: 'dashed'`. */
+    dashed?: boolean;
     /**
-     * Table width as a percentage of the plot, 0 or omitted to size from
-     * `cellWidth` instead. Column proportions are preserved, so a per-column
-     * `cellWidth` array still controls the relative widths, and the percentage
-     * only decides the total.
+     * Dash style, the three-way form of `dashed`. Set, it wins over the boolean;
+     * unset, the boolean still decides, so a line built before this existed draws
+     * exactly as it did.
      */
-    widthPercent?: number;
-    /** Table height as a percentage of the plot, 0 or omitted to size from `cellHeight`. */
-    heightPercent?: number;
+    lineStyle?: CanvasLineStyle;
+    /** Right-axis tag text. Defaults to the formatted price. */
+    label?: string;
+    /** Solid colored badge segment at the start of the pill group (e.g. 'BUY', 'TP', 'SL'). */
+    badge?: string;
+    /** Quantity segment rendered as a neutral box after the badge. */
+    qty?: string | number;
+    /** Info text segment (order type, price, P&L ...) — the classic left tag text. */
+    leftLabel?: string;
     /**
-     * Relative row heights, one per row, defaulting to 1. A separator row is the
-     * reason this exists: stretched to fill a pane, an equal split makes a rule
-     * between two sections as tall as the sections themselves.
+     * Fraction of the plot width the line spans, measured from the right (price)
+     * axis. 1 = full width (default); 0.3 = only the rightmost 30%, like a
+     * partial-width order line. The right-axis tag is always drawn.
      */
-    rowWeights?: readonly number[];
-    /** Backdrop behind the whole grid, drawn before the cells. */
-    background?: string;
-    /** Hit-test id, so a host can route clicks the way it does for other primitives. */
-    id?: string;
+    extentFromRight?: number;
+    /** Draw a cancel (✕) segment at the end of the pill group; hit-tests as `${id}::close`. */
+    closeButton?: boolean;
+    /** Stable id returned by hit-test (for click/drag routing). */
+    id: string;
+    /** Cursor hint when hovered (e.g. 'ns-resize' for draggable lines). */
+    cursor?: string;
 }
-declare const DEFAULT_CHART_TABLE_OPTIONS: ChartTableOptions;
-/** Top-left corner of the grid for a position keyword, in media px. */
-declare function tableOrigin(position: TablePosition, margin: number, w: number, h: number, plotW: number, plotH: number): {
-    x: number;
-    y: number;
-};
-declare class ChartTable implements IPrimitive {
-    private _rows;
+declare class PriceLine implements IPrimitive {
     private _opts;
     private _host;
-    /** Last drawn rect in media px, for hit-testing without recomputing layout. */
-    private _rect;
-    constructor(options?: Partial<ChartTableOptions>);
+    private _ghostPrice;
+    /** Pill-group geometry from the last draw (media px) for hit-testing. */
+    private _group;
+    constructor(opts: PriceLineOptions);
     attached(host: PrimitiveHost): void;
     detached(): void;
+    get price(): number;
+    /** Move the line; schedules a repaint via the host. */
+    setPrice(price: number): void;
+    /** Update the info segment text (e.g. live position P&L); repaints. */
+    setLeftLabel(text: string): void;
+    /**
+     * Restyle in place; repaints. `id` is the hit-test handle the chart routes
+     * clicks and drags through, so it is not patchable — swapping it under a
+     * live drag would strand the gesture.
+     *
+     * A last-price line is the case this exists for: it has to follow the tick
+     * direction, and only `setPrice` was updatable, so the colour was stuck at
+     * whatever it was constructed with.
+     */
+    setOptions(patch: Partial<Omit<PriceLineOptions, 'id'>>): void;
+    /**
+     * Show a dimmed reference line at the pre-drag price while the user drags
+     * (pass the original price on drag start, null on drag end to clear).
+     */
+    setDragGhost(price: number | null): void;
+    options(): Readonly<PriceLineOptions>;
     zOrder(): ZOrder;
-    options(): Readonly<ChartTableOptions>;
-    setOptions(patch: Partial<ChartTableOptions>): void;
-    /** Replace the grid. Rows may be ragged; each is drawn to its own length. */
-    setRows(rows: readonly (readonly TableCell[])[]): void;
-    rows(): readonly (readonly TableCell[])[];
+    autoscaleInfo(): {
+        min: number;
+        max: number;
+    } | null;
     draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
-    hitTest(x: number, y: number): PrimitiveHit | null;
+    hitTest(x: number, y: number, rc: PrimitiveRenderContext): PrimitiveHit | null;
 }
 
 /**
- * Indicator registry (ARCHITECTURE.md §6A, §8). The sibling of the chart-type
- * registry: that one answers *"how do I paint an array of bars"*, this one
- * answers *"what do I compute, what does it plot, and what can a user tune"*.
+ * Pane legend (ARCHITECTURE.md §8) — the row at the top-left
+ * of a pane: a color swatch, the source's name, its parameters, the value under
+ * the crosshair, and inline action buttons on the right.
  *
- * A descriptor is data, not code-in-the-core — the chart never switches on an
- * indicator id. Each `plot` names a registered **chart type**, so indicators
- * ride the existing Family-A renderers and add no drawing code at all.
+ * Drawn on the canvas rather than in the DOM, like `BuySellButtons` and
+ * `DomLadder`, so it composites into screenshots and costs no DOM per pane.
+ * Buttons hit-test as `${id}::close`, `${id}::hide`, and `${id}::settings`, so
+ * the host routes them through the same `subscribeClick` path as order pills.
  *
- * The built-in descriptors live in the lazy `openalgo-charts/indicators` tier;
- * only the registry and the runtime ship in the base bundle, so an app that
- * plots its own maths pays nothing for the catalog.
+ * Rows stack: several legends on one pane offset each other vertically, which
+ * the host does by giving each a `row` index.
+ *
+ * This row is also the chart's status line, so `statusLine` carries the
+ * per-field switches a settings dialog expects (logo, title, market status,
+ * chart values, bar change, volume, last day change, background). Every switch
+ * defaults to the behaviour that predates it, so a caller that passes none sees
+ * the row it always saw. Fields the primitive cannot compute (a logo bitmap,
+ * whether the market is open, the change since yesterday's close) arrive
+ * through `status`; with no source they draw nothing at all rather than a
+ * placeholder.
  */
 
-/** Which price a calculation reads from each bar. */
-type IndicatorSource = 'open' | 'high' | 'low' | 'close' | 'hl2' | 'hlc3' | 'ohlc4' | 'volume';
+type PaneLegendAction = 'hide' | 'settings' | 'up' | 'down' | 'maximize' | 'close';
 /**
- * One tunable input. `type` is what a settings UI renders; the core only reads
- * `key`/`default`.
- *
- * `tooltip` is help text for the row. A label has to stay short enough to fit a
- * dense panel, which leaves nowhere to say what a parameter actually does, and a
- * ported study whose every input carried an explanation arrives here with that
- * explanation dropped. A settings UI renders it as a hover affordance beside the
- * label; the core ignores it.
+ * One reading on a legend row. Multi-plot sources show one per plot, each in
+ * that plot's own color (an MA ribbon's four averages, MACD's three lines) —
+ * a single string in a single color cannot say which number is which.
  */
-type IndicatorInput = {
-    key: string;
-    type: 'number';
-    label: string;
-    default: number;
-    min?: number;
-    max?: number;
-    step?: number;
-    group?: string;
-    tooltip?: string;
-} | {
-    key: string;
-    type: 'boolean';
-    label: string;
-    default: boolean;
-    group?: string;
-    tooltip?: string;
-} | {
-    key: string;
-    type: 'color';
-    label: string;
-    default: string;
-    group?: string;
-    tooltip?: string;
-} | {
-    key: string;
-    type: 'text';
-    label: string;
-    default: string;
-    group?: string;
-    tooltip?: string;
-} | {
-    key: string;
-    type: 'select';
-    label: string;
-    default: string;
-    options: readonly {
-        label: string;
-        value: string;
-    }[];
-    group?: string;
-    tooltip?: string;
-} | {
-    key: string;
-    type: 'source';
-    label: string;
-    default: IndicatorSource;
-    group?: string;
-    tooltip?: string;
+interface LegendValue {
+    /** Dimmed prefix, e.g. `O` / `H` / `Vol`. */
+    label?: string;
+    text: string;
+    /** Defaults to the row's `valueColor`, then `color`, then the theme text. */
+    color?: string;
+    /**
+     * Which status-line switch owns this reading. Untagged readings are the
+     * source's own last value, governed by `statusLine.lastValueLabel`.
+     */
+    field?: LegendField;
+    /** Higher values retain this whole reading on narrow rows. Series readings default to 1; status metadata ranks lower. */
+    priority?: number;
 }
 /**
- * A timeframe code (`'5m'`, `'1d'`), for a study that folds the chart's bars
- * up to a coarser interval. A settings UI renders it as a select over the
- * registered intervals, so the value is always one the engine can bucket by;
- * a free text box would accept `'5min'` and leave the study computing on a
- * code it cannot resolve. An empty default means "the chart's own interval".
+ * Status-line groups a host can feed and switch off independently. The legend
+ * never derives these: it tags what the host hands it, so one switch hides one
+ * group and leaves the rest of the row alone.
  */
- | {
-    key: string;
-    type: 'interval';
-    label: string;
-    default: string;
-    group?: string;
-    tooltip?: string;
-}
+type LegendField = 'ohlc' | 'change' | 'volume' | 'openInterest';
 /**
- * A wall-clock instant in the chart's zone, written `YYYY-MM-DD HH:MM` (the
- * time part optional), for an anchor a user picks by date: the start of an
- * anchored VWAP, an event to measure from. It is carried as that string, not
- * as UTC seconds, so a layout saved in one zone restores to the same wall
- * clock in another, and `zonedStringToUtcSeconds` turns it into a bar time.
+ * Which name the title shows. `description` and `ticker` come from `status`;
+ * with neither supplied the title falls back to `title`, which always exists.
  */
- | {
-    key: string;
-    type: 'time';
-    label: string;
-    default: string;
-    group?: string;
-    tooltip?: string;
-};
-/** Dash pattern for a level, a drawing, or a plot. */
-type IndicatorLineStyle = 'solid' | 'dashed' | 'dotted';
-/** Line-style options, for a settings UI's Style tab. */
-declare const INDICATOR_LINE_STYLES: readonly {
-    label: string;
-    value: string;
-}[];
-/** Settings keys the runtime derives for a plot's appearance. */
-declare function plotStyleKeys(plot: IndicatorPlot): {
-    color: string;
-    width: string;
-    lineStyle: string;
-    opacity: string;
-    type: string;
-};
+type LegendTitleMode = 'symbol' | 'description' | 'ticker';
 /**
- * Per-plot appearance inputs, generated from the descriptor rather than
- * hand-written on each one — every indicator gets colour, opacity, thickness,
- * and line style for free, and a settings UI can render them as a "Style" tab
- * beside the descriptor's own `inputs`.
- *
- * Defaults come from the plot's declared style (and its legacy `colorKey`), so
- * an indicator that already ships colours keeps them.
+ * The parts of the status line the primitive has no way to know. The host
+ * supplies what it has; anything missing is simply not drawn.
  */
-declare function indicatorStyleInputs(descriptor: IndicatorDescriptor): IndicatorInput[];
+interface LegendStatusData {
+    /** Already-decoded logo (an `<img>`, an `ImageBitmap`, a canvas). */
+    logo?: CanvasImageSource;
+    /** Long name for `titleMode: 'description'`, e.g. `Apple Inc.`. */
+    description?: string;
+    /** Exchange ticker for `titleMode: 'ticker'`, e.g. `NASDAQ:AAPL`. */
+    ticker?: string;
+    /** Session state, e.g. `{ text: 'Market open', color: '#26a69a' }`. */
+    marketStatus?: LegendValue;
+    /** Change against the previous close, e.g. `{ text: '+1.20 (+0.75%)' }`. */
+    lastDayChange?: LegendValue;
+}
 /**
- * Chart types a plot can be re-rendered as. A moving average is a line by
- * default, but the same column of numbers reads better as a histogram or an
- * area depending on what you are looking for — and a descriptor cannot know
- * which. Restricted to the types that make sense for a single value column.
+ * A snapshot, or a getter the legend calls each frame, so live fields (market
+ * status, day change) can change without the host patching options at tick
+ * speed. Returning `null` means "nothing to show".
  */
-declare const INDICATOR_PLOT_STYLES: readonly {
-    label: string;
-    value: string;
-}[];
-/** Canonical option list for a `type: 'source'` input, for settings UIs. */
-declare const INDICATOR_SOURCES: readonly {
-    label: string;
-    value: IndicatorSource;
-}[];
-type IndicatorSettings = Record<string, unknown>;
-/** One plotted line/band/histogram. `type` is any registered chart type. */
-/** A shaded band between two of an indicator's plots. */
-interface IndicatorFillSpec {
-    /** The two plot keys to fill between. */
-    between: readonly [string, string];
-    /** Colour where the first plot is above the second. */
-    colorUp?: string;
-    /** Colour where the second is above the first. */
-    colorDown?: string;
-    /** Settings keys holding those colours, so the band is restyleable. */
-    colorUpKey?: string;
-    colorDownKey?: string;
-    /** 0..1. Defaults to 0.12. */
-    opacity?: number;
-    /**
-     * Draw the band on the price pane even though the indicator owns a pane of
-     * its own. The pair with `IndicatorPlot.overlay`: a study can already send
-     * one plot to the candles, and a band between two such plots belongs beside
-     * them rather than in the study pane the fill would otherwise land in.
-     * Ignored for an `'onchart'` descriptor, which is on the price pane already.
-     */
-    overlay?: boolean;
-}
+type LegendStatusSource = LegendStatusData | (() => LegendStatusData | null);
 /**
- * What `colorParts` answers: a candle plot's colour split three ways, which is
- * how a study paints a wick in full colour over a translucent body. `body` is
- * the bar's colour (and the only part a line, histogram or column reads); a
- * part left undefined falls back to `colorBy`, then to the plot's own colour.
+ * Per-field switches for the status line. Existing reading fields default to
+ * on; open interest and the background plate default to off. A missing reading
+ * draws nothing whether its switch is on or off.
  */
-type PlotBarColor = {
-    body?: string;
-    wick?: string;
-    border?: string;
-};
-interface IndicatorPlot {
-    /** Key into the `calc` result. */
-    key: string;
-    /** Registered chart type used to draw it ('line', 'histogram', 'area', ...). */
-    type: SeriesType;
-    /** Legend title. */
-    title: string;
-    /** Style overrides merged onto the chart type's defaults. */
-    style?: SeriesStyle;
-    /** Price axis for this plot. Defaults to 'right'. */
-    priceScaleId?: PriceScaleId;
-    /**
-     * Value formatting for the axis and crosshair tag of the scale this plot maps
-     * to: `percent` for a ratio study, `volume` for a cumulative one, `custom` for
-     * anything else.
-     *
-     * Like `style.precision`, this is a property of the **price scale**, not of the
-     * series, so it belongs to a plot that owns its pane. Setting it on an
-     * `'onchart'` plot reformats the instrument's own axis, which is almost never
-     * what a study wants.
-     *
-     * `percent` suffixes the value as it stands and does not scale it, so a study
-     * returning a 0..1 fraction should keep returning it and read `0.62%`. Scaling
-     * inside `calc` to make the axis read better changes the plotted value, and the
-     * legend, the crosshair and every downstream calculation with it.
-     */
-    priceFormat?: PriceFormat;
-    /**
-     * Draw this one plot on the price pane even though the indicator owns a pane
-     * of its own. An oscillator that also wants a signal
-     * band or a stop line sitting on the candles is the case: the study belongs in
-     * its own pane, one of its columns belongs on price, and splitting it into two
-     * indicators would make the user configure the same inputs twice.
-     *
-     * Ignored for an `'onchart'` descriptor, which is already on the price pane.
-     */
-    overlay?: boolean;
+interface LegendStatusLineOptions {
+    /** Symbol logo, when `status` supplies one. */
+    logo?: boolean;
+    /** The bold name. Also the "name label" switch for an indicator row. */
+    title?: boolean;
+    /** Which name the title shows. Default `symbol`. */
+    titleMode?: LegendTitleMode;
+    /** Session state from `status.marketStatus`. */
+    marketStatus?: boolean;
+    /** The OHLC readout: readings tagged `field: 'ohlc'`. */
+    chartValues?: boolean;
+    /** Change over the hovered bar: readings tagged `field: 'change'`. */
+    barChange?: boolean;
+    /** Readings tagged `field: 'volume'`. */
+    volume?: boolean;
+    /** Readings tagged `field: 'openInterest'`. Off by default. */
+    openInterest?: boolean;
+    /** Change since the previous close, from `status.lastDayChange`. */
+    lastDayChange?: boolean;
     /**
-     * Draw the column shifted this many bars to the right (negative: left). The
-     * column itself stays one value per bar and `calc` returns exactly what it
-     * always did; only where each value is painted moves. Positive is what a
-     * displaced cloud or a projected channel wants: the last `offset` values land
-     * in the right margin, past the newest candle, where no bar exists to hold
-     * them. It shifts the drawn series only. A fill between two plots with the
-     * same offset follows; the legend reads the value drawn under the cursor.
+     * The source's own reading (untagged values). This is the scales-and-lines
+     * "last value label" control, which lands here because the legend is what
+     * draws that number on this row.
      */
-    offset?: number;
+    lastValueLabel?: boolean;
     /**
-     * Settings key holding this plot's color, so a settings change restyles the
-     * series without a full rebuild.
+     * Plate behind the row's text, for legibility over candles. Off by default:
+     * the row has never had one, and turning it on is a deliberate choice.
      */
-    colorKey?: string;
+    background?: boolean;
+    /** Plate opacity, 0..1. Default 0.8, matching the hover plate. */
+    backgroundOpacity?: number;
+    /** Plate color. Defaults to the theme background. */
+    backgroundColor?: string;
+}
+interface PaneLegendOptions {
+    /** Explicit false suppresses OI without discarding its saved switch. Set by an owning chart. */
+    hasOpenInterest?: boolean;
+    /** Stable id; buttons hit-test as `${id}::close` etc. */
+    id: string;
+    /** Bold source name, e.g. `RSI`. */
+    title: string;
+    /** Dimmed parameter summary after the title, e.g. `14 close`. */
+    params?: string;
+    /** Swatch color; omitted draws no swatch. */
+    color?: string;
     /**
-     * Four `calc` keys to draw this plot as bar-shaped elements instead of one
-     * value per bar: candles, hollow candles, OHLC bars, high-low.
-     *
-     * A single column cannot express those at all, and the alternative (a second
-     * result shape for `calc`) would fork the contract every descriptor and every
-     * helper is written against. Naming four columns inside the *same*
-     * `IndicatorValues` keeps one shape: a smoothed Heikin-Ashi overlay, a
-     * higher-timeframe candle, a synthetic spread instrument each return four
-     * ordinary columns and point at them from here.
-     *
-     * The named columns must all exist and be bar-aligned, or `addIndicator`
-     * throws. `key` stays the series identity and the legend reading falls back to
-     * the `close` column.
+     * Color for the live value. Defaults to `color`, then the theme's text — so a
+     * row can tint its reading (an up/down change) without being forced to show a
+     * swatch in that same color.
      */
-    ohlc?: {
-        open: string;
-        high: string;
-        low: string;
-        close: string;
-    };
+    valueColor?: string;
+    /** Vertical slot on the pane (0 = topmost). */
+    row?: number;
     /**
-     * Per-bar colour, for plots whose meaning changes bar to bar — a MACD
-     * histogram is four colours by sign and direction, a conditional study two.
-     * Return `undefined` to fall back to the plot's own colour.
+     * Which inline action buttons to draw, left to right. Each hit-tests as
+     * `${id}::<action>`:
+     *  - `up` / `down` — move this pane one slot (`::up` / `::down`)
+     *  - `hide`        — toggle visibility (`::hide`)
+     *  - `maximize`    — expand this pane to fill the chart (`::maximize`)
+     *  - `close`       — remove the source, and its pane if it empties (`::close`)
      *
-     * Reaches the renderer as `Bar.color`, so every Family-A plot type honours
-     * it: histogram, column, candles, OHLC bars, line, step and area.
-     */
-    colorBy?(ctx: {
-        value: number;
-        index: number;
-        values: IndicatorValues;
-        settings: IndicatorSettings;
-    }): string | undefined;
-    /**
-     * Per-bar colour split three ways, for a candle plot whose wick or border
-     * should not follow its body: a solid wick over a translucent body, a
-     * border in the trend colour. Takes precedence over `colorBy` for the parts
-     * it names; a part it leaves undefined falls back to `colorBy`, then to the
-     * plot's own colour. A value plot (line, histogram, column) reads `body` only.
+     * When only some actions fit, the end of this list stays visible.
+     * Defaults to `['up', 'down', 'hide', 'maximize', 'close']` for pane sources
+     * and `['hide', 'close']` for overlays (pass explicitly to override).
      */
-    colorParts?(ctx: {
-        value: number;
-        index: number;
-        values: IndicatorValues;
-        settings: IndicatorSettings;
-    }): PlotBarColor | undefined;
-}
-/** A horizontal reference level (RSI 70/30, Stochastic 80/20, a zero line). */
-interface IndicatorLevel {
-    price: number;
-    color?: string;
-    title?: string;
-    /** Legacy two-state dash switch. `lineStyle` wins when both are given. */
-    dashed?: boolean;
-    lineWidth?: number;
-    lineStyle?: IndicatorLineStyle;
+    actions?: readonly PaneLegendAction[];
+    /** Rendered as hidden (dimmed, eye hollow). */
+    hidden?: boolean;
+    /** Rendered as maximized (the maximize glyph becomes restore). */
+    maximized?: boolean;
+    /** Text size in media px. Default 11. */
+    font?: number;
+    /** Left inset from the plot edge in media px. Default 8. */
+    left?: number;
+    /** Top inset in media px. Default 6. */
+    top?: number;
+    /** Per-field status-line switches. Patching merges field by field. */
+    statusLine?: LegendStatusLineOptions;
+    /** Host-supplied status-line data (logo, names, market state, day change). */
+    status?: LegendStatusSource;
 }
-/** One end of an indicator drawing: a time on the shared axis, a price on the pane's scale. */
-interface DrawAnchor {
-    time: number;
-    price: number;
+declare class PaneLegend implements IPrimitive {
+    private _opts;
+    private _host;
+    private _values;
+    /** Button geometry from the last draw, in media px, for hit-testing. */
+    private _buttons;
+    /** Right edge of the drawn row, in media px. */
+    private _width;
+    private _plotWidth;
+    private _plotHeight;
+    constructor(opts: PaneLegendOptions);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    autoscaleInfo(): null;
+    /** A single live reading after the params (typically crosshair-driven). */
+    setValue(text: string, color?: string): void;
+    /** One reading per plot, each in its own color. */
+    setValues(values: readonly LegendValue[]): void;
+    setOptions(patch: Partial<PaneLegendOptions>): void;
+    /** Resolve the host's status data for this frame; `{}` when it has none. */
+    private _status;
+    options(): PaneLegendOptions;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    hitTest(x: number, y: number): PrimitiveHit | null;
 }
+
 /**
- * A free-standing shape an indicator paints in its own pane, anchored to time
- * and price rather than to a bar index.
+ * A grid overlay pinned to a corner of the pane rather than to bars.
  *
- * Plots, levels and markers each answer a different question and none of them
- * answers this one: a pivot-to-pivot trendline, a supply zone, an order block,
- * a measured-move projection are all geometry between two arbitrary points, and
- * a column of one value per bar cannot express any of them. Anchors are times,
- * so a shape stays put when history is paged in and every logical index shifts.
+ * Seasonality heatmaps, performance summaries and signal scoreboards are all
+ * the same shape: a small table of coloured cells that stays put while the
+ * chart pans underneath. That makes this a screen-space primitive like the
+ * watermark and the pane legend, not a series: it has no time anchor, takes no
+ * part in autoscale, and survives a zoom untouched.
  */
-type IndicatorDrawing = {
-    kind: 'line';
-    from: DrawAnchor;
-    to: DrawAnchor;
-    color?: string;
-    lineWidth?: number;
-    lineStyle?: IndicatorLineStyle;
-    /** Continue the line past its anchor to the pane edge. */
-    extendLeft?: boolean;
-    extendRight?: boolean;
-} | {
-    kind: 'box';
-    from: DrawAnchor;
-    to: DrawAnchor;
-    /** Border colour. Omit `fillColor` to draw an outline only. */
-    color?: string;
-    fillColor?: string;
-    /** Fill alpha, 0..1. Defaults to 0.12. */
-    opacity?: number;
-    lineWidth?: number;
-    /** Caption drawn on a plate at the centre of the box; `\n` splits lines. */
-    text?: string;
-    textColor?: string;
-    /**
-     * Detail shown on a plate while the pointer rests on the box, and gone
-     * when it leaves; `\n` splits lines. A zone that carries its size, its
-     * age and what formed it cannot print all of that on the box without
-     * hiding the candles under it, so the caption names it and this explains
-     * it. The box becomes hit-testable, and `id` (or the tooltip text) is
-     * what `subscribeClick` reports for it.
-     */
-    tooltip?: string;
-    /** Hit id, for `subscribeClick`. Defaults to the tooltip text. */
-    id?: string;
-} | {
-    kind: 'label';
-    at: DrawAnchor;
-    /** `\n` splits lines. */
+
+type TablePosition = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+interface TableCell {
     text: string;
-    /** Plate fill. */
-    color?: string;
+    /** Cell fill. Transparent when omitted, so the pane shows through. */
+    bgColor?: string;
+    /** Text colour. Derived from `bgColor` for contrast when omitted. */
     textColor?: string;
-    /** Which edge of the plate sits on the anchor. Defaults to 'center'. */
     align?: 'left' | 'center' | 'right';
-    /** Hover detail, as on a box. */
-    tooltip?: string;
-    /** Hit id, for `subscribeClick`. Defaults to the tooltip text. */
-    id?: string;
-} | {
-    kind: 'polyline';
-    points: readonly DrawAnchor[];
-    color?: string;
-    lineWidth?: number;
-    /** Close the path back to the first point (a triangle, a wedge). */
-    closed?: boolean;
-    fillColor?: string;
-    /** Fill alpha, 0..1. Defaults to 0.12. */
-    opacity?: number;
-};
-/** `calc` output: one array per plot key, aligned 1:1 with the input bars. */
-type IndicatorValues = Record<string, readonly (number | null)[]>;
-/** Per-instance scratch owned by the descriptor (Tier-2 data lands here). */
-type IndicatorStore = Record<string, unknown>;
-/**
- * The fourth, optional argument to `calc` (and the sixth to `calcTail`): what
- * the calculation cannot read off the bars themselves.
- *
- * It is optional so that every descriptor written against `calc(bars, settings,
- * store)` keeps its exact signature and its exact behaviour, which is the whole
- * point: a calculation that ignores the context computes what it always did.
- */
-interface IndicatorCalcContext {
+    /** Overrides the table's `fontSize` for this cell, for a heading row. */
+    fontSize?: number;
+    bold?: boolean;
+}
+interface ChartTableOptions {
+    position: TablePosition;
+    /** Gap from the pane edge, media px. */
+    margin: number;
+    /** Column width in media px. A per-column array sizes each one separately. */
+    cellWidth: number | readonly number[];
+    cellHeight: number;
     /**
-     * Where the last bar stands, so a study can act once per bar rather than once
-     * per tick, or refuse to signal off a bar that is still moving.
+     * Type size in media px, or `'auto'` to fit each cell: as large as its row
+     * allows, shrunk until its text also fits its column. A stretched grid with
+     * one long label would otherwise either clip that cell or be sized down as a
+     * whole to suit it.
      */
-    barState: {
-        /** The most recent update appended a bar rather than replacing one. */
-        isNew: boolean;
-        /** The last bar has closed: its interval has elapsed on the chart clock. */
-        isConfirmed: boolean;
-        /** A live feed is driving updates, rather than a one-off history load. */
-        isRealtime: boolean;
-        /** Index of the last bar, `bars.length - 1` (-1 when there are none). */
-        lastIndex: number;
-    };
-    /** The instrument, when the host knows one. See `IndicatorAttachContext`. */
-    symbol?: string;
-    /** The timeframe (`'5m'`, `'1d'`), on the same terms as `symbol`. */
-    interval?: string;
-    /** The chart's IANA zone, the calendar its axis is labelled in. */
-    timezone: string;
-    /** Chart wall clock in UTC seconds, the clock the countdown row reads. */
-    now(): number;
+    fontSize: number | 'auto';
+    /** Grid line colour. Omit to draw no grid. */
+    borderColor?: string;
+    borderWidth: number;
     /**
-     * The instrument's tick size, from the **price pane's** `minMove`.
-     *
-     * The price pane and not the indicator's own, because `calc` runs on the
-     * instrument's bars whichever pane the plot lands in, and a study pane is not
-     * quoted in the instrument's tick: an RSI is a dimensionless 0..100 band, so
-     * its scale carries no tick at all to read.
-     *
-     * `undefined` when the host has not told the chart what it is, which is the
-     * honest answer rather than a guessed 0.01: an indicator sizing a range in
-     * ticks has to tell "one paisa" apart from "nobody said".
+     * Table width as a percentage of the plot, 0 or omitted to size from
+     * `cellWidth` instead. Column proportions are preserved, so a per-column
+     * `cellWidth` array still controls the relative widths, and the percentage
+     * only decides the total.
      */
-    tickSize?: number;
-}
-/** What an alert's `when` predicate is handed, for the bar it is judging. */
-interface IndicatorAlertContext {
-    bars: readonly Bar[];
-    values: IndicatorValues;
-    settings: Readonly<IndicatorSettings>;
-    /** The bar being evaluated. */
-    index: number;
-}
-/**
- * A condition the runtime watches, declared by the descriptor rather than wired
- * up by the host: the indicator is the only thing that knows what a crossover of
- * its own columns means.
- *
- * Evaluated once per bar, for bars that are new since the last evaluation, so
- * adding the indicator to a loaded chart fires nothing for history.
- */
-interface IndicatorAlertSpec {
-    /** Stable within the descriptor, e.g. `'cross-up'`. */
-    id: string;
-    /** Short human label, e.g. `'MACD crossed up'`. */
-    title: string;
+    widthPercent?: number;
+    /** Table height as a percentage of the plot, 0 or omitted to size from `cellHeight`. */
+    heightPercent?: number;
     /**
-     * Longer text for a notification; defaults to `title`. A function is handed
-     * the same context `when` judged, so the message can carry the bar's own
-     * numbers: the price it crossed at, the histogram reading, a JSON body for a
-     * webhook. It runs only for a bar `when` accepted.
+     * Relative row heights, one per row, defaulting to 1. A separator row is the
+     * reason this exists: stretched to fill a pane, an equal split makes a rule
+     * between two sections as tall as the sections themselves.
      */
-    message?: string | ((ctx: IndicatorAlertContext) => string);
-    when(ctx: IndicatorAlertContext): boolean;
+    rowWeights?: readonly number[];
+    /** Backdrop behind the whole grid, drawn before the cells. */
+    background?: string;
+    /** Hit-test id, so a host can route clicks the way it does for other primitives. */
+    id?: string;
+}
+declare const DEFAULT_CHART_TABLE_OPTIONS: ChartTableOptions;
+/** Top-left corner of the grid for a position keyword, in media px. */
+declare function tableOrigin(position: TablePosition, margin: number, w: number, h: number, plotW: number, plotH: number): {
+    x: number;
+    y: number;
+};
+declare class ChartTable implements IPrimitive {
+    private _rows;
+    private _opts;
+    private _host;
+    /** Last drawn rect in media px, for hit-testing without recomputing layout. */
+    private _rect;
+    constructor(options?: Partial<ChartTableOptions>);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    options(): Readonly<ChartTableOptions>;
+    setOptions(patch: Partial<ChartTableOptions>): void;
+    /** Replace the grid. Rows may be ragged; each is drawn to its own length. */
+    setRows(rows: readonly (readonly TableCell[])[]): void;
+    rows(): readonly (readonly TableCell[])[];
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    hitTest(x: number, y: number): PrimitiveHit | null;
 }
+
 /**
- * Thrown by a `calc` (or any hook) to say its inputs cannot produce a study,
- * the way a script language's runtime error does: a period at or below zero, a
- * fast length above the slow one, a benchmark the provider cannot serve.
+ * Vertical gradient across the band, graded between two prices rather than
+ * two pixel rows.
  *
- * Any error out of a recompute is caught by the runtime and published on the
- * instance's data status as `{ state: 'error' }`, so the chart keeps drawing
- * every other indicator and a host can show the reason beside this one. This
- * class exists so a descriptor can throw a **named** condition and a host can
- * tell a bad input, which the user can fix, from a bug, which they cannot.
+ * The stops are anchored in PRICE, not in pixels, because that is what the
+ * shading is claiming: a band graded from its 70 level down to its 30 means
+ * those levels, and a viewport-relative gradient would slide off them the
+ * moment the pane is panned or the scale re-fits.
  */
-declare class IndicatorInputError extends Error {
-    constructor(message: string);
+interface FillGradient {
+    /** Price the top stop sits at. Omitted: the band's own highest value. */
+    topValue?: number;
+    /** Price the bottom stop sits at. Omitted: the band's own lowest value. */
+    bottomValue?: number;
+    topColor: string;
+    bottomColor: string;
 }
-/**
- * Bars of another instrument or interval, supplied by the host on request.
- *
- * The engine is handed one symbol's bars and owns no transport, so a study
- * that compares against a benchmark, or a Tier-2 provider that needs a second
- * series, asks the host through this and the host answers from wherever it
- * keeps history. `from` and `to` are UTC seconds; `signal` is aborted when the
- * instance is removed or its settings change, so a provider can drop the
- * request rather than answer into the void.
- */
-interface IndicatorBarsRequest {
-    symbol: string;
-    exchange?: string;
-    interval: string;
-    from: number;
-    to: number;
-    signal?: AbortSignal;
+interface IndicatorFillOptions {
+    /** Fill colour where the first series is above the second. */
+    colorUp: string;
+    /** Fill colour where the second is above the first. */
+    colorDown: string;
+    /** 0..1. Defaults to 0.12 — a band must not drown the candles it sits behind. */
+    opacity?: number;
+    /**
+     * Set to grade the band instead of flat-filling it, in place of
+     * `colorUp`/`colorDown`. A point carrying its own `color` still overrides it.
+     * Unset leaves the two-colour fill exactly as it was.
+     */
+    gradient?: FillGradient;
 }
-type IndicatorBarsProvider = (request: IndicatorBarsRequest) => Promise<readonly Bar[]>;
-/** Payload of the `'indicator:alert'` event on the chart's own bus. */
-interface IndicatorAlertPayload {
-    /** Descriptor id, e.g. `'macd'`. */
-    indicatorId: string;
-    /** Instance id, so a host can tell three EMAs apart. */
-    instanceId: string;
-    alertId: string;
-    title: string;
-    message: string;
-    /** The bar that triggered it: UTC seconds, and its index in `bars`. */
-    time: number;
+/** One bar's pair of values; `null` where either plot has no value yet. */
+interface FillPoint {
+    /** Logical index on the shared time axis (fractional is fine). */
     index: number;
+    a: number | null;
+    b: number | null;
+    /**
+     * Paints this bar onward in one colour, for a band shaded by something other
+     * than which line leads: trend state, a regime, a third series. The run is
+     * split at the bar where the colour changes, so it is per-bar and not merely
+     * per-crossing. Most specific wins: this, then the gradient, then up/down.
+     */
+    color?: string;
 }
-/** Optional instrument identity supplied by the host. */
-interface ChartDataContext {
-    symbol?: string;
-    exchange?: string;
-    interval?: string;
+declare class IndicatorFill implements IPrimitive {
+    private _points;
+    private _opts;
+    private _host;
+    private _visible;
+    constructor(options: IndicatorFillOptions);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    /** Behind the series, so the lines and candles stay crisp on top of it. */
+    zOrder(): ZOrder;
+    /** The plots it spans already drive the scale; the fill must not widen it. */
+    autoscaleInfo(): null;
+    setPoints(points: readonly FillPoint[]): void;
+    setOptions(patch: Partial<IndicatorFillOptions>): void;
+    setVisible(on: boolean): void;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
 }
-/** Source identity changed, or the available source-bar range changed. */
-type IndicatorDataChange = 'context' | 'range';
-/** Observable state of an indicator's external data lifecycle. */
-type IndicatorDataStatus = {
-    state: 'loading' | 'ready' | 'empty' | 'unsupported';
-} | {
-    state: 'error';
-    error: unknown;
-};
-/** What an indicator's `attach` lifecycle can reach. */
-interface IndicatorAttachContext {
-    /** Optional host identity, independent of the indicator's own settings. */
+
+/**
+ * Indicator runtime (ARCHITECTURE.md §8). Turns an `IndicatorDescriptor` into
+ * live chart objects: one series per plot, optional reference levels, an
+ * optional fixed pane range — and recomputes them when the source data or the
+ * settings change.
+ *
+ * It adds **no rendering code**. Every plot names a registered chart type, so
+ * indicators draw through the same Family-A renderers as any other series.
+ */
+
+/** The slice of the chart the runtime needs. Keeps this module testable alone. */
+interface IndicatorHost {
+    /** Forget a disposed instance, including disposal through its public handle. */
+    indicatorRemoved?(instanceId: string): void;
+    /** Optional instrument identity and source-range notifications. */
     dataContext?(): Readonly<ChartDataContext> | undefined;
-    /** Read bars and identity again when the host publishes a change. */
     subscribeDataChanges?(listener: (change: IndicatorDataChange) => void): () => void;
-    /** Publish status and an explicit retry action for this instance. */
-    setDataStatus?(status: IndicatorDataStatus): void;
-    setDataRetry?(retry: (() => void) | null): void;
-    /** Instance lifetime. Aborted on removal, preserved across style changes. */
-    signal?: AbortSignal;
-    /** Current settings (live — read at call time, not captured). */
-    settings(): Readonly<IndicatorSettings>;
-    /** The chart's current source bars. */
-    bars(): readonly Bar[];
-    /** Re-run `calc` and repaint — call when external data arrives. */
-    requestRecompute(): void;
-    /** Scratch this instance owns; the same object `calc` receives. */
-    store: IndicatorStore;
+    /** Add the pane-legend row (name + inline up/down/hide/maximize/close). */
+    addIndicatorLegend(opts: {
+        id: string;
+        title: string;
+        params: string;
+        color?: string;
+        row: number;
+        paneIndex: number;
+    }): PaneLegend;
+    removeIndicatorLegend(legend: PaneLegend): void;
+    /** How many legends already sit on this pane, so rows stack. */
+    legendRowsOn(paneIndex: number): number;
+    addIndicatorSeries(type: string, paneIndex: number, style: Record<string, unknown> | undefined, priceScaleId: string | undefined, 
+    /** Axis/crosshair formatting for the scale this plot maps to. */
+    priceFormat?: PriceFormat): SeriesApi;
     /**
-     * The instrument the chart is showing, when the host knows it.
+     * Add a reference level. One options object rather than seven positional
+     * arguments: the list grew a width and a dash style in 1.7.1, and a call site
+     * of seven bare values is where the next one gets passed in the wrong slot.
+     */
+    addIndicatorLevel(level: {
+        price: number;
+        color: string;
+        /** Kept for hosts predating `lineStyle`; always `lineStyle === 'dashed'`. */
+        dashed: boolean;
+        lineWidth: number;
+        lineStyle: IndicatorLineStyle;
+        label: string;
+        id: string;
+    }, paneIndex: number): PriceLine;
+    removeIndicatorLevel(line: PriceLine): void;
+    /** Attach a band drawn behind the plots (an Ichimoku cloud). */
+    addIndicatorFill(fill: IndicatorFill, paneIndex: number): void;
+    removeIndicatorFill(fill: IndicatorFill): void;
+    /**
+     * Detach a signal-marker layer. There is no matching `add`: the layer comes
+     * from `series.createMarkers()` on a plot's own series, so it already lands in
+     * the right pane. Removing a series does not remove its primitives, hence this.
+     */
+    removeIndicatorMarkers(markers: SeriesMarkers): void;
+    /** Attach a corner-pinned summary grid to a pane, and detach it again. */
+    addIndicatorTable(paneIndex: number): ChartTable;
+    removeIndicatorTable(table: ChartTable): void;
+    /**
+     * Attach an arbitrary primitive to a pane, and detach it again. Carries both
+     * the descriptor's drawing layer and whatever a Tier-2 `attach` lifecycle
+     * wants to paint, so those two do not need a host method each.
      *
-     * Hosts can supply this through `IndicatorHost` or Chart's explicit data
-     * context. Without a configured identity it stays undefined. External
-     * studies read `dataContext` to include the exchange as well.
+     * Optional, like `timezone`, so a host predating it still satisfies this
+     * interface: an indicator that draws simply draws nothing there.
+     */
+    addIndicatorPrimitive?(primitive: IPrimitive, paneIndex: number): void;
+    removeIndicatorPrimitive?(primitive: IPrimitive): void;
+    /**
+     * Recompute whatever the host has marked stale, before a caller reads a value.
+     *
+     * Optional, like `timezone`, so a host predating it still satisfies this
+     * interface: one that recomputes eagerly has nothing to flush.
+     */
+    flushIndicators?(): void;
+    /** Bars of the primary price series — the calculation input. */
+    sourceBars(): readonly Bar[];
+    /** Selected candle after native or linked hover; absent means latest. */
+    legendIndex?(): number | undefined;
+    /** Index of a fresh pane for an indicator that wants its own. */
+    nextPaneIndex(): number;
+    /**
+     * The chart's configured IANA zone. Optional so a host predating the option
+     * still satisfies this interface; absent means the shipped default.
+     *
+     * A descriptor is handed bars and settings and never the chart, so this is
+     * how the calendar an anchor resets on (a VWAP session, a seasonality month)
+     * reaches the calculation. See `IndicatorInstance._descriptorSettings`.
+     */
+    timezone?(): string;
+    /**
+     * The instrument and timeframe on screen, when the host knows them. The
+     * host can supply an explicit `dataContext` instead. Without either hook,
+     * a descriptor sees `undefined` rather than a guessed identity.
      */
     symbol?(): string | undefined;
-    /** The chart's timeframe (`'5m'`, `'1d'`), on the same terms as `symbol`. */
     interval?(): string | undefined;
-    /** The chart's IANA zone, the one its axis is labelled in. */
-    timezone?(): string;
-    /** Chart wall clock in UTC seconds, the same clock the countdown row uses. */
+    /** Chart wall clock in UTC seconds. Absent means the system clock. */
     now?(): number;
     /**
-     * Ask the host for another instrument's (or interval's) bars. Always present
-     * under `chart.addIndicator`; it rejects when the host has registered no
-     * provider (`chart.setBarsProvider`), so a study can treat the rejection as
-     * "unsupported here" and say so through `setDataStatus`.
+     * Publish an indicator's per-bar colours onto the **primary price series**,
+     * or withdraw them with `null`. `owner` is the instance id: a host holds one
+     * overlay at a time and only lets its current owner withdraw it, so a second
+     * publisher taking over does not get cleared by the first one's teardown.
+     *
+     * Optional, like `timezone`: a host that does not implement it simply gives a
+     * `barColors` descriptor nowhere to publish, and the indicator's own plots are
+     * unaffected.
+     */
+    setBarColors?(colors: readonly (string | null)[] | null, owner: string): void;
+    /** Emit on the chart's event bus (indicator alerts, and `attach`'s own events). */
+    emit?(event: string, payload: unknown): void;
+    /**
+     * Bars of another instrument or interval, from wherever the host keeps its
+     * history. Optional: without it the attach context's `requestBars` rejects,
+     * which a study reads as "not available on this chart".
      */
     requestBars?(request: IndicatorBarsRequest): Promise<readonly Bar[]>;
-    /** The pane this instance drew into. Moves when panes are reordered. */
-    paneIndex?(): number;
-    /** Attach a primitive to this indicator's pane, and detach it again. */
-    addPrimitive?(p: IPrimitive): void;
-    removePrimitive?(p: IPrimitive): void;
     /**
-     * Emit on the chart's own event bus, the one `chart.on(name, cb)` listens to.
+     * Tick size of the named pane's price scale, or undefined when none is set.
+     * Optional so a host predating it still satisfies this interface.
      *
-     * The declarative `alerts` slot covers a condition read off the bars; this is
-     * the imperative half, for an indicator whose signal arrives from outside the
-     * calculation entirely (a subscription its `attach` opened).
+     * Per pane, and the panes genuinely differ: a pane that does not quote the
+     * instrument has no tick to report. Pane 0 is the price pane, so it is the
+     * one to ask for the instrument's own step.
      */
-    emit?(event: string, payload: unknown): void;
-}
-/**
- * What `levels` is handed. It carries `bars` and `values` **and** spreads the
- * settings keys onto itself, so the built-ins written against the original
- * `levels(settings)` signature keep working unchanged: they read
- * `ctx.overbought` (or pass `ctx` to a `num(s, key, default)` helper) and find
- * exactly what they found before. A widened parameter is the only way a level
- * can be data-derived (yesterday's high, the session VWAP band), and that is a
- * whole class of level that could not be expressed at all before.
- *
- * The three data members are optional for the same backward-compatibility
- * reason, not because the runtime ever omits them: it always passes all three,
- * but a caller holding only a settings bag must still be able to invoke
- * `levels` directly. A descriptor that needs the data should default them
- * (`ctx.bars ?? []`).
- *
- * `settings`, `bars` and `values` are therefore reserved keys, the way
- * `timezone` already is in the settings a `calc` receives: an input declared
- * under one of those names is shadowed here.
- */
-type IndicatorLevelContext = IndicatorSettings & {
-    settings?: Readonly<IndicatorSettings>;
-    bars?: readonly Bar[];
-    values?: IndicatorValues;
-};
-interface IndicatorDescriptor {
-    /** Registry key, e.g. `'macd'`. */
-    id: string;
-    /** Display name, e.g. `'MACD'`. */
-    name: string;
-    /** Grouping for a picker UI ('Trend', 'Momentum', 'Volume', 'Volatility'). */
-    category?: string;
-    /** `'onchart'` overlays the price pane; `'pane'` gets its own pane. */
-    placement: 'onchart' | 'pane';
-    inputs: readonly IndicatorInput[];
-    plots: readonly IndicatorPlot[];
-    /**
-     * Shaded bands between pairs of plots — the Ichimoku cloud, a Bollinger
-     * channel. A pair of lines is not the same picture as a filled region: the
-     * fill is what makes "price is above the cloud" readable at a glance, and
-     * which side leads is itself the signal, hence the two colours.
-     */
-    fills?: readonly IndicatorFillSpec[];
-    /**
-     * Full recompute over every bar. Must return arrays the same length as
-     * `bars` (use `null` for warmup gaps — the line renderer breaks across them
-     * and autoscale skips them).
-     *
-     * Tier-1 indicators are pure functions of `(bars, settings)` and ignore
-     * `store`. Tier-2 indicators — the ones with their own data — read the
-     * external series their `attach` lifecycle put in `store`.
-     */
-    calc(bars: readonly Bar[], settings: Readonly<IndicatorSettings>, store: IndicatorStore, ctx?: IndicatorCalcContext): IndicatorValues;
-    /**
-     * Optional per-instance lifecycle, for indicators whose data is not derived
-     * from the chart's bars (open interest, CVD, an external feed). Called once
-     * when the instance is created; return a teardown function.
-     *
-     * Fetch into `ctx.store`, then call `ctx.requestRecompute()` — `calc` runs
-     * again and reads what you stored.
-     */
-    attach?(ctx: IndicatorAttachContext): (() => void) | void;
-    /**
-     * Optional incremental path, called instead of `calc` when only the tail
-     * changed (a live tick). Return values for indices `[fromIndex, bars.length)`
-     * — the runtime splices them onto the previous result — or `null` to fall
-     * back to a full `calc`.
-     *
-     * Without it every tick costs a full recompute. That is a few hundred
-     * microseconds for one indicator over 50k bars, but it is O(n) per tick per
-     * indicator, so implement this for anything meant to run in a busy live pane.
-     */
-    calcTail?(bars: readonly Bar[], settings: Readonly<IndicatorSettings>, fromIndex: number, previous: IndicatorValues, store: IndicatorStore, ctx?: IndicatorCalcContext): IndicatorValues | null;
-    /**
-     * Optional bar-anchored signal markers — a named "Buy"/"Sell" plate, an arrow
-     * at a crossover. Runs after every `calc`, so it reads the values it just
-     * produced rather than recomputing anything.
-     *
-     * A plot cannot express this: a plot is a column of prices drawn as a line or
-     * histogram, whereas a signal is a discrete event with a label. Returning `[]`
-     * (when a `showLabels`-style input is off, say) clears the layer.
-     */
-    markers?(ctx: {
-        bars: readonly Bar[];
-        values: IndicatorValues;
-        settings: Readonly<IndicatorSettings>;
-    }): readonly SeriesMarker[];
-    /**
-     * Optional summary grid pinned to a corner of the pane.
-     *
-     * Some studies are not a value per bar at all: a seasonality heatmap is a
-     * matrix of monthly returns, a scoreboard is a handful of statistics. Those
-     * have no place in `calc`, whose contract is one column per plot aligned to
-     * the bars, so they come back through here instead. Runs after every `calc`.
-     *
-     * Return `null` (or a zero-row grid) to draw nothing, which is how a
-     * `showTable`-style input should switch it off.
-     */
-    table?(ctx: {
-        bars: readonly Bar[];
-        values: IndicatorValues;
-        settings: Readonly<IndicatorSettings>;
-    }): {
-        rows: readonly (readonly TableCell[])[];
-        options?: Partial<ChartTableOptions>;
-    } | null;
-    /**
-     * Optional free-standing shapes drawn in the indicator's pane: trendlines
-     * between pivots, supply and demand boxes, projection labels. Runs after
-     * every `calc`, like `markers` and `table`, and the returned list replaces the
-     * previous one wholesale, so returning `[]` clears the layer.
-     */
-    draws?(ctx: {
-        bars: readonly Bar[];
-        values: IndicatorValues;
-        settings: Readonly<IndicatorSettings>;
-    }): readonly IndicatorDrawing[];
-    /**
-     * Optional per-bar shading behind everything else in the indicator's pane: a
-     * full-height column per bar, `null` where nothing should be shaded.
-     *
-     * A regime study answers "which state is the market in right now", and that is
-     * a property of the whole bar, not a price. Drawn as a plot it would need a
-     * value to sit at and would fight the pane's autoscale; as a column behind the
-     * candles it reads at a glance and costs the scale nothing.
-     *
-     * Runs after every `calc`. Return `[]` to clear the layer.
-     */
-    background?(ctx: {
-        bars: readonly Bar[];
-        values: IndicatorValues;
-        settings: Readonly<IndicatorSettings>;
-    }): readonly (string | null)[];
+    tickSize?(paneIndex: number): number | undefined;
     /**
-     * Optional recolouring of the **main price candles**, one entry per bar,
-     * `null` to leave that bar with its own colour.
+     * Write a number the way the price axis of that pane writes it.
      *
-     * Distinct from a plot's `colorBy`, which paints the indicator's own series: a
-     * trend filter, a volatility regime or a higher-timeframe bias is a statement
-     * about the price bars themselves, and drawing it as a second series beside
-     * them says something weaker.
+     * The legend sits inches from the axis and names the same quantity, so the
+     * two disagreeing is the reading a user has to reconcile themselves. Deriving
+     * the format here from a tick got that wrong twice over: a study pane carries
+     * no tick at all, so a percentage read `0.618` beside an axis saying `0.62`,
+     * and a price pane's tick alone misses the precision floor and the host's own
+     * formatter, so a volume study read seven digits where its axis said `1.20M`.
      *
-     * Only one indicator's colours can be on the candles at a time; the most
-     * recent publisher wins, and publishers run in `addIndicator` order, so the
-     * winner is the same one from frame to frame. Removing it, or hiding it,
-     * restores the bars' own colours.
-     */
-    barColors?(ctx: {
-        bars: readonly Bar[];
-        values: IndicatorValues;
-        settings: Readonly<IndicatorSettings>;
-    }): readonly (string | null)[];
-    /**
-     * Optional conditions the runtime watches on the descriptor's behalf, emitted
-     * as `'indicator:alert'` on the chart's event bus with an
-     * {@link IndicatorAlertPayload}. See {@link IndicatorAlertSpec}.
-     */
-    alerts?: readonly IndicatorAlertSpec[];
-    /**
-     * Optional horizontal reference levels drawn in the indicator's pane.
-     * Recomputed after every `calc`, so a level derived from the data (the
-     * previous day's high) tracks it. See `IndicatorLevelContext` for why the
-     * argument still reads as a settings bag.
-     */
-    levels?(ctx: IndicatorLevelContext): readonly IndicatorLevel[];
-    /**
-     * Optional fixed price range for the indicator's own pane (RSI 0..100).
-     * Applied only when the indicator creates its pane — two indicators sharing a
-     * pane would otherwise fight over it.
+     * Asking the scale removes the second opinion. Optional so a host driving
+     * this module alone still works, falling back to the magnitude ladder.
      */
-    range?(settings: Readonly<IndicatorSettings>): {
+    formatPrice?(paneIndex: number, value: number): string | undefined;
+    /** Pin a pane's price scale to a fixed range, or release it with `null`. */
+    setPaneRange(paneIndex: number, range: {
         min: number;
         max: number;
-    } | null;
+    } | null): void;
+}
+/** Public handle returned by `chart.addIndicator(...)`. */
+interface IndicatorApi {
+    /** External data state, or null for a study without a managed lifecycle. */
+    dataStatus(): Readonly<IndicatorDataStatus> | null;
+    /** Observe changes; immediately receives the current managed status, if any. */
+    subscribeDataStatus(listener: (status: Readonly<IndicatorDataStatus>) => void): () => void;
+    /** Retry external history when the descriptor supplies a retry action. */
+    retryData(): void;
+    /** Unique instance id (several instances of one indicator can coexist). */
+    readonly id: string;
+    /** The descriptor id, e.g. `'macd'`. */
+    readonly indicatorId: string;
+    /** Display name. */
+    readonly name: string;
+    /** Pane the indicator drew into. */
+    readonly paneIndex: number;
+    /** Current settings (a copy). */
+    settings(): IndicatorSettings;
+    /** Merge a settings patch, recompute, and restyle. */
+    setSettings(patch: Readonly<IndicatorSettings>): void;
+    /** The series backing one plot key, for direct styling. */
+    series(plotKey: string): SeriesApi | undefined;
+    /** Latest computed values (a reference — do not mutate). */
+    values(): IndicatorValues;
+    /** Whether the plots are drawn (the legend's eye toggle). */
+    visible(): boolean;
+    /** Show or hide every plot without removing the instance. */
+    setVisible(on: boolean): void;
+    /** This indicator's legend row, or null if it has none. */
+    legend(): PaneLegend | null;
+    /** Refresh the legend readings for a bar index; omit for the latest bar. */
+    updateLegendValues(index?: number): void;
+    /** Remove every series, level, and legend row this indicator created. */
+    remove(): void;
 }
-/** Register an indicator descriptor. Later registrations of the same id win. */
-declare function registerIndicator(descriptor: IndicatorDescriptor): void;
-declare function getIndicator(id: string): IndicatorDescriptor;
-declare function hasIndicator(id: string): boolean;
-declare function registeredIndicators(): IndicatorDescriptor[];
-/** The descriptor's declared defaults as a settings object. */
-declare function indicatorDefaults(descriptor: IndicatorDescriptor): IndicatorSettings;
-/** Read one bar's value for a price source. */
-declare function sourceValue(bar: Bar, source: IndicatorSource): number;
-/** Read a whole bar array for a price source. */
-declare function sourceValues(bars: readonly Bar[], source: IndicatorSource): number[];
-
-/**
- * Horizontal price line primitive (ARCHITECTURE.md §8). The reusable base for
- * order/SL/TP/alert/indicator-level lines: a line across the plot plus a fixed
- * right-axis price tag and an optional broker-style segmented pill group on the
- * line — [badge][qty][label][✕] — with hover / dragging states (the chart
- * passes `hoverId`/`dragId` on the render context) and a drag ghost at the
- * pre-drag price via `setDragGhost`. Interaction semantics are unchanged from
- * the classic tag: the ✕ hit-tests as `${id}::close`, everything else drags.
- */
 
-interface PriceLineOptions {
+/** A primary-source mutation, emitted after indicator invalidation. */
+interface ChartDataUpdate {
+    kind: 'update' | 'reset' | 'prepend';
+    time?: number;
+}
+/** Minimum headless chart surface needed to evaluate alerts. */
+interface AlertChartHost {
+    primaryBars(): readonly Bar[];
+    getDataContext(): Readonly<ChartDataContext> | undefined;
+    on(event: string, callback: (payload: unknown) => void): () => void;
+    emit(event: string, payload: unknown): void;
+    /** Flushes computed study values. Only required by indicator-source alerts. */
+    indicators?(): readonly (Pick<IndicatorApi, 'id' | 'paneIndex' | 'series' | 'values'> & Partial<Pick<IndicatorApi, 'indicatorId'>>)[];
+    addPrimitive?(primitive: IPrimitive, paneIndex?: number): void;
+    removePrimitive?(primitive: IPrimitive): void;
+    alertState?(): AlertsDocument | undefined;
+    setAlertState?(document: AlertsDocument | undefined): void;
+}
+type AlertCondition = 'crossing' | 'crossingUp' | 'crossingDown' | 'greaterThan' | 'lessThan' | 'enteringRange' | 'leavingRange' | 'matches';
+type AlertPolicy = 'onBarClose' | 'onTouch';
+type AlertRepeat = 'once' | 'everyTime';
+type AlertState = 'armed' | 'triggered' | 'expired' | 'disabled';
+/** Prices are in primary-series units. Range conditions require upperPrice. */
+interface PriceAlertSource {
+    kind: 'price';
     price: number;
-    color: string;
-    /** Line thickness in media px. Default 1. */
-    lineWidth?: number;
-    /** Legacy two-state dash switch, equivalent to `lineStyle: 'dashed'`. */
-    dashed?: boolean;
-    /**
-     * Dash style, the three-way form of `dashed`. Set, it wins over the boolean;
-     * unset, the boolean still decides, so a line built before this existed draws
-     * exactly as it did.
-     */
-    lineStyle?: CanvasLineStyle;
-    /** Right-axis tag text. Defaults to the formatted price. */
-    label?: string;
-    /** Solid colored badge segment at the start of the pill group (e.g. 'BUY', 'TP', 'SL'). */
-    badge?: string;
-    /** Quantity segment rendered as a neutral box after the badge. */
-    qty?: string | number;
-    /** Info text segment (order type, price, P&L ...) — the classic left tag text. */
-    leftLabel?: string;
-    /**
-     * Fraction of the plot width the line spans, measured from the right (price)
-     * axis. 1 = full width (default); 0.3 = only the rightmost 30%, like a
-     * partial-width order line. The right-axis tag is always drawn.
-     */
-    extentFromRight?: number;
-    /** Draw a cancel (✕) segment at the end of the pill group; hit-tests as `${id}::close`. */
-    closeButton?: boolean;
-    /** Stable id returned by hit-test (for click/drag routing). */
+    upperPrice?: number;
+}
+/** A threshold in plot units, anchored to one specific study instance. */
+interface IndicatorAlertSource {
+    kind: 'indicator';
+    instanceId: string;
+    plotKey: string;
+    value: number;
+    upperValue?: number;
+}
+interface BarConditionAlertSource {
+    kind: 'barCondition';
     id: string;
-    /** Cursor hint when hovered (e.g. 'ns-resize' for draggable lines). */
-    cursor?: string;
 }
-declare class PriceLine implements IPrimitive {
-    private _opts;
-    private _host;
-    private _ghostPrice;
-    /** Pill-group geometry from the last draw (media px) for hit-testing. */
-    private _group;
-    constructor(opts: PriceLineOptions);
-    attached(host: PrimitiveHost): void;
-    detached(): void;
-    get price(): number;
-    /** Move the line; schedules a repaint via the host. */
-    setPrice(price: number): void;
-    /** Update the info segment text (e.g. live position P&L); repaints. */
-    setLeftLabel(text: string): void;
-    /**
-     * Restyle in place; repaints. `id` is the hit-test handle the chart routes
-     * clicks and drags through, so it is not patchable — swapping it under a
-     * live drag would strand the gesture.
-     *
-     * A last-price line is the case this exists for: it has to follow the tick
-     * direction, and only `setPrice` was updatable, so the colour was stuck at
-     * whatever it was constructed with.
-     */
-    setOptions(patch: Partial<Omit<PriceLineOptions, 'id'>>): void;
-    /**
-     * Show a dimmed reference line at the pre-drag price while the user drags
-     * (pass the original price on drag start, null on drag end to clear).
-     */
-    setDragGhost(price: number | null): void;
-    options(): Readonly<PriceLineOptions>;
-    zOrder(): ZOrder;
-    autoscaleInfo(): {
-        min: number;
-        max: number;
-    } | null;
-    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
-    hitTest(x: number, y: number, rc: PrimitiveRenderContext): PrimitiveHit | null;
+interface DrawingAlertSource {
+    kind: 'drawing';
+    drawingId: string;
+    level?: string;
+    /** Required for a drawing on a study pane, so prices are not compared to different units. */
+    input?: {
+        instanceId: string;
+        plotKey: string;
+    };
+}
+type AlertSource = PriceAlertSource | IndicatorAlertSource | BarConditionAlertSource | DrawingAlertSource;
+/** Missing values, an absent anchor or a paused/context-mismatched chart are unavailable. */
+interface AlertAvailability {
+    available: boolean;
+    reason?: string;
+    paneIndex?: number;
+}
+interface AlertDrawingValue {
+    price: number;
+    upperPrice?: number;
+    paneIndex: number;
+}
+interface AlertDrawingLevel {
+    id: string;
+    title: string;
+}
+interface AlertDrawingInfo extends AlertAvailability {
+    levels: readonly AlertDrawingLevel[];
+}
+/** Implemented by the optional drawing tier; the alert engine never imports it. */
+interface AlertDrawingProvider {
+    get(id: string): unknown;
+    valueAt(id: string, time: number, level?: string): AlertDrawingValue | undefined;
+    alertInfo(id: string): AlertDrawingInfo;
+}
+interface BarConditionContext {
+    /** Only the prefix through index is exposed, including for confirmed-bar checks. */
+    bars: readonly Bar[];
+    index: number;
+}
+interface BarCondition {
+    id: string;
+    title: string;
+    /** Runs at the alert's chosen policy, never for loaded history. */
+    when(context: BarConditionContext): boolean;
+}
+/** An alert belongs to the instrument and interval present when it was armed. */
+interface AlertScope {
+    symbol?: string;
+    exchange?: string;
+    interval?: string;
+}
+interface AlertInput {
+    id?: string;
+    source: AlertSource;
+    condition?: AlertCondition;
+    /** Defaults to onBarClose. An intrabar touch may disappear from final history. */
+    policy?: AlertPolicy;
+    repeat?: AlertRepeat;
+    state?: 'armed' | 'disabled';
+    title?: string;
+    message?: string;
+    cooldownSeconds?: number;
+    /** UTC seconds. At this instant the alert expires before it can trigger. */
+    expiresAt?: number;
+    /** Opaque host routing data. The controller never interprets or delivers it. */
+    payload?: unknown;
+}
+type AlertPatch = Partial<Omit<AlertInput, 'id'>>;
+/** Lifecycle record. Snapshots detach mutable configuration, retaining opaque payloads. */
+interface Alert extends Omit<AlertInput, 'id' | 'condition' | 'policy' | 'repeat' | 'state' | 'title' | 'cooldownSeconds'> {
+    id: string;
+    condition: AlertCondition;
+    policy: AlertPolicy;
+    repeat: AlertRepeat;
+    state: AlertState;
+    title: string;
+    cooldownSeconds: number;
+    scope: AlertScope;
+    lastTriggeredAt?: number;
+    lastTriggeredTime?: number;
+    /** Newest confirmed bar already judged, including a nonmatch. */
+    lastClosedTime?: number;
+    /** Newest intrabar match consumed, including one suppressed by cooldown. */
+    lastTouchedTime?: number;
+}
+/** Portable trader records. JSON persistence rejects unsupported host payloads. */
+interface AlertsDocument {
+    version: 1;
+    alerts: Alert[];
+}
+/** Shared delivery fields for trader and indicator-authored alerts. */
+interface AlertEventPayload {
+    alertId: string;
+    title: string;
+    message?: string;
+    /** Source bar UTC seconds and source index, not delivery wall-clock time. */
+    time: number;
+    index: number;
+}
+interface AlertTriggeredPayload extends AlertEventPayload {
+    price: number;
+    alert: Alert;
+}
+interface AlertControllerOptions {
+    /** Delivery and expiry clock in UTC seconds. Defaults to Date.now() / 1000. */
+    now?: () => number;
+    drawings?: AlertDrawingProvider;
+    /** PriceLine visuals are enabled on chart hosts; disable for a model-only consumer. */
+    visuals?: boolean;
 }
 
 /**
- * Pane legend (ARCHITECTURE.md §8) — the row at the top-left
- * of a pane: a color swatch, the source's name, its parameters, the value under
- * the crosshair, and inline action buttons on the right.
- *
- * Drawn on the canvas rather than in the DOM, like `BuySellButtons` and
- * `DomLadder`, so it composites into screenshots and costs no DOM per pane.
- * Buttons hit-test as `${id}::close`, `${id}::hide`, and `${id}::settings`, so
- * the host routes them through the same `subscribeClick` path as order pills.
+ * Indicator registry (ARCHITECTURE.md §6A, §8). The sibling of the chart-type
+ * registry: that one answers *"how do I paint an array of bars"*, this one
+ * answers *"what do I compute, what does it plot, and what can a user tune"*.
  *
- * Rows stack: several legends on one pane offset each other vertically, which
- * the host does by giving each a `row` index.
+ * A descriptor is data, not code-in-the-core — the chart never switches on an
+ * indicator id. Each `plot` names a registered **chart type**, so indicators
+ * ride the existing Family-A renderers and add no drawing code at all.
  *
- * This row is also the chart's status line, so `statusLine` carries the
- * per-field switches a settings dialog expects (logo, title, market status,
- * chart values, bar change, volume, last day change, background). Every switch
- * defaults to the behaviour that predates it, so a caller that passes none sees
- * the row it always saw. Fields the primitive cannot compute (a logo bitmap,
- * whether the market is open, the change since yesterday's close) arrive
- * through `status`; with no source they draw nothing at all rather than a
- * placeholder.
+ * The built-in descriptors live in the lazy `openalgo-charts/indicators` tier;
+ * only the registry and the runtime ship in the base bundle, so an app that
+ * plots its own maths pays nothing for the catalog.
  */
 
-type PaneLegendAction = 'hide' | 'settings' | 'up' | 'down' | 'maximize' | 'close';
+/** Which price a calculation reads from each bar. */
+type IndicatorSource = 'open' | 'high' | 'low' | 'close' | 'hl2' | 'hlc3' | 'ohlc4' | 'volume';
 /**
- * One reading on a legend row. Multi-plot sources show one per plot, each in
- * that plot's own color (an MA ribbon's four averages, MACD's three lines) —
- * a single string in a single color cannot say which number is which.
+ * One tunable input. `type` is what a settings UI renders; the core only reads
+ * `key`/`default`.
+ *
+ * `tooltip` is help text for the row. A label has to stay short enough to fit a
+ * dense panel, which leaves nowhere to say what a parameter actually does, and a
+ * ported study whose every input carried an explanation arrives here with that
+ * explanation dropped. A settings UI renders it as a hover affordance beside the
+ * label; the core ignores it.
  */
-interface LegendValue {
-    /** Dimmed prefix, e.g. `O` / `H` / `Vol`. */
-    label?: string;
-    text: string;
-    /** Defaults to the row's `valueColor`, then `color`, then the theme text. */
-    color?: string;
-    /**
-     * Which status-line switch owns this reading. Untagged readings are the
-     * source's own last value, governed by `statusLine.lastValueLabel`.
-     */
-    field?: LegendField;
+type IndicatorInput = {
+    key: string;
+    type: 'number';
+    label: string;
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    group?: string;
+    tooltip?: string;
+} | {
+    key: string;
+    type: 'boolean';
+    label: string;
+    default: boolean;
+    group?: string;
+    tooltip?: string;
+} | {
+    key: string;
+    type: 'color';
+    label: string;
+    default: string;
+    group?: string;
+    tooltip?: string;
+} | {
+    key: string;
+    type: 'text';
+    label: string;
+    default: string;
+    group?: string;
+    tooltip?: string;
+} | {
+    key: string;
+    type: 'select';
+    label: string;
+    default: string;
+    options: readonly {
+        label: string;
+        value: string;
+    }[];
+    group?: string;
+    tooltip?: string;
+} | {
+    key: string;
+    type: 'source';
+    label: string;
+    default: IndicatorSource;
+    group?: string;
+    tooltip?: string;
 }
 /**
- * Status-line groups a host can feed and switch off independently. The legend
- * never derives these: it tags what the host hands it, so one switch hides one
- * group and leaves the rest of the row alone.
+ * A timeframe code (`'5m'`, `'1d'`), for a study that folds the chart's bars
+ * up to a coarser interval. A settings UI renders it as a select over the
+ * registered intervals, so the value is always one the engine can bucket by;
+ * a free text box would accept `'5min'` and leave the study computing on a
+ * code it cannot resolve. An empty default means "the chart's own interval".
  */
-type LegendField = 'ohlc' | 'change' | 'volume';
+ | {
+    key: string;
+    type: 'interval';
+    label: string;
+    default: string;
+    group?: string;
+    tooltip?: string;
+}
 /**
- * Which name the title shows. `description` and `ticker` come from `status`;
- * with neither supplied the title falls back to `title`, which always exists.
+ * A wall-clock instant in the chart's zone, written `YYYY-MM-DD HH:MM` (the
+ * time part optional), for an anchor a user picks by date: the start of an
+ * anchored VWAP, an event to measure from. It is carried as that string, not
+ * as UTC seconds, so a layout saved in one zone restores to the same wall
+ * clock in another, and `zonedStringToUtcSeconds` turns it into a bar time.
  */
-type LegendTitleMode = 'symbol' | 'description' | 'ticker';
+ | {
+    key: string;
+    type: 'time';
+    label: string;
+    default: string;
+    group?: string;
+    tooltip?: string;
+};
+/** Dash pattern for a level, a drawing, or a plot. */
+type IndicatorLineStyle = 'solid' | 'dashed' | 'dotted';
+/** Line-style options, for a settings UI's Style tab. */
+declare const INDICATOR_LINE_STYLES: readonly {
+    label: string;
+    value: string;
+}[];
+/** Settings keys the runtime derives for a plot's appearance. */
+declare function plotStyleKeys(plot: IndicatorPlot): {
+    color: string;
+    width: string;
+    lineStyle: string;
+    opacity: string;
+    type: string;
+};
 /**
- * The parts of the status line the primitive has no way to know. The host
- * supplies what it has; anything missing is simply not drawn.
+ * Per-plot appearance inputs, generated from the descriptor rather than
+ * hand-written on each one — every indicator gets colour, opacity, thickness,
+ * and line style for free, and a settings UI can render them as a "Style" tab
+ * beside the descriptor's own `inputs`.
+ *
+ * Defaults come from the plot's declared style (and its legacy `colorKey`), so
+ * an indicator that already ships colours keeps them.
  */
-interface LegendStatusData {
-    /** Already-decoded logo (an `<img>`, an `ImageBitmap`, a canvas). */
-    logo?: CanvasImageSource;
-    /** Long name for `titleMode: 'description'`, e.g. `Apple Inc.`. */
-    description?: string;
-    /** Exchange ticker for `titleMode: 'ticker'`, e.g. `NASDAQ:AAPL`. */
-    ticker?: string;
-    /** Session state, e.g. `{ text: 'Market open', color: '#26a69a' }`. */
-    marketStatus?: LegendValue;
-    /** Change against the previous close, e.g. `{ text: '+1.20 (+0.75%)' }`. */
-    lastDayChange?: LegendValue;
-}
+declare function indicatorStyleInputs(descriptor: IndicatorDescriptor): IndicatorInput[];
 /**
- * A snapshot, or a getter the legend calls each frame, so live fields (market
- * status, day change) can change without the host patching options at tick
- * speed. Returning `null` means "nothing to show".
+ * Chart types a plot can be re-rendered as. A moving average is a line by
+ * default, but the same column of numbers reads better as a histogram or an
+ * area depending on what you are looking for — and a descriptor cannot know
+ * which. Restricted to the types that make sense for a single value column.
  */
-type LegendStatusSource = LegendStatusData | (() => LegendStatusData | null);
+declare const INDICATOR_PLOT_STYLES: readonly {
+    label: string;
+    value: string;
+}[];
+/** Canonical option list for a `type: 'source'` input, for settings UIs. */
+declare const INDICATOR_SOURCES: readonly {
+    label: string;
+    value: IndicatorSource;
+}[];
+type IndicatorSettings = Record<string, unknown>;
+/** One plotted line/band/histogram. `type` is any registered chart type. */
+/** A shaded band between two of an indicator's plots. */
+interface IndicatorFillSpec {
+    /** The two plot keys to fill between. */
+    between: readonly [string, string];
+    /** Colour where the first plot is above the second. */
+    colorUp?: string;
+    /** Colour where the second is above the first. */
+    colorDown?: string;
+    /** Settings keys holding those colours, so the band is restyleable. */
+    colorUpKey?: string;
+    colorDownKey?: string;
+    /** 0..1. Defaults to 0.12. */
+    opacity?: number;
+    /**
+     * Draw the band on the price pane even though the indicator owns a pane of
+     * its own. The pair with `IndicatorPlot.overlay`: a study can already send
+     * one plot to the candles, and a band between two such plots belongs beside
+     * them rather than in the study pane the fill would otherwise land in.
+     * Ignored for an `'onchart'` descriptor, which is on the price pane already.
+     */
+    overlay?: boolean;
+}
 /**
- * Per-field switches for the status line. Every one defaults to on, so the
- * absent option object reproduces the row exactly as it drew before these
- * existed. A field whose data is missing draws nothing whether it is on or off.
+ * What `colorParts` answers: a candle plot's colour split three ways, which is
+ * how a study paints a wick in full colour over a translucent body. `body` is
+ * the bar's colour (and the only part a line, histogram or column reads); a
+ * part left undefined falls back to `colorBy`, then to the plot's own colour.
  */
-interface LegendStatusLineOptions {
-    /** Symbol logo, when `status` supplies one. */
-    logo?: boolean;
-    /** The bold name. Also the "name label" switch for an indicator row. */
-    title?: boolean;
-    /** Which name the title shows. Default `symbol`. */
-    titleMode?: LegendTitleMode;
-    /** Session state from `status.marketStatus`. */
-    marketStatus?: boolean;
-    /** The OHLC readout: readings tagged `field: 'ohlc'`. */
-    chartValues?: boolean;
-    /** Change over the hovered bar: readings tagged `field: 'change'`. */
-    barChange?: boolean;
-    /** Readings tagged `field: 'volume'`. */
-    volume?: boolean;
-    /** Change since the previous close, from `status.lastDayChange`. */
-    lastDayChange?: boolean;
+type PlotBarColor = {
+    body?: string;
+    wick?: string;
+    border?: string;
+};
+interface IndicatorPlot {
+    /** Key into the `calc` result. */
+    key: string;
+    /** Registered chart type used to draw it ('line', 'histogram', 'area', ...). */
+    type: SeriesType;
+    /** Legend title. */
+    title: string;
+    /** Style overrides merged onto the chart type's defaults. */
+    style?: SeriesStyle;
+    /** Price axis for this plot. Defaults to 'right'. */
+    priceScaleId?: PriceScaleId;
     /**
-     * The source's own reading (untagged values). This is the scales-and-lines
-     * "last value label" control, which lands here because the legend is what
-     * draws that number on this row.
+     * Value formatting for the axis and crosshair tag of the scale this plot maps
+     * to: `percent` for a ratio study, `volume` for a cumulative one, `custom` for
+     * anything else.
+     *
+     * Like `style.precision`, this is a property of the **price scale**, not of the
+     * series, so it belongs to a plot that owns its pane. Setting it on an
+     * `'onchart'` plot reformats the instrument's own axis, which is almost never
+     * what a study wants.
+     *
+     * `percent` suffixes the value as it stands and does not scale it, so a study
+     * returning a 0..1 fraction should keep returning it and read `0.62%`. Scaling
+     * inside `calc` to make the axis read better changes the plotted value, and the
+     * legend, the crosshair and every downstream calculation with it.
      */
-    lastValueLabel?: boolean;
+    priceFormat?: PriceFormat;
     /**
-     * Plate behind the row's text, for legibility over candles. Off by default:
-     * the row has never had one, and turning it on is a deliberate choice.
+     * Draw this one plot on the price pane even though the indicator owns a pane
+     * of its own. An oscillator that also wants a signal
+     * band or a stop line sitting on the candles is the case: the study belongs in
+     * its own pane, one of its columns belongs on price, and splitting it into two
+     * indicators would make the user configure the same inputs twice.
+     *
+     * Ignored for an `'onchart'` descriptor, which is already on the price pane.
      */
-    background?: boolean;
-    /** Plate opacity, 0..1. Default 0.8, matching the hover plate. */
-    backgroundOpacity?: number;
-    /** Plate color. Defaults to the theme background. */
-    backgroundColor?: string;
-}
-interface PaneLegendOptions {
-    /** Stable id; buttons hit-test as `${id}::close` etc. */
-    id: string;
-    /** Bold source name, e.g. `RSI`. */
-    title: string;
-    /** Dimmed parameter summary after the title, e.g. `14 close`. */
-    params?: string;
-    /** Swatch color; omitted draws no swatch. */
-    color?: string;
+    overlay?: boolean;
     /**
-     * Color for the live value. Defaults to `color`, then the theme's text — so a
-     * row can tint its reading (an up/down change) without being forced to show a
-     * swatch in that same color.
+     * Draw the column shifted this many bars to the right (negative: left). The
+     * column itself stays one value per bar and `calc` returns exactly what it
+     * always did; only where each value is painted moves. Positive is what a
+     * displaced cloud or a projected channel wants: the last `offset` values land
+     * in the right margin, past the newest candle, where no bar exists to hold
+     * them. It shifts the drawn series only. A fill between two plots with the
+     * same offset follows; the legend reads the value drawn under the cursor.
      */
-    valueColor?: string;
-    /** Vertical slot on the pane (0 = topmost). */
-    row?: number;
+    offset?: number;
     /**
-     * Which inline action buttons to draw, left to right. Each hit-tests as
-     * `${id}::<action>`:
-     *  - `up` / `down` — move this pane one slot (`::up` / `::down`)
-     *  - `hide`        — toggle visibility (`::hide`)
-     *  - `maximize`    — expand this pane to fill the chart (`::maximize`)
-     *  - `close`       — remove the source, and its pane if it empties (`::close`)
+     * Settings key holding this plot's color, so a settings change restyles the
+     * series without a full rebuild.
+     */
+    colorKey?: string;
+    /**
+     * Four `calc` keys to draw this plot as bar-shaped elements instead of one
+     * value per bar: candles, hollow candles, OHLC bars, high-low.
      *
-     * Defaults to `['up', 'down', 'hide', 'maximize', 'close']` for pane sources
-     * and `['hide', 'close']` for overlays (pass explicitly to override).
+     * A single column cannot express those at all, and the alternative (a second
+     * result shape for `calc`) would fork the contract every descriptor and every
+     * helper is written against. Naming four columns inside the *same*
+     * `IndicatorValues` keeps one shape: a smoothed Heikin-Ashi overlay, a
+     * higher-timeframe candle, a synthetic spread instrument each return four
+     * ordinary columns and point at them from here.
+     *
+     * The named columns must all exist and be bar-aligned, or `addIndicator`
+     * throws. `key` stays the series identity and the legend reading falls back to
+     * the `close` column.
      */
-    actions?: readonly PaneLegendAction[];
-    /** Rendered as hidden (dimmed, eye hollow). */
-    hidden?: boolean;
-    /** Rendered as maximized (the maximize glyph becomes restore). */
-    maximized?: boolean;
-    /** Text size in media px. Default 11. */
-    font?: number;
-    /** Left inset from the plot edge in media px. Default 8. */
-    left?: number;
-    /** Top inset in media px. Default 6. */
-    top?: number;
-    /** Per-field status-line switches. Patching merges field by field. */
-    statusLine?: LegendStatusLineOptions;
-    /** Host-supplied status-line data (logo, names, market state, day change). */
-    status?: LegendStatusSource;
+    ohlc?: {
+        open: string;
+        high: string;
+        low: string;
+        close: string;
+    };
+    /**
+     * Per-bar colour, for plots whose meaning changes bar to bar — a MACD
+     * histogram is four colours by sign and direction, a conditional study two.
+     * Return `undefined` to fall back to the plot's own colour.
+     *
+     * Reaches the renderer as `Bar.color`, so every Family-A plot type honours
+     * it: histogram, column, candles, OHLC bars, line, step and area.
+     */
+    colorBy?(ctx: {
+        value: number;
+        index: number;
+        values: IndicatorValues;
+        settings: IndicatorSettings;
+    }): string | undefined;
+    /**
+     * Per-bar colour split three ways, for a candle plot whose wick or border
+     * should not follow its body: a solid wick over a translucent body, a
+     * border in the trend colour. Takes precedence over `colorBy` for the parts
+     * it names; a part it leaves undefined falls back to `colorBy`, then to the
+     * plot's own colour. A value plot (line, histogram, column) reads `body` only.
+     */
+    colorParts?(ctx: {
+        value: number;
+        index: number;
+        values: IndicatorValues;
+        settings: IndicatorSettings;
+    }): PlotBarColor | undefined;
 }
-declare class PaneLegend implements IPrimitive {
-    private _opts;
-    private _host;
-    private _values;
-    /** Button geometry from the last draw, in media px, for hit-testing. */
-    private _buttons;
-    /** Right edge of the drawn row, in media px. */
-    private _width;
-    constructor(opts: PaneLegendOptions);
-    attached(host: PrimitiveHost): void;
-    detached(): void;
-    zOrder(): ZOrder;
-    autoscaleInfo(): null;
-    /** A single live reading after the params (typically crosshair-driven). */
-    setValue(text: string, color?: string): void;
-    /** One reading per plot, each in its own color. */
-    setValues(values: readonly LegendValue[]): void;
-    setOptions(patch: Partial<PaneLegendOptions>): void;
-    /** Resolve the host's status data for this frame; `{}` when it has none. */
-    private _status;
-    options(): PaneLegendOptions;
-    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
-    hitTest(x: number, y: number): PrimitiveHit | null;
+/** A horizontal reference level (RSI 70/30, Stochastic 80/20, a zero line). */
+interface IndicatorLevel {
+    price: number;
+    color?: string;
+    title?: string;
+    /** Legacy two-state dash switch. `lineStyle` wins when both are given. */
+    dashed?: boolean;
+    lineWidth?: number;
+    lineStyle?: IndicatorLineStyle;
+}
+/** One end of an indicator drawing: a time on the shared axis, a price on the pane's scale. */
+interface DrawAnchor {
+    time: number;
+    price: number;
 }
-
 /**
- * Vertical gradient across the band, graded between two prices rather than
- * two pixel rows.
+ * A free-standing shape an indicator paints in its own pane, anchored to time
+ * and price rather than to a bar index.
+ *
+ * Plots, levels and markers each answer a different question and none of them
+ * answers this one: a pivot-to-pivot trendline, a supply zone, an order block,
+ * a measured-move projection are all geometry between two arbitrary points, and
+ * a column of one value per bar cannot express any of them. Anchors are times,
+ * so a shape stays put when history is paged in and every logical index shifts.
+ */
+type IndicatorDrawing = {
+    kind: 'line';
+    from: DrawAnchor;
+    to: DrawAnchor;
+    color?: string;
+    lineWidth?: number;
+    lineStyle?: IndicatorLineStyle;
+    /** Continue the line past its anchor to the pane edge. */
+    extendLeft?: boolean;
+    extendRight?: boolean;
+} | {
+    kind: 'box';
+    from: DrawAnchor;
+    to: DrawAnchor;
+    /** Border colour. Omit `fillColor` to draw an outline only. */
+    color?: string;
+    fillColor?: string;
+    /** Fill alpha, 0..1. Defaults to 0.12. */
+    opacity?: number;
+    lineWidth?: number;
+    /** Caption drawn on a plate at the centre of the box; `\n` splits lines. */
+    text?: string;
+    textColor?: string;
+    /**
+     * Detail shown on a plate while the pointer rests on the box, and gone
+     * when it leaves; `\n` splits lines. A zone that carries its size, its
+     * age and what formed it cannot print all of that on the box without
+     * hiding the candles under it, so the caption names it and this explains
+     * it. The box becomes hit-testable, and `id` (or the tooltip text) is
+     * what `subscribeClick` reports for it.
+     */
+    tooltip?: string;
+    /** Hit id, for `subscribeClick`. Defaults to the tooltip text. */
+    id?: string;
+} | {
+    kind: 'label';
+    at: DrawAnchor;
+    /** `\n` splits lines. */
+    text: string;
+    /** Plate fill. */
+    color?: string;
+    textColor?: string;
+    /** Which edge of the plate sits on the anchor. Defaults to 'center'. */
+    align?: 'left' | 'center' | 'right';
+    /** Hover detail, as on a box. */
+    tooltip?: string;
+    /** Hit id, for `subscribeClick`. Defaults to the tooltip text. */
+    id?: string;
+} | {
+    kind: 'polyline';
+    points: readonly DrawAnchor[];
+    color?: string;
+    lineWidth?: number;
+    /** Close the path back to the first point (a triangle, a wedge). */
+    closed?: boolean;
+    fillColor?: string;
+    /** Fill alpha, 0..1. Defaults to 0.12. */
+    opacity?: number;
+};
+/** `calc` output: one array per plot key, aligned 1:1 with the input bars. */
+type IndicatorValues = Record<string, readonly (number | null)[]>;
+/** Per-instance scratch owned by the descriptor (Tier-2 data lands here). */
+type IndicatorStore = Record<string, unknown>;
+/**
+ * The fourth, optional argument to `calc` (and the sixth to `calcTail`): what
+ * the calculation cannot read off the bars themselves.
  *
- * The stops are anchored in PRICE, not in pixels, because that is what the
- * shading is claiming: a band graded from its 70 level down to its 30 means
- * those levels, and a viewport-relative gradient would slide off them the
- * moment the pane is panned or the scale re-fits.
+ * It is optional so that every descriptor written against `calc(bars, settings,
+ * store)` keeps its exact signature and its exact behaviour, which is the whole
+ * point: a calculation that ignores the context computes what it always did.
  */
-interface FillGradient {
-    /** Price the top stop sits at. Omitted: the band's own highest value. */
-    topValue?: number;
-    /** Price the bottom stop sits at. Omitted: the band's own lowest value. */
-    bottomValue?: number;
-    topColor: string;
-    bottomColor: string;
-}
-interface IndicatorFillOptions {
-    /** Fill colour where the first series is above the second. */
-    colorUp: string;
-    /** Fill colour where the second is above the first. */
-    colorDown: string;
-    /** 0..1. Defaults to 0.12 — a band must not drown the candles it sits behind. */
-    opacity?: number;
+interface IndicatorCalcContext {
     /**
-     * Set to grade the band instead of flat-filling it, in place of
-     * `colorUp`/`colorDown`. A point carrying its own `color` still overrides it.
-     * Unset leaves the two-colour fill exactly as it was.
+     * Where the last bar stands, so a study can act once per bar rather than once
+     * per tick, or refuse to signal off a bar that is still moving.
      */
-    gradient?: FillGradient;
+    barState: {
+        /** The most recent update appended a bar rather than replacing one. */
+        isNew: boolean;
+        /** The last bar has closed: its interval has elapsed on the chart clock. */
+        isConfirmed: boolean;
+        /** A live feed is driving updates, rather than a one-off history load. */
+        isRealtime: boolean;
+        /** Index of the last bar, `bars.length - 1` (-1 when there are none). */
+        lastIndex: number;
+    };
+    /** The instrument, when the host knows one. See `IndicatorAttachContext`. */
+    symbol?: string;
+    /** The timeframe (`'5m'`, `'1d'`), on the same terms as `symbol`. */
+    interval?: string;
+    /** The chart's IANA zone, the calendar its axis is labelled in. */
+    timezone: string;
+    /** Chart wall clock in UTC seconds, the clock the countdown row reads. */
+    now(): number;
+    /**
+     * The instrument's tick size, from the **price pane's** `minMove`.
+     *
+     * The price pane and not the indicator's own, because `calc` runs on the
+     * instrument's bars whichever pane the plot lands in, and a study pane is not
+     * quoted in the instrument's tick: an RSI is a dimensionless 0..100 band, so
+     * its scale carries no tick at all to read.
+     *
+     * `undefined` when the host has not told the chart what it is, which is the
+     * honest answer rather than a guessed 0.01: an indicator sizing a range in
+     * ticks has to tell "one paisa" apart from "nobody said".
+     */
+    tickSize?: number;
 }
-/** One bar's pair of values; `null` where either plot has no value yet. */
-interface FillPoint {
-    /** Logical index on the shared time axis (fractional is fine). */
+/** What an alert's `when` predicate is handed, for the bar it is judging. */
+interface IndicatorAlertContext {
+    bars: readonly Bar[];
+    values: IndicatorValues;
+    settings: Readonly<IndicatorSettings>;
+    /** The bar being evaluated. */
     index: number;
-    a: number | null;
-    b: number | null;
+}
+/**
+ * A condition the runtime watches, declared by the descriptor rather than wired
+ * up by the host: the indicator is the only thing that knows what a crossover of
+ * its own columns means.
+ *
+ * Evaluated once per bar, for bars that are new since the last evaluation, so
+ * adding the indicator to a loaded chart fires nothing for history.
+ */
+interface IndicatorAlertSpec {
+    /** Stable within the descriptor, e.g. `'cross-up'`. */
+    id: string;
+    /** Short human label, e.g. `'MACD crossed up'`. */
+    title: string;
     /**
-     * Paints this bar onward in one colour, for a band shaded by something other
-     * than which line leads: trend state, a regime, a third series. The run is
-     * split at the bar where the colour changes, so it is per-bar and not merely
-     * per-crossing. Most specific wins: this, then the gradient, then up/down.
+     * Longer text for a notification; defaults to `title`. A function is handed
+     * the same context `when` judged, so the message can carry the bar's own
+     * numbers: the price it crossed at, the histogram reading, a JSON body for a
+     * webhook. It runs only for a bar `when` accepted.
      */
-    color?: string;
+    message?: string | ((ctx: IndicatorAlertContext) => string);
+    when(ctx: IndicatorAlertContext): boolean;
 }
-declare class IndicatorFill implements IPrimitive {
-    private _points;
-    private _opts;
-    private _host;
-    private _visible;
-    constructor(options: IndicatorFillOptions);
-    attached(host: PrimitiveHost): void;
-    detached(): void;
-    /** Behind the series, so the lines and candles stay crisp on top of it. */
-    zOrder(): ZOrder;
-    /** The plots it spans already drive the scale; the fill must not widen it. */
-    autoscaleInfo(): null;
-    setPoints(points: readonly FillPoint[]): void;
-    setOptions(patch: Partial<IndicatorFillOptions>): void;
-    setVisible(on: boolean): void;
-    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+/**
+ * Thrown by a `calc` (or any hook) to say its inputs cannot produce a study,
+ * the way a script language's runtime error does: a period at or below zero, a
+ * fast length above the slow one, a benchmark the provider cannot serve.
+ *
+ * Any error out of a recompute is caught by the runtime and published on the
+ * instance's data status as `{ state: 'error' }`, so the chart keeps drawing
+ * every other indicator and a host can show the reason beside this one. This
+ * class exists so a descriptor can throw a **named** condition and a host can
+ * tell a bad input, which the user can fix, from a bug, which they cannot.
+ */
+declare class IndicatorInputError extends Error {
+    constructor(message: string);
 }
-
 /**
- * Indicator runtime (ARCHITECTURE.md §8). Turns an `IndicatorDescriptor` into
- * live chart objects: one series per plot, optional reference levels, an
- * optional fixed pane range — and recomputes them when the source data or the
- * settings change.
+ * Bars of another instrument or interval, supplied by the host on request.
  *
- * It adds **no rendering code**. Every plot names a registered chart type, so
- * indicators draw through the same Family-A renderers as any other series.
+ * The engine is handed one symbol's bars and owns no transport, so a study
+ * that compares against a benchmark, or a Tier-2 provider that needs a second
+ * series, asks the host through this and the host answers from wherever it
+ * keeps history. `from` and `to` are UTC seconds; `signal` is aborted when the
+ * instance is removed or its settings change, so a provider can drop the
+ * request rather than answer into the void.
  */
-
-/** The slice of the chart the runtime needs. Keeps this module testable alone. */
-interface IndicatorHost {
-    /** Forget a disposed instance, including disposal through its public handle. */
-    indicatorRemoved?(instanceId: string): void;
-    /** Optional instrument identity and source-range notifications. */
+interface IndicatorBarsRequest {
+    symbol: string;
+    exchange?: string;
+    interval: string;
+    from: number;
+    to: number;
+    signal?: AbortSignal;
+}
+type IndicatorBarsProvider = (request: IndicatorBarsRequest) => Promise<readonly Bar[]>;
+/** Payload of the `'indicator:alert'` event on the chart's own bus. */
+interface IndicatorAlertPayload extends AlertEventPayload {
+    /** Descriptor id, e.g. `'macd'`. */
+    indicatorId: string;
+    /** Instance id, so a host can tell three EMAs apart. */
+    instanceId: string;
+    message: string;
+}
+/** Optional instrument identity and capability supplied by the host. */
+interface ChartDataContext {
+    symbol?: string;
+    exchange?: string;
+    interval?: string;
+    /** Instrument capability, independent of readings: false unsupported, absent unknown. */
+    hasOpenInterest?: boolean;
+}
+/** Source identity changed, or the available source-bar range changed. */
+type IndicatorDataChange = 'context' | 'range';
+/** Observable state of an indicator's external data lifecycle. */
+type IndicatorDataStatus = {
+    state: 'loading' | 'ready' | 'empty' | 'unsupported';
+} | {
+    state: 'error';
+    error: unknown;
+};
+/** What an indicator's `attach` lifecycle can reach. */
+interface IndicatorAttachContext {
+    /** Optional host identity, independent of the indicator's own settings. */
     dataContext?(): Readonly<ChartDataContext> | undefined;
+    /** Read bars and identity again when the host publishes a change. */
     subscribeDataChanges?(listener: (change: IndicatorDataChange) => void): () => void;
-    /** Add the pane-legend row (name + inline up/down/hide/maximize/close). */
-    addIndicatorLegend(opts: {
-        id: string;
-        title: string;
-        params: string;
-        color?: string;
-        row: number;
-        paneIndex: number;
-    }): PaneLegend;
-    removeIndicatorLegend(legend: PaneLegend): void;
-    /** How many legends already sit on this pane, so rows stack. */
-    legendRowsOn(paneIndex: number): number;
-    addIndicatorSeries(type: string, paneIndex: number, style: Record<string, unknown> | undefined, priceScaleId: string | undefined, 
-    /** Axis/crosshair formatting for the scale this plot maps to. */
-    priceFormat?: PriceFormat): SeriesApi;
+    /** Publish status and an explicit retry action for this instance. */
+    setDataStatus?(status: IndicatorDataStatus): void;
+    setDataRetry?(retry: (() => void) | null): void;
+    /** Instance lifetime. Aborted on removal, preserved across style changes. */
+    signal?: AbortSignal;
+    /** Current settings (live — read at call time, not captured). */
+    settings(): Readonly<IndicatorSettings>;
+    /** The chart's current source bars. */
+    bars(): readonly Bar[];
+    /** Re-run `calc` and repaint — call when external data arrives. */
+    requestRecompute(): void;
+    /** Scratch this instance owns; the same object `calc` receives. */
+    store: IndicatorStore;
     /**
-     * Add a reference level. One options object rather than seven positional
-     * arguments: the list grew a width and a dash style in 1.7.1, and a call site
-     * of seven bare values is where the next one gets passed in the wrong slot.
+     * The instrument the chart is showing, when the host knows it.
+     *
+     * Hosts can supply this through `IndicatorHost` or Chart's explicit data
+     * context. Without a configured identity it stays undefined. External
+     * studies read `dataContext` to include the exchange as well.
      */
-    addIndicatorLevel(level: {
-        price: number;
-        color: string;
-        /** Kept for hosts predating `lineStyle`; always `lineStyle === 'dashed'`. */
-        dashed: boolean;
-        lineWidth: number;
-        lineStyle: IndicatorLineStyle;
-        label: string;
-        id: string;
-    }, paneIndex: number): PriceLine;
-    removeIndicatorLevel(line: PriceLine): void;
-    /** Attach a band drawn behind the plots (an Ichimoku cloud). */
-    addIndicatorFill(fill: IndicatorFill, paneIndex: number): void;
-    removeIndicatorFill(fill: IndicatorFill): void;
+    symbol?(): string | undefined;
+    /** The chart's timeframe (`'5m'`, `'1d'`), on the same terms as `symbol`. */
+    interval?(): string | undefined;
+    /** The chart's IANA zone, the one its axis is labelled in. */
+    timezone?(): string;
+    /** Chart wall clock in UTC seconds, the same clock the countdown row uses. */
+    now?(): number;
+    /**
+     * Ask the host for another instrument's (or interval's) bars. Always present
+     * under `chart.addIndicator`; it rejects when the host has registered no
+     * provider (`chart.setBarsProvider`), so a study can treat the rejection as
+     * "unsupported here" and say so through `setDataStatus`.
+     */
+    requestBars?(request: IndicatorBarsRequest): Promise<readonly Bar[]>;
+    /** The pane this instance drew into. Moves when panes are reordered. */
+    paneIndex?(): number;
+    /** Attach a primitive to this indicator's pane, and detach it again. */
+    addPrimitive?(p: IPrimitive): void;
+    removePrimitive?(p: IPrimitive): void;
+    /**
+     * Emit on the chart's own event bus, the one `chart.on(name, cb)` listens to.
+     *
+     * The declarative `alerts` slot covers a condition read off the bars; this is
+     * the imperative half, for an indicator whose signal arrives from outside the
+     * calculation entirely (a subscription its `attach` opened).
+     */
+    emit?(event: string, payload: unknown): void;
+}
+/**
+ * What `levels` is handed. It carries `bars` and `values` **and** spreads the
+ * settings keys onto itself, so the built-ins written against the original
+ * `levels(settings)` signature keep working unchanged: they read
+ * `ctx.overbought` (or pass `ctx` to a `num(s, key, default)` helper) and find
+ * exactly what they found before. A widened parameter is the only way a level
+ * can be data-derived (yesterday's high, the session VWAP band), and that is a
+ * whole class of level that could not be expressed at all before.
+ *
+ * The three data members are optional for the same backward-compatibility
+ * reason, not because the runtime ever omits them: it always passes all three,
+ * but a caller holding only a settings bag must still be able to invoke
+ * `levels` directly. A descriptor that needs the data should default them
+ * (`ctx.bars ?? []`).
+ *
+ * `settings`, `bars` and `values` are therefore reserved keys, the way
+ * `timezone` already is in the settings a `calc` receives: an input declared
+ * under one of those names is shadowed here.
+ */
+type IndicatorLevelContext = IndicatorSettings & {
+    settings?: Readonly<IndicatorSettings>;
+    bars?: readonly Bar[];
+    values?: IndicatorValues;
+};
+interface IndicatorDescriptor {
+    /** Registry key, e.g. `'macd'`. */
+    id: string;
+    /** Display name, e.g. `'MACD'`. */
+    name: string;
+    /** Grouping for a picker UI ('Trend', 'Momentum', 'Volume', 'Volatility'). */
+    category?: string;
+    /** `'onchart'` overlays the price pane; `'pane'` gets its own pane. */
+    placement: 'onchart' | 'pane';
+    inputs: readonly IndicatorInput[];
+    plots: readonly IndicatorPlot[];
     /**
-     * Detach a signal-marker layer. There is no matching `add`: the layer comes
-     * from `series.createMarkers()` on a plot's own series, so it already lands in
-     * the right pane. Removing a series does not remove its primitives, hence this.
+     * Shaded bands between pairs of plots — the Ichimoku cloud, a Bollinger
+     * channel. A pair of lines is not the same picture as a filled region: the
+     * fill is what makes "price is above the cloud" readable at a glance, and
+     * which side leads is itself the signal, hence the two colours.
      */
-    removeIndicatorMarkers(markers: SeriesMarkers): void;
-    /** Attach a corner-pinned summary grid to a pane, and detach it again. */
-    addIndicatorTable(paneIndex: number): ChartTable;
-    removeIndicatorTable(table: ChartTable): void;
+    fills?: readonly IndicatorFillSpec[];
     /**
-     * Attach an arbitrary primitive to a pane, and detach it again. Carries both
-     * the descriptor's drawing layer and whatever a Tier-2 `attach` lifecycle
-     * wants to paint, so those two do not need a host method each.
+     * Full recompute over every bar. Must return arrays the same length as
+     * `bars` (use `null` for warmup gaps — the line renderer breaks across them
+     * and autoscale skips them).
      *
-     * Optional, like `timezone`, so a host predating it still satisfies this
-     * interface: an indicator that draws simply draws nothing there.
+     * Tier-1 indicators are pure functions of `(bars, settings)` and ignore
+     * `store`. Tier-2 indicators — the ones with their own data — read the
+     * external series their `attach` lifecycle put in `store`.
      */
-    addIndicatorPrimitive?(primitive: IPrimitive, paneIndex: number): void;
-    removeIndicatorPrimitive?(primitive: IPrimitive): void;
+    calc(bars: readonly Bar[], settings: Readonly<IndicatorSettings>, store: IndicatorStore, ctx?: IndicatorCalcContext): IndicatorValues;
     /**
-     * Recompute whatever the host has marked stale, before a caller reads a value.
+     * Optional per-instance lifecycle, for indicators whose data is not derived
+     * from the chart's bars (CVD, PCR, an external feed). Called once
+     * when the instance is created; return a teardown function.
      *
-     * Optional, like `timezone`, so a host predating it still satisfies this
-     * interface: one that recomputes eagerly has nothing to flush.
+     * Fetch into `ctx.store`, then call `ctx.requestRecompute()` — `calc` runs
+     * again and reads what you stored.
      */
-    flushIndicators?(): void;
-    /** Bars of the primary price series — the calculation input. */
-    sourceBars(): readonly Bar[];
-    /** Index of a fresh pane for an indicator that wants its own. */
-    nextPaneIndex(): number;
+    attach?(ctx: IndicatorAttachContext): (() => void) | void;
     /**
-     * The chart's configured IANA zone. Optional so a host predating the option
-     * still satisfies this interface; absent means the shipped default.
+     * Optional incremental path, called instead of `calc` when only the tail
+     * changed (a live tick). Return values for indices `[fromIndex, bars.length)`
+     * — the runtime splices them onto the previous result — or `null` to fall
+     * back to a full `calc`.
      *
-     * A descriptor is handed bars and settings and never the chart, so this is
-     * how the calendar an anchor resets on (a VWAP session, a seasonality month)
-     * reaches the calculation. See `IndicatorInstance._descriptorSettings`.
+     * Without it every tick costs a full recompute. That is a few hundred
+     * microseconds for one indicator over 50k bars, but it is O(n) per tick per
+     * indicator, so implement this for anything meant to run in a busy live pane.
      */
-    timezone?(): string;
+    calcTail?(bars: readonly Bar[], settings: Readonly<IndicatorSettings>, fromIndex: number, previous: IndicatorValues, store: IndicatorStore, ctx?: IndicatorCalcContext): IndicatorValues | null;
     /**
-     * The instrument and timeframe on screen, when the host knows them. The
-     * host can supply an explicit `dataContext` instead. Without either hook,
-     * a descriptor sees `undefined` rather than a guessed identity.
+     * Optional bar-anchored signal markers — a named "Buy"/"Sell" plate, an arrow
+     * at a crossover. Runs after every `calc`, so it reads the values it just
+     * produced rather than recomputing anything.
+     *
+     * A plot cannot express this: a plot is a column of prices drawn as a line or
+     * histogram, whereas a signal is a discrete event with a label. Returning `[]`
+     * (when a `showLabels`-style input is off, say) clears the layer.
      */
-    symbol?(): string | undefined;
-    interval?(): string | undefined;
-    /** Chart wall clock in UTC seconds. Absent means the system clock. */
-    now?(): number;
+    markers?(ctx: {
+        bars: readonly Bar[];
+        values: IndicatorValues;
+        settings: Readonly<IndicatorSettings>;
+    }): readonly SeriesMarker[];
     /**
-     * Publish an indicator's per-bar colours onto the **primary price series**,
-     * or withdraw them with `null`. `owner` is the instance id: a host holds one
-     * overlay at a time and only lets its current owner withdraw it, so a second
-     * publisher taking over does not get cleared by the first one's teardown.
+     * Optional summary grid pinned to a corner of the pane.
      *
-     * Optional, like `timezone`: a host that does not implement it simply gives a
-     * `barColors` descriptor nowhere to publish, and the indicator's own plots are
-     * unaffected.
+     * Some studies are not a value per bar at all: a seasonality heatmap is a
+     * matrix of monthly returns, a scoreboard is a handful of statistics. Those
+     * have no place in `calc`, whose contract is one column per plot aligned to
+     * the bars, so they come back through here instead. Runs after every `calc`.
+     *
+     * Return `null` (or a zero-row grid) to draw nothing, which is how a
+     * `showTable`-style input should switch it off.
      */
-    setBarColors?(colors: readonly (string | null)[] | null, owner: string): void;
-    /** Emit on the chart's event bus (indicator alerts, and `attach`'s own events). */
-    emit?(event: string, payload: unknown): void;
+    table?(ctx: {
+        bars: readonly Bar[];
+        values: IndicatorValues;
+        settings: Readonly<IndicatorSettings>;
+    }): {
+        rows: readonly (readonly TableCell[])[];
+        options?: Partial<ChartTableOptions>;
+    } | null;
     /**
-     * Bars of another instrument or interval, from wherever the host keeps its
-     * history. Optional: without it the attach context's `requestBars` rejects,
-     * which a study reads as "not available on this chart".
+     * Optional free-standing shapes drawn in the indicator's pane: trendlines
+     * between pivots, supply and demand boxes, projection labels. Runs after
+     * every `calc`, like `markers` and `table`, and the returned list replaces the
+     * previous one wholesale, so returning `[]` clears the layer.
      */
-    requestBars?(request: IndicatorBarsRequest): Promise<readonly Bar[]>;
+    draws?(ctx: {
+        bars: readonly Bar[];
+        values: IndicatorValues;
+        settings: Readonly<IndicatorSettings>;
+    }): readonly IndicatorDrawing[];
     /**
-     * Tick size of the named pane's price scale, or undefined when none is set.
-     * Optional so a host predating it still satisfies this interface.
+     * Optional per-bar shading behind everything else in the indicator's pane: a
+     * full-height column per bar, `null` where nothing should be shaded.
      *
-     * Per pane, and the panes genuinely differ: a pane that does not quote the
-     * instrument has no tick to report. Pane 0 is the price pane, so it is the
-     * one to ask for the instrument's own step.
+     * A regime study answers "which state is the market in right now", and that is
+     * a property of the whole bar, not a price. Drawn as a plot it would need a
+     * value to sit at and would fight the pane's autoscale; as a column behind the
+     * candles it reads at a glance and costs the scale nothing.
+     *
+     * Runs after every `calc`. Return `[]` to clear the layer.
      */
-    tickSize?(paneIndex: number): number | undefined;
+    background?(ctx: {
+        bars: readonly Bar[];
+        values: IndicatorValues;
+        settings: Readonly<IndicatorSettings>;
+    }): readonly (string | null)[];
     /**
-     * Write a number the way the price axis of that pane writes it.
+     * Optional recolouring of the **main price candles**, one entry per bar,
+     * `null` to leave that bar with its own colour.
      *
-     * The legend sits inches from the axis and names the same quantity, so the
-     * two disagreeing is the reading a user has to reconcile themselves. Deriving
-     * the format here from a tick got that wrong twice over: a study pane carries
-     * no tick at all, so a percentage read `0.618` beside an axis saying `0.62`,
-     * and a price pane's tick alone misses the precision floor and the host's own
-     * formatter, so a volume study read seven digits where its axis said `1.20M`.
+     * Distinct from a plot's `colorBy`, which paints the indicator's own series: a
+     * trend filter, a volatility regime or a higher-timeframe bias is a statement
+     * about the price bars themselves, and drawing it as a second series beside
+     * them says something weaker.
      *
-     * Asking the scale removes the second opinion. Optional so a host driving
-     * this module alone still works, falling back to the magnitude ladder.
+     * Only one indicator's colours can be on the candles at a time; the most
+     * recent publisher wins, and publishers run in `addIndicator` order, so the
+     * winner is the same one from frame to frame. Removing it, or hiding it,
+     * restores the bars' own colours.
      */
-    formatPrice?(paneIndex: number, value: number): string | undefined;
-    /** Pin a pane's price scale to a fixed range, or release it with `null`. */
-    setPaneRange(paneIndex: number, range: {
+    barColors?(ctx: {
+        bars: readonly Bar[];
+        values: IndicatorValues;
+        settings: Readonly<IndicatorSettings>;
+    }): readonly (string | null)[];
+    /**
+     * Optional conditions the runtime watches on the descriptor's behalf, emitted
+     * as `'indicator:alert'` on the chart's event bus with an
+     * {@link IndicatorAlertPayload}. See {@link IndicatorAlertSpec}.
+     */
+    alerts?: readonly IndicatorAlertSpec[];
+    /**
+     * Optional horizontal reference levels drawn in the indicator's pane.
+     * Recomputed after every `calc`, so a level derived from the data (the
+     * previous day's high) tracks it. See `IndicatorLevelContext` for why the
+     * argument still reads as a settings bag.
+     */
+    levels?(ctx: IndicatorLevelContext): readonly IndicatorLevel[];
+    /**
+     * Optional fixed price range for the indicator's own pane (RSI 0..100).
+     * Applied only when the indicator creates its pane — two indicators sharing a
+     * pane would otherwise fight over it.
+     */
+    range?(settings: Readonly<IndicatorSettings>): {
         min: number;
         max: number;
-    } | null): void;
-}
-/** Public handle returned by `chart.addIndicator(...)`. */
-interface IndicatorApi {
-    /** External data state, or null for a study without a managed lifecycle. */
-    dataStatus(): Readonly<IndicatorDataStatus> | null;
-    /** Observe changes; immediately receives the current managed status, if any. */
-    subscribeDataStatus(listener: (status: Readonly<IndicatorDataStatus>) => void): () => void;
-    /** Retry external history when the descriptor supplies a retry action. */
-    retryData(): void;
-    /** Unique instance id (several instances of one indicator can coexist). */
-    readonly id: string;
-    /** The descriptor id, e.g. `'macd'`. */
-    readonly indicatorId: string;
-    /** Display name. */
-    readonly name: string;
-    /** Pane the indicator drew into. */
-    readonly paneIndex: number;
-    /** Current settings (a copy). */
-    settings(): IndicatorSettings;
-    /** Merge a settings patch, recompute, and restyle. */
-    setSettings(patch: Readonly<IndicatorSettings>): void;
-    /** The series backing one plot key, for direct styling. */
-    series(plotKey: string): SeriesApi | undefined;
-    /** Latest computed values (a reference — do not mutate). */
-    values(): IndicatorValues;
-    /** Whether the plots are drawn (the legend's eye toggle). */
-    visible(): boolean;
-    /** Show or hide every plot without removing the instance. */
-    setVisible(on: boolean): void;
-    /** This indicator's legend row, or null if it has none. */
-    legend(): PaneLegend | null;
-    /** Refresh the legend readings for a bar index; omit for the latest bar. */
-    updateLegendValues(index?: number): void;
-    /** Remove every series, level, and legend row this indicator created. */
-    remove(): void;
+    } | null;
 }
+/** Register an indicator descriptor. Later registrations of the same id win. */
+declare function registerIndicator(descriptor: IndicatorDescriptor): void;
+declare function getIndicator(id: string): IndicatorDescriptor;
+declare function hasIndicator(id: string): boolean;
+declare function registeredIndicators(): IndicatorDescriptor[];
+/** The descriptor's declared defaults as a settings object. */
+declare function indicatorDefaults(descriptor: IndicatorDescriptor): IndicatorSettings;
+/** Read one bar's value for a price source. */
+declare function sourceValue(bar: Bar, source: IndicatorSource): number;
+/** Read a whole bar array for a price source. */
+declare function sourceValues(bars: readonly Bar[], source: IndicatorSource): number[];
 
 /**
  * Serialisable chart state — the keystone the persistence-shaped features hang
@@ -2929,6 +3115,8 @@ interface SeriesState {
 }
 interface IndicatorState {
     indicatorId: string;
+    /** Stable workspace identity. Omitted by legacy states and reusable templates. */
+    instanceId?: string;
     settings: IndicatorSettings;
     paneIndex: number;
     /** Omitted by older layouts, which restore the indicator as visible. */
@@ -2947,6 +3135,7 @@ interface ChartState {
         horzLines: boolean;
     };
     crosshairMode?: 'normal' | 'magnet';
+    crosshairSnapToBar?: boolean;
     panes?: PaneState[];
     /** Informational: `restoreState` does not recreate these (it has no data). */
     series?: SeriesState[];
@@ -2957,6 +3146,7 @@ interface ChartState {
      * tier is loaded.
      */
     drawings?: unknown;
+    alerts?: AlertsDocument;
 }
 /** What `restoreState` actually applied, so a caller can finish the job. */
 interface RestoreReport {
@@ -3848,6 +4038,8 @@ interface ChartOptions {
      * bar under the cursor (price pane only).
      */
     crosshairMode?: CrosshairMode;
+    /** Snap the vertical crosshair to the nearest primary bar's center. Default false; independent of the price magnet. */
+    crosshairSnapToBar?: boolean;
     /**
      * Optional chrome on the axis strips: the corner clock and the bar-close
      * countdown. Both are off unless asked for, so a chart that omits this block
@@ -4013,6 +4205,8 @@ declare function compactVolume(v: number): string;
  * floating tooltip. See `subscribeCrosshairMove`.
  */
 interface CrosshairMoveEvent {
+    /** Linked readouts have no physical pointer position and are not pointer gestures. */
+    source?: 'linked';
     /** UTC seconds of the hovered bar, or null when off the data / pointer left. */
     time: number | null;
     /** Logical index under the cursor, or null. */
@@ -4150,6 +4344,8 @@ interface ContextMenuTarget {
     id: string | null;
     /** Indicator instance id, when `kind` is 'indicator'. */
     instanceId?: string;
+    /** Exact plot key when a study's plotted series was hit rather than its legend. */
+    plotKey?: string;
     /** Series type, when `kind` is 'series'. */
     seriesType?: SeriesType;
     /** Which axis strip was hit, when `kind` is 'price-scale'. */
@@ -4235,6 +4431,7 @@ declare class Chart {
     private _height;
     private _hasFitContent;
     private _crosshairMode;
+    private _crosshairSnapToBar;
     private _shortcuts;
     private _trading;
     private _pointerInside;
@@ -4317,6 +4514,7 @@ declare class Chart {
     private readonly _firstDataId;
     /** Handle + record of the primary price series (see `primarySeries`). */
     private _primary;
+    private readonly _seriesRecords;
     private readonly _indicators;
     private _dataContext;
     private _barsProvider;
@@ -4336,6 +4534,7 @@ declare class Chart {
     private _barColorAnchor;
     /** Opaque drawing-tier payload, round-tripped through get/restoreState. */
     private _drawingState;
+    private _alertState;
     /** Pane currently maximized, and the weights to restore when it un-maximizes. */
     private _maximizedPane;
     /** Legend rows per pane, so new ones stack below existing ones. */
@@ -4346,6 +4545,7 @@ declare class Chart {
     private _loadingHistory;
     private _clickCb;
     private _crosshairCb;
+    private _readoutTime;
     private _pointerMoved;
     /** While true, pointer gestures place anchors instead of panning. */
     private _placementMode;
@@ -4406,6 +4606,8 @@ declare class Chart {
     /** Call after a history-paging load resolves to re-enable the trigger. */
     historyLoadComplete(): void;
     get dataLayer(): DataLayer;
+    /** Readonly source bars, without allocating a history copy on each live update. */
+    primaryBars(): readonly Bar[];
     get timeScale(): TimeScale;
     /** Restore a saved logical range (e.g. preserve the user's zoom across a data reload). */
     setVisibleLogicalRange(range: LogicalRange): void;
@@ -4536,6 +4738,8 @@ declare class Chart {
     private _forgetIndicator;
     /** Optional instrument identity supplied by the host, never inferred from bars. */
     getDataContext(): Readonly<ChartDataContext> | undefined;
+    /** Instrument capability from the host. A missing bar reading does not change it. */
+    get hasOpenInterest(): boolean | undefined;
     /** Clear the previous source bars before changing context, then load the new source. */
     setDataContext(context: ChartDataContext | undefined): void;
     /**
@@ -4607,9 +4811,17 @@ declare class Chart {
     /**
      * Subscribe to crosshair movement for an OHLC legend / tooltip. The callback
      * fires with the hovered bar of the primary price series on every move, and
-     * with all-null fields when the pointer leaves the plot.
+     * with all-null fields when the pointer leaves the plot. A linked crosshair
+     * also updates the readout, with source 'linked' and no pointer coordinates.
      */
     subscribeCrosshairMove(cb: (e: CrosshairMoveEvent) => void): void;
+    /**
+     * Update the readout under a link group's separately drawn crosshair. The
+     * physical pointer takes precedence. This never emits a pointer move event,
+     * so hosts do not interpret it as drawing input or echo it to another group.
+     */
+    setLinkedCrosshairIndex(index: number | null): void;
+    private _readoutIndex;
     /**
      * Subscribe to drags of draggable primitives (order / SL / TP lines, drawing
      * handles). Fires per move and on release.
@@ -4809,6 +5021,8 @@ declare class Chart {
     axisChromeOptions(): AxisChromeOptions;
     /** Crosshair behaviour ('normal' or 'magnet'). Set it via `applyOptions`. */
     crosshairMode(): CrosshairMode;
+    /** Whether the vertical crosshair snaps to an existing primary bar's center. */
+    crosshairSnapToBar(): boolean;
     /** The active palette. Swap it with `setTheme`. */
     theme(): ChartTheme;
     /**
@@ -4942,6 +5156,7 @@ declare class Chart {
         timeFormatter?: ((utcSeconds: number, tickMark?: TickMarkType) => string) | undefined;
         timezone?: string;
         crosshairMode?: CrosshairMode;
+        crosshairSnapToBar?: boolean;
     }): void;
     panes(): readonly Pane[];
     /**
@@ -4971,12 +5186,17 @@ declare class Chart {
      * (or `setVisibleLogicalRange`) once the series are populated.
      */
     restoreState(state: unknown): RestoreReport;
+    private _restoreState;
     /**
      * The opaque `drawings` slot in the chart state. The base engine only
      * round-trips it; the drawing tier reads and writes it.
      */
     drawingState(): unknown;
     setDrawingState(value: unknown): void;
+    /** Detached JSON state, also available when no alert controller is attached. */
+    alertState(): AlertsDocument | undefined;
+    /** Runtime snapshot. JSON safety of opaque payloads is checked when state is read. */
+    setAlertState(document: AlertsDocument | undefined): void;
     invalidate(build: (mask: InvalidateMask) => void): void;
     /**
      * Measure the container once more, a frame after construction.
@@ -5449,6 +5669,330 @@ declare class SvgContext {
     private _unsupported;
 }
 
+/**
+ * Aligning a second instrument onto the primary series' bars.
+ *
+ * The x-axis is a gapless logical index over the times the shared DataLayer
+ * holds (ARCHITECTURE.md §4.1, §5.3), so two instruments do not share a bar
+ * index and cannot be laid side by side by position. They are matched by
+ * timestamp, and the two directions of mismatch get opposite answers:
+ *
+ * - **A comparison bar with no primary bar is dropped.** The DataLayer merges
+ *   *every* series' times into one index space, so a time only the comparison
+ *   has would mint a new logical index: a column the primary instrument has no
+ *   candle for, inserted mid-chart, shifting every bar after it. That happens
+ *   for real (a different exchange's holiday calendar, a 24/7 instrument next
+ *   to an NSE one, a feed that emits a stray print), and warping the primary's
+ *   own axis to accommodate a comparison is never the right trade. The print is
+ *   counted in `dropped` so a host can say so rather than silently losing it.
+ *
+ * - **A primary bar with no comparison bar becomes whitespace**, which is a NaN
+ *   bar the line renderer breaks across, so the comparison shows a *gap*. The
+ *   alternative, carrying the last known value forward, draws a flat segment
+ *   through a session the instrument never traded and, worse, in percentage
+ *   mode it anchors the move on the far side of the gap to a print that does
+ *   not exist. Omitting the bar entirely is worse still: the renderer would
+ *   join the two sides with one straight line across the holiday.
+ *
+ * Matching is on the exact timestamp. Bar-open times are bucketed by the candle
+ * builder (§10.2) and stored as UTC seconds (§4.0), so two instruments on the
+ * same interval agree to the second; anything that does not agree is a
+ * different interval, which no tolerance window could rescue.
+ */
+
+/** What one alignment pass did, for a host that wants to report coverage. */
+interface ComparisonAlignment {
+    /** Items handed to the comparison series: one per primary bar. */
+    bars: number;
+    /** Primary bars the comparison also traded (a value is drawn). */
+    matched: number;
+    /** Primary bars with no comparison print (drawn as a gap). */
+    gaps: number;
+    /** Comparison prints discarded for having no primary bar at that time. */
+    dropped: number;
+}
+/**
+ * Project `comparison` onto `primary`'s bars: one item per primary bar, in the
+ * primary's order, so the result occupies exactly the logical indices the chart
+ * already has and adds none of its own.
+ *
+ * Neither input is mutated and neither has to be sorted: matching goes through
+ * a time map, which also collapses a repeated timestamp to its last item, the
+ * same rule the DataLayer applies when it merges (`sortedUniqueByTime`).
+ */
+declare function alignToPrimary(primary: readonly Bar[], comparison: readonly SeriesDataItem[]): {
+    items: SeriesDataItem[];
+    alignment: ComparisonAlignment;
+};
+
+/**
+ * Multi-symbol comparison: put a second instrument on the primary one's pane
+ * and read them together (NIFTY against BANKNIFTY, a stock against its index).
+ *
+ * Headless, in the spirit of `DrawingController` (src/draw/controller.ts) and
+ * `ReplayController`: it owns the series, the alignment and the scales, and
+ * ships no DOM, so the host draws its own symbol chips and legend rows from
+ * `list()`.
+ *
+ * Three decisions carry the design:
+ *
+ * 1. **Each comparison owns a scale.** A free legacy overlay or left scale
+ *    preserves the first source's placement; additional sources use named
+ *    hidden scales so their different price units cannot affect one another.
+ *
+ * 2. **Comparability comes from the scale, not from the data.** The bars handed
+ *    over are stored as the instrument's own prices, so the legend, the
+ *    crosshair and any live update still speak in real prices. What makes the
+ *    lines readable together is the pane mode: `percentage` and
+ *    `indexed-to-100` give every scale its own baseline (its first visible
+ *    close, or an explicit common timestamp), and `_mirror` gives it the same
+ *    band of percent the primary's axis is showing. Without that mirror each
+ *    scale would autoscale to its own data and a 1% mover would look exactly
+ *    like a 10% mover, both filling the pane.
+ *
+ * 3. **Alignment is by timestamp** and lives in `./align`, which documents what
+ *    happens in each direction of mismatch.
+ *
+ * Each comparison owns a scale and baseline. Further instruments use keyed
+ * hidden scales so their absolute prices cannot change another source's units.
+ */
+
+/**
+ * How the pane quotes prices while a comparison is on it. The two rebasing
+ * modes are the reason the lines are comparable at all; `none` leaves the
+ * pane's own mode alone, for a host that wants the raw overlay.
+ */
+type ComparisonMode = 'percentage' | 'indexed-to-100' | 'none';
+/** Independent first-visible closes, or the first visible timestamp shared by all visible sources. */
+type ComparisonBaseline = 'first-visible' | 'common';
+interface ComparisonOptions {
+    /** Instrument label, e.g. 'BANKNIFTY'. Carried on the handle for the host's UI. */
+    symbol: string;
+    /** The instrument's own bars. Aligned to the primary series, see `./align`. */
+    bars: readonly SeriesDataItem[];
+    /** Line colour shorthand; `style.color` wins if both are given. */
+    color?: string;
+    /** Style overrides merged onto the chart type's defaults. */
+    style?: SeriesStyle;
+    /** Renderer for the comparison. Default 'line'. */
+    type?: SeriesType;
+    /** Pane to draw on. Default 0, the price pane. */
+    paneIndex?: number;
+}
+interface ComparisonControllerOptions {
+    /** Pane mode applied while any comparison is on it. Default 'percentage'. */
+    mode?: ComparisonMode;
+    /** Baseline policy. Default 'first-visible' preserves existing integrations. */
+    baseline?: ComparisonBaseline;
+}
+/** What `addComparison` hands back: one instrument on the chart. */
+interface ComparisonHandle {
+    readonly symbol: string;
+    /**
+     * The series this comparison draws through, for style patches and markers.
+     * Data set on it directly skips alignment (use `setBars`), and removing it
+     * directly leaves the pane rebased with nothing on it (use `remove`).
+     */
+    readonly series: SeriesApi;
+    readonly paneIndex: number;
+    /** The hidden scale it maps to. Never the pane's own price axis. */
+    priceScale(): PriceScale;
+    /** How the last alignment against the primary's bars went. */
+    alignment(): ComparisonAlignment;
+    /** Eligible aligned bar in its own price units; null for gaps, suppressed baselines or forming replay candles. */
+    barAt(time: number): Readonly<Bar> | null;
+    /** Replace the instrument's bars (a longer history, a refreshed fetch). */
+    setBars(bars: readonly SeriesDataItem[]): void;
+    /** Take this instrument off the chart. Safe to call twice. */
+    remove(): void;
+    /** Every comparison on this chart, in the order they were added. */
+    list(): readonly ComparisonHandle[];
+}
+/**
+ * The slice of a pane the controller reads. Declared structurally, like
+ * `ReplayViewport`, so nothing here depends on `Pane` beyond the two members
+ * that decide where a comparison can go.
+ */
+interface ComparisonPane {
+    readonly priceScale: PriceScale;
+    series(): readonly {
+        readonly scaleId: string;
+        readonly style?: SeriesStyle;
+    }[];
+}
+/**
+ * The slice of the chart this controller needs. `Chart` satisfies it; declaring
+ * it structurally keeps the controller testable against a stub.
+ */
+interface ComparisonChartHost {
+    addSeries(type: SeriesType, options: AddSeriesOptions): SeriesApi;
+    panes(): readonly ComparisonPane[];
+    addPrimitive(primitive: IPrimitive, paneIndex?: number): void;
+    removePrimitive(primitive: IPrimitive): void;
+    primarySeries(): SeriesApi | null;
+    /** Avoids allocating a primary history copy when the host provides it. */
+    primaryBars?(): readonly Bar[];
+    getVisibleLogicalRange?(): {
+        from: number;
+        to: number;
+    };
+    on?(event: string, callback: (payload: unknown) => void): () => void;
+    /** The shared logical axis locates visible primary bars even when another series adds times. */
+    readonly dataLayer: {
+        readonly length: number;
+        indexToTime?(index: number): number | undefined;
+    };
+}
+declare class ComparisonController {
+    private readonly _chart;
+    private _mode;
+    private _baseline;
+    private readonly _panes;
+    /** Insertion-ordered, and the handle is the key so `remove` is a lookup. */
+    private readonly _items;
+    /** Axis length plus primary identity and boundaries avoid scanning history each frame. */
+    private _alignedAt;
+    /** Guards `realign` against re-entry through its own `setData` repaint. */
+    private _realigning;
+    private _nextScale;
+    private _syncing;
+    private _alignedPrimary;
+    private _primaryLength;
+    private _primaryFirst;
+    private _primaryLast;
+    private readonly _off;
+    private _destroyed;
+    constructor(chart: ComparisonChartHost, options?: ComparisonControllerOptions);
+    /** Put an instrument on the chart alongside the primary series. */
+    add(options: ComparisonOptions): ComparisonHandle;
+    /** Take one instrument off. Returns false if it was already gone. */
+    remove(handle: ComparisonHandle): boolean;
+    /** Every comparison on the chart, in the order they were added. */
+    list(): readonly ComparisonHandle[];
+    /** Take them all off, putting every pane back the way it was found. */
+    clear(): void;
+    /**
+     * Change the mode the panes are held in while comparisons are on them.
+     * Panes that already have one switch immediately.
+     */
+    setMode(mode: ComparisonMode): void;
+    get mode(): ComparisonMode;
+    /** Select a shared timestamp without changing the instruments' stored price units. */
+    setBaseline(baseline: ComparisonBaseline): void;
+    get baseline(): ComparisonBaseline;
+    /** Shared baseline timestamp, or null for no overlap, no visible sources, or independent baselines. */
+    baselineTime(paneIndex?: number): number | null;
+    /**
+     * Re-project onto the primary's current bars. Chart handles data replacement
+     * and replay automatically. A structural host without data events or primary
+     * history identity can call this after replacing its timestamps.
+     */
+    realign(): void;
+    /**
+     * Bring the overlay scales in line with the primary axis, re-aligning first
+     * if the shared time axis has moved under us (a live bar, history paged in,
+     * a replay step). Runs once per base paint through the per-pane hook.
+     *
+     * Re-aligning here writes series data mid-frame, which is safe because the
+     * hook is a `bottom` primitive: it runs after the pane has autoscaled and
+     * before any series is drawn, so the frame that notices the change is also
+     * the frame that draws it. The repaint that write asks for lands on the next
+     * frame, or re-enters this one on a host that runs frames synchronously,
+     * which is what `realign`'s guard is for.
+     */
+    sync(): void;
+    /** Remove every comparison and forget the chart. */
+    destroy(): void;
+    private _dispose;
+    private _needsAlignment;
+    private _rememberAlignment;
+    /**
+     * Preserve the first comparison's legacy placement when the scale is free.
+     * Additional comparisons need their own baselines, and an occupied volume
+     * or left scale must keep its source and units.
+     */
+    private _scaleIdFor;
+    private _openPane;
+    private _closePane;
+    private _applyMode;
+    private _restoreScale;
+    private _restoreMode;
+    /**
+     * Give the overlay the same band of percent the primary axis is showing, so
+     * equal moves land on equal pixels and the divergence between two
+     * instruments is the thing you see.
+     *
+     * Each scale has its own price baseline, and rebasing maps price to the
+     * ratio `price / baseline`. So the
+     * two scales agree exactly when their ranges hold the same ratios, which is
+     * one multiplication: the primary's range times `baseline_overlay /
+     * baseline_primary`. It holds for `indexed-to-100` and `percentage` alike,
+     * since they are one ladder a hundred points apart.
+     *
+     * A null baseline means this scale is not rebasing (linear, logarithmic, or
+     * a pane with nothing visible on it yet). Then there is no shared ladder to
+     * join and the overlay keeps its own autoscale, which is what mode 'none'
+     * asks for: two instruments each filling the pane, comparable in shape only.
+     *
+     * The overlay stays under autoscale throughout, even though the range it
+     * measures is overwritten here every frame. That measurement is one pass over
+     * bars the renderer is about to walk anyway, and paying for it buys the
+     * failure mode we want: a chart that stops calling `sync` falls back to an
+     * independently scaled overlay instead of freezing on a stale range.
+     */
+    private _mirror;
+    private _primaryBars;
+    private _record;
+    private _visible;
+    private _visiblePrimary;
+    private _commonAnchor;
+    private _setSuppressed;
+    private _write;
+    private _align;
+    /**
+     * Ask for a full repaint after a mode change. The pane hands a rebasing scale
+     * its baseline during the autoscale pass, so a `Light` repaint (all a
+     * primitive's `requestUpdate` raises) would paint the new mode before it has
+     * anything to quote against. `applyOptions` is the series handle's own route
+     * to a Full invalidation, and an empty patch changes no style. Several of
+     * them coalesce into one frame, so asking every comparison costs nothing.
+     */
+    private _repaint;
+}
+/**
+ * The controller for a chart, created on first use. Use it to change the mode
+ * for the whole chart, to list what is on it, or to clear it.
+ */
+declare function comparisonController(chart: ComparisonChartHost, options?: ComparisonControllerOptions): ComparisonController;
+/**
+ * Put an instrument on the chart next to the primary one:
+ *
+ * ```ts
+ * const bn = addComparison(chart, { symbol: 'BANKNIFTY', bars, color: '#f0b90b' });
+ * ```
+ *
+ * The pane switches to percentage while any comparison is on it and goes back
+ * to the mode it had when the last one leaves.
+ */
+declare function addComparison(chart: ComparisonChartHost, options: ComparisonOptions): ComparisonHandle;
+
+/** Options for a numeric snapshot of the chart's currently loaded data. */
+interface ChartDataCsvOptions {
+    /** Include every configured study's declared plots, including hidden studies. Default true. */
+    indicators?: boolean;
+    /** Override the chart's registered comparisons, for example with an explicitly managed controller's list. */
+    comparisons?: readonly Pick<ComparisonHandle, 'symbol' | 'barAt'>[];
+}
+/**
+ * CSV with UTC seconds, unrounded OHLC/volume/OI, study values and aligned comparison closes.
+ * Reads only installed primary rows, so replay exposes only its revealed prefix.
+ * Missing or nonfinite values are blank. Study values precede visual plot offsets;
+ * comparison values retain their own price units, regardless of axis rebasing.
+ * Headers have fixed prefixes so custom names cannot become spreadsheet formulas.
+ * Does not fetch data, include trading state or initiate a browser download.
+ */
+declare function exportChartDataCsv(chart: Chart, options?: ChartDataCsvOptions): string;
+
 type ChartObjectKind = 'source' | 'indicator' | 'drawing' | 'profile';
 interface ChartObjectCapabilities {
     readonly select: boolean;
@@ -5786,542 +6330,394 @@ declare class Canvas2dBackend implements IRenderBackend {
      * Nothing to do: the pane's `CanvasLayer` owns the backing store and sized it
      * already. Re-sizing it here would clear a bitmap that was just painted.
      */
-    resize(_widthPx: number, _heightPx: number, _dpr: number): void;
-    /** The same clear `CanvasLayer.clearBitmap` does, so the op stream is unchanged. */
-    beginFrame(clear: boolean): void;
-    drawSeries(entry: RendererEntry, items: readonly DrawItem[], priceToY: (price: number) => number, barSpacing: number, dpr: number, style: SeriesStyle, rc: SeriesRenderContext): void;
-    /** Every call above drew straight to the canvas; there is nothing to flush. */
-    endFrame(): void;
-    overlay2d(): CanvasRenderingContext2D | null;
-    destroy(): void;
-}
-
-/**
- * Histogram / column renderer (ARCHITECTURE.md §6). Used for the volume pane.
- * Bars are drawn from a base value (0) up to each bar's close.
- */
-
-interface HistogramStyle {
-    color: string;
-    /** Optional separate colors keyed by an up/down flag set on the bar's volume sign. */
-    base: number;
-}
-declare const DEFAULT_HISTOGRAM_STYLE: HistogramStyle;
-
-/**
- * Market replay: walk a historical session forward bar by bar so a trader can
- * practise on it, and so every indicator redraws exactly as it stood at that
- * past moment.
- *
- * Headless, in the spirit of `DrawingController` (src/draw/controller.ts): it
- * owns the playhead and the transitions and ships no DOM, so the host renders
- * its own transport bar, scrub slider and clock from `state()` and the events.
- *
- * The mechanic is deliberately boring. Replay feeds the chart a **prefix** of
- * the full bar array through the ordinary `series.setData` path, and that is
- * what makes indicators free: `Chart._setData` calls `_recomputeIndicators` for
- * the primary series, and `IndicatorInstance.recompute` re-reads the whole
- * history from `sourceBars()`. Shorten that history and every indicator, level,
- * fill, marker and legend reconstructs itself as it was at that bar, with no
- * replay-aware code anywhere in the indicator tier.
- */
-
-/** Schedules a repeating callback and returns its canceller. Inject in tests. */
-type ReplayScheduler = (cb: () => void, intervalMs: number) => () => void;
-/**
- * The slice of the time scale replay saves and restores. Declared structurally
- * rather than as `TimeScale` so nothing here depends on the scale's shape
- * beyond the two numbers that *are* the viewport.
- */
-interface ReplayViewport {
-    readonly barSpacing: number;
-    readonly rightOffset: number;
-    setBarSpacing(value: number): void;
-    setRightOffset(value: number): void;
-}
-/**
- * The slice of the chart this controller needs. `Chart` satisfies it; declaring
- * it structurally keeps the controller testable against a stub and free of a
- * circular import back into core.
- */
-interface ReplayChartHost {
-    emit(event: string, payload: unknown): void;
-    readonly timeScale: ReplayViewport;
-    /**
-     * Optional. When the chart can name its own primary price series, `series`
-     * may be omitted and replay drives that one.
-     */
-    primarySeries?(): SeriesApi | null;
-}
-/** Everything a transport bar and a clock need, in one object. */
-interface ReplayState {
-    /** 0-based index of the newest bar currently on the chart. */
-    index: number;
-    /** Bars in the replay set (the scrub bar's maximum is `total - 1`). */
-    total: number;
-    playing: boolean;
-    /** Multiplier over `barMs`: 2 plays two bars per `barMs`. */
-    speed: number;
-    /**
-     * The bar at `index`, the replay clock's "now". Null when there is no data.
-     *
-     * Under intra-bar replay this is the **partial** bar as it stands this step,
-     * not the completed one, which is what makes it the right thing to drive a
-     * host's own forming volume bar or an OHLC readout from.
-     */
-    bar: Bar | null;
-    /**
-     * Which step of the forming bar this is, 0-based, and how many it takes. Both
-     * are 0 and 1 without `subBars`, so a transport that shows them needs no
-     * special case for the plain mode.
-     */
-    subIndex: number;
-    subSteps: number;
-}
-interface ReplayOptions {
-    /**
-     * The series replay drives. The first one owns the timeline; any others (a
-     * volume histogram, a comparison line) are truncated to the same instant by
-     * time, because the shared DataLayer merges *every* series onto one axis and
-     * a series left at full length would drag future timestamps back onto it.
-     *
-     * Optional only if the host chart implements `primarySeries()`.
-     */
-    series?: SeriesApi | readonly SeriesApi[];
-    /**
-     * The full session. Defaults to the primary series' current data. Never
-     * mutated, and never handed to the chart as-is: each frame gets its own slice.
-     */
-    bars?: readonly Bar[];
-    /**
-     * Finer-grained bars the displayed ones are built from: the 1-minute session
-     * under a 5-minute chart. Given these, the playhead advances a **sub-bar** at
-     * a time and the newest bar forms in front of the user the way a live one
-     * does, instead of appearing complete. A 5-minute bar over 1-minute data
-     * takes five steps.
-     *
-     * They must cover the same session as `bars` and be sorted by time; sub-bars
-     * outside any displayed bucket are ignored. The last step of a bucket emits
-     * the displayed bar **verbatim** rather than the aggregate, so a bucket always
-     * closes on exactly the number the chart would have shown without this option,
-     * whatever the two feeds disagree about in between.
-     *
-     * Only the first driven series forms partially. Followers are cut to completed
-     * buckets, because the controller cannot know how to half-aggregate an
-     * arbitrary one: a volume histogram is summed, not OHLC-merged. The partial
-     * bar reaches the host as `ReplayState.bar` on every frame, so a host that
-     * wants a growing volume bar writes it from there.
-     */
-    subBars?: readonly Bar[];
-    /** Bar to open at (0-based). Default 0. */
-    startIndex?: number;
-    /** Wall-clock milliseconds per bar at speed 1. Default 1000. */
-    barMs?: number;
-    /** Initial speed multiplier. Default 1. */
-    speed?: number;
-    /** Called on every playhead move, after the chart has been updated. */
-    onFrame?: (state: ReplayState) => void;
-    /** Playback clock. Default `performance.now`. */
-    now?: () => number;
-    /** Playback timer. Default `setInterval`. */
-    scheduler?: ReplayScheduler;
-}
-declare class ReplayController {
-    private readonly _chart;
-    private readonly _series;
-    private readonly _bars;
-    /** What each driven series held before replay took over, for `stop()`. */
-    private readonly _restore;
-    private readonly _view;
-    private readonly _onFrame;
-    private readonly _now;
-    private readonly _schedule;
-    private readonly _barMs;
-    private readonly _startIndex;
-    private readonly _subBars;
-    /**
-     * For each displayed bar, where its sub-bars start in `_subBars` and how many
-     * there are. Built once: the alternative is a binary search per step, on a
-     * path that runs on every played frame.
-     *
-     * A bucket with no sub-bars takes one step and shows the displayed bar, so a
-     * gap in the finer feed costs that bar its formation, not its existence.
-     */
-    private readonly _subStart;
-    private readonly _subCount;
-    private readonly _intra;
-    private _speed;
-    private _index;
-    /** Step within the forming bar, 0-based. Always 0 without `subBars`. */
-    private _sub;
-    private _playing;
-    /** True once replay owns the chart's data; false before start and after stop. */
-    private _active;
-    private _cancel;
-    private _interval;
-    /** Clock reading the last advance was charged to; keeps playback drift-free. */
-    private _lastAdvance;
-    /**
-     * Constructing the controller **enters replay**: it snapshots the chart's data
-     * and viewport and immediately shows `startIndex`. That is the gesture a
-     * replay button makes, and it means the snapshot is taken before anything has
-     * moved, so `stop()` can put the user back exactly where they were.
-     */
-    constructor(chart: ReplayChartHost, options?: ReplayOptions);
-    /**
-     * Map every sub-bar onto the displayed bar whose bucket it falls in.
-     *
-     * The displayed bars' own times are the bucket starts, so one forward pass
-     * over both sorted arrays does it. A sub-bar before the first displayed bar
-     * belongs to no bucket and is dropped rather than folded into bar 0, which
-     * would open that bar at a price the chart never showed.
-     */
-    private _buildBuckets;
-    /** How many steps the bar at `index` takes. At least one, always. */
-    private _steps;
-    /**
-     * Jump the playhead to a bar. Out-of-range values clamp to the session.
-     *
-     * A seek lands on a **complete** bar even under intra-bar replay: scrubbing to
-     * a half-formed candle is not a position anyone asks for, and it would make
-     * the same slider position mean different things on the way past.
-     */
-    seek(index: number): void;
-    /**
-     * Move `n` steps forward. Stops dead at the end of the session.
-     *
-     * A step is one displayed bar normally, and one sub-bar under intra-bar
-     * replay, so the transport button means "advance the chart by the smallest
-     * amount it can show" in both modes.
-     */
-    step(n?: number): void;
-    /** Move `n` steps back. Stops dead at the first bar. */
-    stepBack(n?: number): void;
-    /**
-     * Move the playhead `delta` steps, carrying across bar boundaries.
-     *
-     * Written as a walk rather than arithmetic on a flat step count because
-     * buckets hold different numbers of sub-bars: a session with a gap, or a
-     * partial first bucket, has no constant steps-per-bar to divide by.
-     */
-    private _advance;
-    /**
-     * Start (or re-speed) playback. Calling it on the last bar plays nothing and
-     * reports `replay:end` instead of arming a timer that could never advance.
-     */
-    play(options?: {
-        speed?: number;
-    }): void;
-    /** Halt playback, leaving the playhead (and the chart) where it is. */
-    pause(): void;
-    /**
-     * Leave replay: every driven series gets its pre-replay data back and the
-     * viewport is restored to the pixel, so a user who exits does not lose their
-     * place. Safe to call twice; a later `seek`/`step`/`play` re-enters replay
-     * from `startIndex`.
-     */
-    stop(): void;
-    state(): ReplayState;
-    /**
-     * Put the chart at `index`. Every transition goes through here (seek, step
-     * and each played frame alike), so arriving at a bar leaves the chart in the
-     * same state however the user got there.
-     */
-    private _apply;
-    /**
-     * One timer tick. The number of bars owed comes from the clock, not from the
-     * tick count, so a coarse or throttled timer still plays at the requested
-     * speed, and a host may drive this from rAF instead with no change here.
-     */
-    private readonly _tick;
-    /** True on the last step of the last bar, which is where playback stops. */
-    private _atEnd;
-    /** The session is over: stop the timer and tell the host once. */
-    private _end;
-    private _stopTimer;
+    resize(_widthPx: number, _heightPx: number, _dpr: number): void;
+    /** The same clear `CanvasLayer.clearBitmap` does, so the op stream is unchanged. */
+    beginFrame(clear: boolean): void;
+    drawSeries(entry: RendererEntry, items: readonly DrawItem[], priceToY: (price: number) => number, barSpacing: number, dpr: number, style: SeriesStyle, rc: SeriesRenderContext): void;
+    /** Every call above drew straight to the canvas; there is nothing to flush. */
+    endFrame(): void;
+    overlay2d(): CanvasRenderingContext2D | null;
+    destroy(): void;
 }
 
 /**
- * Aligning a second instrument onto the primary series' bars.
- *
- * The x-axis is a gapless logical index over the times the shared DataLayer
- * holds (ARCHITECTURE.md §4.1, §5.3), so two instruments do not share a bar
- * index and cannot be laid side by side by position. They are matched by
- * timestamp, and the two directions of mismatch get opposite answers:
- *
- * - **A comparison bar with no primary bar is dropped.** The DataLayer merges
- *   *every* series' times into one index space, so a time only the comparison
- *   has would mint a new logical index: a column the primary instrument has no
- *   candle for, inserted mid-chart, shifting every bar after it. That happens
- *   for real (a different exchange's holiday calendar, a 24/7 instrument next
- *   to an NSE one, a feed that emits a stray print), and warping the primary's
- *   own axis to accommodate a comparison is never the right trade. The print is
- *   counted in `dropped` so a host can say so rather than silently losing it.
- *
- * - **A primary bar with no comparison bar becomes whitespace**, which is a NaN
- *   bar the line renderer breaks across, so the comparison shows a *gap*. The
- *   alternative, carrying the last known value forward, draws a flat segment
- *   through a session the instrument never traded and, worse, in percentage
- *   mode it anchors the move on the far side of the gap to a print that does
- *   not exist. Omitting the bar entirely is worse still: the renderer would
- *   join the two sides with one straight line across the holiday.
- *
- * Matching is on the exact timestamp. Bar-open times are bucketed by the candle
- * builder (§10.2) and stored as UTC seconds (§4.0), so two instruments on the
- * same interval agree to the second; anything that does not agree is a
- * different interval, which no tolerance window could rescue.
+ * Histogram / column renderer (ARCHITECTURE.md §6). Used for the volume pane.
+ * Bars are drawn from a base value (0) up to each bar's close.
  */
 
-/** What one alignment pass did, for a host that wants to report coverage. */
-interface ComparisonAlignment {
-    /** Items handed to the comparison series: one per primary bar. */
-    bars: number;
-    /** Primary bars the comparison also traded (a value is drawn). */
-    matched: number;
-    /** Primary bars with no comparison print (drawn as a gap). */
-    gaps: number;
-    /** Comparison prints discarded for having no primary bar at that time. */
-    dropped: number;
+interface HistogramStyle {
+    color: string;
+    /** Optional separate colors keyed by an up/down flag set on the bar's volume sign. */
+    base: number;
+}
+declare const DEFAULT_HISTOGRAM_STYLE: HistogramStyle;
+
+/** UTC seconds when this recorded candle becomes complete and available. */
+type ReplayBarEndTime = (bar: Bar, index: number) => number;
+/** Explicit availability avoids treating a coarse candle's open as its close. */
+interface ReplayTiming {
+    barEndTime: ReplayBarEndTime;
+    /** Required with finer bars; their final prices also need a known availability time. */
+    subBarEndTime?: ReplayBarEndTime;
 }
-/**
- * Project `comparison` onto `primary`'s bars: one item per primary bar, in the
- * primary's order, so the result occupies exactly the logical indices the chart
- * already has and adds none of its own.
- *
- * Neither input is mutated and neither has to be sorted: matching goes through
- * a time map, which also collapses a repeated timestamp to its last item, the
- * same rule the DataLayer applies when it merges (`sortedUniqueByTime`).
- */
-declare function alignToPrimary(primary: readonly Bar[], comparison: readonly SeriesDataItem[]): {
-    items: SeriesDataItem[];
-    alignment: ComparisonAlignment;
-};
 
 /**
- * Multi-symbol comparison: put a second instrument on the primary one's pane
- * and read them together (NIFTY against BANKNIFTY, a stock against its index).
- *
- * Headless, in the spirit of `DrawingController` (src/draw/controller.ts) and
- * `ReplayController`: it owns the series, the alignment and the scales, and
- * ships no DOM, so the host draws its own symbol chips and legend rows from
- * `list()`.
- *
- * Three decisions carry the design:
- *
- * 1. **The comparison never touches the primary's axis.** It goes on the pane's
- *    hidden overlay scale (`priceScaleId: ''`, see `Pane._scaleFor`), which
- *    autoscales on its own and draws no ticks, so a 46,000 instrument next to a
- *    22,000 one cannot compress the primary's candles or relabel its ladder.
- *
- * 2. **Comparability comes from the scale, not from the data.** The bars handed
- *    over are stored as the instrument's own prices, so the legend, the
- *    crosshair and any live update still speak in real prices. What makes the
- *    lines readable together is the pane mode: `percentage` and
- *    `indexed-to-100` give every scale its own baseline (the first *visible*
- *    bar, so panning re-bases), and `_mirror` then gives the overlay the same
- *    band of percent the primary's axis is showing. Without that mirror each
- *    scale would autoscale to its own data and a 1% mover would look exactly
- *    like a 10% mover, both filling the pane.
+ * Market replay: walk a historical session forward bar by bar so a trader can
+ * practise on it, and so every indicator redraws exactly as it stood at that
+ * past moment.
  *
- * 3. **Alignment is by timestamp** and lives in `./align`, which documents what
- *    happens in each direction of mismatch.
+ * Headless, in the spirit of `DrawingController` (src/draw/controller.ts): it
+ * owns the playhead and the transitions and ships no DOM, so the host renders
+ * its own transport bar, scrub slider and clock from `state()` and the events.
  *
- * Known limit: a pane has exactly *one* hidden overlay scale, so every
- * comparison on a pane shares one baseline. That is exactly right for one
- * comparison, which is the common case, and it is why a second comparison in
- * the same pane is quoted against the first instrument's price. Keyed overlay
- * scales in `Pane` are the fix; until then, put further instruments on their
- * own pane with `paneIndex`.
+ * The mechanic is deliberately boring. Replay feeds the chart a **prefix** of
+ * the full bar array through the ordinary `series.setData` path, and that is
+ * what makes indicators free: `Chart._setData` calls `_recomputeIndicators` for
+ * the primary series, and `IndicatorInstance.recompute` re-reads the whole
+ * history from `sourceBars()`. Shorten that history and every indicator, level,
+ * fill, marker and legend reconstructs itself as it was at that bar, with no
+ * replay-aware code anywhere in the indicator tier.
  */
 
+/** Schedules a repeating callback and returns its canceller. Inject in tests. */
+type ReplayScheduler = (cb: () => void, intervalMs: number) => () => void;
 /**
- * How the pane quotes prices while a comparison is on it. The two rebasing
- * modes are the reason the lines are comparable at all; `none` leaves the
- * pane's own mode alone, for a host that wants the raw overlay.
+ * The slice of the time scale replay saves and restores. Declared structurally
+ * rather than as `TimeScale` so nothing here depends on the scale's shape
+ * beyond the two numbers that *are* the viewport.
  */
-type ComparisonMode = 'percentage' | 'indexed-to-100' | 'none';
-interface ComparisonOptions {
-    /** Instrument label, e.g. 'BANKNIFTY'. Carried on the handle for the host's UI. */
-    symbol: string;
-    /** The instrument's own bars. Aligned to the primary series, see `./align`. */
-    bars: readonly SeriesDataItem[];
-    /** Line colour shorthand; `style.color` wins if both are given. */
-    color?: string;
-    /** Style overrides merged onto the chart type's defaults. */
-    style?: SeriesStyle;
-    /** Renderer for the comparison. Default 'line'. */
-    type?: SeriesType;
-    /** Pane to draw on. Default 0, the price pane. */
-    paneIndex?: number;
-}
-interface ComparisonControllerOptions {
-    /** Pane mode applied while any comparison is on it. Default 'percentage'. */
-    mode?: ComparisonMode;
+interface ReplayViewport {
+    readonly barSpacing: number;
+    readonly rightOffset: number;
+    setBarSpacing(value: number): void;
+    setRightOffset(value: number): void;
 }
-/** What `addComparison` hands back: one instrument on the chart. */
-interface ComparisonHandle {
-    readonly symbol: string;
+/**
+ * The slice of the chart this controller needs. `Chart` satisfies it; declaring
+ * it structurally keeps the controller testable against a stub and free of a
+ * circular import back into core.
+ */
+interface ReplayChartHost {
+    emit(event: string, payload: unknown): void;
+    readonly timeScale: ReplayViewport;
     /**
-     * The series this comparison draws through, for style patches and markers.
-     * Data set on it directly skips alignment (use `setBars`), and removing it
-     * directly leaves the pane rebased with nothing on it (use `remove`).
+     * Optional. When the chart can name its own primary price series, `series`
+     * may be omitted and replay drives that one.
      */
-    readonly series: SeriesApi;
-    readonly paneIndex: number;
-    /** The hidden scale it maps to. Never the pane's own price axis. */
-    priceScale(): PriceScale;
-    /** How the last alignment against the primary's bars went. */
-    alignment(): ComparisonAlignment;
-    /** Replace the instrument's bars (a longer history, a refreshed fetch). */
-    setBars(bars: readonly SeriesDataItem[]): void;
-    /** Take this instrument off the chart. Safe to call twice. */
-    remove(): void;
-    /** Every comparison on this chart, in the order they were added. */
-    list(): readonly ComparisonHandle[];
+    primarySeries?(): SeriesApi | null;
 }
-/**
- * The slice of a pane the controller reads. Declared structurally, like
- * `ReplayViewport`, so nothing here depends on `Pane` beyond the two members
- * that decide where a comparison can go.
- */
-interface ComparisonPane {
-    readonly priceScale: PriceScale;
-    series(): readonly {
-        readonly scaleId: string;
-    }[];
+/** Everything a transport bar and a clock need, in one object. */
+interface ReplayState {
+    /** 0-based newest bar; -1 before the first observation in timed replay. */
+    index: number;
+    /** Bars in the replay set (the scrub bar's maximum is `total - 1`). */
+    total: number;
+    playing: boolean;
+    /** Multiplier over `barMs`: 2 plays two bars per `barMs`. */
+    speed: number;
+    /**
+     * The bar at `index`, the replay clock's "now". Null when there is no data.
+     *
+     * Under intra-bar replay this is the **partial** bar as it stands this step,
+     * not the completed one, which is what makes it the right thing to drive a
+     * host's own forming volume bar or an OHLC readout from.
+     */
+    bar: Bar | null;
+    /**
+     * Which step of the forming bar this is, 0-based, and how many it takes. Both
+     * are 0 and 1 without `subBars`, so a transport that shows them needs no
+     * special case for the plain mode.
+     */
+    subIndex: number;
+    subSteps: number;
 }
-/**
- * The slice of the chart this controller needs. `Chart` satisfies it; declaring
- * it structurally keeps the controller testable against a stub.
- */
-interface ComparisonChartHost {
-    addSeries(type: SeriesType, options: AddSeriesOptions): SeriesApi;
-    panes(): readonly ComparisonPane[];
-    addPrimitive(primitive: IPrimitive, paneIndex?: number): void;
-    removePrimitive(primitive: IPrimitive): void;
-    primarySeries(): SeriesApi | null;
-    /** Only `length` is read: it changes exactly when the shared time axis does. */
-    readonly dataLayer: {
-        readonly length: number;
-    };
+interface ReplayOptions {
+    /** Explicit candle availability for time-aligned replay. Omitted preserves index-based replay. */
+    timing?: ReplayTiming;
+    /** Initial UTC availability time. Requires timing; otherwise startIndex selects a completed candle. */
+    startTime?: number;
+    /** False prepares and validates the snapshot without changing the chart. Default true. */
+    autoStart?: boolean;
+    /**
+     * The series replay drives. The first one owns the timeline; any others (a
+     * volume histogram, a comparison line) are truncated to the same instant by
+     * time, because the shared DataLayer merges *every* series onto one axis and
+     * a series left at full length would drag future timestamps back onto it.
+     *
+     * Optional only if the host chart implements `primarySeries()`.
+     */
+    series?: SeriesApi | readonly SeriesApi[];
+    /**
+     * The full session. Defaults to the primary series' current data. Never
+     * mutated, and never handed to the chart as-is: each frame gets its own slice.
+     */
+    bars?: readonly Bar[];
+    /**
+     * Finer-grained bars the displayed ones are built from: the 1-minute session
+     * under a 5-minute chart. Given these, the playhead advances a **sub-bar** at
+     * a time and the newest bar forms in front of the user the way a live one
+     * does, instead of appearing complete. A 5-minute bar over 1-minute data
+     * takes five steps.
+     *
+     * They must cover the same session as `bars` and be sorted by time; sub-bars
+     * outside any displayed bucket are ignored. The last step of a bucket emits
+     * the displayed bar **verbatim** rather than the aggregate, so a bucket always
+     * closes on exactly the number the chart would have shown without this option,
+     * whatever the two feeds disagree about in between.
+     *
+     * Only the first driven series forms partially. Followers are cut to completed
+     * buckets, because the controller cannot know how to half-aggregate an
+     * arbitrary one: a volume histogram is summed, not OHLC-merged. The partial
+     * bar reaches the host as `ReplayState.bar` on every frame, so a host that
+     * wants a growing volume bar writes it from there.
+     */
+    subBars?: readonly Bar[];
+    /** Bar to open at (0-based). Default 0. */
+    startIndex?: number;
+    /** Wall-clock milliseconds per bar at speed 1. Default 1000. */
+    barMs?: number;
+    /** Initial speed multiplier. Default 1. */
+    speed?: number;
+    /** Called on every playhead move, after the chart has been updated. */
+    onFrame?: (state: ReplayState) => void;
+    /** Playback clock. Default `performance.now`. */
+    now?: () => number;
+    /** Playback timer. Default `setInterval`. */
+    scheduler?: ReplayScheduler;
 }
-declare class ComparisonController {
+declare class ReplayController {
     private readonly _chart;
-    private _mode;
-    private readonly _panes;
-    /** Insertion-ordered, and the handle is the key so `remove` is a lookup. */
-    private readonly _items;
+    private readonly _series;
+    private readonly _bars;
+    /** What each driven series held before replay took over, for `stop()`. */
+    private readonly _restore;
+    private readonly _view;
+    private readonly _onFrame;
+    private readonly _now;
+    private readonly _schedule;
+    private readonly _barMs;
+    private readonly _startIndex;
+    private readonly _timeline;
+    private readonly _startTime;
+    private _time;
+    private _pointIndex;
+    private readonly _subBars;
     /**
-     * `dataLayer.length` as of the last alignment. Alignment depends only on the
-     * primary's set of *times*, and that set is what the length counts, so this
-     * is an O(1) staleness check for a per-frame hook (see `sync`).
+     * For each displayed bar, where its sub-bars start in `_subBars` and how many
+     * there are. Built once: the alternative is a binary search per step, on a
+     * path that runs on every played frame.
+     *
+     * A bucket with no sub-bars takes one step and shows the displayed bar, so a
+     * gap in the finer feed costs that bar its formation, not its existence.
      */
-    private _alignedAt;
-    /** Guards `realign` against re-entry through its own `setData` repaint. */
-    private _realigning;
-    constructor(chart: ComparisonChartHost, options?: ComparisonControllerOptions);
-    /** Put an instrument on the chart alongside the primary series. */
-    add(options: ComparisonOptions): ComparisonHandle;
-    /** Take one instrument off. Returns false if it was already gone. */
-    remove(handle: ComparisonHandle): boolean;
-    /** Every comparison on the chart, in the order they were added. */
-    list(): readonly ComparisonHandle[];
-    /** Take them all off, putting every pane back the way it was found. */
-    clear(): void;
+    private readonly _subStart;
+    private readonly _subCount;
+    private readonly _intra;
+    private _speed;
+    private _index;
+    /** Step within the forming bar, 0-based. Always 0 without `subBars`. */
+    private _sub;
+    private _playing;
+    /** True once replay owns the chart's data; false before start and after stop. */
+    private _active;
+    private _cancel;
+    private _interval;
+    /** Clock reading the last advance was charged to; keeps playback drift-free. */
+    private _lastAdvance;
     /**
-     * Change the mode the panes are held in while comparisons are on them.
-     * Panes that already have one switch immediately.
+     * Constructing the controller **enters replay**: it snapshots the chart's data
+     * and viewport and immediately shows `startIndex`. That is the gesture a
+     * replay button makes, and it means the snapshot is taken before anything has
+     * moved, so `stop()` can put the user back exactly where they were.
      */
-    setMode(mode: ComparisonMode): void;
-    get mode(): ComparisonMode;
+    constructor(chart: ReplayChartHost, options?: ReplayOptions);
     /**
-     * Re-project every instrument onto the primary's current bars. Called for
-     * free when the shared time axis changes (see `sync`); a host only needs it
-     * after replacing the primary's data with a *different* set of the same
-     * length, which the length check cannot see.
+     * Map every sub-bar onto the displayed bar whose bucket it falls in.
+     *
+     * The displayed bars' own times are the bucket starts, so one forward pass
+     * over both sorted arrays does it. A sub-bar before the first displayed bar
+     * belongs to no bucket and is dropped rather than folded into bar 0, which
+     * would open that bar at a price the chart never showed.
      */
-    realign(): void;
+    private _buildBuckets;
+    /** How many steps the bar at `index` takes. At least one, always. */
+    private _steps;
     /**
-     * Bring the overlay scales in line with the primary axis, re-aligning first
-     * if the shared time axis has moved under us (a live bar, history paged in,
-     * a replay step). Runs once per base paint through the per-pane hook.
+     * Jump the playhead to a bar. Out-of-range values clamp to the session.
      *
-     * Re-aligning here writes series data mid-frame, which is safe because the
-     * hook is a `bottom` primitive: it runs after the pane has autoscaled and
-     * before any series is drawn, so the frame that notices the change is also
-     * the frame that draws it. The repaint that write asks for lands on the next
-     * frame, or re-enters this one on a host that runs frames synchronously,
-     * which is what `realign`'s guard is for.
+     * A seek lands on a **complete** bar even under intra-bar replay: scrubbing to
+     * a half-formed candle is not a position anyone asks for, and it would make
+     * the same slider position mean different things on the way past.
      */
-    sync(): void;
-    /** Remove every comparison and forget the chart. */
-    destroy(): void;
+    seek(index: number): void;
+    /** Project only observations available by these UTC seconds. Requires timing. */
+    seekTime(time: number): void;
+    /** Availability clock in timed mode; the displayed bar's timestamp in legacy mode. */
+    time(): number | null;
+    /** Observation timestamps for a shared clock. Requires timing; returns a copy. */
+    timePoints(): readonly number[];
     /**
-     * Where a comparison can sit on a pane. The hidden overlay is the right
-     * answer, but there is only one of it per pane and the volume histogram in
-     * the price pane is usually already on it (that is what `priceScaleId: ''`
-     * is best known for). Sharing it would autoscale price and volume together
-     * and flatten both, so when it is taken the comparison goes to the left axis
-     * instead: a visible second ladder is a far smaller surprise than an
-     * invisible line at the bottom of the pane.
+     * Move `n` steps forward. Stops dead at the end of the session.
+     *
+     * A step is one displayed bar normally, and one sub-bar under intra-bar
+     * replay, so the transport button means "advance the chart by the smallest
+     * amount it can show" in both modes.
      */
-    private _scaleIdFor;
-    private _openPane;
-    private _closePane;
-    private _applyMode;
-    private _restoreMode;
+    step(n?: number): void;
+    /** Move `n` steps back. Stops dead at the first bar. */
+    stepBack(n?: number): void;
     /**
-     * Give the overlay the same band of percent the primary axis is showing, so
-     * equal moves land on equal pixels and the divergence between two
-     * instruments is the thing you see.
-     *
-     * Both scales rebase against a baseline of their own (the first visible bar
-     * on each), and a rebase maps price to the ratio `price / baseline`. So the
-     * two scales agree exactly when their ranges hold the same ratios, which is
-     * one multiplication: the primary's range times `baseline_overlay /
-     * baseline_primary`. It holds for `indexed-to-100` and `percentage` alike,
-     * since they are one ladder a hundred points apart.
-     *
-     * A null baseline means this scale is not rebasing (linear, logarithmic, or
-     * a pane with nothing visible on it yet). Then there is no shared ladder to
-     * join and the overlay keeps its own autoscale, which is what mode 'none'
-     * asks for: two instruments each filling the pane, comparable in shape only.
+     * Move the playhead `delta` steps, carrying across bar boundaries.
      *
-     * The overlay stays under autoscale throughout, even though the range it
-     * measures is overwritten here every frame. That measurement is one pass over
-     * bars the renderer is about to walk anyway, and paying for it buys the
-     * failure mode we want: a chart that stops calling `sync` falls back to an
-     * independently scaled overlay instead of freezing on a stale range.
+     * Written as a walk rather than arithmetic on a flat step count because
+     * buckets hold different numbers of sub-bars: a session with a gap, or a
+     * partial first bucket, has no constant steps-per-bar to divide by.
      */
-    private _mirror;
-    private _primaryBars;
-    private _align;
+    private _advance;
     /**
-     * Ask for a full repaint after a mode change. The pane hands a rebasing scale
-     * its baseline during the autoscale pass, so a `Light` repaint (all a
-     * primitive's `requestUpdate` raises) would paint the new mode before it has
-     * anything to quote against. `applyOptions` is the series handle's own route
-     * to a Full invalidation, and an empty patch changes no style. Several of
-     * them coalesce into one frame, so asking every comparison costs nothing.
+     * Start (or re-speed) playback. Calling it on the last bar plays nothing and
+     * reports `replay:end` instead of arming a timer that could never advance.
      */
-    private _repaint;
+    play(options?: {
+        speed?: number;
+    }): void;
+    /** Halt playback, leaving the playhead (and the chart) where it is. */
+    pause(): void;
+    /**
+     * Leave replay: every driven series gets its pre-replay data back and the
+     * viewport is restored to the pixel, so a user who exits does not lose their
+     * place. Safe to call twice; a later `seek`/`step`/`play` re-enters replay
+     * from `startIndex`.
+     */
+    stop(): void;
+    state(): ReplayState;
+    /**
+     * Put the chart at `index`. Every transition goes through here (seek, step
+     * and each played frame alike), so arriving at a bar leaves the chart in the
+     * same state however the user got there.
+     */
+    private _apply;
+    private _write;
+    /**
+     * One timer tick. The number of bars owed comes from the clock, not from the
+     * tick count, so a coarse or throttled timer still plays at the requested
+     * speed, and a host may drive this from rAF instead with no change here.
+     */
+    private readonly _tick;
+    /** True on the last step of the last bar, which is where playback stops. */
+    private _atEnd;
+    /** The session is over: stop the timer and tell the host once. */
+    private _end;
+    private _stopTimer;
+}
+
+/** True while replay owns this chart, including when its playback clock is paused. */
+declare function isReplaying(chart: object): boolean;
+
+type ReplayScope = 'focused' | 'all';
+/** Chart implements this; headless hosts may supply the lifecycle hooks too. */
+interface ReplayGroupChartHost extends ReplayChartHost {
+    readonly isDestroyed?: boolean;
+    on?(event: 'destroy', callback: () => void): () => void;
+}
+interface ReplayGroupMember {
+    id: string;
+    chart: ReplayGroupChartHost;
+    /** Transport and clock options belong to the group. */
+    options: Pick<ReplayOptions, 'series' | 'bars' | 'subBars' | 'onFrame'> & {
+        timing: ReplayTiming;
+    };
+}
+interface ReplayGroupState {
+    active: boolean;
+    destroyed: boolean;
+    scope: ReplayScope;
+    focusedId: string;
+    /** UTC availability time, or null when the active histories have no observations. */
+    time: number | null;
+    /** Index in the union of active observation times; -1 before the first. */
+    index: number;
+    total: number;
+    playing: boolean;
+    speed: number;
+    members: readonly {
+        id: string;
+        active: boolean;
+        state: ReplayState;
+    }[];
+}
+interface ReplayGroupOptions {
+    /** Default focused. Changing toolbar focus alone does not redirect replay. */
+    scope?: ReplayScope;
+    /** Default the first member. */
+    focusedId?: string;
+    startTime?: number;
+    /** Wall-clock milliseconds per observation at speed 1. Default 1000. */
+    barMs?: number;
+    speed?: number;
+    now?: () => number;
+    scheduler?: ReplayScheduler;
+    /** Runs after all active charts reach a frame or transport transition. */
+    onChange?: (state: ReplayGroupState) => void;
+}
+/** One opt-in clock driving validated ReplayControllers by availability time. */
+declare class ReplayGroup {
+    private _members;
+    private _activeIds;
+    private _times;
+    private _scope;
+    private _focusedId;
+    private _time;
+    private _startTime;
+    private _active;
+    private _destroyed;
+    private _playing;
+    private _busy;
+    private _closing;
+    private _revision;
+    private _speed;
+    private readonly _barMs;
+    private readonly _now;
+    private readonly _scheduler;
+    private readonly _onChange?;
+    private _cancel;
+    private _clockRevision;
+    private _lastAdvance;
+    private _pending;
+    constructor(members: readonly ReplayGroupMember[], options?: ReplayGroupOptions);
+    state(): ReplayGroupState;
+    seekTime(time: number): void;
+    /** Seek an observation index, clamped to the active timeline. */
+    seek(index: number): void;
+    step(n?: number): void;
+    stepBack(n?: number): void;
+    private _move;
+    setScope(scope: ReplayScope, focusedId?: string): void;
+    play(options?: {
+        speed?: number;
+    }): void;
+    pause(): void;
+    /** Restore data/viewports, retaining the captured session for later re-entry. */
+    stop(): void;
+    /** Restore surviving charts and release snapshots, listeners and ownership. */
+    destroy(): void;
+    private _validateScope;
+    private _prepare;
+    private _prepareEntering;
+    private _install;
+    private _wanted;
+    private _rebuildTimes;
+    private _check;
+    private _apply;
+    private _atEnd;
+    private _tick;
+    private _clearClock;
+    private _emit;
+    private _notify;
+    private _execute;
+    private _chartGone;
+    private _cleanup;
 }
-/**
- * The controller for a chart, created on first use. Use it to change the mode
- * for the whole chart, to list what is on it, or to clear it.
- */
-declare function comparisonController(chart: ComparisonChartHost, options?: ComparisonControllerOptions): ComparisonController;
-/**
- * Put an instrument on the chart next to the primary one:
- *
- * ```ts
- * const bn = addComparison(chart, { symbol: 'BANKNIFTY', bars, color: '#f0b90b' });
- * ```
- *
- * The pane switches to percentage while any comparison is on it and goes back
- * to the mode it had when the last one leaves.
- */
-declare function addComparison(chart: ComparisonChartHost, options: ComparisonOptions): ComparisonHandle;
 
 /**
  * Time alignment for chart linking: the one thing that makes a grid of charts
@@ -6409,7 +6805,7 @@ declare function followerRange(leader: LinkDataLayer, follower: LinkDataLayer, r
  * ships no DOM, so the host draws its own link badge / colour chips and decides
  * which charts belong to which group.
  *
- * Three channels sync, each switchable on its own because a user routinely
+ * Four channels sync, each switchable on its own because a user routinely
  * wants one without the others (mirror the cursor across four timeframes but
  * keep each zoom; or slave every chart's symbol but let each keep its own
  * window):
@@ -6417,6 +6813,7 @@ declare function followerRange(leader: LinkDataLayer, follower: LinkDataLayer, r
  * - **crosshair**: hovering one chart marks the same instant on the others.
  * - **viewport**: panning or zooming one moves the others to the same window.
  * - **symbol**: changing the instrument on one changes it on the others.
+ * - **interval**: changing a timeframe asks each following host to adopt it.
  *
  * Four decisions carry the design.
  *
@@ -6476,6 +6873,8 @@ interface LinkChart {
     panes(): readonly unknown[];
     addPrimitive(primitive: IPrimitive, paneIndex?: number): void;
     removePrimitive(primitive: IPrimitive): void;
+    /** Optional readout support alongside the group's vertical marker. */
+    setLinkedCrosshairIndex?(index: number | null): void;
 }
 interface LinkOptions {
     /** Mirror the hovered instant onto every other member. Default true. */
@@ -6484,6 +6883,8 @@ interface LinkOptions {
     viewport?: boolean;
     /** Mirror the instrument, via each member's `onSymbol`. Default false. */
     symbol?: boolean;
+    /** Mirror the timeframe, via each member's `onInterval`. Default false. */
+    interval?: boolean;
     /** What a follower does with an instant it has no bar for. Default 'nearest'. */
     whenMissing?: LinkMissingPolicy;
 }
@@ -6496,6 +6897,10 @@ interface LinkMemberOptions {
      * it still broadcasts its own changes, it just never follows anyone else's.
      */
     onSymbol?: (symbol: string, chart: LinkChart) => void;
+    /** The interval this chart is showing, if the host tracks one. */
+    interval?: string;
+    /** Apply the interval synchronously; return false to refuse an unsupported token. */
+    onInterval?: (interval: string, chart: LinkChart) => boolean | void;
 }
 /** Every option resolved, as `options()` reports them. */
 type ResolvedLinkOptions = Required<LinkOptions>;
@@ -6505,6 +6910,7 @@ declare class LinkGroup {
     /** True while the group is applying a change to followers. See decision 3. */
     private _broadcasting;
     private _symbol;
+    private _interval;
     private _destroyed;
     constructor(options?: LinkOptions);
     options(): ResolvedLinkOptions;
@@ -6524,6 +6930,8 @@ declare class LinkGroup {
     has(chart: LinkChart): boolean;
     /** The instrument the group has agreed on, or null if nobody declared one. */
     symbol(): string | null;
+    /** Latest interval selected by a member, even while interval linking is off. */
+    interval(): string | null;
     /**
      * The member's own logical index its linked crosshair is marking, or null
      * when it is showing none (it is the chart being hovered, the leader's
@@ -6551,6 +6959,8 @@ declare class LinkGroup {
      * symbol sync is on, loads it into every other member that can follow.
      */
     setSymbol(chart: LinkChart, symbol: string): void;
+    /** Report a host-owned interval selection; followers opt in through `onInterval`. */
+    setInterval(chart: LinkChart, interval: string): void;
     /** Unlink everything: no listeners, no linked crosshairs, no references. */
     destroy(): void;
     private _onCrosshair;
@@ -6559,6 +6969,9 @@ declare class LinkGroup {
     private _applySymbol;
     /** Push the group's agreed symbol onto everyone who is not already on it. */
     private _convergeSymbol;
+    private _applyInterval;
+    private _followInterval;
+    private _convergeInterval;
     /**
      * Run `apply` on every member except the originator, exactly once, with the
      * echo guard held. `onLeader` (optional) runs on the originator itself.
@@ -6647,6 +7060,14 @@ interface Tick {
     ltq?: number;
     /** Cumulative day volume (Quote mode). */
     cumDayVolume?: number;
+    /**
+     * Open interest as at this tick, where the feed carries it. Unlike the two
+     * quantities above it is not accumulated into the bar: it replaces, because
+     * it is a level and not a flow (see `Bar.oi`). A feed that does not report it
+     * leaves the built bar without one, which is the honest result rather than a
+     * zero that reads as "nobody is holding this".
+     */
+    oi?: number;
 }
 interface CandleUpdate {
     bar: Bar;
@@ -7270,6 +7691,86 @@ interface TradeFeed {
     subscribePositions(cb: (positions: unknown[]) => void): UnsubscribeFn;
 }
 
+interface InstrumentCalendar {
+    /** HHMM-HHMM[:days], with opening weekdays 1 (Sunday) through 7. */
+    readonly sessions: readonly string[];
+    /** Local opening dates replace weekly sessions. An empty list closes that date. */
+    readonly exceptions?: Readonly<Record<string, readonly string[]>>;
+}
+/** Host-supplied market rules, separate from observations and saved user preferences. */
+interface InstrumentMetadata {
+    readonly symbol: string;
+    readonly exchange: string;
+    readonly timezone: string;
+    readonly priceTick: number;
+    readonly pricePrecision: number;
+    /** In the order adapter's units. This is a grid, never a lot conversion factor. */
+    readonly quantityStep: number;
+    readonly intervals: readonly string[];
+    readonly calendar: InstrumentCalendar;
+    readonly hasOpenInterest?: boolean;
+}
+interface InstrumentSession {
+    /** Local opening date, including for an overnight window. */
+    readonly date: string;
+    /** UTC seconds, inclusive. */
+    readonly open: number;
+    /** UTC seconds, exclusive. */
+    readonly close: number;
+}
+/** Validated, detached rules. Construction does not change global intervals or chart defaults. */
+declare class Instrument {
+    readonly metadata: InstrumentMetadata;
+    private readonly _sessions;
+    private readonly _exceptions;
+    constructor(input: unknown);
+    /** Provider tokens are exact: a feed may distinguish monthly M from minute m. */
+    supportsInterval(code: string): boolean;
+    /** Formats display only. The source bars retain their unrounded values. */
+    formatPrice(value: number): string;
+    /** Resolve an active window. Closed dates and breaks return null, never inferred hours. */
+    sessionAt(utcSeconds: number): InstrumentSession | null;
+    /** The host clears old bars and owns source loading; only metadata is applied here. */
+    applyTo(chart: Chart, interval: string): void;
+}
+
+type TradingOperation = 'place' | 'modify' | 'cancel';
+/** Optional restrictions on existing write paths; omissions preserve legacy support. */
+interface TradingCapabilities {
+    readonly place?: boolean | 'unknown';
+    readonly modify?: boolean | 'unknown';
+    readonly cancel?: boolean | 'unknown';
+    /** Accepted types for new orders. An empty list disables placement. */
+    readonly orderTypes?: readonly OrderType$1[];
+    /** Accepted modes for new orders; does not change the broker's actual mode. */
+    readonly modes?: readonly ('live' | 'analyzer')[];
+}
+interface TradingCapabilityRequest {
+    readonly operation: TradingOperation;
+    readonly symbol?: string;
+    readonly exchange?: string;
+    readonly orderId?: string;
+    readonly type?: OrderType$1;
+    readonly mode?: 'live' | 'analyzer';
+}
+/** A configured provider returning undefined declares that support is unavailable. */
+type TradingCapabilitySource = TradingCapabilities | ((request: Readonly<TradingCapabilityRequest>) => TradingCapabilities | undefined);
+type TradingCapabilityResult = {
+    supported: true;
+} | {
+    supported: false;
+    reason: string;
+};
+/** Shared by host controls and the write boundary. Never grants broker authority. */
+declare function checkTradingCapability(source: TradingCapabilitySource | undefined, request: TradingCapabilityRequest): TradingCapabilityResult;
+/** Raised only before delivery, so an unsupported write does not become ambiguous. */
+declare class TradingCapabilityError extends Error {
+    readonly preflight: true;
+    readonly operation: TradingOperation;
+    constructor(operation: TradingOperation, reason: string);
+}
+declare function assertTradingCapability(source: TradingCapabilitySource | undefined, request: TradingCapabilityRequest): void;
+
 /** Limits apply to each pool, whose identity belongs to one data feed. */
 interface HistoryRequestPoolOptions {
     maxConcurrent?: number;
@@ -7443,6 +7944,12 @@ interface OpenAlgoConfig {
     apiKey: string;
     /** Injectable fetch (defaults to global fetch); lets the adapter be tested offline. */
     fetchImpl?: typeof fetch;
+    /**
+     * Instrument capability from host metadata. Explicit false omits the API's
+     * placeholder OI column before it can become a misleading cash reading.
+     * Missing/unknown capability preserves finite observations, including zero.
+     */
+    hasOpenInterest?(request: Readonly<BarsRequest>): boolean | undefined;
 }
 interface HistoryRow {
     timestamp?: number | string;
@@ -7452,6 +7959,8 @@ interface HistoryRow {
     low: number;
     close: number;
     volume?: number;
+    /** Present on a derivatives response; the platform always sends the column. */
+    oi?: number;
 }
 interface HistoryResponse {
     status?: string;
@@ -7461,7 +7970,7 @@ interface HistoryResponse {
 /** Pure: coerce a row timestamp (epoch s / epoch ms / IST string) to UTC seconds. */
 declare function rowTimeToUtcSeconds(value: number | string): number;
 /** Pure: map an OpenAlgo history response into sorted internal bars. */
-declare function mapHistoryResponse(json: HistoryResponse): Bar[];
+declare function mapHistoryResponse(json: HistoryResponse, hasOpenInterest?: boolean): Bar[];
 declare class OpenAlgoDataFeed implements DataFeed {
     private readonly _config;
     private readonly _fetch;
@@ -7925,6 +8434,8 @@ interface ModifyPatch {
  * implement `OrderFeed` for the engine's write path.
  */
 interface OrderFeed {
+    /** Optional support declaration; a configured provider can report unavailable metadata. */
+    readonly capabilities?: TradingCapabilitySource$1;
     place(req: PlaceRequest & {
         mode: TradeMode;
     }): Promise<{
@@ -7960,6 +8471,8 @@ type ModeCheck = 'off' | 'auto' | 'always';
 interface OpenAlgoTradeConfig {
     baseUrl: string;
     apiKey: string;
+    /** Optional host/broker restrictions; omitted preserves the existing OpenAlgo path. */
+    capabilities?: TradingCapabilitySource;
     /**
      * Instrument constraints for the advisory pre-trade check on `place`, looked
      * up per order. Return undefined when the instrument is unknown; the
@@ -8085,7 +8598,8 @@ declare class OpenAlgoTradeFeed implements OrderFeed {
      * or a retried promise does not become two orders.
      */
     private _claimToken;
-    place(req: PlaceRequest & {
+    get capabilities(): TradingCapabilitySource | undefined;
+    place(request: PlaceRequest & {
         mode: TradeMode;
     }): Promise<{
         orderId: string;
@@ -8106,7 +8620,7 @@ declare class OpenAlgoTradeFeed implements OrderFeed {
      * that an ambiguous order did not reach the exchange.
      */
     releaseToken(token: string): void;
-    modify(orderId: string, patch: {
+    modify(orderId: string, changes: {
         price?: number;
         triggerPrice?: number;
         qty?: number;
@@ -8533,6 +9047,11 @@ interface AggTick {
     time: number;
     price: number;
     qty: number;
+    /**
+     * Open interest as at this tick, where the feed carries it. Carried onto the
+     * bar as the latest reading rather than accumulated: see `Bar.oi`.
+     */
+    oi?: number;
 }
 interface BarUpdate {
     bar: Bar;
@@ -8957,4 +9476,67 @@ declare function lerp(a: number, b: number, t: number): number;
  */
 declare function roundToTick(value: number, step: number): number;
 
-export { ALT_PRESET, type AddSeriesOptions, type AggTick, type AxisChromeOptions, type AxisStyle, BAR_CACHE_VERSION, BUILTIN_COMMANDS, type Bar, BarCache, type BarCacheOptions, type BarCacheStats, type BarCacheStore, type BarSubscriptionOptions, type BarUpdate, type BarsPage, type BarsPageRequest, type BarsRequest, type BrandingChangedEvent, type Bucketing, BuySellButtons, type BuySellButtonsOptions, CHART_STATE_VERSION, type CachedBars, type CachedBarsRequest, type CalendarBucketing, type CalendarUnit, CandleBuilder, type CandleBuilderOptions, type CandleGeometry, type CandleStyle, type CandleTier, type CandleUpdate, Canvas2dBackend, type CanvasLineStyle, type CanvasOptions, Chart, type ChartClickEvent, type ChartDataContext, type ChartDragEndEvent, type ChartDragEvent, type ChartEvent, type ChartEventOptions, type ChartNavigationOptions, type ChartObjectCapabilities, type ChartObjectDefinition, type ChartObjectDrawing, type ChartObjectDrawingSource, type ChartObjectKind, type ChartObjectProvider, type ChartObjectSnapshot, ChartObjects, type ChartObjectsOptions, type ChartOptions, type ChartSettingsColorPairInput, type ChartSettingsInput, type ChartSettingsState, type ChartSettingsTab, type ChartSettingsTabId, type ChartSettingsValue, type ChartSettingsValues, type ChartState, ChartTable, type ChartTableOptions, type ChartTheme, type ChartWatermarkOptions, type ComparisonAlignment, type ComparisonChartHost, ComparisonController, type ComparisonControllerOptions, type ComparisonHandle, type ComparisonMode, type ComparisonOptions, type ComparisonPane, type ContextMenuEvent, type ContextMenuTarget, type ContextMenuTargetKind, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairStyle, type CustomShortcut, DEFAULT_CANDLE_BUILDER_OPTIONS, DEFAULT_CANDLE_STYLE, DEFAULT_CHART_TABLE_OPTIONS, DEFAULT_HISTOGRAM_STYLE, DEFAULT_KEYMAP, DEFAULT_PRICE_SCALE_OPTIONS, DEFAULT_THEME, DEFAULT_TIMEZONE, DEFAULT_TIME_NAVIGATOR_OPTIONS, DEFAULT_TIME_SCALE_OPTIONS, DEFAULT_TRADING_COLORS, DEFAULT_ZOOM_GLIDE_OPTIONS, type DataFeed, DataLayer, DataLoadingController, type DataLoadingOptions, type DataLoadingSnapshot, type DataLoadingStatus, type DataUpdateReason, type DecodedOrder, type DepthLevel, type DoubleClickAction, type DoubleClickEvent, type DrawAnchor, type DrawItem, EventMarkers, type ExportSvgOptions, FakeDataFeed, type FeedScheduler, type FillGradient, type FillPoint, type GridAxisStyle, type GridOptions, type GridStyle, type HistogramStyle, type HistoryLoadingStatus, HistoryRequestPool, type HistoryRequestPoolOptions, INDICATOR_LINE_STYLES, INDICATOR_PLOT_STYLES, INDICATOR_SOURCES, type IPrimitive, type IRenderBackend, IST_OFFSET_SECONDS, type IndexedBar, type IndicatorAlertContext, type IndicatorAlertPayload, type IndicatorAlertSpec, type IndicatorApi, type IndicatorAttachContext, IndicatorBackground, type IndicatorBarsProvider, type IndicatorBarsRequest, type IndicatorCalcContext, type IndicatorDataChange, type IndicatorDataStatus, type IndicatorDescriptor, type IndicatorDrawing, IndicatorDrawings, IndicatorFill, type IndicatorFillOptions, type IndicatorFillSpec, type IndicatorHost, type IndicatorInput, IndicatorInputError, type IndicatorLevel, type IndicatorLevelContext, type IndicatorLineStyle, type IndicatorPlot, type IndicatorSettings, type IndicatorSource, type IndicatorState, type IndicatorStore, type IndicatorValues, type IntervalBucketing, type IntervalDescriptor, type IntervalParts, InvalidationLevel, type IstParts, type KeymapEntry, LINK_CROSSHAIR_ALPHA, type LateTickPolicy, type LegendField, type LegendStatusData, type LegendStatusLineOptions, type LegendStatusSource, type LegendTitleMode, type LegendValue, type LinePoint, type LinkChart, LinkCrosshair, type LinkDataLayer, LinkGroup, type LinkMemberOptions, type LinkMissingPolicy, type LinkOptions, type LiveBarMeta, type LogicalRange, LogoWatermark, type LogoWatermarkOptions, type LtpEvent, type MarkerPosition, type MarkerShape, type MarkerSize, type MarketDepth, type MarketPhase, type MarketPhaseFn, type MaybePromise, type ModeCheck, type OpenAlgoConfig, OpenAlgoDataFeed, type OpenAlgoLiveConfig, OpenAlgoLiveDataFeed, type OpenAlgoTradeConfig, OpenAlgoTradeFeed, type OpenAlgoWsConfig, OpenAlgoWsFeed, type OrderBookSnapshot, type OrderDecodeCode, type OrderDecodeIssue, type OrderDecodeResult, type OrderSide$1 as OrderSide, type OrderType$1 as OrderType, type OrderUpdateEvent, type OriginalTime, PRICE_LEVEL_KINDS, PRICE_SCALE_MODES, Pane, type PaneInvalidation, PaneLegend, type PaneLegendAction, type PaneLegendOptions, type PaneState, type PickHost, type PickKind, type PlaceOrder, type PlotBarColor, type PlotMarginOptions, type PointerInfo, type PointerKind, type PointerModifiers, type PointerSample, type PositionSide, type PriceAxisState, type PriceFormat, type PriceLevelInput, type PriceLevelKind, type PriceLevelQuote, type PriceLevelStyle, type PriceLevelValues, PriceLevels, type PriceLevelsOptions, PriceLine, type PriceLineOptions, type PriceRange, PriceScale, type PriceScaleId, type PriceScaleMode, type PriceScaleOptions, type PriceScaleState, type PrimitiveAnchor, type PrimitiveHit, type PrimitiveHost, type PrimitivePlacement, type PrimitiveRenderContext, type QuarantinedRow, type RawOrder, type RenderBackendFactory, type RenderBackendKind, type RenderDevice, type RendererChoice, type RendererEntry, type RendererFallbackEvent, type RendererFallbackReason, type ReplayChartHost, ReplayController, type ReplayOptions, type ReplayScheduler, ReplayShade, type ReplayShadeOptions, type ReplayState, type ReplayViewport, type ResolvedLinkOptions, type RestoreReport, SCALE_FONT_MAX, SCALE_FONT_MIN, type ScaleCanvasOptions, type SeriesApi, type SeriesDataItem, type SeriesId, type SeriesMarker, SeriesMarkers, type SeriesRenderContext, type SeriesState, type SeriesStyle, type SeriesType, type SessionSpec, type ShortcutListItem, ShortcutManager, type ShortcutManagerOptions, type ShortcutPreset, type ShortcutScope, type ShortcutTriggerEvent, type Size, type SocketFactory, type SocketLike, type SupertrendPoint, SvgContext, type SvgContextOptions, SvgLinearGradient, type TableCell, type TablePosition, TextWatermark, type TextWatermarkOptions, type Tick, TickBarAggregator, type TickBarOptions, type TickCountBucketing, type TickMarkType, type TickTimeframe, TimeNavigator, type TimeNavigatorAction, type TimeNavigatorOptions, TimeScale, type TimeScaleOp, type TimeScaleOptions, type TradeFeed, type TradeMarkerVariant, TradeMarkersPrimitive, type TradingColors, TradingController, type TradingHost, type TradingLineStyle, type TradingLineVariant, type TradingOrder, type TradingOrderSide, type TradingOrderType, type TradingPosition, type TradingSettings, type TradingSyncPayload, type TradingTrade, type UTCSeconds, UnknownIntervalError, type UnsubscribeFn, VERSION, type VolumeBucketing, type VolumeMode, type WatermarkPosition, type Whitespace, type WsClientWarning, type WsControlMessage, type WsMode, type WsState, type ZOrder, type ZonedParts, type ZonedPeriod, type ZoomAnchor, ZoomGlide, type ZoomGlideOptions, addComparison, alignToPrimary, applyChartSettings, atr, autoscaleRange, backendDegradation, backoffDelayMs, barCacheKey, barCloseSec, beginPick, bestHit, bitmapSize, bucketStartOf, calendarPeriodFlags, candleGeometry, candleTier, chartSettingsSchema, clamp, classifyAuthAck, compactVolume, comparisonController, computePriceLevels, conflateBars, conflateItems, conflationGroupSize, createChart, createLinkGroup, createRenderBackend, darkTheme, dashPattern, decodeOrder, drawLabel, drawShape, effectiveMarkerPx, ema, emaSeries, epochMsToUtcSeconds, eventToCombo, followerIndex, followerRange, formatCombo, formatIstCrosshairLabel, formatIstDate, formatIstTime, formatIstTimeSeconds, formatSubscribe, formatUnsubscribe, formatZonedCrosshairLabel, formatZonedDate, formatZonedTime, formatZonedTimeSeconds, fromGradient, generateBars, getChartType, getIndicator, hasIndicator, inSessionAt, indicatorDefaults, indicatorStyleInputs, intervalParts, intervalToSeconds, isDailyInterval, isIntradayInterval, isKnownInterval, isNewIstDay, isNewZonedDay, isNewZonedMonth, isNewZonedPeriod, isNewZonedQuarter, isNewZonedWeek, isNewZonedYear, isRebasing, isReservedCombo, isSecondsInterval, isTickInterval, isTimeBucketed, isValidCombo, isValidTimezone, isWhitespace, istStringToUtcSeconds, lastPriceLevelFromSeriesStyle, lerp, lightTheme, mapHistoryResponse, mapOrder, mapOrderStatus, mapPosition, markerSizePx, mergeBars, nextBucketStart, niceTicks, normalizeCombo, optimalBarWidth, parseCombo, parseMessage, parseSessionSpec, parseTopic, plotStyleKeys, precisionForStep, readChartSettings, readSequence, registerChartType, registerIndicator, registerInterval, registerRenderBackend, registeredChartTypes, registeredIndicators, registeredIntervals, registeredRenderBackends, resolveCrosshairStyle, resolveGridStyle, resolveInterval, resolvePlotMargins, resolveRenderBackend, resolveScaleStyle, roundToTick, rowTimeToUtcSeconds, rsi, rsiSeries, seriesStyleForLastPriceLevel, sessionFlags, sessionStartFlags, sessionStartIndices, sharedHistoryRequests, snapToDevicePixel, sourceValue, sourceValues, startOfZonedDay, startOfZonedMonth, startOfZonedWeek, supertrend, supertrendSeries, tableOrigin, toBar, trueRange, tryResolveInterval, unregisterInterval, unregisterRenderBackend, utcSecondsToIstDateString, utcSecondsToIstParts, utcSecondsToZonedDateString, utcSecondsToZonedParts, version, verticalGradient, watermarkRect, withAlpha, withBarCache, zoneOffsetSeconds, zonedDayIndex, zonedStringToUtcSeconds, zonedWallClockToUtcSeconds, zonedWeekIndex };
+/** Headless, chart-owned trader alerts. Hosts subscribe to alert:triggered for delivery. */
+declare class AlertController {
+    private readonly _chart;
+    private readonly _records;
+    private readonly _off;
+    private readonly _now;
+    private readonly _drawings;
+    private readonly _visuals;
+    private _timer;
+    private _timerAt;
+    private _paused;
+    private _restoring;
+    private _replay;
+    private _destroyed;
+    private _revision;
+    constructor(_chart: AlertChartHost, options?: AlertControllerOptions);
+    add(input: AlertInput): Alert;
+    update(id: string, patch: AlertPatch): Alert | undefined;
+    remove(id: string): boolean;
+    private _remove;
+    list(): Alert[];
+    toJSON(): AlertsDocument;
+    /** Validate the complete replacement before touching current alerts or their visuals. */
+    fromJSON(input: unknown): void;
+    private _saveState;
+    /** Availability is independent of lifecycle state; disabled records can still have valid anchors. */
+    availability(id: string): AlertAvailability;
+    enable(id: string): Alert | undefined;
+    disable(id: string): Alert | undefined;
+    /** Explicit host pause is independent of replay and never delivers a backlog. */
+    setPaused(paused: boolean): void;
+    destroy(): void;
+    private _assertAlive;
+    private _seed;
+    private _seedAll;
+    private _onObjects;
+    private _syncVisual;
+    private _onData;
+    private _plot;
+    private _reading;
+    private _closedMatch;
+    private _touchMatch;
+    private _barMatch;
+    private _drawingValue;
+    private _drawingTouch;
+    private _trigger;
+    private _expireDue;
+    private _clearTimer;
+    private _scheduleExpiry;
+}
+
+/** Shared editor fields in source units. Drawing bands own their bounds. */
+declare function alertSettingsSchema(source: AlertSource, condition?: AlertCondition): readonly IndicatorInput[];
+
+/** Validate and detach a version-1 document, or migrate a legacy bare list. */
+declare function parseAlertsDocument(input: unknown): AlertsDocument;
+
+/** Register runtime code by stable id; persisted alerts store only that id. */
+declare function registerBarCondition(condition: BarCondition): void;
+declare function unregisterBarCondition(id: string): boolean;
+declare function getBarCondition(id: string): Readonly<BarCondition> | undefined;
+declare function registeredBarConditions(): readonly Readonly<BarCondition>[];
+
+export { ALT_PRESET, type AddSeriesOptions, type AggTick, type Alert, type AlertAvailability, type AlertChartHost, type AlertCondition, AlertController, type AlertControllerOptions, type AlertDrawingInfo, type AlertDrawingLevel, type AlertDrawingProvider, type AlertDrawingValue, type AlertEventPayload, type AlertInput, type AlertPatch, type AlertPolicy, type AlertRepeat, type AlertScope, type AlertSource, type AlertState, type AlertTriggeredPayload, type AlertsDocument, type AxisChromeOptions, type AxisStyle, BAR_CACHE_VERSION, BUILTIN_COMMANDS, type Bar, BarCache, type BarCacheOptions, type BarCacheStats, type BarCacheStore, type BarCondition, type BarConditionAlertSource, type BarConditionContext, type BarSubscriptionOptions, type BarUpdate, type BarsPage, type BarsPageRequest, type BarsRequest, type BrandingChangedEvent, type Bucketing, BuySellButtons, type BuySellButtonsOptions, CHART_STATE_VERSION, type CachedBars, type CachedBarsRequest, type CalendarBucketing, type CalendarUnit, CandleBuilder, type CandleBuilderOptions, type CandleGeometry, type CandleStyle, type CandleTier, type CandleUpdate, Canvas2dBackend, type CanvasLineStyle, type CanvasOptions, Chart, type ChartClickEvent, type ChartDataContext, type ChartDataCsvOptions, type ChartDataUpdate, type ChartDragEndEvent, type ChartDragEvent, type ChartEvent, type ChartEventOptions, type ChartNavigationOptions, type ChartObjectCapabilities, type ChartObjectDefinition, type ChartObjectDrawing, type ChartObjectDrawingSource, type ChartObjectKind, type ChartObjectProvider, type ChartObjectSnapshot, ChartObjects, type ChartObjectsOptions, type ChartOptions, type ChartSettingsColorPairInput, type ChartSettingsInput, type ChartSettingsState, type ChartSettingsTab, type ChartSettingsTabId, type ChartSettingsValue, type ChartSettingsValues, type ChartState, ChartTable, type ChartTableOptions, type ChartTheme, type ChartWatermarkOptions, type ComparisonAlignment, type ComparisonBaseline, type ComparisonChartHost, ComparisonController, type ComparisonControllerOptions, type ComparisonHandle, type ComparisonMode, type ComparisonOptions, type ComparisonPane, type ContextMenuEvent, type ContextMenuTarget, type ContextMenuTargetKind, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairStyle, type CustomShortcut, DEFAULT_CANDLE_BUILDER_OPTIONS, DEFAULT_CANDLE_STYLE, DEFAULT_CHART_TABLE_OPTIONS, DEFAULT_HISTOGRAM_STYLE, DEFAULT_KEYMAP, DEFAULT_PRICE_SCALE_OPTIONS, DEFAULT_THEME, DEFAULT_TIMEZONE, DEFAULT_TIME_NAVIGATOR_OPTIONS, DEFAULT_TIME_SCALE_OPTIONS, DEFAULT_TRADING_COLORS, DEFAULT_ZOOM_GLIDE_OPTIONS, type DataFeed, DataLayer, DataLoadingController, type DataLoadingOptions, type DataLoadingSnapshot, type DataLoadingStatus, type DataUpdateReason, type DecodedOrder, type DepthLevel, type DoubleClickAction, type DoubleClickEvent, type DrawAnchor, type DrawItem, type DrawingAlertSource, EventMarkers, type ExportSvgOptions, FakeDataFeed, type FeedScheduler, type FillGradient, type FillPoint, type GridAxisStyle, type GridOptions, type GridStyle, type HistogramStyle, type HistoryLoadingStatus, HistoryRequestPool, type HistoryRequestPoolOptions, INDICATOR_LINE_STYLES, INDICATOR_PLOT_STYLES, INDICATOR_SOURCES, type IPrimitive, type IRenderBackend, IST_OFFSET_SECONDS, type IndexedBar, type IndicatorAlertContext, type IndicatorAlertPayload, type IndicatorAlertSource, type IndicatorAlertSpec, type IndicatorApi, type IndicatorAttachContext, IndicatorBackground, type IndicatorBarsProvider, type IndicatorBarsRequest, type IndicatorCalcContext, type IndicatorDataChange, type IndicatorDataStatus, type IndicatorDescriptor, type IndicatorDrawing, IndicatorDrawings, IndicatorFill, type IndicatorFillOptions, type IndicatorFillSpec, type IndicatorHost, type IndicatorInput, IndicatorInputError, type IndicatorLevel, type IndicatorLevelContext, type IndicatorLineStyle, type IndicatorPlot, type IndicatorSettings, type IndicatorSource, type IndicatorState, type IndicatorStore, type IndicatorValues, Instrument, type InstrumentCalendar, type InstrumentMetadata, type InstrumentSession, type IntervalBucketing, type IntervalDescriptor, type IntervalParts, InvalidationLevel, type IstParts, type KeymapEntry, LINK_CROSSHAIR_ALPHA, type LateTickPolicy, type LegendField, type LegendStatusData, type LegendStatusLineOptions, type LegendStatusSource, type LegendTitleMode, type LegendValue, type LinePoint, type LinkChart, LinkCrosshair, type LinkDataLayer, LinkGroup, type LinkMemberOptions, type LinkMissingPolicy, type LinkOptions, type LiveBarMeta, type LogicalRange, LogoWatermark, type LogoWatermarkOptions, type LtpEvent, type MarkerPosition, type MarkerShape, type MarkerSize, type MarketDepth, type MarketPhase, type MarketPhaseFn, type MaybePromise, type ModeCheck, type OpenAlgoConfig, OpenAlgoDataFeed, type OpenAlgoLiveConfig, OpenAlgoLiveDataFeed, type OpenAlgoTradeConfig, OpenAlgoTradeFeed, type OpenAlgoWsConfig, OpenAlgoWsFeed, type OrderBookSnapshot, type OrderDecodeCode, type OrderDecodeIssue, type OrderDecodeResult, type OrderSide$1 as OrderSide, type OrderType$1 as OrderType, type OrderUpdateEvent, type OriginalTime, PRICE_LEVEL_KINDS, PRICE_SCALE_MODES, Pane, type PaneInvalidation, PaneLegend, type PaneLegendAction, type PaneLegendOptions, type PaneState, type PickHost, type PickKind, type PlaceOrder, type PlotBarColor, type PlotMarginOptions, type PointerInfo, type PointerKind, type PointerModifiers, type PointerSample, type PositionSide, type PriceAlertSource, type PriceAxisState, type PriceFormat, type PriceLevelInput, type PriceLevelKind, type PriceLevelQuote, type PriceLevelStyle, type PriceLevelValues, PriceLevels, type PriceLevelsOptions, PriceLine, type PriceLineOptions, type PriceRange, PriceScale, type PriceScaleId, type PriceScaleMode, type PriceScaleOptions, type PriceScaleState, type PrimitiveAnchor, type PrimitiveHit, type PrimitiveHost, type PrimitivePlacement, type PrimitiveRenderContext, type QuarantinedRow, type RawOrder, type RenderBackendFactory, type RenderBackendKind, type RenderDevice, type RendererChoice, type RendererEntry, type RendererFallbackEvent, type RendererFallbackReason, type ReplayBarEndTime, type ReplayChartHost, ReplayController, ReplayGroup, type ReplayGroupChartHost, type ReplayGroupMember, type ReplayGroupOptions, type ReplayGroupState, type ReplayOptions, type ReplayScheduler, type ReplayScope, ReplayShade, type ReplayShadeOptions, type ReplayState, type ReplayTiming, type ReplayViewport, type ResolvedLinkOptions, type RestoreReport, SCALE_FONT_MAX, SCALE_FONT_MIN, type ScaleCanvasOptions, type SeriesApi, type SeriesDataItem, type SeriesId, type SeriesMarker, SeriesMarkers, type SeriesRenderContext, type SeriesState, type SeriesStyle, type SeriesType, type SessionSpec, type ShortcutListItem, ShortcutManager, type ShortcutManagerOptions, type ShortcutPreset, type ShortcutScope, type ShortcutTriggerEvent, type Size, type SocketFactory, type SocketLike, type SupertrendPoint, SvgContext, type SvgContextOptions, SvgLinearGradient, type TableCell, type TablePosition, TextWatermark, type TextWatermarkOptions, type Tick, TickBarAggregator, type TickBarOptions, type TickCountBucketing, type TickMarkType, type TickTimeframe, TimeNavigator, type TimeNavigatorAction, type TimeNavigatorOptions, TimeScale, type TimeScaleOp, type TimeScaleOptions, type TradeFeed, type TradeMarkerVariant, TradeMarkersPrimitive, type TradingCapabilities, TradingCapabilityError, type TradingCapabilityRequest, type TradingCapabilityResult, type TradingCapabilitySource, type TradingColors, TradingController, type TradingHost, type TradingLineStyle, type TradingLineVariant, type TradingOperation, type TradingOrder, type TradingOrderSide, type TradingOrderType, type TradingPosition, type TradingSettings, type TradingSyncPayload, type TradingTrade, type UTCSeconds, UnknownIntervalError, type UnsubscribeFn, VERSION, type VolumeBucketing, type VolumeMode, type WatermarkPosition, type Whitespace, type WsClientWarning, type WsControlMessage, type WsMode, type WsState, type ZOrder, type ZonedParts, type ZonedPeriod, type ZoomAnchor, ZoomGlide, type ZoomGlideOptions, addComparison, alertSettingsSchema, alignToPrimary, applyChartSettings, assertTradingCapability, atr, autoscaleRange, backendDegradation, backoffDelayMs, barCacheKey, barCloseSec, beginPick, bestHit, bitmapSize, bucketStartOf, calendarPeriodFlags, candleGeometry, candleTier, chartSettingsSchema, checkTradingCapability, clamp, classifyAuthAck, compactVolume, comparisonController, computePriceLevels, conflateBars, conflateItems, conflationGroupSize, createChart, createLinkGroup, createRenderBackend, darkTheme, dashPattern, decodeOrder, drawLabel, drawShape, effectiveMarkerPx, ema, emaSeries, epochMsToUtcSeconds, eventToCombo, exportChartDataCsv, followerIndex, followerRange, formatCombo, formatIstCrosshairLabel, formatIstDate, formatIstTime, formatIstTimeSeconds, formatSubscribe, formatUnsubscribe, formatZonedCrosshairLabel, formatZonedDate, formatZonedTime, formatZonedTimeSeconds, fromGradient, generateBars, getBarCondition, getChartType, getIndicator, hasIndicator, inSessionAt, indicatorDefaults, indicatorStyleInputs, intervalParts, intervalToSeconds, isDailyInterval, isIntradayInterval, isKnownInterval, isNewIstDay, isNewZonedDay, isNewZonedMonth, isNewZonedPeriod, isNewZonedQuarter, isNewZonedWeek, isNewZonedYear, isRebasing, isReplaying, isReservedCombo, isSecondsInterval, isTickInterval, isTimeBucketed, isValidCombo, isValidTimezone, isWhitespace, istStringToUtcSeconds, lastPriceLevelFromSeriesStyle, lerp, lightTheme, mapHistoryResponse, mapOrder, mapOrderStatus, mapPosition, markerSizePx, mergeBars, nextBucketStart, niceTicks, normalizeCombo, optimalBarWidth, parseAlertsDocument, parseCombo, parseMessage, parseSessionSpec, parseTopic, plotStyleKeys, precisionForStep, readChartSettings, readSequence, registerBarCondition, registerChartType, registerIndicator, registerInterval, registerRenderBackend, registeredBarConditions, registeredChartTypes, registeredIndicators, registeredIntervals, registeredRenderBackends, resolveCrosshairStyle, resolveGridStyle, resolveInterval, resolvePlotMargins, resolveRenderBackend, resolveScaleStyle, roundToTick, rowTimeToUtcSeconds, rsi, rsiSeries, seriesStyleForLastPriceLevel, sessionFlags, sessionStartFlags, sessionStartIndices, sharedHistoryRequests, snapToDevicePixel, sourceValue, sourceValues, startOfZonedDay, startOfZonedMonth, startOfZonedWeek, supertrend, supertrendSeries, tableOrigin, toBar, trueRange, tryResolveInterval, unregisterBarCondition, unregisterInterval, unregisterRenderBackend, utcSecondsToIstDateString, utcSecondsToIstParts, utcSecondsToZonedDateString, utcSecondsToZonedParts, version, verticalGradient, watermarkRect, withAlpha, withBarCache, zoneOffsetSeconds, zonedDayIndex, zonedStringToUtcSeconds, zonedWallClockToUtcSeconds, zonedWeekIndex };