openalgo-charts 1.0.0

package/dist/trade/index.d.ts

@@ -0,0 +1,680 @@
+/**
+ * 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;
+}
+/** A working order is one still live in the book (not terminal). */
+declare function isWorking(o: Order): boolean;
+
+/**
+ * P&L and risk math (ARCHITECTURE.md §9.1). Pure functions — the hot path on
+ * every LTP tick, and the part most worth unit-testing.
+ */
+
+/** Unrealized P&L for a position at the given last price. */
+declare function unrealizedPnl(position: Position, ltp: number): number;
+/** Unrealized P&L as a percentage of the entry notional. */
+declare function unrealizedPnlPercent(position: Position, ltp: number): number;
+/** Breakeven price (entry ± per-unit charges; charges default 0). */
+declare function breakeven(position: Position, chargesPerUnit?: number): number;
+/** Risk:reward for a bracket relative to entry. Returns null if risk is zero. */
+declare function riskReward(entry: number, stop: number, target: number): number | null;
+/** True if a stop/target is correctly placed for the side (long: SL<entry<TP). */
+declare function bracketValid(side: 'BUY' | 'SELL', entry: number, stop: number, target: number): boolean;
+
+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 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;
+}
+
+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 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;
+}
+
+/**
+ * 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;
+/** 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Working-order line (ARCHITECTURE.md §9.1). A horizontal line at the order
+ * price, colored by side, labelled with side/qty/distance-from-LTP. Phase 8 is
+ * read-only; drag-to-modify and the ✕ cancel hit-zone arrive in Phase 9 (the
+ * hit-test already returns the order id + an ns-resize cursor for that).
+ */
+
+declare class WorkingOrderLine implements IPrimitive {
+    private _order;
+    private _ltp;
+    private _host;
+    constructor(order: Order);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    get order(): Order;
+    update(order: Order): void;
+    setLtp(ltp: number): void;
+    autoscaleInfo(): {
+        min: number;
+        max: number;
+    };
+    private _price;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    hitTest(x: number, y: number, rc: PrimitiveRenderContext): PrimitiveHit | null;
+}
+
+/**
+ * Position marker (ARCHITECTURE.md §9.1). A line at the average entry price with
+ * a live unrealized-P&L tag (₹ and %), colored by P&L sign, plus a breakeven
+ * reference. Updates cheaply on every LTP tick (overlay-only repaint).
+ */
+
+declare class PositionMarker implements IPrimitive {
+    private _position;
+    private _ltp;
+    private _host;
+    constructor(position: Position);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    get position(): Position;
+    update(position: Position): void;
+    setLtp(ltp: number): void;
+    autoscaleInfo(): {
+        min: number;
+        max: number;
+    };
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    hitTest(x: number, y: number, rc: PrimitiveRenderContext): PrimitiveHit | null;
+}
+
+/**
+ * Bracket group (ARCHITECTURE.md §9.1). SL + Target lines tied to a position,
+ * with shaded risk (red) and reward (green) zones and an R:R label — the core
+ * advanced-trade-management visualisation. Phase 8 is read-only; Phase 9 makes
+ * the SL/TP lines draggable (OCO modify).
+ */
+
+interface BracketState {
+    symbol: string;
+    side: OrderSide;
+    entry: number;
+    stop: number;
+    target: number;
+}
+declare class BracketGroup implements IPrimitive {
+    private _state;
+    private _host;
+    constructor(state: BracketState);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    get state(): BracketState;
+    update(state: BracketState): void;
+    autoscaleInfo(): {
+        min: number;
+        max: number;
+    };
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    hitTest(x: number, y: number, rc: PrimitiveRenderContext): PrimitiveHit | null;
+}
+
+/**
+ * Trade controller (ARCHITECTURE.md §9.3) — read-only in Phase 8. The single
+ * source of truth: it reconciles order/position book snapshots into on-chart
+ * primitives (add/update/remove) and pushes LTP into them for live P&L. On a
+ * reconnect, a fresh snapshot is diffed against current primitives, so vanished
+ * orders are removed (STALE handling) with no special code path.
+ */
+
+/** Where the controller attaches/detaches its primitives (the chart implements this). */
+interface TradeHost {
+    addPrimitive(p: IPrimitive): void;
+    removePrimitive(p: IPrimitive): void;
+}
+declare class TradeController {
+    private readonly _host;
+    private readonly _orderLines;
+    private readonly _markers;
+    private readonly _brackets;
+    private readonly _ltp;
+    constructor(host: TradeHost);
+    /** Reconcile a full book snapshot. Idempotent — safe to call on every update or reconnect. */
+    reconcile(orders: readonly Order[], positions: readonly Position[]): void;
+    private _reconcileOrderLines;
+    private _reconcilePositions;
+    private _reconcileBrackets;
+    /** Push a last price; updates the live P&L / distance on bound primitives. */
+    onLtp(symbol: string, ltp: number): void;
+    /** Test/introspection helpers. */
+    orderLineCount(): number;
+    positionCount(): number;
+    bracketCount(): number;
+}
+
+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;
+}
+
+/**
+ * Order state machine (ARCHITECTURE.md §9.5). Explicit client-side states with
+ * a guarded transition table — no optimistic guesswork. Pure and fully testable.
+ *
+ *   pending_place ─ack→ working ─fill→ filled
+ *                 ─reject→ rejected
+ *   working/partial ─submitModify→ modify_pending ─ack→ working / ─reject→ working
+ *   working/partial ─submitCancel→ cancel_pending ─cancelled→ cancelled / ─reject→ working
+ *   any non-terminal ─reconnectAbsent→ stale
+ */
+type ClientOrderState = 'pending_place' | 'working' | 'partial' | 'filled' | 'modify_pending' | 'cancel_pending' | 'rejected' | 'cancelled' | 'stale';
+type OrderEvent = 'ack' | 'partialFill' | 'fill' | 'reject' | 'submitModify' | 'submitCancel' | 'cancelled' | 'reconnectAbsent';
+declare function isTerminal(state: ClientOrderState): boolean;
+/** Whether `event` is allowed from `state`. */
+declare function canTransition(state: ClientOrderState, event: OrderEvent): boolean;
+/** Apply `event`; returns the next state, or the same state if the event is invalid. */
+declare function transition(state: ClientOrderState, event: OrderEvent): ClientOrderState;
+
+interface PriceBand {
+    lower: number;
+    upper: number;
+}
+interface ValidationResult {
+    ok: boolean;
+    reason?: string;
+    /** Price after tick-size snapping (when applicable). */
+    price?: number;
+}
+interface OrderConstraints {
+    tickSize: number;
+    priceBand?: PriceBand;
+    /** Max quantity per single order (exchange freeze limit). */
+    freezeQty?: number;
+}
+/** True if `price` lies within the inclusive band. */
+declare function withinPriceBand(price: number, band: PriceBand): boolean;
+/**
+ * Validate a price + qty against constraints. Snaps price to the tick size and
+ * returns the snapped value; rejects out-of-band prices and over-freeze qty.
+ */
+declare function validateOrder(price: number, qty: number, c: OrderConstraints): ValidationResult;
+
+/**
+ * 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';
+type GateFn = (req: PlaceRequest) => boolean | Promise<boolean>;
+interface OrderEngineOptions {
+    feed: OrderFeed;
+    constraints: OrderConstraints;
+    mode?: TradeMode;
+    /** Armed = fire immediately; otherwise the gate must approve each order. */
+    armed?: boolean;
+    gate?: GateFn;
+    minModifyIntervalMs?: number;
+    now?: () => number;
+    idGen?: () => string;
+    /** Called when a drag-modify price fails validation (so the UI can snap back). */
+    onValidationError?: (reason: string) => void;
+}
+interface PlaceResult {
+    ok: boolean;
+    clientId?: string;
+    state?: ClientOrderState;
+    reason?: string;
+}
+declare class OrderEngine {
+    private readonly _feed;
+    private readonly _constraints;
+    private readonly _mode;
+    private readonly _armed;
+    private readonly _gate?;
+    private readonly _minModifyMs;
+    private readonly _now;
+    private readonly _idGen;
+    private readonly _onValidationError?;
+    private readonly _orders;
+    private readonly _byBroker;
+    private readonly _sentTokens;
+    private readonly _lastModifyAt;
+    private readonly _pendingModify;
+    private _counter;
+    constructor(opts: OrderEngineOptions);
+    get mode(): TradeMode;
+    state(clientId: string): ClientOrderState | undefined;
+    placeOrder(req: PlaceRequest): Promise<PlaceResult>;
+    /** One-click market order. */
+    placeMarket(symbol: string, side: OrderSide, qty: number): Promise<PlaceResult>;
+    /** Link two orders as OCO: when one fills/cancels, the other is cancelled. */
+    linkOco(clientIdA: string, clientIdB: string): void;
+    /**
+     * Rate-limited modify (drag): coalesces to the latest, sends at most every
+     * minModifyMs. An invalid price (tick/band/freeze) is NOT enqueued or sent —
+     * it surfaces via `onValidationError` so the UI can snap the line back.
+     */
+    requestModify(clientId: string, price: number): void;
+    /** Force-send any pending modify (e.g. on drag end). */
+    commitModify(clientId: string): Promise<void>;
+    private _flushModify;
+    cancelOrder(clientId: string): Promise<void>;
+    /** Broker fill event (by broker id). Advances state and triggers OCO. */
+    onFill(brokerId: string, full: boolean): void;
+    private _cancelOcoPeer;
+    /** On reconnect, mark any non-terminal order absent from the fresh book as STALE. */
+    onReconnect(presentBrokerIds: ReadonlySet<string>): void;
+}
+
+/**
+ * Deterministic in-memory broker simulator (ARCHITECTURE.md §11.1). Holds order
+ * and position snapshots and notifies subscribers — lets the trade layer be
+ * tested and demoed with zero network. Phase 9 extends it with the place/modify/
+ * cancel state machine; Phase 8 uses it read-only (seed snapshots + emit LTP).
+ */
+
+declare class FakeBroker implements OrderFeed {
+    private _orders;
+    private _positions;
+    private readonly _bookListeners;
+    private readonly _ltpListeners;
+    private readonly _depthListeners;
+    private _idCounter;
+    /** Set to a reason to make the next place() reject (test hook). */
+    rejectNextPlace: string | null;
+    onBook(cb: (orders: Order[], positions: Position[]) => void): void;
+    onLtp(cb: (symbol: string, ltp: number) => void): void;
+    /** Replace the current book snapshot and notify (simulates a poll / WS update / reconnect). */
+    setBook(orders: Order[], positions: Position[]): void;
+    emitLtp(symbol: string, ltp: number): void;
+    onDepth(cb: (symbol: string, depth: MarketDepth) => void): void;
+    emitDepth(symbol: string, depth: MarketDepth): void;
+    /** Build a deterministic N-level synthetic book around `ltp` (demo/test helper). */
+    static makeDepth(ltp: number, levels: number, tickSize?: number): MarketDepth;
+    orders(): readonly Order[];
+    positions(): readonly Position[];
+    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>;
+    /** Simulate a fill for an order (test hook). */
+    fill(orderId: string): void;
+    private _notify;
+}
+
+/**
+ * Depth-of-market ladder (ARCHITECTURE.md §9.4). Docked to the right of the
+ * plot, price-aligned to the price scale. Depth-agnostic: it reads the level
+ * count from the payload (5 / 20 / 30 / 50 / 200) at runtime. Viewport
+ * virtualization keeps a deep book at 60 fps; price-bucket aggregation compacts
+ * deep books; a size heatmap highlights resting liquidity; and it degrades
+ * gracefully to nothing when no depth is available.
+ *
+ * Pure helpers (capability / aggregation / virtualization) are split out for
+ * unit testing; the primitive draws on the top (overlay) canvas so frequent
+ * depth updates only repaint the cheap overlay.
+ */
+
+type LadderTier = 'none' | 'compact' | 'deep';
+/** Capability tier from the live payload — drives graceful degradation. */
+declare function ladderCapability(depth: MarketDepth): LadderTier;
+interface LadderRow {
+    price: number;
+    bidQty: number;
+    askQty: number;
+}
+/**
+ * Merge bids + asks into price rows, optionally bucketing every `groupBy` ticks
+ * (price-step aggregation for deep books). Returns rows sorted high → low price.
+ */
+declare function buildRows(depth: MarketDepth, tickSize: number, groupBy?: number): LadderRow[];
+/**
+ * Virtualize: keep only rows whose y is inside the plot (± one row) and cap the
+ * count to `maxRows` nearest the vertical centre (around the LTP). This is what
+ * keeps a 200-level book cheap and readable.
+ */
+declare function visibleRows(rows: readonly LadderRow[], priceToY: (p: number) => number, plotHeight: number, rowHeight: number, maxRows: number): LadderRow[];
+interface DomLadderOptions {
+    tickSize: number;
+    /** Strip width in media px. */
+    width: number;
+    /** Group every N ticks into one row (deep-book aggregation). */
+    groupBy: number;
+    /** Max rows drawn per frame (virtualization cap). */
+    maxRows: number;
+    rowHeight: number;
+}
+declare const DEFAULT_DOM_LADDER_OPTIONS: DomLadderOptions;
+declare class DomLadder implements IPrimitive {
+    private _opts;
+    private _depth;
+    private _host;
+    private _rowHits;
+    constructor(options?: Partial<DomLadderOptions>);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    setDepth(depth: MarketDepth): void;
+    tier(): LadderTier;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    hitTest(x: number, y: number, rc: PrimitiveRenderContext): PrimitiveHit | null;
+}
+
+declare const TRADE_TIER: "trade";
+
+export { BracketGroup, type BracketState, type ClientOrderState, DEFAULT_DOM_LADDER_OPTIONS, DomLadder, type DomLadderOptions, FakeBroker, type GateFn, type LadderRow, type LadderTier, type Order, type OrderConstraints, OrderEngine, type OrderEngineOptions, type OrderEvent, type OrderFeed, type OrderRole, type OrderSide, type OrderStatus, type OrderType, type PlaceRequest, type PlaceResult, type Position, PositionMarker, type PriceBand, TRADE_TIER, TradeController, type TradeHost, type TradeMode, type ValidationResult, WorkingOrderLine, bracketValid, breakeven, buildRows, canTransition, isTerminal, isWorking, ladderCapability, riskReward, transition, unrealizedPnl, unrealizedPnlPercent, validateOrder, visibleRows, withinPriceBand };