@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/lib/GenericComponent.d.ts

@@ -0,0 +1,124 @@
+import React, { Component } from "react";
+import PropTypes from "prop-types";
+import { noop } from "./utils";
+import { type StockChartContextValue } from "./StockChartContext";
+import type { AnyRecord, CanvasContexts } from "./types";
+export declare function getAxisCanvas(contexts: CanvasContexts | undefined): CanvasRenderingContext2D | undefined;
+export declare function getMouseCanvas(contexts: CanvasContexts | undefined): CanvasRenderingContext2D | undefined;
+export interface GenericComponentProps {
+    svgDraw: (moreProps: AnyRecord) => React.ReactNode;
+    canvasDraw?: (ctx: CanvasRenderingContext2D, moreProps: AnyRecord) => void;
+    drawOn: string[];
+    clip?: boolean;
+    edgeClip?: boolean;
+    interactiveCursorClass?: string;
+    selected?: boolean;
+    enableDragOnHover?: boolean;
+    disablePan?: boolean;
+    shouldDisablePanOnMouseDown?: (event: unknown) => boolean;
+    canvasToDraw?: (contexts: CanvasContexts | undefined) => CanvasRenderingContext2D | undefined;
+    allowAnyChart?: boolean;
+    isHover?: (moreProps: AnyRecord, e?: unknown) => boolean;
+    onClick?: (moreProps: AnyRecord, e?: unknown) => void;
+    onClickWhenHover?: (moreProps: AnyRecord, e?: unknown) => void;
+    onClickOutside?: (moreProps: AnyRecord, e?: unknown) => void;
+    onPan?: (moreProps: AnyRecord, e?: unknown) => void;
+    onPanEnd?: (moreProps: AnyRecord, e?: unknown) => void;
+    onDragStart?: (moreProps: AnyRecord, e?: unknown) => void;
+    onDrag?: (moreProps: AnyRecord, e?: unknown) => void;
+    onDragComplete?: (moreProps: AnyRecord, e?: unknown) => void;
+    onDoubleClick?: (moreProps: AnyRecord, e?: unknown) => void;
+    onDoubleClickWhenHover?: (moreProps: AnyRecord, e?: unknown) => void;
+    onContextMenu?: (moreProps: AnyRecord, e?: unknown) => void;
+    onContextMenuWhenHover?: (moreProps: AnyRecord, e?: unknown) => void;
+    onMouseMove?: (moreProps: AnyRecord, e?: unknown) => void;
+    onMouseDown?: (moreProps: AnyRecord, e?: unknown) => void;
+    onHover?: (moreProps: AnyRecord, e?: unknown) => void;
+    onUnHover?: (moreProps: AnyRecord, e?: unknown) => void;
+    chartId?: number | string;
+    morePropsDecorator?: (moreProps: AnyRecord) => AnyRecord;
+}
+interface GenericComponentState {
+    updateCount: number;
+}
+declare class GenericComponent extends Component<GenericComponentProps, GenericComponentState> {
+    static contextType: React.Context<StockChartContextValue | undefined>;
+    static propTypes: {
+        svgDraw: PropTypes.Validator<(...args: any[]) => any>;
+        canvasDraw: PropTypes.Requireable<(...args: any[]) => any>;
+        drawOn: PropTypes.Validator<any[]>;
+        clip: PropTypes.Validator<boolean>;
+        edgeClip: PropTypes.Validator<boolean>;
+        interactiveCursorClass: PropTypes.Requireable<string>;
+        selected: PropTypes.Validator<boolean>;
+        enableDragOnHover: PropTypes.Validator<boolean>;
+        disablePan: PropTypes.Validator<boolean>;
+        shouldDisablePanOnMouseDown: PropTypes.Requireable<(...args: any[]) => any>;
+        canvasToDraw: PropTypes.Validator<(...args: any[]) => any>;
+        isHover: PropTypes.Requireable<(...args: any[]) => any>;
+        onClick: PropTypes.Requireable<(...args: any[]) => any>;
+        onClickWhenHover: PropTypes.Requireable<(...args: any[]) => any>;
+        onClickOutside: PropTypes.Requireable<(...args: any[]) => any>;
+        onPan: PropTypes.Requireable<(...args: any[]) => any>;
+        onPanEnd: PropTypes.Requireable<(...args: any[]) => any>;
+        onDragStart: PropTypes.Requireable<(...args: any[]) => any>;
+        onDrag: PropTypes.Requireable<(...args: any[]) => any>;
+        onDragComplete: PropTypes.Requireable<(...args: any[]) => any>;
+        onDoubleClick: PropTypes.Requireable<(...args: any[]) => any>;
+        onDoubleClickWhenHover: PropTypes.Requireable<(...args: any[]) => any>;
+        onContextMenu: PropTypes.Requireable<(...args: any[]) => any>;
+        onContextMenuWhenHover: PropTypes.Requireable<(...args: any[]) => any>;
+        onMouseMove: PropTypes.Requireable<(...args: any[]) => any>;
+        onMouseDown: PropTypes.Requireable<(...args: any[]) => any>;
+        onHover: PropTypes.Requireable<(...args: any[]) => any>;
+        onUnHover: PropTypes.Requireable<(...args: any[]) => any>;
+        chartId: PropTypes.Requireable<NonNullable<string | number | null | undefined>>;
+    };
+    static defaultProps: {
+        svgDraw: any;
+        canvasToDraw: (contexts: CanvasContexts | undefined) => CanvasRenderingContext2D | undefined;
+        clip: true;
+        edgeClip: false;
+        selected: false;
+        disablePan: false;
+        enableDragOnHover: false;
+        onClickWhenHover: typeof noop;
+        onClickOutside: typeof noop;
+        onDragStart: typeof noop;
+        onMouseMove: typeof noop;
+        onMouseDown: typeof noop;
+    };
+    context: StockChartContextValue;
+    moreProps: AnyRecord;
+    suscriberId: number;
+    dragInProgress: boolean | undefined;
+    someDragInProgress: boolean | undefined;
+    iSetTheCursorClass: boolean | undefined;
+    evaluationInProgress: boolean | undefined;
+    constructor(props: GenericComponentProps);
+    componentDidMount(): void;
+    componentWillUnmount(): void;
+    componentDidUpdate(prevProps?: Readonly<Partial<GenericComponentProps>>): void;
+    updateMorePropsFromContext(context: StockChartContextValue): void;
+    updateMoreProps(moreProps: AnyRecord): void;
+    shouldTypeProceed(_type: string, _moreProps: AnyRecord): boolean;
+    preEvaluate(_type?: string, _moreProps?: AnyRecord, _e?: unknown): void;
+    listener(type: string, moreProps: AnyRecord, state: unknown, e: unknown): void;
+    evaluateType(type: string, e: unknown): void;
+    isHover(e: unknown): boolean;
+    getPanConditions(): {
+        draggable: any;
+        panEnabled: boolean;
+        shouldDisablePanOnMouseDown: ((event: unknown) => boolean) | undefined;
+    };
+    draw({ trigger, force }?: {
+        trigger?: string;
+        force?: boolean;
+    }): void;
+    getMoreProps(): AnyRecord;
+    preCanvasDraw(_ctx: CanvasRenderingContext2D, _moreProps: AnyRecord): void;
+    postCanvasDraw(_ctx: CanvasRenderingContext2D, _moreProps: AnyRecord): void;
+    drawOnCanvas(): void;
+    render(): React.JSX.Element | null;
+}
+export default GenericComponent;

package/dist/dts/lib/StockChartContext.d.ts

@@ -0,0 +1,53 @@
+import React from "react";
+import type { AnyRecord, CanvasContexts } from "./types";
+export interface ChartConfig {
+    id: number | string;
+    paneId?: string;
+    yScaleId?: string;
+    origin: [number, number];
+    padding: number | {
+        top: number;
+        bottom: number;
+    };
+    yScale: any;
+    yExtents: any[];
+    width: number;
+    height: number;
+    mouseCoordinates?: {
+        at: string;
+        format: (n: number) => string;
+    };
+}
+export interface StockChartContextValue {
+    plotData: any[];
+    fullData: any[];
+    chartConfig: ChartConfig[];
+    xScale: any;
+    xAccessor: (d: any) => any;
+    displayXAccessor: (d: any) => any;
+    width: number;
+    height: number;
+    chartCanvasType: "svg" | "hybrid";
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    ratio: number;
+    getCanvasContexts?: () => CanvasContexts | undefined;
+    xAxisZoom?: (newDomain: any[]) => void;
+    yAxisZoom?: (chartId: string | number, newDomain: any[]) => void;
+    amIOnTop?: (id: string | number) => boolean;
+    redraw?: () => void;
+    subscribe: (id: string | number, rest: AnyRecord) => void;
+    unsubscribe: (id: string | number) => void;
+    setCursorClass?: (className: string | null | undefined) => void;
+    generateSubscriptionId: () => number;
+    getMutableState: () => AnyRecord;
+    morePropsDecorator?: (moreProps: AnyRecord) => AnyRecord;
+}
+declare const StockChartContext: React.Context<StockChartContextValue | undefined>;
+export declare const StockChartProvider: React.Provider<StockChartContextValue | undefined>;
+export declare const useStockChart: () => StockChartContextValue;
+export default StockChartContext;

package/dist/dts/lib/adapters/BaseAdapter.d.ts

@@ -0,0 +1,25 @@
+import type { OrderbookSnapshot, StockDataAdapter, SymbolInfo, Timeframe, Trade, Unsubscribe } from "../types/adapter";
+import type { OHLCVBar } from "../types/ohlcv";
+export type RawOHLCVBar = Omit<OHLCVBar, "date" | "index" | "dataIndex"> & {
+    date: string | number | Date;
+    index?: number;
+    dataIndex?: number;
+};
+export declare abstract class BaseAdapter implements StockDataAdapter {
+    protected readonly baseUrl: string;
+    protected readonly cacheTtlMs: number;
+    private readonly requestCache;
+    protected constructor(baseUrl?: string, cacheTtlMs?: number);
+    protected buildUrl(path: string): string;
+    protected buildWebSocketUrl(path: string): string;
+    protected requestJson<T>(path: string, init?: RequestInit): Promise<T>;
+    protected memoize<T>(cacheKey: string, loader: () => Promise<T>): Promise<T>;
+    protected normalizeBar(rawBar: RawOHLCVBar, fallbackIndex: number): OHLCVBar;
+    protected normalizeBars(rawBars: readonly RawOHLCVBar[]): OHLCVBar[];
+    abstract fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date): Promise<readonly OHLCVBar[]>;
+    abstract fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number): Promise<readonly OHLCVBar[]>;
+    abstract subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    abstract subscribeToTrades(symbol: string, onTrade: (trade: Trade) => void): Unsubscribe;
+    abstract subscribeToOrderbook(symbol: string, onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    abstract searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+}

package/dist/dts/lib/adapters/BinanceAdapter.d.ts

@@ -0,0 +1,51 @@
+import type { CanonicalFetchResult, DataAdapter, GetBarsParams, GetBarsResult, KLineBar, Level2Snapshot, TickData } from "./DataAdapter";
+import type { SourceSemanticsDescriptor } from "@vninvestcharts/engine-core";
+/** Error carrying the upstream HTTP status so callers can handle geo-blocks (451) gracefully. */
+export declare class BinanceHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare class BinanceAdapter implements DataAdapter {
+    readonly name = "binance";
+    /**
+     * Latched when Binance answers HTTP 451 (regional block). Demo shells read this
+     * to serve offline data with a visible status instead of an empty chart.
+     * Cleared on the next successful fetch.
+     */
+    private regionBlocked;
+    /** True after an observed HTTP 451 until a fetch succeeds again. */
+    isRegionBlocked(): boolean;
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    getBars(params: GetBarsParams): Promise<GetBarsResult>;
+    fetchBarsInRange(symbol: string, timeframe: string, from: Date, to: Date, signal?: AbortSignal): Promise<readonly KLineBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: string, before: Date, limit?: number, signal?: AbortSignal): Promise<readonly KLineBar[]>;
+    getBarsCanonical(params: GetBarsParams): Promise<CanonicalFetchResult>;
+    subscribeLevel2(params: {
+        symbol: string;
+        depth: number;
+        callback: (snapshot: Level2Snapshot) => void;
+    }): () => void;
+    subscribeTicks(params: {
+        symbol: string;
+        callback: (tick: TickData) => void;
+    }): () => void;
+    subscribeKline(params: {
+        symbol: string;
+        interval: string;
+        callback: (bar: KLineBar & {
+            isClosed?: boolean;
+        }) => void;
+    }): () => void;
+    fetchLevel2History(params: {
+        symbol: string;
+        from: number;
+        to: number;
+        depth: number;
+    }): Promise<Level2Snapshot[]>;
+    fetchTickHistory(params: {
+        symbol: string;
+        from: number;
+        to: number;
+    }): Promise<TickData[]>;
+}
+export declare const binanceAdapter: BinanceAdapter;

package/dist/dts/lib/adapters/CSVAdapter.d.ts

@@ -0,0 +1,17 @@
+import { BaseAdapter } from "./BaseAdapter";
+import type { OHLCVBar } from "../types/ohlcv";
+import type { OrderbookSnapshot, SymbolInfo, Timeframe, Trade, Unsubscribe } from "../types/adapter";
+/**
+ * CSVAdapter loads and parses offline/local CSV data.
+ */
+export declare class CSVAdapter extends BaseAdapter {
+    private parsedBars;
+    constructor(csvContent: string, baseUrl?: string);
+    private parseCSV;
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    subscribeToTrades(symbol: string, onTrade: (trade: Trade) => void): Unsubscribe;
+    subscribeToOrderbook(symbol: string, onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+}

package/dist/dts/lib/adapters/ContinuousContractAdapter.d.ts

@@ -0,0 +1,63 @@
+/**
+ * ContinuousContractAdapter - Client-side adapter for continuous futures contracts
+ *
+ * Implements DataAdapter interface for seamless integration with chart widget.
+ * Delegates heavy stitching computation to BFF (ContinuousContractAdapter.server.ts)
+ * but provides local roll logic for immediate feedback and offline capability.
+ */
+import type { DataAdapter, KLineBar, GetBarsParams, GetBarsResult, CanonicalFetchResult } from "./DataAdapter";
+import type { SourceSemanticsDescriptor } from "@vninvestcharts/engine-core";
+import type { ContinuousContractConfig, ContinuousContractMetadata } from "./ContinuousContractTypes";
+export declare class ContinuousContractAdapter implements DataAdapter {
+    readonly name = "continuous-futures";
+    private config;
+    private rootSymbol;
+    private fetchRawBars?;
+    constructor(rootSymbol: string, config?: Partial<ContinuousContractConfig>, fetchRawBars?: (symbol: string, timeframe: string, from: Date, to: Date) => Promise<readonly KLineBar[]>);
+    /** Get the continuous contract configuration */
+    getConfig(): ContinuousContractConfig;
+    /** Update roll configuration */
+    setConfig(config: Partial<ContinuousContractConfig>): void;
+    getBars(params: GetBarsParams): Promise<GetBarsResult>;
+    getBarsCanonical(params: GetBarsParams): Promise<CanonicalFetchResult>;
+    fetchBarsInRange?(symbol: string, timeframe: string, from: Date, to: Date, signal?: AbortSignal): Promise<readonly KLineBar[]>;
+    fetchBarsBefore?(symbol: string, timeframe: string, before: Date, limit?: number, signal?: AbortSignal): Promise<readonly KLineBar[]>;
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    /**
+     * Fetch continuous contract bars - tries BFF first, falls back to local computation
+     */
+    private fetchContinuousBars;
+    /**
+     * Fetch from BFF endpoint
+     */
+    private fetchFromBFF;
+    /**
+     * Local computation fallback - stitches contracts client-side
+     * Requires individual contract data to be available via another adapter
+     */
+    private computeLocally;
+    /**
+     * Get or fetch continuous contract metadata
+     */
+    getMetadata(): Promise<ContinuousContractMetadata>;
+    /**
+     * Generate synthetic metadata for development/testing
+     */
+    private generateSyntheticMetadata;
+    /**
+     * Build coverage fragments for canonical fetch
+     */
+    private buildCoverage;
+    private mapToContinuousParams;
+    private getCacheKey;
+    private cacheBars;
+    private intervalToMs;
+}
+/**
+ * Factory function to create adapter for a continuous contract
+ */
+export declare function createContinuousContractAdapter(rootSymbol: string, config?: Partial<ContinuousContractConfig>): ContinuousContractAdapter;
+/**
+ * Get available continuous contract configurations
+ */
+export declare function getAvailableContinuousContracts(): string[];

package/dist/dts/lib/adapters/ContinuousContractTypes.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Continuous Futures Contract Types
+ *
+ * Defines types for continuous futures contracts with roll logic and back-adjustment.
+ * Supports multiple roll methods: Ratio, Panama (Cumulative Difference), Backward Ratio.
+ */
+import type { KLineBar } from "./DataAdapter";
+/** Futures contract metadata */
+export interface FuturesContract {
+    /** Unique contract identifier (e.g., "VN30F2409", "VN30F2412") */
+    symbol: string;
+    /** Underlying symbol (e.g., "VN30F") */
+    rootSymbol: string;
+    /** Expiry date (Unix ms) */
+    expiry: number;
+    /** First trading date (Unix ms) */
+    firstTradeDate: number;
+    /** Last trading date (Unix ms) - typically a few days before expiry */
+    lastTradeDate: number;
+    /** Contract month code (F, G, H, J, K, M, N, Q, U, V, X, Z) */
+    monthCode: string;
+    /** Contract year (2-digit) */
+    year: number;
+    /** Tick size */
+    tickSize: number;
+    /** Contract multiplier */
+    multiplier: number;
+    /** Exchange */
+    exchange: string;
+}
+/** Continuous contract configuration */
+export interface ContinuousContractConfig {
+    /** Root symbol for the continuous contract (e.g., "VN30F1M" for front month) */
+    rootSymbol: string;
+    /** Roll method to use */
+    rollMethod: RollMethod;
+    /** Roll trigger: days before expiry or volume-based */
+    rollTrigger: RollTrigger;
+    /** Days before expiry to roll (if rollTrigger === "days-before-expiry") */
+    rollDaysBeforeExpiry?: number;
+    /** Volume threshold for volume-based roll (if rollTrigger === "volume") */
+    volumeThreshold?: number;
+    /** Whether to adjust volumes during back-adjustment */
+    adjustVolumes: boolean;
+    /** Custom roll calendar (overrides auto-detection) */
+    customRollDates?: number[];
+}
+/** Roll adjustment methods */
+export type RollMethod = "ratio" | "panama" | "backward-ratio";
+/** Roll trigger types */
+export type RollTrigger = "days-before-expiry" | "volume" | "open-interest" | "custom";
+/** Roll point information */
+export interface RollPoint {
+    /** Timestamp of roll (Unix ms) */
+    timestamp: number;
+    /** Expiring contract symbol */
+    fromContract: string;
+    /** New contract symbol */
+    toContract: string;
+    /** Price of expiring contract at roll */
+    fromPrice: number;
+    /** Price of new contract at roll */
+    toPrice: number;
+    /** Adjustment factor applied */
+    adjustmentFactor: number;
+    /** Cumulative adjustment up to this point (for Panama) */
+    cumulativeAdjustment: number;
+    /** Roll method used */
+    method: RollMethod;
+}
+/** Continuous contract metadata returned by adapter */
+export interface ContinuousContractMetadata {
+    /** Root symbol */
+    rootSymbol: string;
+    /** All contracts in the chain */
+    contracts: FuturesContract[];
+    /** Roll points in chronological order */
+    rollPoints: RollPoint[];
+    /** Current active contract */
+    activeContract: string;
+    /** Next roll date (Unix ms) */
+    nextRollDate: number | null;
+    /** Total cumulative adjustment (for Panama method) */
+    totalCumulativeAdjustment: number;
+    /** Data range available */
+    dataRange: {
+        from: number;
+        to: number;
+    };
+}
+/** Parameters for fetching continuous contract bars */
+export interface GetContinuousBarsParams {
+    /** Continuous contract root symbol (e.g., "VN30F1M") */
+    rootSymbol: string;
+    /** Timeframe/interval */
+    interval: string;
+    /** Fetch type */
+    type: "init" | "forward" | "backward";
+    /** Anchor timestamp for backward fetch */
+    timestamp: number | null;
+    /** Maximum bars to return */
+    limit: number;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Override roll config for this request */
+    rollConfig?: Partial<ContinuousContractConfig>;
+}
+/** Result with continuous contract bars and metadata */
+export interface GetContinuousBarsResult {
+    /** Adjusted continuous bars */
+    bars: KLineBar[];
+    /** Whether more historical data available */
+    hasMore: boolean;
+    /** Metadata about the continuous contract */
+    metadata: ContinuousContractMetadata;
+    /** Roll points within the returned range */
+    rollPointsInRange: RollPoint[];
+}
+/** Server-side stitching request (BFF) */
+export interface StitchContinuousRequest {
+    rootSymbol: string;
+    interval: string;
+    from: number;
+    to: number;
+    rollConfig: ContinuousContractConfig;
+}
+/** Server-side stitching response (BFF) */
+export interface StitchContinuousResponse {
+    bars: KLineBar[];
+    metadata: ContinuousContractMetadata;
+    rollPoints: RollPoint[];
+    /** Source contracts used */
+    sourceContracts: string[];
+    /** Any warnings (e.g., missing data gaps) */
+    warnings: string[];
+}
+/** Futures contract calendar entry */
+export interface ContractCalendarEntry {
+    rootSymbol: string;
+    contracts: FuturesContract[];
+    /** Typical roll schedule (e.g., "quarterly", "monthly", "serial") */
+    rollSchedule: "monthly" | "quarterly" | "serial" | "custom";
+    /** Exchange trading hours */
+    tradingHours: {
+        timezone: string;
+        sessions: Array<{
+            open: string;
+            close: string;
+            days: number[];
+        }>;
+    };
+}
+/** Default roll configurations for known VN futures */
+export declare const DEFAULT_VN_FUTURES_ROLL_CONFIG: Record<string, ContinuousContractConfig>;

package/dist/dts/lib/adapters/DBAdapter.d.ts

@@ -0,0 +1,16 @@
+import { BaseAdapter } from "./BaseAdapter";
+import type { OHLCVBar } from "../types/ohlcv";
+import type { OrderbookSnapshot, SymbolInfo, Timeframe, Trade, Unsubscribe } from "../types/adapter";
+/**
+ * DBAdapter simulated database queries executor for stock data.
+ */
+export declare class DBAdapter extends BaseAdapter {
+    private readonly queryExecutor;
+    constructor(queryExecutor?: (sql: string, params: unknown[]) => Promise<unknown[]>, baseUrl?: string);
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    subscribeToTrades(symbol: string, onTrade: (trade: Trade) => void): Unsubscribe;
+    subscribeToOrderbook(symbol: string, onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+}

package/dist/dts/lib/adapters/DataAdapter.d.ts

@@ -0,0 +1,136 @@
+/**
+ * CE20: DataAdapter abstraction for demo data fetching.
+ *
+ * This is intentionally separate from `StockDataAdapter` (used by VNInvestCharts for
+ * chart rendering). `DataAdapter` handles historical bar loading for the demo shell.
+ */
+import type { CoverageFragment, CoverageBulkSlotInfo, SourceSemanticsDescriptor } from "@vninvestcharts/engine-core";
+/** A single OHLCV bar with a Unix-ms timestamp. */
+export interface KLineBar {
+    timestamp: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+/** Whether we are fetching the initial set, newer bars, or older bars. */
+export type GetBarsType = "init" | "forward" | "backward";
+export interface GetBarsParams {
+    type: GetBarsType;
+    symbol: string;
+    interval: string;
+    /**
+     * Anchor timestamp (ms).
+     * - "init"/"forward": unused (pass null)
+     * - "backward": fetch bars whose close time is strictly before this value
+     */
+    timestamp: number | null;
+    limit: number;
+    signal?: AbortSignal;
+}
+export interface GetBarsResult {
+    bars: KLineBar[];
+    /** true when the source may have more bars further back */
+    hasMore: boolean;
+}
+/**
+ * Canonical fetch result that carries coverage fragments alongside bars.
+ *
+ * `coverage` describes exactly which time ranges were resolved by this fetch
+ * call and why any sub-range remains unresolved. The consumer (planner, cache
+ * writer) can use this to reclassify gaps from `not-fetched` to a concrete
+ * `GapReason` without making a second API call.
+ */
+export interface CanonicalFetchResult extends GetBarsResult {
+    /** One or more fragments describing the resolved and unresolved coverage. */
+    readonly coverage: readonly CoverageFragment[];
+}
+export interface Level2Snapshot {
+    symbol: string;
+    timestamp: number;
+    bids: [price: number, size: number][];
+    asks: [price: number, size: number][];
+}
+export interface TickData {
+    symbol: string;
+    timestamp: number;
+    price: number;
+    size: number;
+    side: "buy" | "sell";
+}
+export interface DataAdapter {
+    readonly name: string;
+    getBars(params: GetBarsParams): Promise<GetBarsResult>;
+    /**
+     * Optional exact-range helper for sources that can fetch directly by [from, to].
+     * The widget bridge prefers this over `getBars()` when present so it does not
+     * collapse range requests into a latest-page bootstrap.
+     */
+    fetchBarsInRange?(symbol: string, timeframe: string, from: Date, to: Date, signal?: AbortSignal): Promise<readonly KLineBar[]>;
+    /**
+     * Optional backward-anchor helper mirroring the widget contract directly.
+     */
+    fetchBarsBefore?(symbol: string, timeframe: string, before: Date, limit?: number, signal?: AbortSignal): Promise<readonly KLineBar[]>;
+    /**
+     * Optional canonical variant of getBars that also returns coverage fragments.
+     * Adapters that can accurately report what they fetched (and what they could
+     * not) should implement this method.  The demo bridge prefers this over
+     * getBars when present.
+     */
+    getBarsCanonical?(params: GetBarsParams): Promise<CanonicalFetchResult>;
+    getSourceSemantics?(): SourceSemanticsDescriptor;
+    /** Subscribe to Level 2 order book updates */
+    subscribeLevel2?(params: {
+        symbol: string;
+        depth: number;
+        callback: (snapshot: Level2Snapshot) => void;
+    }): () => void;
+    /** Subscribe to tick/print data */
+    subscribeTicks?(params: {
+        symbol: string;
+        callback: (tick: TickData) => void;
+    }): () => void;
+    /**
+     * Subscribe to live kline (candle) updates for the given symbol + interval.
+     * Emits the current candle on every update (same `timestamp` while the candle
+     * is open; a new `timestamp` when a new candle opens). Consumers dedupe by
+     * timestamp so re-emits update the open candle in place.
+     */
+    subscribeKline?(params: {
+        symbol: string;
+        interval: string;
+        callback: (bar: KLineBar & {
+            isClosed?: boolean;
+        }) => void;
+    }): () => void;
+    /** Fetch historical Level 2 snapshots (if available) */
+    fetchLevel2History?(params: {
+        symbol: string;
+        from: number;
+        to: number;
+        depth: number;
+    }): Promise<Level2Snapshot[]>;
+    /** Fetch historical tick data */
+    fetchTickHistory?(params: {
+        symbol: string;
+        from: number;
+        to: number;
+    }): Promise<TickData[]>;
+    /**
+     * Phase 4 — Optional bulk coverage endpoint for multi-chart prefetch.
+     *
+     * When implemented, the widget can issue 1 bulk request instead of N
+     * individual fetchBarsInRange calls during layout change.
+     *
+     * Returns coverage metadata per slotId, allowing the widget to:
+     * - Determine which ranges are already available
+     * - Only fetch missing gaps
+     * - Mount charts with coverage data for zero-wait render
+     */
+    fetchCoverageBulk?(slots: Array<{
+        slotId: string;
+        symbol: string;
+        timeframe: string;
+    }>): Promise<Record<string, CoverageBulkSlotInfo>>;
+}

package/dist/dts/lib/adapters/DjangoVnstockAdapter.d.ts

@@ -0,0 +1,15 @@
+import type { OrderbookSnapshot, SymbolInfo, Timeframe, Trade, Unsubscribe } from "../types/adapter";
+import type { OHLCVBar } from "../types/ohlcv";
+import { BaseAdapter } from "./BaseAdapter";
+import type { SourceSemanticsDescriptor } from "@vninvestcharts/engine-core";
+export declare class DjangoVnstockAdapter extends BaseAdapter {
+    constructor(baseUrl?: string, cacheTtlMs?: number);
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    subscribeToTrades(symbol: string, onTrade: (trade: Trade) => void): Unsubscribe;
+    subscribeToOrderbook(symbol: string, onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+}
+export declare function createRestAdapter(baseUrl?: string): DjangoVnstockAdapter;