@christtrade/depth 0.12.21

package/types/hooks/useChartInteraction.d.ts

@@ -0,0 +1,160 @@
+import { type MutableRefObject, type RefObject } from 'react';
+import { type Drawing, type DraftDrawing, type Anchor, DrawingAnchorId, ActiveDrawingTool } from '../lib/types/drawing-types';
+import { type ChartPane, type Indicator, type Rect } from '../lib/types/indicator-types';
+import { type Crosshair } from '../lib/renderers/renderer';
+import { type PluginToolActiveContext } from '../core/DrawingRegistry';
+import type { ChartTypePlugin, ChartTypeActiveContext } from '../core/PluginRegistry';
+import { type RenderEngine } from '../core/RenderEngine';
+import { type TypedEventBus } from '../core/TypedEventBus';
+import { type SessionMapper } from '../core/SessionMapper';
+import { type TradingSession, type DataLevel, type SymbolInfo } from '../interfaces/IDataAdapter';
+import { type LiveTransformer } from '../interfaces/ICoordinateTransformer';
+import { type ViewBounds, type PriceHistory, type TradePoint, type OhlcvBarMs } from '../lib/types';
+import { type FootprintBar } from '../lib/types/footprint';
+import { type ChartSettings } from '../lib/types/chart-settings';
+import { type Timeframe } from '../lib/timeframes';
+import { type BookState } from '../lib/types';
+import { type SerialTrade } from '../lib/types';
+import { type FeaturesOptions } from '../core/DepthChart';
+import { type DomPanelHandle } from '../lib/types';
+type ShiftAnchor = {
+    ts: bigint;
+    price: number;
+    x: number;
+    y: number;
+};
+export interface UseChartInteractionParams {
+    status: 'loading' | 'ready' | 'error';
+    /**
+     * This chart cell's id. In a multi-chart layout every cell shares one
+     * eventBus, so status:compute emissions are tagged with this id and each
+     * StatusBar only reacts to its own cell's events.
+     */
+    cellId: number;
+    baseCanvasRef: RefObject<HTMLCanvasElement>;
+    uiCanvasRef: RefObject<HTMLCanvasElement>;
+    chartAreaRef: RefObject<HTMLDivElement>;
+    containerRef: RefObject<HTMLDivElement>;
+    viewRef: MutableRefObject<ViewBounds | null>;
+    /** Auto-computed right price-axis width (css px). */
+    priceScaleWidthRef: MutableRefObject<number>;
+    /** Resolved symbol info - used to derive the instrument tick size. */
+    symbolInfoRef: MutableRefObject<SymbolInfo | null>;
+    layoutsCacheRef: MutableRefObject<Record<string, Rect>>;
+    isYAxisAutoRef: MutableRefObject<boolean>;
+    drawingsRef: MutableRefObject<Drawing[]>;
+    draftRef: MutableRefObject<DraftDrawing | null>;
+    selectedDrawingIdRef: MutableRefObject<string | null>;
+    hoveredDrawingIdRef: MutableRefObject<string | null>;
+    hotAnchorRef: MutableRefObject<DrawingAnchorId | null>;
+    draggingAnchorRef: MutableRefObject<{
+        drawingId: string;
+        anchor: DrawingAnchorId;
+    } | null>;
+    dragStartRef: MutableRefObject<{
+        x: number;
+        y: number;
+    } | null>;
+    dragPrevDataRef: MutableRefObject<{
+        ts: bigint;
+        price: number;
+    } | null>;
+    dragPrevPixelRef: MutableRefObject<{
+        x: number;
+        y: number;
+    } | null>;
+    fvpLiveRecalcRef: MutableRefObject<boolean>;
+    activeCtxRef: MutableRefObject<PluginToolActiveContext | null>;
+    panesRef: MutableRefObject<ChartPane[]>;
+    indicatorsRef: MutableRefObject<Indicator[]>;
+    draggingDividerRef: MutableRefObject<number>;
+    dragPaneIdRef: MutableRefObject<string | null>;
+    hoveredDividerIdxRef: MutableRefObject<number>;
+    hoveredDividerIdxRefLocked: MutableRefObject<boolean>;
+    hoveredPaneIdRef: MutableRefObject<string | null>;
+    activeToolRef: MutableRefObject<ActiveDrawingTool>;
+    chartSettingsRef: MutableRefObject<ChartSettings>;
+    activeTimeframeRef: MutableRefObject<Timeframe>;
+    sessionMapperRef: MutableRefObject<SessionMapper>;
+    resolvedSessionRef: MutableRefObject<TradingSession | null>;
+    renderEngineRef: MutableRefObject<RenderEngine | null>;
+    pluginChartTypesRef: MutableRefObject<Map<string, ChartTypePlugin>>;
+    activeChartTypeBottomBarIds: MutableRefObject<Set<string>>;
+    crosshairRef: MutableRefObject<Crosshair | null>;
+    isDragging: MutableRefObject<boolean>;
+    dragMode: MutableRefObject<string>;
+    isHoldingCtrlRef: MutableRefObject<boolean>;
+    isHoldingShiftRef: MutableRefObject<boolean>;
+    lastMouse: MutableRefObject<{
+        x: number;
+        y: number;
+    }>;
+    hasDragged: MutableRefObject<boolean>;
+    longPressTimer: MutableRefObject<ReturnType<typeof setTimeout> | null>;
+    showTooltipRef: MutableRefObject<boolean>;
+    shiftAnchorRef: MutableRefObject<ShiftAnchor | null>;
+    shiftAnchor2Ref: MutableRefObject<ShiftAnchor | null>;
+    showShiftInfo: MutableRefObject<boolean>;
+    lastStatusLineUpdateRef: MutableRefObject<number>;
+    horizonRef: MutableRefObject<bigint>;
+    tradesRef: MutableRefObject<TradePoint[]>;
+    priceHistoryRef: MutableRefObject<PriceHistory[]>;
+    allPriceHistoryRef: MutableRefObject<PriceHistory[]>;
+    ohlcvBarsRef: MutableRefObject<{
+        barNs: bigint;
+        bars: OhlcvBarMs[];
+        display: OhlcvBarMs[];
+    }>;
+    previewBarsRef: MutableRefObject<OhlcvBarMs[]>;
+    dataLevelRef: MutableRefObject<DataLevel | null>;
+    openBarRef: MutableRefObject<FootprintBar | null>;
+    candleCacheRef: MutableRefObject<Map<bigint, any> | null>;
+    footprintBarsRef: MutableRefObject<FootprintBar[]>;
+    datasetStartRef: MutableRefObject<bigint>;
+    datasetEndRef: MutableRefObject<bigint>;
+    horizonScrollAnimRef: MutableRefObject<any>;
+    liveBookRef: MutableRefObject<BookState>;
+    tradeLineInteractionRef: MutableRefObject<any>;
+    selectedTradeRef: MutableRefObject<TradePoint | null>;
+    transformer: LiveTransformer;
+    eventBus: TypedEventBus;
+    features: FeaturesOptions;
+    showTimeframeWindowRef: MutableRefObject<boolean>;
+    setActiveTool: (tool: ActiveDrawingTool) => void;
+    setSelectedDrawingId: (id: string | null) => void;
+    setSettingsBarPos: (pos: {
+        x: number;
+        y: number;
+    } | null) => void;
+    setContextMenu: (ctx: any) => void;
+    setPanes: (updater: ((prev: ChartPane[]) => ChartPane[]) | ChartPane[]) => void;
+    setChartSettings: (updater: ((prev: ChartSettings) => ChartSettings) | ChartSettings) => void;
+    setEditingTextId: (id: string | null) => void;
+    setOpenSettingsDialog: (open: boolean) => void;
+    setShowTimeframeWindow: (show: boolean) => void;
+    setTimeframeWindowInput: (input: string) => void;
+    setPendingText: (text: {
+        x: number;
+        y: number;
+        anchor: Anchor;
+    } | null) => void;
+    pushDrawParams: () => void;
+    /** Publish this pane's visible time range to a time/date-range-synced layout. */
+    publishTimeRangeSync: () => void;
+    scheduleResample: () => void;
+    runIndicatorWorker: (trades: SerialTrade[], barNs: bigint) => void;
+    getTradesUpToHorizon: (horizon: bigint) => TradePoint[];
+    updateSettingsBarPos: (id: string | null) => void;
+    handleDeleteDrawing: (id: string) => void;
+    autofitPanesSilent: () => void;
+    autofitIndicatorPanes: () => void;
+    getPanel: () => DomPanelHandle | null;
+    getLayouts: () => Record<string, Rect>;
+    recomputeLayouts: () => void;
+    syncPixelLayouts: (panes?: ChartPane[]) => void;
+    applyLayoutsToDom: (layouts: Record<string, Rect>) => void;
+    buildChartTypeActiveCtx: () => ChartTypeActiveContext;
+    hideTimeScale: boolean;
+}
+export declare function useChartInteraction(p: UseChartInteractionParams): void;
+export {};

package/types/hooks/useChartLayout.d.ts

@@ -0,0 +1,21 @@
+import { type MutableRefObject, type RefObject } from 'react';
+import { type ChartPane, type Rect } from '../lib/types/indicator-types';
+import { type ChartSettings } from '../lib/types/chart-settings';
+export interface UseChartLayoutParams {
+    baseCanvasRef: RefObject<HTMLCanvasElement>;
+    panesRef: MutableRefObject<ChartPane[]>;
+    chartSettingsRef: MutableRefObject<ChartSettings>;
+    /** Auto-computed right price-axis width (css px). */
+    priceScaleWidthRef: MutableRefObject<number>;
+    hideTimeScale: boolean;
+}
+export interface UseChartLayoutResult {
+    layoutsCacheRef: MutableRefObject<Record<string, Rect>>;
+    legendElemsRef: MutableRefObject<Map<string, HTMLDivElement>>;
+    panePixelLayouts: Record<string, Rect>;
+    recomputeLayouts: () => void;
+    getLayouts: () => Record<string, Rect>;
+    syncPixelLayouts: (nextPanes?: ChartPane[]) => void;
+    applyLayoutsToDom: (layouts: Record<string, Rect>) => void;
+}
+export declare function useChartLayout(p: UseChartLayoutParams): UseChartLayoutResult;

package/types/hooks/useChartPlugin.d.ts

@@ -0,0 +1,34 @@
+import { type MutableRefObject } from 'react';
+import { type RenderEngine } from '../core/RenderEngine';
+import { type TypedEventBus } from '../core/TypedEventBus';
+import { type ChartTypePlugin, type ChartTypeActiveContext } from '../core/PluginRegistry';
+import { type ChartPane, type Indicator } from '../lib/types/indicator-types';
+import { type DataLevel } from '../interfaces/IDataAdapter';
+import { type Timeframe } from '../lib/timeframes';
+import { type TradePoint } from '../lib/types';
+export interface UseChartPluginParams {
+    renderEngineRef: MutableRefObject<RenderEngine | null>;
+    uiCanvasRef: MutableRefObject<HTMLCanvasElement | null>;
+    eventBus: TypedEventBus;
+    indicatorsRef: MutableRefObject<Indicator[]>;
+    panesRef: MutableRefObject<ChartPane[]>;
+    horizonRef: MutableRefObject<bigint>;
+    activeTimeframeRef: MutableRefObject<Timeframe>;
+    dataLevelRef: MutableRefObject<DataLevel | null>;
+    setPanes: (updater: ChartPane[] | ((prev: ChartPane[]) => ChartPane[])) => void;
+    setIndicators: (inds: Indicator[]) => void;
+    runIndicatorWorker: (trades: TradePoint[], barNs: bigint) => void;
+    getTradesUpToHorizon: (horizon: bigint) => TradePoint[];
+    pushDrawParams: () => void;
+}
+export interface UseChartPluginResult {
+    pluginChartTypesRef: MutableRefObject<Map<string, ChartTypePlugin>>;
+    activeChartTypeBottomBarIds: MutableRefObject<Set<string>>;
+    pluginChartTypes: ChartTypePlugin[];
+    setPluginChartTypes: (types: ChartTypePlugin[]) => void;
+    pluginChartTypeComputedRef: MutableRefObject<Map<string, unknown>>;
+    activatePluginIndicator: (indicator: Indicator, pane?: ChartPane) => void;
+    replacePluginIndicator: (indicator: Indicator) => void;
+    buildChartTypeActiveCtx: () => ChartTypeActiveContext;
+}
+export declare function useChartPlugin(p: UseChartPluginParams): UseChartPluginResult;

package/types/hooks/useChartSettings.d.ts

@@ -0,0 +1,44 @@
+import { type MutableRefObject } from 'react';
+import { type ViewBounds, type TradePoint, type PriceHistory, type OhlcvBarMs } from '../lib/types';
+import { type FootprintBar } from '../lib/types/footprint';
+import { type ChartSettings } from '../lib/types/chart-settings';
+import { type DataLevel } from '../interfaces/IDataAdapter';
+import { type RenderEngine } from '../core/RenderEngine';
+import { type CompactBuffer } from '../lib/compact-buffer';
+export interface UseChartSettingsParams {
+    chartSettingsRef: MutableRefObject<ChartSettings>;
+    isYAxisAutoRef: MutableRefObject<boolean>;
+    viewRef: MutableRefObject<ViewBounds | null>;
+    priceHistoryRef: MutableRefObject<PriceHistory[]>;
+    tradesRef: MutableRefObject<TradePoint[]>;
+    dataLevelRef: MutableRefObject<DataLevel | null>;
+    ohlcvBarsRef: MutableRefObject<{
+        barNs: bigint;
+        bars: OhlcvBarMs[];
+        display: OhlcvBarMs[];
+    }>;
+    previewBarsRef: MutableRefObject<OhlcvBarMs[]>;
+    openBarRef: MutableRefObject<FootprintBar | null>;
+    horizonRef: MutableRefObject<bigint>;
+    compactBufRef: MutableRefObject<CompactBuffer>;
+    selectedDrawingIdRef: MutableRefObject<string | null>;
+    renderEngineRef: MutableRefObject<RenderEngine | null>;
+    scheduleResample: () => void;
+    rebuildContrastBitmap: (contrast: number) => void;
+    requestFootprintRebuild: () => void;
+    pushDrawParams: () => void;
+    updateSettingsBarPos: (id: string | null) => void;
+    hidePriceScale: boolean;
+    hideTimeScale: boolean;
+    /**
+     * This pane's model settings. When they differ from the defaults (i.e. the
+     * pane was restored from a save, or already customized), they take precedence
+     * over the localStorage fallback as the initial settings.
+     */
+    modelSettings?: ChartSettings;
+}
+export interface UseChartSettingsResult {
+    chartSettings: ChartSettings;
+    setChartSettings: (updater: ChartSettings | ((prev: ChartSettings) => ChartSettings)) => void;
+}
+export declare function useChartSettings(p: UseChartSettingsParams): UseChartSettingsResult;

package/types/hooks/useChartSubscriptions.d.ts

@@ -0,0 +1,64 @@
+import { type MutableRefObject } from 'react';
+import { type ChartTypePlugin, type ChartTypeActiveContext } from '../core/PluginRegistry';
+import { type AccountManager } from '../core/AccountManager';
+import { type RenderEngine } from '../core/RenderEngine';
+import { type TypedEventBus } from '../core/TypedEventBus';
+import { type ChartPane, type Indicator } from '../lib/types/indicator-types';
+import { type ChartSettings } from '../lib/types/chart-settings';
+import { type TradePoint, type OhlcvBarMs, type ViewBounds } from '../lib/types';
+import { type DataLevel } from '../interfaces/IDataAdapter';
+import { type FootprintBar } from '../lib/types/footprint';
+import { type SerialTrade } from '../lib/types';
+import { type TradeLineHitMap } from '../lib/renderers/drawTradeLines';
+import { type Timeframe } from '../lib/timeframes';
+import { type CrosshairSync, type SyncInLayout, type TimeRangeSync } from '../lib/types/layout-sync';
+export interface UseChartSubscriptionsParams {
+    eventBus: TypedEventBus;
+    chartId: number;
+    account: AccountManager;
+    pluginChartTypesRef: MutableRefObject<Map<string, ChartTypePlugin>>;
+    activeChartTypeBottomBarIds: MutableRefObject<Set<string>>;
+    hitMapRef: MutableRefObject<TradeLineHitMap>;
+    indicatorsRef: MutableRefObject<Indicator[]>;
+    panesRef: MutableRefObject<ChartPane[]>;
+    renderEngineRef: MutableRefObject<RenderEngine | null>;
+    horizonRef: MutableRefObject<bigint>;
+    activeTimeframeRef: MutableRefObject<Timeframe>;
+    chartSettingsRef: MutableRefObject<ChartSettings>;
+    pluginChartTypeComputedRef: MutableRefObject<Map<string, unknown>>;
+    dataLevelRef: MutableRefObject<DataLevel | null>;
+    previewBarsRef: MutableRefObject<OhlcvBarMs[]>;
+    candleCacheRef: MutableRefObject<Map<bigint, any> | null>;
+    ohlcvBarsRef: MutableRefObject<{
+        barNs: bigint;
+        bars: OhlcvBarMs[];
+        display: OhlcvBarMs[];
+    }>;
+    openBarRef: MutableRefObject<FootprintBar | null>;
+    viewRef: MutableRefObject<ViewBounds | null>;
+    accountSnapRef: MutableRefObject<any>;
+    setActiveTool: (tool: any) => void;
+    setActiveTimeframe: (tf: Timeframe) => void;
+    handleTimeframeChange: (tf: Timeframe) => void;
+    setPanes: (updater: ChartPane[] | ((prev: ChartPane[]) => ChartPane[])) => void;
+    setIndicators: (inds: Indicator[]) => void;
+    setPluginChartTypes: (types: ChartTypePlugin[]) => void;
+    setChartSettings: (updater: ChartSettings | ((prev: ChartSettings) => ChartSettings)) => void;
+    resetView: () => void;
+    buildChartTypeActiveCtx: () => ChartTypeActiveContext;
+    pushDrawParams: () => void;
+    runIndicatorWorker: (trades: SerialTrade[], barNs: bigint) => void;
+    getTradesUpToHorizon: (horizon: bigint) => TradePoint[];
+    syncPixelLayouts: (panes?: ChartPane[]) => void;
+    autofitIndicatorPanes: () => void;
+    handleAddIndicator: (id: string) => void;
+    handleRemoveIndicator: (id: string) => void;
+    onSymbolChange: (symbol: string) => void;
+    /** This layout's live sync switches (a ref: the handlers outlive a render). */
+    syncInLayoutRef: MutableRefObject<SyncInLayout>;
+    /** Take (or drop) the crosshair another cell is broadcasting. */
+    applyCrosshairSync: (sync: CrosshairSync | null) => void;
+    /** Follow another cell's time axis. */
+    applyTimeRangeSync: (sync: TimeRangeSync) => void;
+}
+export declare function useChartSubscriptions(p: UseChartSubscriptionsParams): void;

package/types/hooks/useChartView.d.ts

@@ -0,0 +1,47 @@
+import { type MutableRefObject } from 'react';
+import { type ViewBounds, type TradePoint, type PriceHistory, type OhlcvBarMs } from '../lib/types';
+import { type ChartSettings } from '../lib/types/chart-settings';
+import { type DataLevel } from '../interfaces/IDataAdapter';
+import { type RenderEngine } from '../core/RenderEngine';
+import { type ChartPane, type Indicator } from '../lib/types/indicator-types';
+import { FootprintBar } from '../core';
+export interface UseChartViewParams {
+    viewRef: MutableRefObject<ViewBounds | null>;
+    transformer: import('../interfaces/ICoordinateTransformer').LiveTransformer;
+    isYAxisAutoRef: MutableRefObject<boolean>;
+    setChartSettings: (updater: ChartSettings | ((prev: ChartSettings) => ChartSettings)) => void;
+    priceHistoryRef: MutableRefObject<PriceHistory[]>;
+    tradesRef: MutableRefObject<TradePoint[]>;
+    previewBarsRef: MutableRefObject<OhlcvBarMs[]>;
+    ohlcvBarsRef: MutableRefObject<{
+        barNs: bigint;
+        bars: OhlcvBarMs[];
+        display: OhlcvBarMs[];
+    }>;
+    openBarRef: MutableRefObject<FootprintBar>;
+    chartSettingsRef: MutableRefObject<ChartSettings>;
+    horizonRef: MutableRefObject<bigint>;
+    dataLevelRef: MutableRefObject<DataLevel | null>;
+    activeTimeframeRef: MutableRefObject<{
+        barNs: bigint;
+        label?: string;
+    }>;
+    scheduleResample: () => void;
+    pushDrawParams: () => void;
+    /** Publish this pane's visible time range to a time/date-range-synced layout. */
+    publishTimeRangeSync: () => void;
+    renderEngineRef: MutableRefObject<RenderEngine | null>;
+    updateSettingsBarPos: (id: string | null) => void;
+    selectedDrawingIdRef: MutableRefObject<string | null>;
+    panesRef: MutableRefObject<ChartPane[]>;
+    indicatorsRef: MutableRefObject<Indicator[]>;
+    setPanes: (updater: ChartPane[] | ((prev: ChartPane[]) => ChartPane[])) => void;
+}
+export interface UseChartViewResult {
+    resetYAxis: (setPersistent?: boolean) => void;
+    resetXAxis: () => void;
+    resetView: () => void;
+    autofitPanesSilent: () => void;
+    autofitIndicatorPanes: () => void;
+}
+export declare function useChartView(p: UseChartViewParams): UseChartViewResult;

package/types/hooks/usePlaybackEngine.d.ts

@@ -0,0 +1,85 @@
+import { TypedEventBus } from '../core';
+export declare const BASE_REDRAW_INTERVAL_MS = 100;
+export declare const DEFAULT_STEP_NS = 5000000000n;
+/** Parse a step-size token into nanoseconds. Unknown tokens fall back to 5s. */
+export declare function stepSizeToNs(stepSize: string): bigint;
+export type PlaybackStatus = 'paused' | 'playing';
+export type PlaybackMode = 'step' | 'realtime';
+export type PlaybackState = {
+    mode: PlaybackMode;
+    status: PlaybackStatus;
+    /** Step mode only: snap the horizon to step-size boundaries when advancing. */
+    stepSnap: boolean;
+    speed: number;
+    stepSize: string;
+    wallStart: number;
+    dataStart: bigint;
+    datasetStart: bigint;
+    /** Left edge of the *currently loaded* window (moves when we jump-load). */
+    loadedStart: bigint;
+    dataEnd: bigint;
+    rafHandle: number;
+    lastBaseRedrawWall: number;
+    _stallStart: number | undefined;
+    _lastRafTime: number | undefined;
+};
+export type PlaybackUi = {
+    mode: PlaybackMode;
+    status: PlaybackStatus;
+    stepSnap: boolean;
+    speed: number;
+    stepSize: string;
+    datasetStart: bigint;
+    datasetEnd: bigint;
+};
+export type PlaybackChartHandle = {
+    /**
+     * `recenter` = this move was asked for (Go to, a step past the view edge),
+     * so the pane should bring its view along. Playback's per-tick follow is the
+     * pane's own business and doesn't set it.
+     */
+    seekHorizon: (t: bigint, recenter?: boolean) => void;
+};
+export interface PrefetchOptions {
+    /**
+     * Prefetch the next chunk when the estimated time to reach the loaded edge
+     * drops below `measuredLoadLatency x safetyFactor`. Higher = more lead.
+     * Default 2.5.
+     */
+    safetyFactor?: number;
+    /** Always keep at least this much wall-time of lead, in ms. Default 300. */
+    minLeadMs?: number;
+}
+interface UsePlaybackEngineOptions {
+    chartRefs: React.MutableRefObject<(PlaybackChartHandle | null)[]>;
+    sharedHorizonRef: React.MutableRefObject<bigint>;
+    /** Request a forward chunk; `spanNs` is the desired data-time span to fetch. */
+    onRequestMore?: (spanNs?: bigint) => void;
+    onTick?: (tNs: bigint) => void;
+    eventBus: TypedEventBus;
+    prefetch?: PrefetchOptions;
+    /**
+     * The symbol whose data gates the clock - in a layout, the focused pane's.
+     * Data events carrying any other symbol are somebody else's pane and must
+     * not stop playback. Omit (or return undefined) to accept everything, which
+     * is what a single-symbol host wants.
+     */
+    clockSymbol?: () => string | undefined;
+}
+export declare function usePlaybackEngine({ chartRefs, sharedHorizonRef, onRequestMore, onTick, eventBus, prefetch, clockSymbol, }: UsePlaybackEngineOptions): {
+    readonly ui: PlaybackUi;
+    readonly notifyDataBounds: (datasetStart: bigint, dataEnd: bigint) => void;
+    readonly play: () => void;
+    readonly pause: () => void;
+    readonly stepForward: () => void;
+    readonly stepBack: () => void;
+    readonly jumpToStart: () => void;
+    readonly jumpToEnd: () => void;
+    readonly setSpeed: (s: number) => void;
+    readonly setStepSize: (s: string) => void;
+    readonly setMode: (mode: PlaybackMode) => void;
+    readonly setStepSnap: (snap: boolean) => void;
+    readonly scrub: (t: bigint) => void;
+    readonly pbRef: import("react").MutableRefObject<PlaybackState>;
+};
+export {};

package/types/hooks/useRenderEngine.d.ts

@@ -0,0 +1,64 @@
+import { type MutableRefObject, type RefObject } from 'react';
+import { RenderEngine } from '../core/RenderEngine';
+import { type TypedEventBus } from '../core/TypedEventBus';
+import { type ViewBounds, type TradePoint, type PriceHistory, type OhlcvBarMs } from '../lib/types';
+import { type ChartPane, type Indicator, type Rect } from '../lib/types/indicator-types';
+import { type FootprintBar } from '../lib/types/footprint';
+import { type ChartSettings } from '../lib/types/chart-settings';
+import { type DataLevel } from '../interfaces/IDataAdapter';
+import { type LiveTransformer } from '../interfaces/ICoordinateTransformer';
+type HeatmapBitmapOffsets = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+type CacheBounds = {
+    tMin: bigint;
+    tMax: bigint;
+    pMin: number;
+    pMax: number;
+};
+export interface UseRenderEngineParams {
+    renderEngineRef: MutableRefObject<RenderEngine | null>;
+    baseCanvasRef: RefObject<HTMLCanvasElement>;
+    drawingsCanvasRef: RefObject<HTMLCanvasElement>;
+    uiCanvasRef: RefObject<HTMLCanvasElement>;
+    eventBus: TypedEventBus;
+    /** Which cell of the layout this chart is - stamped onto bus events so the
+     *  other cells can tell our repaints from theirs. */
+    chartId: number;
+    viewRef: MutableRefObject<ViewBounds | null>;
+    /** Auto-computed right price-axis width (css px). */
+    priceScaleWidthRef: MutableRefObject<number>;
+    tradesRef: MutableRefObject<TradePoint[]>;
+    getLayouts: () => Record<string, Rect>;
+    heatmapBitmapRef: MutableRefObject<ImageBitmap | null>;
+    cacheBoundsRef: MutableRefObject<CacheBounds | null>;
+    heatmapBitmapOffsetsRef: MutableRefObject<HeatmapBitmapOffsets>;
+    panesRef: MutableRefObject<ChartPane[]>;
+    indicatorsRef: MutableRefObject<Indicator[]>;
+    priceHistoryRef: MutableRefObject<PriceHistory[]>;
+    footprintBarsRef: MutableRefObject<FootprintBar[]>;
+    activeTimeframeRef: MutableRefObject<{
+        barNs: bigint;
+    }>;
+    chartSettingsRef: MutableRefObject<ChartSettings>;
+    horizonRef: MutableRefObject<bigint>;
+    candleCacheRef: MutableRefObject<Map<bigint, any> | null>;
+    openBarRef: MutableRefObject<FootprintBar | null>;
+    dataLevelRef: MutableRefObject<DataLevel | null>;
+    ohlcvBarsRef: MutableRefObject<{
+        barNs: bigint;
+        bars: OhlcvBarMs[];
+        display: OhlcvBarMs[];
+    }>;
+    previewBarsRef: MutableRefObject<OhlcvBarMs[]>;
+    transformer: LiveTransformer;
+    hideTimeScale: boolean;
+}
+export interface UseRenderEngineResult {
+    doBaseRedraw: () => void;
+}
+export declare function useRenderEngine(p: UseRenderEngineParams): UseRenderEngineResult;
+export {};

package/types/hooks/useTradeLines.d.ts

@@ -0,0 +1,80 @@
+import type { TradeLine, ViewBounds } from '../lib/types';
+import { type TradeLineHitMap, type GhostInteractionState } from '../lib/renderers/drawTradeLines';
+import type { ChartSettings } from '../lib/types/chart-settings';
+import { LiveTransformer, type SymbolInfo } from '../core';
+import { Rect } from '../lib/types/indicator-types';
+type CursorStyle = 'default' | 'ns-resize' | 'pointer' | 'grab' | 'grabbing' | 'not-allowed';
+interface UseTradeLines {
+    tradeLines: TradeLine[];
+    onLinesChange: (lines: TradeLine[]) => void;
+    onSyncLines: (lines: TradeLine[]) => void;
+    onLineDelete: (line: TradeLine) => void;
+    hitMapRef: React.MutableRefObject<TradeLineHitMap>;
+    chartWRef: React.MutableRefObject<number>;
+    chartHRef: React.MutableRefObject<number>;
+    /** Y offset (CSS px) of the main chart pane from the top of the canvas. Non-zero when indicator panes sit above the main area. */
+    chartOYRef?: React.MutableRefObject<number>;
+    getLayouts: () => Record<string, Rect>;
+    boundsRef: React.MutableRefObject<ViewBounds>;
+    chartSettingsRef: React.MutableRefObject<ChartSettings>;
+    redraw: () => void;
+    /** Resolved symbol info - the instrument tick size for price snapping is derived from it. */
+    symbolInfoRef?: React.MutableRefObject<SymbolInfo | null>;
+    /**
+     * Optional ref to the canonical lines map from useTradingState.
+     * When provided, line price updates during drag are written directly into
+     * this map (no React state update) so the canvas sees fresh values on
+     * every animation frame without triggering re-renders.
+     */
+    linesRef?: React.MutableRefObject<Map<string, TradeLine>>;
+    /** Live lookup for lines that bypass React state. See `findLine`. */
+    resolveLine?: (id: string) => TradeLine | undefined;
+    /**
+     * Shared with useTradingState. We write the active line id here on drag
+     * start and clear it on drag end, so line rebuilds (e.g. from playback
+     * ticks) know to preserve the line currently under the cursor.
+     */
+    draggingLineIdRef?: React.MutableRefObject<string | null>;
+    transformer: LiveTransformer;
+    /**
+     * Called when the user finishes dragging a ghost TP/SL pill (mouseup).
+     * lineId  - the entry line this ghost belongs to (e.g. "position:abc123")
+     * kind    - 'tp' | 'sl'
+     * index   - 0-based slot index
+     * price   - final price (snapped to tickSize)
+     */
+    onGhostMove?: (lineId: string, kind: 'tp' | 'sl', index: number, price: number) => void;
+}
+interface UseTradeLinesReturn {
+    hoveredLineId: string | null;
+    draggingLineId: string | null;
+    /** Last computed cursor. One render behind - for rendering, not for reading
+     *  inside a pointer handler; use `cursorRef` there. */
+    cursor: CursorStyle;
+    /**
+     * The same value, written synchronously.
+     *
+     * The chart's own mousemove handler runs `onMouseMove` and then decides, in
+     * that same tick, whether the trade lines have claimed the cursor. Reading
+     * React state there is always one event stale, which is worst exactly when
+     * it matters: move onto a line and stop, and the state set by that last
+     * event has no following event to apply it - the pointer keeps the chart's
+     * crosshair until you jiggle the mouse.
+     */
+    cursorRef: React.MutableRefObject<CursorStyle>;
+    /**
+     * Returns the current ghost interaction state.
+     * Call this inside your redraw callback - it reads from the ref so it is
+     * always up-to-date without needing React state.
+     */
+    getGhostState: () => GhostInteractionState;
+    onMouseMove: (e: React.MouseEvent<HTMLCanvasElement>) => void;
+    onMouseDown: (e: React.MouseEvent<HTMLCanvasElement>) => void;
+    onMouseUp: (e: React.MouseEvent<HTMLCanvasElement>) => void;
+    onMouseLeave: (e: React.MouseEvent<HTMLCanvasElement>) => void;
+    onContextMenu: (e: React.MouseEvent<HTMLCanvasElement>) => void;
+    onDoubleClick: (e: React.MouseEvent<HTMLCanvasElement>) => void;
+    onClick: (e: React.MouseEvent<HTMLCanvasElement>) => void;
+}
+export declare function useTradeLines({ tradeLines, onLinesChange, onSyncLines, onLineDelete, hitMapRef, chartWRef, chartHRef, chartOYRef, getLayouts, boundsRef, chartSettingsRef, redraw, symbolInfoRef, onGhostMove, linesRef, resolveLine, draggingLineIdRef, transformer, }: UseTradeLines): UseTradeLinesReturn;
+export {};