openalgo-charts 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1621 @@
+/** Library version string, e.g. `"0.0.0"`. Replaced at release time. */
+declare const VERSION = "0.1.0";
+/** Returns the current library version. */
+declare function version(): string;
+
+/**
+ * Invalidation model (ARCHITECTURE.md §3.2).
+ *
+ * A single global level is too coarse for multi-pane indicators and trade
+ * overlays, so the mask carries a **global level + a per-pane map + a queue of
+ * time-scale operations**. Multiple invalidations within one frame coalesce via
+ * {@link InvalidateMask.merge}.
+ */
+/** How much of a pane (or the whole chart) must be repainted this frame. */
+declare const InvalidationLevel: {
+    /** Nothing to do. */
+    readonly None: 0;
+    /** Repaint only the top (overlay) canvas — crosshair, hover, dragging primitives. */
+    readonly Cursor: 1;
+    /** Repaint the base canvas at the current scales — series moved/changed, no rescale. */
+    readonly Light: 2;
+    /** Recompute scales/ticks then repaint everything. */
+    readonly Full: 3;
+};
+type InvalidationLevel = (typeof InvalidationLevel)[keyof typeof InvalidationLevel];
+/** Per-pane invalidation entry. `autoScale` requests a price-axis rescale. */
+interface PaneInvalidation {
+    level: InvalidationLevel;
+    autoScale: boolean;
+}
+/** Discrete operations applied to the shared time scale before painting. */
+type TimeScaleOp = {
+    type: 'fitContent';
+} | {
+    type: 'applyBarSpacing';
+    value: number;
+} | {
+    type: 'applyRightOffset';
+    value: number;
+} | {
+    type: 'reset';
+};
+declare class InvalidateMask {
+    private _globalLevel;
+    private readonly _panes;
+    private _timeScaleOps;
+    constructor(globalLevel?: InvalidationLevel);
+    get globalLevel(): InvalidationLevel;
+    /** Raise the chart-wide level (monotonic — only ever increases). */
+    invalidateGlobal(level: InvalidationLevel): void;
+    /** Raise a single pane's level without touching the others. */
+    invalidatePane(paneIndex: number, invalidation: PaneInvalidation): void;
+    paneInvalidation(paneIndex: number): PaneInvalidation | undefined;
+    panes(): ReadonlyMap<number, PaneInvalidation>;
+    addTimeScaleOp(op: TimeScaleOp): void;
+    timeScaleOps(): readonly TimeScaleOp[];
+    isEmpty(): boolean;
+    /** Fold another mask into this one (coalescing multiple invalidations per frame). */
+    merge(other: InvalidateMask): void;
+}
+
+/**
+ * Frame scheduler (ARCHITECTURE.md §3.2). Coalesces many `requestFrame()` calls
+ * within a single tick into one `onFrame` invocation. The rAF function is
+ * injectable so the loop is deterministically testable without a browser.
+ */
+type RafScheduler = (cb: () => void) => number;
+type RafCanceller = (handle: number) => void;
+
+/**
+ * HiDPI canvas handling (ARCHITECTURE.md §3.1).
+ *
+ * Each canvas has two coordinate systems: **media** (CSS px, what you reason
+ * about) and **bitmap** (device px = media × devicePixelRatio, the backing
+ * buffer). Drawing 1px lines in the bitmap scope with integer snapping keeps
+ * them crisp on retina/HiDPI displays.
+ */
+interface Size {
+    width: number;
+    height: number;
+}
+/** Pure: compute the integer device-pixel backing-buffer size for a canvas. */
+declare function bitmapSize(mediaWidth: number, mediaHeight: number, dpr: number): Size;
+/** Pure: snap a media-space coordinate to a crisp device-pixel edge. */
+declare function snapToDevicePixel(mediaCoord: number, dpr: number): number;
+/**
+ * A single `<canvas>` element with media/bitmap sizing. Constructed only in a
+ * browser; the size math above is the part exercised by unit tests.
+ */
+declare class CanvasLayer {
+    readonly element: HTMLCanvasElement;
+    readonly ctx: CanvasRenderingContext2D;
+    private _mediaWidth;
+    private _mediaHeight;
+    private _dpr;
+    constructor(doc: Document, zIndex: number);
+    get mediaWidth(): number;
+    get mediaHeight(): number;
+    get pixelRatio(): number;
+    /** Resize backing buffer + CSS box. No-op if nothing changed. */
+    resize(mediaWidth: number, mediaHeight: number, dpr: number): void;
+    /** Clear the whole bitmap and reset the transform to bitmap (device-px) scope. */
+    clearBitmap(): void;
+}
+
+interface PriceRange {
+    min: number;
+    max: number;
+}
+/**
+ * Price-scale mode. `linear` and `logarithmic` are full coordinate transforms;
+ * `percentage`/`indexed-to-100` (rebase to a baseline) and overlay scales are
+ * not yet implemented — see END_TO_END_AUDIT.md / README known limitations.
+ */
+type PriceScaleMode = 'linear' | 'logarithmic';
+interface PriceScaleOptions {
+    /** Fraction of pane height kept empty at top/bottom (default 0.1 each). */
+    marginTop: number;
+    marginBottom: number;
+    /** Instrument tick size (minMove), e.g. 0.05. 0 → infer from range. */
+    minMove: number;
+    /** Linear or logarithmic price↔y mapping. */
+    mode: PriceScaleMode;
+    /** Flip the axis (price increases downward) — for spread/short views. */
+    inverted: boolean;
+}
+declare const DEFAULT_PRICE_SCALE_OPTIONS: PriceScaleOptions;
+/**
+ * Pure: compute a price range from data extremes plus top/bottom margins.
+ * Returns a padded [min,max]; widens a degenerate (flat) range so it's drawable.
+ */
+declare function autoscaleRange(low: number, high: number, marginTop: number, marginBottom: number): PriceRange;
+declare class PriceScale {
+    private _options;
+    private _height;
+    private _min;
+    private _max;
+    private _autoScale;
+    constructor(options?: Partial<PriceScaleOptions>);
+    get options(): PriceScaleOptions;
+    setHeight(height: number): void;
+    get height(): number;
+    setPriceRange(range: PriceRange): void;
+    priceRange(): PriceRange;
+    /** Whether the range tracks the data (true) or has been set manually (false). */
+    get autoScale(): boolean;
+    setAutoScale(on: boolean): void;
+    /**
+     * Manually scale the visible range around its centre. `factor` > 1 widens the
+     * range (compress / zoom out), < 1 narrows it (expand / zoom in). Switches the
+     * scale to manual mode so autoscale stops overriding it.
+     */
+    scaleAroundCenter(factor: number): void;
+    /**
+     * Pan the visible range vertically by `dy` media px (dragging the plot up/down).
+     * Works in transformed space so it's correct for log scales, and respects
+     * `inverted`. Switches to manual mode so autoscale stops overriding it.
+     */
+    panByPixels(dy: number): void;
+    /** Recompute the visible range from data extremes + configured margins. */
+    autoscale(low: number, high: number): void;
+    /** Coordinate transform for the active mode (identity for linear, log10 for log). */
+    private _t;
+    private _tInv;
+    /** Price → y (media px). Higher price → smaller y (top of pane), unless inverted. */
+    priceToY(price: number): number;
+    /** y (media px) → price. */
+    yToPrice(y: number): number;
+    /** Decimal precision implied by minMove (or the visible range if unset). */
+    precision(): number;
+    /** Snap a price to the instrument tick size (no-op if minMove is 0). */
+    snapToTick(price: number): number;
+    /** Format a price for axis/label display. */
+    format(price: number): string;
+    /** Clamp a y to the pane (used by crosshair/order dragging). */
+    clampY(y: number): number;
+}
+
+interface LogicalRange {
+    from: number;
+    to: number;
+}
+interface TimeScaleOptions {
+    barSpacing: number;
+    minBarSpacing: number;
+    maxBarSpacing: number;
+    /** Empty bars of space kept to the right of the latest bar. */
+    rightOffset: number;
+}
+declare const DEFAULT_TIME_SCALE_OPTIONS: TimeScaleOptions;
+declare class TimeScale {
+    private _barSpacing;
+    private _rightOffset;
+    private readonly _minBarSpacing;
+    private readonly _maxBarSpacing;
+    private _width;
+    private _baseIndex;
+    constructor(options?: Partial<TimeScaleOptions>);
+    setWidth(width: number): void;
+    get width(): number;
+    get barSpacing(): number;
+    setBarSpacing(value: number): void;
+    get rightOffset(): number;
+    setRightOffset(value: number): void;
+    /** Logical index of the latest bar; the right edge anchors to baseIndex+rightOffset. */
+    setBaseIndex(index: number): void;
+    private _rightEdgeIndex;
+    /** Logical index → x (media px), bar center. */
+    indexToX(index: number): number;
+    /** x (media px) → fractional logical index. */
+    xToIndex(x: number): number;
+    /** Currently visible logical index range (fractional, unclamped to data). */
+    visibleRange(): LogicalRange;
+    /**
+     * Pan by a pixel delta. Positive `dx` drags chart content to the right
+     * (revealing older bars), matching a natural left-button drag.
+     */
+    scrollByPixels(dx: number): void;
+    /**
+     * Zoom around an anchor x (the cursor): change bar spacing by `factor`
+     * while keeping whatever logical index sits under `focusX` pinned there.
+     * `factor` > 1 zooms in (wider bars).
+     */
+    zoomAtX(focusX: number, factor: number): void;
+    /** Choose bar spacing so `barCount` bars fit the width, anchored at the right edge. */
+    fitContent(barCount: number): void;
+}
+
+/**
+ * Internal time is always **UTC seconds** (integer). Feed adapters convert
+ * broker formats (IST strings, epoch ms) to this at the edge; see ARCHITECTURE.md §4.0.
+ */
+type UTCSeconds = number;
+/** The original, caller-supplied time value, echoed back untouched in callbacks. */
+type OriginalTime = number | string;
+/** A single OHLC(V) bar. `volume` is optional (not all feeds carry it). */
+interface Bar {
+    time: UTCSeconds;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+/** A single value point (for line/area/baseline series). */
+interface LinePoint {
+    time: UTCSeconds;
+    value: number;
+}
+/** A whitespace point: occupies a logical index for alignment but draws nothing. */
+interface Whitespace {
+    time: UTCSeconds;
+}
+declare function isWhitespace(p: Bar | LinePoint | Whitespace): p is Whitespace;
+
+/**
+ * Shared data layer (ARCHITECTURE.md §4.1). One per chart. Merges all series by
+ * time onto a single logical-index space (0..N-1) so price + volume + indicator
+ * panes stay aligned, and so non-trading gaps collapse (an absent time simply
+ * has no logical index). Per-series rows are addressable by that shared index.
+ */
+
+type SeriesId = number;
+interface IndexedBar {
+    index: number;
+    bar: Bar;
+}
+declare class DataLayer {
+    private readonly _series;
+    private _sortedTimes;
+    private readonly _indexByTime;
+    private _nextId;
+    /** Register a new series; returns its id. */
+    createSeries(): SeriesId;
+    removeSeries(id: SeriesId): void;
+    /** Bulk-load (full replace) one series' data, then re-merge the time axis. */
+    setSeriesData(id: SeriesId, bars: readonly Bar[]): void;
+    /**
+     * Upsert bars into a series by time (used for history paging / backfill /
+     * out-of-order corrections — ARCHITECTURE.md §4.2). Existing times are
+     * replaced; new times are inserted; the result stays time-sorted.
+     *
+     * Prepending older bars shifts every existing logical index up by the
+     * inserted count — callers preserve the viewport by re-reading `baseIndex`
+     * (the invariant `rightEdge − index` is unchanged, so visible bars don't move).
+     */
+    addBars(id: SeriesId, bars: readonly Bar[]): void;
+    /**
+     * Apply a single live bar (ARCHITECTURE.md §4.2 hot path). Returns the kind of
+     * change so the chart auto-scrolls only on a genuine right-edge append:
+     * - `'append'`  → newer than the last bar (advances baseIndex)
+     * - `'replace'` → same time as the last bar (intra-bar tick) or an existing time
+     * - `'insert'`  → an older time inserted into history (late / out-of-order)
+     */
+    update(id: SeriesId, bar: Bar): 'append' | 'replace' | 'insert';
+    private _appendTime;
+    /** Number of logical indices (distinct time points across all series). */
+    get length(): number;
+    /** Logical index of the latest real bar (length - 1), or -1 if empty. */
+    get baseIndex(): number;
+    indexToTime(index: number): number | undefined;
+    timeToIndex(time: number): number | undefined;
+    /** All bars of a series paired with their shared logical index. */
+    indexedBars(id: SeriesId): IndexedBar[];
+    /** Bars of a series whose logical index lies within [fromIndex, toIndex]. */
+    visibleBars(id: SeriesId, fromIndex: number, toIndex: number): IndexedBar[];
+    private _rebuild;
+}
+
+/**
+ * Unified style bag for all Family-A series types (ARCHITECTURE.md §6A). Each
+ * renderer reads the fields it needs; per-type defaults are filled by the
+ * chart-type registry. Keeping one optional-field interface avoids a sprawling
+ * discriminated union at the rendering boundary.
+ */
+interface SeriesStyle {
+    upColor?: string;
+    downColor?: string;
+    borderUpColor?: string;
+    borderDownColor?: string;
+    wickUpColor?: string;
+    wickDownColor?: string;
+    borderVisible?: boolean;
+    wickVisible?: boolean;
+    hollow?: boolean;
+    /** Scale candle body width by volume / maxVisibleVolume (volume candles). */
+    volumeScaled?: boolean;
+    color?: string;
+    lineWidth?: number;
+    step?: boolean;
+    markers?: boolean;
+    markerRadius?: number;
+    areaTopColor?: string;
+    areaBottomColor?: string;
+    baseValue?: number;
+    topColor?: string;
+    bottomColor?: string;
+    highColor?: string;
+    lowColor?: string;
+    closeColor?: string;
+    base?: number;
+    /** Box size for stacking P&F X/O glyphs. */
+    boxSize?: number;
+    /** Kagi thick (yang) line color. */
+    thickColor?: string;
+    /** Kagi thin (yin) line color. */
+    thinColor?: string;
+}
+
+/**
+ * Chart theme (palette). A single object drives chart chrome (background, grid,
+ * axes, crosshair), series defaults (up/down, line, area gradient, last price),
+ * and the trade layer (buy/sell, profit/loss). Renderers read theme colors when
+ * a per-series style field is absent, so one theme restyles the whole chart.
+ */
+interface ChartTheme {
+    background: string;
+    grid: string;
+    axisText: string;
+    axisLine: string;
+    crosshair: string;
+    upColor: string;
+    downColor: string;
+    wickUpColor: string;
+    wickDownColor: string;
+    lineColor: string;
+    areaTopColor: string;
+    areaBottomColor: string;
+    baselineTopLine: string;
+    baselineTopFill: string;
+    baselineBottomLine: string;
+    baselineBottomFill: string;
+    lastPriceUp: string;
+    lastPriceDown: string;
+    lastPriceText: string;
+    buy: string;
+    sell: string;
+    profit: string;
+    loss: string;
+}
+declare const darkTheme: ChartTheme;
+declare const lightTheme: ChartTheme;
+declare const DEFAULT_THEME: ChartTheme;
+
+/**
+ * Chart-type registry (ARCHITECTURE.md §6A). Every series type registers a
+ * descriptor: how to draw it and how it contributes to autoscale. The core
+ * iterates descriptors, so adding a style is one registration — no core change.
+ * Phase 5 fills the Family-A (time-indexed) types; Families B/C plug in later.
+ */
+
+type SeriesType = 'candlestick' | 'hollow-candle' | 'volume-candle' | 'bar' | 'high-low' | 'line' | 'line-markers' | 'step' | 'area' | 'hlc-area' | 'baseline' | 'column' | 'histogram' | 'point-figure' | 'kagi';
+interface DrawItem {
+    x: number;
+    bar: Bar;
+}
+interface SeriesRenderContext {
+    plotHeight: number;
+    maxVolume: number;
+    theme: ChartTheme;
+}
+interface RendererEntry {
+    defaultStyle: SeriesStyle;
+    /** True for the price series whose last close drives the last-price line. */
+    isPriceSeries: boolean;
+    draw(ctx: CanvasRenderingContext2D, items: readonly DrawItem[], toY: (v: number) => number, barSpacing: number, dpr: number, style: SeriesStyle, rc: SeriesRenderContext): void;
+    /** Min/max price contribution of one bar to autoscale. */
+    extents(bar: Bar, style: SeriesStyle): {
+        min: number;
+        max: number;
+    };
+}
+/** Register a chart type. `type` accepts a built-in `SeriesType` or any custom string. */
+declare function registerChartType(type: SeriesType | (string & {}), entry: RendererEntry): void;
+declare function getChartType(type: SeriesType | (string & {})): RendererEntry;
+declare function registeredChartTypes(): string[];
+
+/**
+ * Primitive / plugin API (ARCHITECTURE.md §8). The extension point that keeps
+ * the core small and powers markers, events, indicators, and the trade layer.
+ * A primitive draws on a pane, optionally contributes to autoscale, and
+ * optionally hit-tests for hover/drag.
+ */
+
+type ZOrder = 'bottom' | 'normal' | 'top';
+interface PrimitiveRenderContext {
+    timeScale: TimeScale;
+    priceScale: PriceScale;
+    dataLayer: DataLayer;
+    plotWidth: number;
+    plotHeight: number;
+    priceAxisWidth: number;
+    dpr: number;
+    theme: ChartTheme;
+}
+interface PrimitiveHit {
+    externalId: string;
+    zOrder: ZOrder;
+    /** Pixel distance from the cursor (smaller wins ties before z-order). */
+    distance: number;
+    cursor?: string;
+}
+/** Injected when a primitive is attached; lets it request a repaint. */
+interface PrimitiveHost {
+    requestUpdate(): void;
+}
+interface IPrimitive {
+    /** Layer order vs series: 'bottom' (behind), 'normal' (over), 'top' (overlay). */
+    zOrder(): ZOrder;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    /** Optional: expand the pane's autoscale range so this primitive isn't clipped. */
+    autoscaleInfo?(): {
+        min: number;
+        max: number;
+    } | null;
+    /** Optional: topmost hit under (x,y) in media px (relative to the pane plot). */
+    hitTest?(x: number, y: number, rc: PrimitiveRenderContext): PrimitiveHit | null;
+    attached?(host: PrimitiveHost): void;
+    detached?(): void;
+}
+/** Pick the best hit across primitives: nearest distance, then z-order priority. */
+declare function bestHit(hits: readonly (PrimitiveHit | null)[]): PrimitiveHit | null;
+
+type MarkerShape = 'arrowUp' | 'arrowDown' | 'circle' | 'square' | 'triangleUp' | 'triangleDown' | 'diamond' | 'flag' | 'text';
+type MarkerPosition = 'aboveBar' | 'belowBar' | 'inBar' | 'atPrice';
+type MarkerSize = 'tiny' | 'small' | 'medium' | 'big';
+interface SeriesMarker {
+    time: number;
+    position: MarkerPosition;
+    price?: number;
+    shape: MarkerShape;
+    size: MarkerSize;
+    color: string;
+    text?: string;
+    id?: string;
+}
+/** Base glyph size in CSS px for a marker size preset. */
+declare function markerSizePx(size: MarkerSize): number;
+/** Effective glyph px, clamped so it never exceeds the current bar spacing. */
+declare function effectiveMarkerPx(size: MarkerSize, barSpacing: number): number;
+declare function drawShape(ctx: CanvasRenderingContext2D, shape: MarkerShape, cx: number, cy: number, px: number, color: string): void;
+declare class SeriesMarkers implements IPrimitive {
+    private readonly _seriesId;
+    private _markers;
+    private _host;
+    private _lastPositions;
+    constructor(seriesId: SeriesId);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    setMarkers(markers: readonly SeriesMarker[]): void;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    hitTest(x: number, y: number): PrimitiveHit | null;
+}
+
+/**
+ * Series records (ARCHITECTURE.md §4.3). A series references its rows in the
+ * shared DataLayer by id, names a registered chart type, and carries a style
+ * bag. The chart-type registry (§6A) supplies the renderer + autoscale extents,
+ * so the core never switches on type.
+ */
+
+interface SeriesRecord {
+    dataId: SeriesId;
+    type: SeriesType;
+    style: SeriesStyle;
+}
+/** Public handle returned by `chart.addSeries(...)`. */
+interface SeriesApi {
+    setData(bars: readonly Bar[]): void;
+    prependData(bars: readonly Bar[]): void;
+    update(bar: Bar): void;
+    /** Create a markers layer (buy/sell signals, shapes) bound to this series. */
+    createMarkers(): SeriesMarkers;
+}
+
+/**
+ * A pane is one vertically-stacked drawing region (price pane, volume pane,
+ * indicator pane). It owns a base + top canvas (ARCHITECTURE.md §3.1) and a
+ * price scale, and renders its series against the shared time scale + DataLayer.
+ */
+
+interface PaneRenderContext {
+    timeScale: TimeScale;
+    dataLayer: DataLayer;
+    dpr: number;
+    priceAxisWidth: number;
+    timeAxisHeight: number;
+    /** Only the bottom pane draws the time axis. */
+    showTimeAxis: boolean;
+    /** Enable OHLC-preserving conflation when bars fall below ~0.5px (§4.4). */
+    conflate: boolean;
+    /** Conflation aggressiveness (1 = perf only; higher = more smoothing). */
+    conflationFactor: number;
+    /** Active palette — drives chrome, series defaults, and trade colors. */
+    theme: ChartTheme;
+    /** Draw the vertical (time) grid lines. */
+    showVertGrid: boolean;
+    /** Draw the horizontal (price) grid lines. */
+    showHorzGrid: boolean;
+}
+declare class Pane {
+    readonly element: HTMLElement;
+    readonly base: CanvasLayer;
+    readonly top: CanvasLayer;
+    readonly priceScale: PriceScale;
+    /** Relative height weight within the chart (price=1, volume≈0.3). */
+    weight: number;
+    private readonly _series;
+    private readonly _primitives;
+    private _width;
+    private _height;
+    constructor(doc: Document);
+    addSeries(record: SeriesRecord): void;
+    series(): readonly SeriesRecord[];
+    addPrimitive(primitive: IPrimitive, host: PrimitiveHost): void;
+    /** Remove a primitive if present; returns true if it was found. */
+    removePrimitive(primitive: IPrimitive): boolean;
+    /** Detach every primitive (lifecycle cleanup) and remove the pane element. */
+    destroy(): void;
+    private _primitiveContext;
+    /** Topmost primitive hit at media-px (x,y) relative to this pane's plot. */
+    hitTestPrimitives(x: number, y: number, ctx: PaneRenderContext): PrimitiveHit | null;
+    resize(width: number, height: number, dpr: number): void;
+    private _layout;
+    /** Recompute the price range from the visible bars of all series in this pane. */
+    autoscale(ctx: PaneRenderContext): void;
+    /** Paint background + grid + series + axes on the base canvas. */
+    paintBase(ctx: PaneRenderContext): void;
+    /**
+     * Top (overlay) canvas: top-layer primitives + crosshair. Cheap repaint on
+     * cursor moves. `cross.x` is the shared plot x (vertical line, drawn in every
+     * pane for a global crosshair); `cross.yLocal` is the price-line y for the
+     * hovered pane only (null elsewhere); `cross.showTimeTag` draws the date tag
+     * on the bottom pane's axis strip.
+     */
+    paintTop(cross: {
+        x: number;
+        yLocal: number | null;
+        showTimeTag: boolean;
+    } | null, ctx: PaneRenderContext): void;
+    /** Price at a media-px y on this pane (for crosshair magnet). */
+    yToPrice(y: number): number;
+}
+
+/**
+ * Crosshair state + magnet snapping (ARCHITECTURE.md §6). Pure helpers so the
+ * snap logic is unit-testable; drawing lives in render/crosshair.ts.
+ */
+
+type CrosshairMode = 'normal' | 'magnet';
+
+/**
+ * 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. Drag handling is added by the trade layer in Phase 9.
+ */
+
+interface PriceLineOptions {
+    price: number;
+    color: string;
+    lineWidth: number;
+    dashed: boolean;
+    /** Right-axis tag text. Defaults to the formatted price. */
+    label?: string;
+    /** Optional tag drawn at the LEFT end of the line (NinjaTrader-style order tag). */
+    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
+     * NinjaTrader order line. The right-axis tag is always drawn.
+     */
+    extentFromRight?: number;
+    /** Draw a small cancel (cross) box at the right end; 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 class PriceLine implements IPrimitive {
+    private _opts;
+    private _host;
+    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 left-end tag text (e.g. live position P&L); repaints. */
+    setLeftLabel(text: string): 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;
+}
+
+/**
+ * Event markers (ARCHITECTURE.md §8.2): Earnings / Dividend / Split badges in a
+ * strip near the bottom of the plot. Time-anchored only (no price). Hover/click
+ * carry an external id for tooltip wiring. Data source is an integration concern
+ * (OpenAlgo has no corporate-actions calendar) — the renderer ships regardless.
+ */
+
+interface ChartEvent {
+    time: number;
+    type: 'earnings' | 'dividend' | 'split' | 'news' | string;
+    label: string;
+    color?: string;
+    id?: string;
+}
+declare class EventMarkers implements IPrimitive {
+    private _events;
+    private _host;
+    private _positions;
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    setEvents(events: readonly ChartEvent[]): void;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    hitTest(x: number, y: number): PrimitiveHit | null;
+}
+
+/**
+ * Top-level chart orchestrator (ARCHITECTURE.md §3.3). Owns the shared
+ * DataLayer + time scale, the panes, the invalidate mask, and the render loop.
+ * Phase 2 renders static candlesticks with price/time axes; pan/zoom (Phase 3)
+ * and live data (Phase 4) build on this.
+ */
+
+interface ChartOptions {
+    document?: Document;
+    pixelRatio?: () => number;
+    raf?: {
+        schedule: RafScheduler;
+        cancel?: RafCanceller;
+    };
+    /** Full palette; pass `darkTheme` (default), `lightTheme`, or a custom ChartTheme. */
+    theme?: ChartTheme;
+    priceAxisWidth?: number;
+    timeAxisHeight?: number;
+    /**
+     * Crosshair behaviour. 'normal' (default) — the cross follows the pointer
+     * exactly. 'magnet' — the horizontal line snaps to the nearest O/H/L/C of the
+     * bar under the cursor (price pane only).
+     */
+    crosshairMode?: CrosshairMode;
+    /** Time source for kinetic animation (defaults to performance.now). */
+    now?: () => number;
+    /** Enable OHLC-preserving conflation when zoomed out (§4.4). Default false. */
+    conflate?: boolean;
+    /** Conflation aggressiveness (default 1). */
+    conflationFactor?: number;
+    /** Grid line visibility. Both default to true. */
+    grid?: {
+        vertLines?: boolean;
+        horzLines?: boolean;
+    };
+    /** Accessible label for the chart container (screen readers). */
+    ariaLabel?: string;
+}
+interface AddSeriesOptions {
+    /** Target pane index (0 = price). Higher panes are created on demand. */
+    paneIndex?: number;
+    /** Style overrides merged onto the chart type's defaults. */
+    style?: SeriesStyle;
+}
+/**
+ * Emitted on every crosshair move (and `null` fields on pointer-leave) so a host
+ * can render an OHLC legend / tooltip. `bar` is the hovered bar of the primary
+ * price series; `point` is container-relative media px for positioning a
+ * floating tooltip. See `subscribeCrosshairMove`.
+ */
+interface CrosshairMoveEvent {
+    /** UTC seconds of the hovered bar, or null when off the data / pointer left. */
+    time: number | null;
+    /** Logical index under the cursor, or null. */
+    index: number | null;
+    /** Price under the cursor on the hovered pane, or null. */
+    price: number | null;
+    /** Hovered bar of the primary (first) price series, or null. */
+    bar: Bar | null;
+    /** Cursor position in container media px, or null on leave. */
+    point: {
+        x: number;
+        y: number;
+    } | null;
+}
+declare class Chart {
+    private readonly _container;
+    private readonly _doc;
+    private readonly _pixelRatio;
+    private readonly _theme;
+    private readonly _panes;
+    private readonly _loop;
+    private readonly _dataLayer;
+    private readonly _timeScale;
+    private readonly _priceAxisWidth;
+    private readonly _timeAxisHeight;
+    private _pending;
+    private _resizeObserver;
+    private _width;
+    private _height;
+    private _hasFitContent;
+    private readonly _crosshairMode;
+    private readonly _now;
+    private readonly _conflate;
+    private readonly _conflationFactor;
+    private _gridVert;
+    private _gridHorz;
+    private _cursorPane;
+    private _cursor;
+    private _dragging;
+    private _dragStartX;
+    private _dragStartY;
+    private _lastDragY;
+    private readonly _pointers;
+    private _pinch;
+    private _pinchPane;
+    private _liveRegion;
+    private _dragStartOffset;
+    private _lastDragX;
+    private _lastDragT;
+    private _dragVelocity;
+    private _kineticHandle;
+    private readonly _firstDataId;
+    /** Pane holding the primary price series (only this pane gets magnet snapping). */
+    private _firstPaneIndex;
+    private _historyLoader;
+    private _loadingHistory;
+    private _clickCb;
+    private _crosshairCb;
+    private _pointerMoved;
+    private _downPane;
+    private _downX;
+    private _downLocalY;
+    private _dragId;
+    private _dragCb;
+    private _dragEndCb;
+    private _axisDrag;
+    private _axisStartCoord;
+    private _axisStartMin;
+    private _axisStartMax;
+    private _axisStartSpacing;
+    constructor(container: HTMLElement, options?: ChartOptions);
+    /** Register a callback fired when the user pans near the left (oldest) edge. */
+    setHistoryLoader(loader: () => void): void;
+    /** Call after a history-paging load resolves to re-enable the trigger. */
+    historyLoadComplete(): void;
+    get dataLayer(): DataLayer;
+    get timeScale(): TimeScale;
+    /** Add a series and return its data handle. */
+    addSeries(type: SeriesType, options?: AddSeriesOptions): SeriesApi;
+    /** Add a horizontal price line (order/SL/TP/alert/level) to a pane. */
+    addPriceLine(opts: PriceLineOptions, paneIndex?: number): PriceLine;
+    /** Add an earnings/dividend/split event-marker strip to a pane. */
+    addEventMarkers(paneIndex?: number): EventMarkers;
+    /** Subscribe to clicks on hit-testable primitives (markers, events, lines). */
+    subscribeClick(cb: (externalId: string) => void): void;
+    /**
+     * 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.
+     */
+    subscribeCrosshairMove(cb: (e: CrosshairMoveEvent) => void): void;
+    /** Subscribe to drags of draggable lines (order/SL/TP). Fires per move and on release. */
+    subscribeDrag(onDrag: (externalId: string, price: number) => void, onDragEnd?: (externalId: string, price: number) => void): void;
+    /** Public: attach any primitive (indicators, profiles, custom overlays) to a pane. */
+    addPrimitive(primitive: IPrimitive, paneIndex?: number): void;
+    /**
+     * Map a price to a container-relative Y in media (CSS) px, for positioning DOM
+     * overlays (order panels, tooltips) over a pane. Returns null if the pane
+     * doesn't exist. The inverse is `coordinateToPrice`.
+     */
+    priceToCoordinate(price: number, paneIndex?: number): number | null;
+    /** Map a container-relative media-px Y back to a price on a pane (inverse of priceToCoordinate). */
+    coordinateToPrice(y: number, paneIndex?: number): number | null;
+    /**
+     * Toggle the vertical (time) and/or horizontal (price) grid lines at runtime.
+     * Omitted fields keep their current visibility. Repaints every pane.
+     */
+    setGridOptions(opts: {
+        vertLines?: boolean;
+        horzLines?: boolean;
+    }): void;
+    /** Current grid line visibility. */
+    gridOptions(): {
+        vertLines: boolean;
+        horzLines: boolean;
+    };
+    /**
+     * Flatten every pane's base + overlay canvas into one opaque canvas (device
+     * px). The chart renders as stacked layered canvases, so the browser's native
+     * right-click "Save image" only captures the layer under the pointer (usually
+     * the transparent crosshair overlay) — use this to export the full chart.
+     */
+    takeScreenshot(): HTMLCanvasElement;
+    private _addPrimitive;
+    /** Remove a primitive from whichever pane holds it. */
+    removePrimitive(primitive: IPrimitive): void;
+    /** A host for the (lazy-loaded) trade layer to attach/detach its primitives on a pane. */
+    tradeHost(paneIndex?: number): {
+        addPrimitive(p: IPrimitive): void;
+        removePrimitive(p: IPrimitive): void;
+    };
+    /** Apply one live bar; auto-scroll only on a genuine right-edge append. */
+    private _updateBar;
+    private _ensurePane;
+    private _setData;
+    /** History paging: merge older bars, preserving the viewport (§4.2). */
+    private _prependData;
+    private _addPane;
+    panes(): readonly Pane[];
+    invalidate(build: (mask: InvalidateMask) => void): void;
+    applySize(width: number, height: number): void;
+    /** Distribute height across panes by weight; sync the shared time-scale width. */
+    private _relayout;
+    private _weightTotal;
+    /** Cumulative top + height of each pane, by weight (the source of truth for hit-testing). */
+    private _paneLayout;
+    private _renderContext;
+    private _observeSize;
+    private _onFrame;
+    private _attachInput;
+    private _localPoint;
+    private readonly _onPointerDown;
+    private readonly _onPointerMove;
+    private readonly _onPointerUp;
+    private readonly _onPointerLeave;
+    private readonly _onWheel;
+    /**
+     * Restore the default view: fit all bars on the time axis and re-enable
+     * auto-scaling on every price axis (undoing any pan/zoom or manual axis drag).
+     * Same as double-clicking the chart.
+     */
+    resetScale(): void;
+    private readonly _onDblClick;
+    private _beginPinch;
+    private _updatePinch;
+    private readonly _onKeyDown;
+    /** Refresh the polite live-region summary screen readers announce. */
+    private _updateAccessibleSummary;
+    private _updateCursor;
+    private _maybeLoadHistory;
+    private _startKinetic;
+    private _stopKinetic;
+    destroy(): void;
+}
+/** Create a chart inside the given container element. */
+declare function createChart(container: HTMLElement, options?: ChartOptions): Chart;
+
+declare function verticalGradient(ctx: CanvasRenderingContext2D, heightPx: number, topColor: string, bottomColor: string): CanvasGradient;
+
+/**
+ * Generate up to ~`maxTicks` nicely-rounded tick values spanning [min, max].
+ * Returns ascending values aligned to the chosen step (may sit slightly inside
+ * the range). Returns a single midpoint when the range is degenerate.
+ */
+declare function niceTicks(min: number, max: number, maxTicks?: number): number[];
+/** Decimal places implied by a price step / tick size (for label formatting). */
+declare function precisionForStep(step: number): number;
+
+/**
+ * Candlestick renderer (ARCHITECTURE.md §6). Pure geometry helpers are split
+ * out for unit testing; drawing happens in the bitmap (device-px) scope.
+ */
+
+interface CandleStyle {
+    upColor: string;
+    downColor: string;
+    borderUpColor: string;
+    borderDownColor: string;
+    wickUpColor: string;
+    wickDownColor: string;
+    borderVisible: boolean;
+    wickVisible: boolean;
+    /** Draw up-candle bodies as outlines only (hollow candles). */
+    hollow?: boolean;
+    /** Per-bar body-width scale 0..1 (volume candles); 1 = full width. */
+    widthScale?: (bar: Bar) => number;
+}
+declare const DEFAULT_CANDLE_STYLE: CandleStyle;
+/**
+ * Pure: optimal candle body width in device px for a given bar spacing. Leaves
+ * a ~1px gap between candles, keeps a minimum of 1px, and matches odd/even
+ * parity with the wick so the body stays symmetric about the (1px) wick.
+ */
+declare function optimalBarWidth(barSpacing: number, dpr: number): number;
+
+/**
+ * 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;
+
+/**
+ * Live candle aggregation (ARCHITECTURE.md §10.2). The WS feed does not deliver
+ * interval candles — LTP mode gives a tick price (+ last-traded-qty), Quote mode
+ * gives a *cumulative day* volume. This builder buckets ticks into interval OHLC
+ * with explicit volume, session-reset, and late-tick policies. Pure and
+ * deterministic (no Date/rAF) so it is fully unit-testable.
+ */
+
+type VolumeMode = 'ltq-sum' | 'day-delta';
+type LateTickPolicy = 'foldIntoBar' | 'dropOlderThanPrevBar';
+interface CandleBuilderOptions {
+    intervalSec: number;
+    /** 'ltq-sum' accumulates last-traded-qty; 'day-delta' diffs cumulative day volume. */
+    volumeMode: VolumeMode;
+    lateTickPolicy: LateTickPolicy;
+    /**
+     * UTC-seconds of a known session open. Buckets align to it so e.g. 5-minute
+     * bars start at 09:15, not at an arbitrary epoch floor. Defaults to 0 (epoch).
+     */
+    sessionAnchorSec: number;
+}
+declare const DEFAULT_CANDLE_BUILDER_OPTIONS: CandleBuilderOptions;
+interface Tick {
+    time: UTCSeconds;
+    price: number;
+    /** Last-traded quantity (LTP mode). */
+    ltq?: number;
+    /** Cumulative day volume (Quote mode). */
+    cumDayVolume?: number;
+}
+interface CandleUpdate {
+    bar: Bar;
+    /** True when this tick started a new interval bar (append vs mutate-in-place). */
+    isNew: boolean;
+}
+declare class CandleBuilder {
+    private readonly _opts;
+    private _current;
+    private _cumAtBarStart;
+    private _lastCum;
+    private _hasCum;
+    constructor(options?: Partial<CandleBuilderOptions>);
+    /** Seed with the last historical bar so the first live tick continues it. */
+    seed(lastBar: Bar, cumDayVolumeSoFar?: number): void;
+    current(): Bar | null;
+    /** Bucket-start (bar-open) time for a tick, aligned to the session anchor. */
+    bucketStart(time: UTCSeconds): UTCSeconds;
+    /**
+     * Feed one tick. Returns the affected bar (mutated current or a fresh one),
+     * or `null` if the tick was dropped by the late-tick policy.
+     */
+    onTick(tick: Tick): CandleUpdate | null;
+    private _foldInto;
+    private _volumeForNewBar;
+    private _volumeForSameBar;
+}
+
+/**
+ * Logo / brand watermark (ARCHITECTURE.md §8). Draws a small image (or an
+ * already-decoded bitmap) faintly in a corner of the plot — the way charting
+ * apps stamp a product/brand mark. Because it draws on the canvas it is captured
+ * by `chart.takeScreenshot()`, and an optional `tint` recolors the opaque pixels
+ * so a single-color logo reads on both dark and light themes.
+ *
+ * Source-agnostic: pass a `src` (URL or data URI) or a preloaded `image`. The
+ * library ships no logo of its own, keeping the bundle lean.
+ */
+
+type WatermarkPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+interface LogoWatermarkOptions {
+    /** Image URL or data URI. Ignored when `image` is provided. */
+    src?: string;
+    /** A preloaded image/bitmap to draw (skips loading). */
+    image?: CanvasImageSource & {
+        width: number;
+        height: number;
+    };
+    /** Corner (or center) to anchor to. Default `bottom-right`. */
+    position?: WatermarkPosition;
+    /** Gap from the plot edges in px. Default `12`. */
+    margin?: number;
+    /** Rendered logo height in px; width follows the source aspect. Default `28`. */
+    height?: number;
+    /** 0..1. Default `0.7`. */
+    opacity?: number;
+    /** Recolor the opaque pixels to this color (e.g. a faint theme gray). */
+    tint?: string;
+    /** Layer order vs the series. Default `top`. */
+    zOrder?: ZOrder;
+}
+/** Top-left placement (in media px) of a `w x h` logo within a `plotW x plotH` plot. */
+declare function watermarkRect(position: WatermarkPosition, margin: number, w: number, h: number, plotW: number, plotH: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+declare class LogoWatermark implements IPrimitive {
+    private _opts;
+    private _host;
+    private _img;
+    private _ready;
+    private _tintCanvas;
+    private _tintKey;
+    constructor(opts?: LogoWatermarkOptions);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    autoscaleInfo(): null;
+    /** Live restyle. Pass a new `src`/`image` to swap the logo. */
+    setOptions(patch: Partial<LogoWatermarkOptions>): void;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    /** Recolor the opaque logo pixels to `color` at (dw x dh) device px, cached. */
+    private _tinted;
+}
+
+/**
+ * Exponential moving average (ARCHITECTURE.md §8 — an indicator that validates
+ * the series/extensibility model). Pure; the result is plotted as a `line`
+ * series, demonstrating derived data on the shared time axis.
+ */
+
+/** EMA over a numeric series. Seeds from the first value; k = 2/(period+1). */
+declare function ema(values: readonly number[], period: number): number[];
+/**
+ * EMA of bar closes as plottable bars (close = ema; O/H/L = ema), ready to feed
+ * a `line` series via `series.setData(...)`.
+ */
+declare function emaSeries(bars: readonly Bar[], period: number): Bar[];
+
+/**
+ * Relative Strength Index — Wilder's RSI, matching `openalgo.ta.rsi(close, 14)`.
+ *
+ * Uses Wilder smoothing (RMA): the first average gain/loss is the simple mean of
+ * the first `period` deltas, then each subsequent average carries
+ * `(prev*(period-1) + current)/period`. Warmup bars (before enough data) are NaN.
+ */
+
+/** Wilder RSI over a numeric series. Returns NaN for the first `period` slots. */
+declare function rsi(values: readonly number[], period?: number): number[];
+/**
+ * RSI of bar closes as plottable bars (close = rsi). Warmup bars carry NaN so a
+ * `line` series breaks cleanly before the first value (the renderer skips
+ * non-finite points) instead of dropping to zero.
+ */
+declare function rsiSeries(bars: readonly Bar[], period?: number): Bar[];
+
+/**
+ * Average True Range — Wilder's ATR, matching `openalgo.ta.atr(high, low, close, 14)`.
+ * Shared by the Supertrend indicator. True range of the first bar is high-low.
+ */
+/** True range series. tr[0] = high[0]-low[0]; thereafter the classic 3-way max. */
+declare function trueRange(high: readonly number[], low: readonly number[], close: readonly number[]): number[];
+/** Wilder ATR. First value (SMA of the first `period` TRs) lands at index period-1; earlier slots NaN. */
+declare function atr(high: readonly number[], low: readonly number[], close: readonly number[], period?: number): number[];
+
+/**
+ * Supertrend — matching `openalgo.ta.supertrend(high, low, close, period=10, multiplier=3.0)`,
+ * which returns (supertrend value, direction). Direction follows the OpenAlgo
+ * convention: -1 = uptrend (line is support below price), +1 = downtrend (line
+ * is resistance above price). ATR uses Wilder smoothing (see ./atr).
+ */
+
+interface SupertrendPoint {
+    /** The Supertrend band value, or NaN during ATR warmup. */
+    value: number;
+    /** -1 = uptrend (bullish), +1 = downtrend (bearish). */
+    direction: -1 | 1;
+}
+/** Supertrend value + direction per bar. Warmup bars carry value=NaN. */
+declare function supertrend(bars: readonly Bar[], period?: number, multiplier?: number): SupertrendPoint[];
+/**
+ * Supertrend as two plottable `line` series for direction coloring: `up`
+ * (uptrend / support, typically green) carries the value only while direction is
+ * -1; `down` (downtrend / resistance, typically red) only while +1. The inactive
+ * series carries NaN, so each renders as separate segments that swap at flips
+ * (the line renderer breaks across non-finite points).
+ */
+declare function supertrendSeries(bars: readonly Bar[], period?: number, multiplier?: number): {
+    up: Bar[];
+    down: Bar[];
+};
+
+/**
+ * Optional OHLC-preserving conflation / downsampling (ARCHITECTURE.md §4.4).
+ * When zoomed far out, many bars map to sub-pixel widths; drawing them all is
+ * wasted work. Conflation merges groups of bars into one, preserving candle
+ * shape — open = first, close = last, high = max, low = min, volume = sum
+ * (never a lossy average). Off by default; enabling it changes nothing until
+ * bars fall below the pixel threshold.
+ */
+
+/**
+ * How many source bars to merge per drawn bar. Returns 1 (no conflation) while
+ * each bar is at least `minPx` wide; otherwise ceil(minPx / barWidthPx) scaled
+ * by `factor` (higher = more aggressive smoothing).
+ */
+declare function conflationGroupSize(barSpacing: number, dpr: number, minPx?: number, factor?: number): number;
+/** Merge a single group of bars into one OHLC-preserving bar (uses the first bar's time). */
+declare function mergeBars(group: readonly Bar[]): Bar;
+/** Conflate a bar series into groups of `groupSize` (identity when groupSize ≤ 1). */
+declare function conflateBars(bars: readonly Bar[], groupSize: number): Bar[];
+/** Conflate already-projected draw items: merge bars and place x at the group centre. */
+declare function conflateItems<T extends {
+    x: number;
+    bar: Bar;
+}>(items: readonly T[], groupSize: number): {
+    x: number;
+    bar: Bar;
+}[];
+
+/** Cancels a subscription. */
+type UnsubscribeFn = () => void;
+interface BarsRequest {
+    symbol: string;
+    exchange: string;
+    /** Interval token, e.g. "1m", "5m", "1h", "D". */
+    interval: string;
+    from?: UTCSeconds;
+    to?: UTCSeconds;
+}
+/**
+ * Broker-agnostic market-data source. The chart depends only on this.
+ * `subscribeBars` is optional: a history-only feed (e.g. `OpenAlgoDataFeed`) omits
+ * it, while a live feed (`OpenAlgoLiveDataFeed`, or your own) implements it.
+ */
+interface DataFeed {
+    getBars(req: BarsRequest): Promise<Bar[]>;
+    subscribeBars?(req: BarsRequest, onBar: (bar: Bar) => void): UnsubscribeFn;
+    subscribeDepth?(req: BarsRequest, onDepth: (depth: MarketDepth) => void): UnsubscribeFn;
+}
+interface DepthLevel {
+    price: number;
+    qty: number;
+    orders?: number;
+}
+/** Variable-depth book; `bids`/`asks` length = whatever the broker streams (5..200). */
+interface MarketDepth {
+    bids: DepthLevel[];
+    asks: DepthLevel[];
+    ltp: number;
+    ltq?: number;
+}
+type OrderSide$1 = 'BUY' | 'SELL';
+type OrderType$1 = 'MARKET' | 'LIMIT' | 'SL' | 'SL-M';
+interface PlaceOrder {
+    symbol: string;
+    exchange: string;
+    side: OrderSide$1;
+    type: OrderType$1;
+    qty: number;
+    price?: number;
+    triggerPrice?: number;
+    /** Idempotency token so a retried place never double-fills. */
+    clientToken?: string;
+}
+/** Broker-agnostic trading source. */
+interface TradeFeed {
+    placeOrder(o: PlaceOrder): Promise<{
+        orderId: string;
+    }>;
+    modifyOrder(orderId: string, patch: Partial<PlaceOrder>): Promise<void>;
+    cancelOrder(orderId: string): Promise<void>;
+    subscribeOrders(cb: (orders: unknown[]) => void): UnsubscribeFn;
+    subscribePositions(cb: (positions: unknown[]) => void): UnsubscribeFn;
+}
+
+/**
+ * OpenAlgo REST adapter (ARCHITECTURE.md §10.0). The chart depends only on the
+ * `DataFeed` interface; this is the only file that knows OpenAlgo's REST shape.
+ *
+ * History endpoint: POST `${baseUrl}/api/v1/history`.
+ * NOTE: the exact request/response field names must be verified against the
+ * running OpenAlgo build and pinned here; the mapper below is tolerant of
+ * epoch-seconds, epoch-ms, and IST date/time string timestamps.
+ */
+
+interface OpenAlgoConfig {
+    baseUrl: string;
+    apiKey: string;
+    /** Injectable fetch (defaults to global fetch); lets the adapter be tested offline. */
+    fetchImpl?: typeof fetch;
+}
+interface HistoryRow {
+    timestamp?: number | string;
+    time?: number | string;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+interface HistoryResponse {
+    status?: string;
+    data?: HistoryRow[];
+}
+/** 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 class OpenAlgoDataFeed implements DataFeed {
+    private readonly _config;
+    private readonly _fetch;
+    constructor(config: OpenAlgoConfig);
+    getBars(req: BarsRequest): Promise<Bar[]>;
+}
+
+/**
+ * OpenAlgo WebSocket adapter (ARCHITECTURE.md §10, C2). Speaks the documented
+ * OpenAlgo WS proxy protocol (default port 8765, or wss://host/ws in production):
+ *
+ *   1. authenticate: { action:'authenticate', api_key }
+ *   2. subscribe   : { action:'subscribe', symbol, exchange, mode }   mode 1=LTP 2=Quote 3=Depth
+ *                    (Depth adds depth_level, e.g. 5/20/30/50)
+ *   3. server pushes { type:'market_data', mode, topic:'SYM.EXCH', data:{...} }
+ *   4. heartbeat   : server 'ping' → client 'pong' (30s)
+ *
+ * Maps inbound LTP / Quote / Depth into typed callbacks the chart consumes
+ * (candle builder, last price, DOM ladder). The socket is injectable so the
+ * adapter is unit-testable with a fake socket and no network.
+ */
+
+type WsMode = 'LTP' | 'Quote' | 'Depth';
+/** Socket lifecycle reported by `onState`. */
+type WsState = 'connecting' | 'open' | 'closed' | 'error';
+/** A non-market-data control frame (auth / subscribe ack, or a server error). */
+interface WsControlMessage {
+    type?: string;
+    status?: string;
+    message?: string;
+    [k: string]: unknown;
+}
+/** Minimal socket surface (the browser WebSocket satisfies this). */
+interface SocketLike {
+    send(data: string): void;
+    close(): void;
+    onopen: (() => void) | null;
+    onclose: (() => void) | null;
+    onerror?: (() => void) | null;
+    onmessage: ((ev: {
+        data: string;
+    }) => void) | null;
+    /** 1 === OPEN (browser WebSocket.OPEN). Used to gate sends. */
+    readyState?: number;
+}
+type SocketFactory = (url: string) => SocketLike;
+interface OpenAlgoWsConfig {
+    url: string;
+    apiKey: string;
+    socketFactory?: SocketFactory;
+}
+interface LtpEvent {
+    symbol: string;
+    exchange: string;
+    ltp: number;
+    ltq?: number;
+    /** Cumulative day volume (Quote mode) — feeds the candle builder's day-delta mode. */
+    volume?: number;
+    timeSec: number;
+}
+/**
+ * Pure: build a subscribe message — `{ action, symbol, exchange, mode }`, where
+ * `mode` is the numeric OpenAlgo data mode. Depth subscriptions may request a
+ * `depth_level` (broker-dependent: 5/20/30/50).
+ */
+declare function formatSubscribe(mode: WsMode, symbol: string, exchange: string, depthLevel?: number): string;
+declare function formatUnsubscribe(mode: WsMode, symbol: string, exchange: string): string;
+/**
+ * Pure: classify + normalise an inbound message into an LTP or Depth event.
+ * Payload fields live under `data` per the protocol, but the parser also
+ * tolerates a flat shape for resilience across broker adapters.
+ */
+declare function parseMessage(raw: unknown): {
+    kind: 'ltp';
+    event: LtpEvent;
+} | {
+    kind: 'depth';
+    symbol: string;
+    exchange: string;
+    depth: MarketDepth;
+} | null;
+declare class OpenAlgoWsFeed {
+    private readonly _config;
+    private readonly _factory;
+    private _sock;
+    private _open;
+    private readonly _queue;
+    private readonly _ltpCbs;
+    private readonly _depthCbs;
+    private readonly _stateCbs;
+    private readonly _controlCbs;
+    constructor(config: OpenAlgoWsConfig);
+    connect(): void;
+    /** Subscribe to socket lifecycle (connecting / open / closed / error). */
+    onState(cb: (state: WsState) => void): () => void;
+    /** Subscribe to control frames — auth / subscribe acks and server errors. */
+    onControl(cb: (msg: WsControlMessage) => void): () => void;
+    private _emitState;
+    /** Authenticate first, then flush any queued subscriptions (protocol order). */
+    private _onOpen;
+    /** Send now if open; otherwise queue until onopen (browsers throw on send-before-open). */
+    private _send;
+    private _flush;
+    onLtp(cb: (e: LtpEvent) => void): () => void;
+    onDepth(cb: (symbol: string, exchange: string, depth: MarketDepth) => void): () => void;
+    subscribe(mode: WsMode, symbol: string, exchange: string, depthLevel?: number): void;
+    unsubscribe(mode: WsMode, symbol: string, exchange: string): void;
+    close(): void;
+    private _dispatch;
+}
+
+/**
+ * Trade-layer data model (ARCHITECTURE.md §9). Broker-agnostic shapes the
+ * TradeFeed produces; the chart depends only on these, not on OpenAlgo's REST.
+ */
+type OrderSide = 'BUY' | 'SELL';
+type OrderType = 'MARKET' | 'LIMIT' | 'SL' | 'SL-M';
+/** Lifecycle states (§9.5). Phase 8 reconciles read-only; Phase 9 drives writes. */
+type OrderStatus = 'pending' | 'working' | 'partial' | 'filled' | 'cancelled' | 'rejected';
+type OrderRole = 'entry' | 'sl' | 'tp';
+interface Order {
+    id: string;
+    symbol: string;
+    side: OrderSide;
+    type: OrderType;
+    qty: number;
+    filledQty: number;
+    price: number;
+    triggerPrice?: number;
+    status: OrderStatus;
+    /** Links SL/TP child orders to their position/entry. */
+    parentId?: string;
+    role?: OrderRole;
+}
+interface Position {
+    symbol: string;
+    /** Net signed quantity: positive = long, negative = short, 0 = flat. */
+    netQty: number;
+    avgPrice: number;
+}
+
+/**
+ * Order engine (ARCHITECTURE.md §9.5) — the chart-trading write path. Drives the
+ * order state machine with: client-token idempotency, an arm/confirm gate,
+ * pre-trade validation, rate-limited drag-modify, OCO linking, and analyzer
+ * (sandbox) mode. Network-agnostic: it talks to an injected OrderFeed (the
+ * FakeBroker simulates it in tests/demos).
+ */
+
+interface PlaceRequest {
+    symbol: string;
+    exchange?: string;
+    side: OrderSide;
+    type: OrderType;
+    qty: number;
+    price?: number;
+    triggerPrice?: number;
+    /** Product: CNC (delivery), NRML (F&O carry), MIS (intraday). Required by OpenAlgo. */
+    product?: 'CNC' | 'NRML' | 'MIS';
+    /** Idempotency token; a retry with the same token is never double-sent. */
+    clientToken?: string;
+}
+interface OrderFeed {
+    place(req: PlaceRequest & {
+        mode: TradeMode;
+    }): Promise<{
+        orderId: string;
+    }>;
+    modify(orderId: string, patch: {
+        price?: number;
+        triggerPrice?: number;
+        qty?: number;
+    }): Promise<void>;
+    cancel(orderId: string): Promise<void>;
+}
+type TradeMode = 'live' | 'analyzer';
+
+/**
+ * OpenAlgo trade adapter (ARCHITECTURE.md §10.0). Implements the order engine's
+ * OrderFeed over OpenAlgo REST (`/api/v1/placeorder`, `/modifyorder`,
+ * `/cancelorder`) plus orderbook/positionbook fetches for reconciliation.
+ *
+ * Payloads match the local OpenAlgo docs: `placeorder` requires
+ * strategy/symbol/action/exchange/pricetype/product/quantity; `modifyorder`
+ * additionally requires the full order context, so we cache each order's context
+ * (from place + the order book) and merge the patch on modify. Book responses
+ * return string quantities/prices, which are coerced to numbers. Fetch is
+ * injectable for offline tests; verify field names against your OpenAlgo build.
+ */
+
+interface OpenAlgoTradeConfig {
+    baseUrl: string;
+    apiKey: string;
+    /** Strategy label sent with orders (OpenAlgo groups by strategy). */
+    strategy?: string;
+    /** Default product when a request doesn't specify one. */
+    defaultProduct?: 'CNC' | 'NRML' | 'MIS';
+    fetchImpl?: typeof fetch;
+}
+declare class OpenAlgoTradeFeed implements OrderFeed {
+    private readonly _config;
+    private readonly _fetch;
+    private readonly _strategy;
+    private readonly _defaultProduct;
+    private readonly _ctx;
+    constructor(config: OpenAlgoTradeConfig);
+    private _post;
+    place(req: PlaceRequest & {
+        mode: TradeMode;
+    }): Promise<{
+        orderId: string;
+    }>;
+    modify(orderId: string, patch: {
+        price?: number;
+        triggerPrice?: number;
+        qty?: number;
+    }): Promise<void>;
+    cancel(orderId: string): Promise<void>;
+    /** Fetch the order book for reconciliation (maps to broker-agnostic Order[]). */
+    getOrders(): Promise<Order[]>;
+    /** Fetch the position book for reconciliation. */
+    getPositions(): Promise<Position[]>;
+}
+interface RawOrder {
+    orderid?: string;
+    symbol?: string;
+    exchange?: string;
+    action?: string;
+    pricetype?: string;
+    product?: string;
+    quantity?: number | string;
+    filled_quantity?: number | string;
+    price?: number | string;
+    trigger_price?: number | string;
+    order_status?: string;
+}
+interface RawPosition {
+    symbol?: string;
+    quantity?: number | string;
+    average_price?: number | string;
+}
+declare function mapOrder(r: RawOrder): Order;
+declare function mapPosition(r: RawPosition): Position;
+
+/**
+ * Composed OpenAlgo live data feed (resolves audit V2-M1). Implements the full
+ * `DataFeed` contract by combining history (REST), live ticks (WS), and a
+ * per-subscription `CandleBuilder` — so `subscribeBars()` actually delivers live
+ * interval bars instead of being a no-op trap.
+ */
+
+interface OpenAlgoLiveConfig extends OpenAlgoConfig {
+    /** WS proxy URL, e.g. ws://127.0.0.1:8765. */
+    wsUrl: string;
+    /** Volume accounting for the live candle builder (default 'ltq-sum'). */
+    volumeMode?: VolumeMode;
+}
+/** Map an interval token (e.g. '1m','5m','1h','D') to seconds for bucketing. */
+declare function intervalToSeconds(interval: string): number;
+declare class OpenAlgoLiveDataFeed implements DataFeed {
+    private readonly _rest;
+    private readonly _ws;
+    private readonly _volumeMode;
+    constructor(config: OpenAlgoLiveConfig);
+    getBars(req: BarsRequest): Promise<Bar[]>;
+    /** Live interval bars: WS LTP → CandleBuilder → onBar (mutated/append bar). */
+    subscribeBars(req: BarsRequest, onBar: (bar: Bar) => void): UnsubscribeFn;
+    subscribeDepth(req: BarsRequest, onDepth: (depth: MarketDepth) => void): UnsubscribeFn;
+    close(): void;
+}
+
+/**
+ * Deterministic, in-memory data feed for tests and demos. No network.
+ * Generates a reproducible synthetic OHLC walk from a fixed seed so that
+ * pixel-diff and unit tests are stable across runs (no Math.random / Date.now).
+ */
+declare class FakeDataFeed implements DataFeed {
+    private readonly intervalSec;
+    constructor(intervalSec?: number);
+    getBars(req: BarsRequest): Promise<Bar[]>;
+    subscribeBars(_req: BarsRequest, _onBar: (bar: Bar) => void): UnsubscribeFn;
+}
+/** Pure, seeded synthetic bar generator (deterministic — no global randomness). */
+declare function generateBars(startTime: number, count: number, intervalSec: number): Bar[];
+
+/**
+ * Tick aggregation (ARCHITECTURE.md §10.2). Aggregates raw trade ticks into
+ * bars on a chosen timeframe — clock interval, tick count, or traded volume.
+ * Incremental and deterministic, so it works live and is unit-testable.
+ *
+ * This is the foundation for tick / volume timeframes and (with classified
+ * bid/ask ticks) for the footprint aggregator. Tick-count and volume bars need
+ * real trade ticks — OHLCV alone can't produce them.
+ */
+
+type TickTimeframe = {
+    mode: 'interval';
+    seconds: number;
+    anchorSec?: number;
+} | {
+    mode: 'ticks';
+    count: number;
+} | {
+    mode: 'volume';
+    perBar: number;
+};
+interface AggTick {
+    time: number;
+    price: number;
+    qty: number;
+}
+interface BarUpdate {
+    bar: Bar;
+    isNew: boolean;
+}
+declare class TickBarAggregator {
+    private readonly _tf;
+    private _cur;
+    private _count;
+    constructor(tf: TickTimeframe);
+    current(): Bar | null;
+    onTick(tick: AggTick): BarUpdate;
+}
+
+/**
+ * Time conversions (ARCHITECTURE.md §4.0). Internal time is always UTC seconds.
+ * Feed adapters convert broker formats here, at the edge:
+ *   - REST history → IST date/time strings
+ *   - WS feed      → epoch milliseconds
+ * India observes no DST, so IST is a fixed UTC+5:30 offset.
+ */
+/** IST offset in seconds (UTC+5:30). */
+declare const IST_OFFSET_SECONDS: number;
+/** Epoch milliseconds → UTC seconds. */
+declare function epochMsToUtcSeconds(ms: number): number;
+/**
+ * Parse an IST wall-clock date/time string to UTC seconds. Accepts
+ * `YYYY-MM-DD`, `YYYY-MM-DD HH:MM[:SS]`, and the `T`-separated ISO variant.
+ * Parsing is explicit (never relies on the host machine's locale/timezone).
+ */
+declare function istStringToUtcSeconds(input: string): number;
+interface IstParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    /** 0 = Sunday .. 6 = Saturday, in IST. */
+    weekday: number;
+}
+/** UTC seconds → IST calendar parts (for axis labels / tick decisions). */
+declare function utcSecondsToIstParts(utcSeconds: number): IstParts;
+/** Format UTC seconds as an IST `HH:MM` clock label. */
+declare function formatIstTime(utcSeconds: number): string;
+/** Format UTC seconds as an IST `HH:MM:SS` clock label (sub-minute / tick timeframes). */
+declare function formatIstTimeSeconds(utcSeconds: number): string;
+/** Format UTC seconds as an IST `YYYY-MM-DD` date (for OpenAlgo history requests). */
+declare function utcSecondsToIstDateString(utcSeconds: number): string;
+/** Format UTC seconds as an IST `DD Mon` date label. */
+declare function formatIstDate(utcSeconds: number): string;
+/** True if the two UTC-second instants fall on different IST calendar days. */
+declare function isNewIstDay(prevUtcSeconds: number, utcSeconds: number): boolean;
+
+/** Clamp `value` into the inclusive range [min, max]. */
+declare function clamp(value: number, min: number, max: number): number;
+/** Linear interpolation between `a` and `b` by fraction `t` (0..1). */
+declare function lerp(a: number, b: number, t: number): number;
+/**
+ * Round `value` to the nearest multiple of `step` (the instrument tick size).
+ * Used for snapping dragged order/SL/TP prices to a valid tick. Returns
+ * `value` unchanged when `step <= 0`.
+ */
+declare function roundToTick(value: number, step: number): number;
+
+export { type AddSeriesOptions, type AggTick, type Bar, type BarUpdate, type BarsRequest, CandleBuilder, type CandleBuilderOptions, type CandleStyle, type CandleUpdate, Chart, type ChartEvent, type ChartOptions, type ChartTheme, type CrosshairMoveEvent, DEFAULT_CANDLE_BUILDER_OPTIONS, DEFAULT_CANDLE_STYLE, DEFAULT_HISTOGRAM_STYLE, DEFAULT_PRICE_SCALE_OPTIONS, DEFAULT_THEME, DEFAULT_TIME_SCALE_OPTIONS, type DataFeed, type DepthLevel, type DrawItem, EventMarkers, FakeDataFeed, type HistogramStyle, type IPrimitive, IST_OFFSET_SECONDS, InvalidationLevel, type LateTickPolicy, type LinePoint, type LogicalRange, LogoWatermark, type LogoWatermarkOptions, type LtpEvent, type MarkerPosition, type MarkerShape, type MarkerSize, type MarketDepth, type OpenAlgoConfig, OpenAlgoDataFeed, type OpenAlgoLiveConfig, OpenAlgoLiveDataFeed, type OpenAlgoTradeConfig, OpenAlgoTradeFeed, type OpenAlgoWsConfig, OpenAlgoWsFeed, type OrderSide$1 as OrderSide, type OrderType$1 as OrderType, type OriginalTime, Pane, type PaneInvalidation, type PlaceOrder, PriceLine, type PriceLineOptions, type PriceRange, PriceScale, type PriceScaleMode, type PriceScaleOptions, type PrimitiveHit, type PrimitiveHost, type PrimitiveRenderContext, type RendererEntry, type SeriesApi, type SeriesMarker, SeriesMarkers, type SeriesRenderContext, type SeriesStyle, type SeriesType, type Size, type SocketFactory, type SocketLike, type SupertrendPoint, type Tick, TickBarAggregator, type TickTimeframe, TimeScale, type TimeScaleOp, type TimeScaleOptions, type TradeFeed, type UTCSeconds, type UnsubscribeFn, VERSION, type VolumeMode, type WatermarkPosition, type Whitespace, type WsControlMessage, type WsMode, type WsState, type ZOrder, atr, autoscaleRange, bestHit, bitmapSize, clamp, conflateBars, conflateItems, conflationGroupSize, createChart, darkTheme, drawShape, effectiveMarkerPx, ema, emaSeries, epochMsToUtcSeconds, formatIstDate, formatIstTime, formatIstTimeSeconds, formatSubscribe, formatUnsubscribe, generateBars, getChartType, intervalToSeconds, isNewIstDay, isWhitespace, istStringToUtcSeconds, lerp, lightTheme, mapHistoryResponse, mapOrder, mapPosition, markerSizePx, mergeBars, niceTicks, optimalBarWidth, parseMessage, precisionForStep, registerChartType, registeredChartTypes, roundToTick, rowTimeToUtcSeconds, rsi, rsiSeries, snapToDevicePixel, supertrend, supertrendSeries, trueRange, utcSecondsToIstDateString, utcSecondsToIstParts, version, verticalGradient, watermarkRect };