@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/VNInvestMultiCharts.types.d.ts

@@ -0,0 +1,130 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { PatTier } from "@vninvestcharts/engine-core";
+import type { ChartLayout, SymbolLinkGroupId, VisibleRangePayload } from "@vninvestcharts/engine-react";
+import type { VNInvestChartsProps } from "./VNInvestCharts";
+import type { ThemeConfig } from "./theme/ThemeConfig";
+import type { CorporateEvent } from "./components/events/CorporateEventsOverlay";
+import type { WatchlistAdapter } from "./types/watchlist";
+import type { DockAdvisoryData, DockTapeData } from "./components/dock/RightSidebarDockHost";
+import type { WidgetChartHandle } from "./utils/widgetHelpers";
+import type { SeriesConfig } from "../lib/core";
+export interface MultiChartConfig {
+    id: string;
+    symbol: string;
+    timeframe: string;
+    visibleRange?: VisibleRangePayload;
+    symbolLinkGroup?: SymbolLinkGroupId | null;
+    engineState?: Record<string, unknown>;
+}
+export interface VNInvestMultiChartsProps {
+    layout?: ChartLayout;
+    charts?: MultiChartConfig[];
+    defaultLayout?: ChartLayout;
+    syncVisibleRange?: boolean;
+    syncCrosshair?: boolean;
+    syncDrawings?: boolean;
+    syncSymbolLinks?: boolean;
+    syncTimeframe?: boolean;
+    syncChartType?: boolean;
+    syncReplay?: boolean;
+    syncTime?: boolean;
+    workspaceId?: string;
+    onWorkspaceSave?: (workspaceId: string) => void;
+    onWorkspaceLoad?: (workspaceId: string) => void;
+    resizeAdapter?: VNInvestChartsProps["resizeAdapter"];
+    keyboardAdapter?: VNInvestChartsProps["keyboardAdapter"];
+    clockAdapter?: VNInvestChartsProps["clockAdapter"];
+    storageAdapter?: VNInvestChartsProps["storageAdapter"];
+    portalAdapter?: VNInvestChartsProps["portalAdapter"];
+    registryAdapter?: VNInvestChartsProps["registryAdapter"];
+    broadcastChannelAdapter?: VNInvestChartsProps["broadcastChannelAdapter"];
+    tenantPat?: string;
+    /** CS-3: host-pinned offline license, workspace level like tenantPat. */
+    licenseKey?: string;
+    /** CS-6: host licensing observer, workspace level like tenantPat. */
+    onLicenseDiagnostic?: VNInvestChartsProps["onLicenseDiagnostic"];
+    client?: VNInvestChartsProps["client"];
+    authHandler?: VNInvestChartsProps["authHandler"];
+    onTelemetry?: VNInvestChartsProps["onTelemetry"];
+    onError?: VNInvestChartsProps["onError"];
+    portalRoot?: HTMLElement | null;
+    shadowRoot?: ShadowRoot | null;
+    crossTabSync?: boolean;
+    showWorkspaceToolbar?: boolean;
+    showDrawingToolbar?: boolean;
+    showBottomPanel?: boolean;
+    showSymbolBadges?: boolean;
+    quickTimeframes?: string[];
+    syncOverrideMap?: Record<string, Record<string, boolean>>;
+    onSyncOverrideChange?: (syncOverrideMap: Record<string, Record<string, boolean>>) => void;
+    showCorporateEvents?: boolean;
+    corporateEvents?: readonly CorporateEvent[];
+    showPaperTradePanel?: boolean;
+    showTapePanel?: boolean;
+    showRightDock?: boolean;
+    watchlistAdapter?: WatchlistAdapter;
+    dockTierGate?: boolean;
+    maxCharts?: number;
+    upgradeUrl?: string;
+    onTierLimitExceeded?: (info: {
+        required: number;
+        max: number;
+        tier: PatTier | undefined;
+    }) => void;
+    tape?: DockTapeData;
+    advisory?: DockAdvisoryData;
+    sizingMode?: "fixed" | "percent";
+    riskPercent?: number;
+    initialEquity?: number;
+    onSizingChange?: (cfg: {
+        mode: "fixed" | "percent";
+        riskPercent: number;
+        initialEquity: number;
+    }) => void;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    defaultChartProps?: Partial<VNInvestChartsProps>;
+    onLayoutChange?: (layout: ChartLayout) => void;
+    onChartAdd?: (chartId: string) => void;
+    onChartRemove?: (chartId: string) => void;
+    onActiveChartChange?: (chartId: string | null) => void;
+    onSyncChange?: (settings: {
+        visibleRange?: boolean;
+        crosshair?: boolean;
+        drawings?: boolean;
+        symbolLinks?: boolean;
+        timeframe?: boolean;
+        chartType?: boolean;
+    }) => void;
+    renderBottomPanel?: (context: {
+        activeChartId: string | null;
+        activeChartHandle: WidgetChartHandle | null;
+        plotData: any[];
+        activeIndicators: any[];
+        onAddIndicator?: (config: SeriesConfig) => void;
+    }) => ReactNode;
+    renderRightPanel?: (context: {
+        chartId: string;
+        activeChartHandle: any;
+    }) => ReactNode;
+}
+export interface VNInvestMultiChartsRef {
+    addChart: (config: MultiChartConfig) => void;
+    removeChart: (chartId: string) => void;
+    getChartHandle: (chartId: string) => WidgetChartHandle | undefined;
+    getAllChartHandles: () => WidgetChartHandle[];
+    setLayout: (layout: ChartLayout) => void;
+    getLayout: () => ChartLayout;
+    saveWorkspace: (workspaceId: string) => Promise<void>;
+    loadWorkspace: (workspaceId: string) => Promise<void>;
+    setSyncVisibleRange: (enabled: boolean) => void;
+    setTheme: (config: ThemeConfig) => void;
+    setSyncCrosshair: (enabled: boolean) => void;
+    setSyncDrawings: (enabled: boolean) => void;
+    setSyncSymbolLinks: (enabled: boolean) => void;
+    setSyncTimeframe: (enabled: boolean) => void;
+    setSyncChartType: (enabled: boolean) => void;
+    setActiveChart: (chartId: string | null) => void;
+    getActiveChart: () => string | null;
+}

package/dist/dts/widget/WidgetEmptyState.d.ts

@@ -0,0 +1,11 @@
+export interface WidgetEmptyStateProps {
+    loading: boolean;
+    error?: Error | null;
+    /**
+     * UX-05: recovery action. The error copy tells the user to retry, so the
+     * state must actually offer one — previously the only way out was reloading
+     * the page.
+     */
+    onRetry?: () => void;
+}
+export declare const WidgetEmptyState: import("react").MemoExoticComponent<({ loading, error, onRetry }: WidgetEmptyStateProps) => import("react").JSX.Element>;

package/dist/dts/widget/WidgetErrorBoundary.d.ts

@@ -0,0 +1,26 @@
+import type { ContextType, ErrorInfo, ReactNode } from "react";
+import { Component } from "react";
+import { WidgetI18nContext } from "./context/WidgetI18nContext";
+export interface WidgetErrorBoundaryProps {
+    children: ReactNode;
+    onError?: (error: Error, info: ErrorInfo) => void;
+    /** BL-10: called after the user clicks retry (parent may remount content). */
+    onRetry?: () => void;
+}
+interface WidgetErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+export declare class WidgetErrorBoundary extends Component<WidgetErrorBoundaryProps, WidgetErrorBoundaryState> {
+    static contextType: import("react").Context<import("./context/WidgetI18nContext").WidgetI18nContextValue>;
+    context: ContextType<typeof WidgetI18nContext>;
+    state: WidgetErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): {
+        hasError: boolean;
+        error: Error;
+    };
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    private handleRetry;
+    render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+}
+export {};

package/dist/dts/widget/adapters/ContinuousFuturesStockDataAdapter.d.ts

@@ -0,0 +1,18 @@
+import type { StockDataAdapter, Timeframe, Unsubscribe, Trade, OrderbookSnapshot, SymbolInfo } from "../../lib/types/adapter";
+import type { OHLCVBar } from "../../lib/types/ohlcv";
+import type { CoverageFragment, SourceSemanticsDescriptor } from "@vninvestcharts/engine-core";
+export declare class ContinuousFuturesStockDataAdapter implements StockDataAdapter {
+    private continuousAdapter;
+    private baseAdapter;
+    private symbol;
+    constructor(symbol: string, baseAdapter: StockDataAdapter);
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date, chartId?: string): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number, chartId?: string): 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[]>;
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    getLastBackfillCoverage?(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+    getLastRangeCoverage?(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+}

package/dist/dts/widget/adapters/DataProviderAdapterWrapper.d.ts

@@ -0,0 +1,14 @@
+import { type StockDataAdapter, type OHLCVBar, type SymbolInfo, type Trade, type OrderbookSnapshot } from "../../lib/types/adapter";
+import { type IChartDataProvider } from "../types/dataProvider";
+export declare class DataProviderAdapterWrapper implements StockDataAdapter {
+    private provider;
+    label: string;
+    constructor(provider: IChartDataProvider);
+    getSourceSemantics?(): any;
+    fetchBarsInRange(symbol: string, timeframe: string, from: Date, to: Date, _chartId?: string): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: string, before: Date, limit?: number, _chartId?: string): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: string, onBar: (bar: OHLCVBar) => void): () => void;
+    subscribeToTrades(_symbol: string, _onTrade: (trade: Trade) => void): () => void;
+    subscribeToOrderbook(_symbol: string, _onUpdate: (snapshot: OrderbookSnapshot) => void): () => void;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+}

package/dist/dts/widget/adapters/MultiSourceDataAdapter.d.ts

@@ -0,0 +1,24 @@
+import type { StockDataAdapter, OHLCVBar, Timeframe, Trade, OrderbookSnapshot, SymbolInfo, Unsubscribe } from "../../lib/types/adapter";
+import type { CoverageFragment } from "@vninvestcharts/engine-core";
+export interface SourceRoute {
+    pattern: RegExp;
+    adapter: StockDataAdapter;
+}
+export interface MultiSourceDataAdapterConfig {
+    routes: SourceRoute[];
+    defaultAdapter: StockDataAdapter;
+}
+export declare class MultiSourceDataAdapter implements StockDataAdapter {
+    private readonly config;
+    private readonly _cache;
+    constructor(config: MultiSourceDataAdapterConfig);
+    private _resolve;
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date, chartId?: string): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number, chartId?: string): 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[]>;
+    getLastBackfillCoverage?(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+    getLastRangeCoverage?(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+}

package/dist/dts/widget/adapters/VNInvestClient.d.ts

@@ -0,0 +1,161 @@
+/**
+ * WP-02: VNInvestClient — moved from src/demo/dataSources/
+ * HTTP client for the VNInvest REST API with PAT Bearer authentication.
+ * No React dependency — safe to use in non-component contexts.
+ */
+import type { StockItem, WhaleFeedResponse, RawOHLCVBar, OrderFlowResponse, AdvisorySessionResponse, AdvisorySessionV2, TapeResponse } from "../../lib/types/vninvest";
+import type { AdCampaign } from "../types/saas";
+/** Resolve API base URL (priority: global override → localStorage → current origin → default). */
+export declare function resolveApiBase(): string;
+/** Map of common timeframe aliases to VNInvest canonical formats. */
+export declare const TIMEFRAME_MAP: Record<string, string>;
+/** Response of GET /core/v1/widget/ad — array of eligible campaigns. */
+export interface WidgetAdResponse {
+    campaigns: AdCampaign[];
+}
+export interface AuthMeResponse {
+    access?: string;
+    refresh?: string;
+    token?: string;
+    token_prefix?: string;
+    plan: string;
+    active_pat_count: number;
+    max_active_pats: number;
+    tenant: {
+        tenant_id: string;
+        tenant_code: string;
+        display_name: string;
+        plan: string;
+        max_active_pats: number;
+        status: string;
+        features?: string[];
+    };
+    user: {
+        id: number;
+        username: string;
+        email: string;
+        first_name: string;
+        last_name: string;
+        is_staff: boolean;
+    };
+    abilities: string[];
+    entitlements: Record<string, unknown>;
+}
+/** Parameters for the cursor-paged /bars/ endpoint. */
+export type VNIBarsParams = {
+    type: "init";
+    symbol: string;
+    timeframe: string;
+    from?: number;
+    to?: number;
+    limit?: number;
+} | {
+    type: "backward";
+    symbol: string;
+    timeframe: string;
+    before: number;
+    limit: number;
+    snapshotId?: string;
+};
+/** Response from the cursor-paged /bars/ endpoint. */
+export interface VNIBarsPageResponse {
+    bars: RawOHLCVBar[];
+    hasMoreBefore: boolean;
+    hasMoreAfter: boolean;
+    nextBefore: number | null;
+    nextAfter: number | null;
+    snapshotId: string | null;
+}
+export { BARS_LIMIT_MAX } from "./nativeShapes";
+export type BarsHotWindowTelemetry = {
+    cacheHits: number;
+    inFlightCollapses: number;
+    networkRequests: number;
+    lastUpdatedAt: number | null;
+};
+export type BarsHotWindowLoadGateStatus = "healthy" | "warning" | "rollback";
+export type BarsHotWindowLoadGateThresholds = {
+    minimumObservedRequests: number;
+    healthySavedRequestRatio: number;
+    rollbackSavedRequestRatio: number;
+    healthyNetworkRequestRatio: number;
+    rollbackNetworkRequestRatio: number;
+};
+export type BarsHotWindowLoadGateReport = {
+    status: BarsHotWindowLoadGateStatus;
+    reasons: readonly string[];
+    telemetry: BarsHotWindowTelemetry;
+    totalRequests: number;
+    cacheHitRatio: number;
+    collapseRatio: number;
+    networkRequestRatio: number;
+    savedRequestRatio: number;
+    thresholds: BarsHotWindowLoadGateThresholds;
+};
+export declare const DEFAULT_BARS_HOT_WINDOW_LOAD_GATE_THRESHOLDS: BarsHotWindowLoadGateThresholds;
+export declare function diffBarsHotWindowTelemetry(before: BarsHotWindowTelemetry, after: BarsHotWindowTelemetry): BarsHotWindowTelemetry;
+export declare function evaluateBarsHotWindowLoadGate(telemetry: BarsHotWindowTelemetry, thresholds?: BarsHotWindowLoadGateThresholds): BarsHotWindowLoadGateReport;
+export interface WidgetAuthHandler {
+    getToken: () => string | Promise<string>;
+    getRefreshToken?: () => string | Promise<string>;
+    onTokensUpdated?: (tokens: {
+        patToken: string;
+        refreshToken?: string;
+    }) => void | Promise<void>;
+    onAuthError?: (error: Error) => void;
+}
+export declare class VNInvestClient {
+    private _pat;
+    private _base;
+    private _authHandler?;
+    constructor(patToken?: string);
+    setAuthHandler(handler: WidgetAuthHandler): void;
+    setPAT(token: string): void;
+    /**
+     * Transport-only credential sync. Sets `_pat` WITHOUT touching storage —
+     * storage belongs to credentialStore alone. The SaaS context calls this before
+     * validation when its resolved credential (tenant > user > env) differs from
+     * what this transport carries; otherwise a user-pasted PAT sits in storage
+     * while requests go out with a stale or empty token, and the backend 401s with
+     * "Authentication credentials were not provided." No-op when equal.
+     */
+    syncTransportPat(token: string): void;
+    private _notifyPatChanged;
+    getPAT(): string;
+    setBase(url: string): void;
+    getBase(): string;
+    hasPAT(): boolean;
+    private buildHeaders;
+    private _fetch;
+    getChart(symbol: string, options?: {
+        timeframe?: string;
+        days?: number;
+    }): Promise<RawOHLCVBar[]>;
+    validateMe(): Promise<AuthMeResponse>;
+    /** Fetch eligible ad campaigns. Bearer PAT auto-attached; premium → empty list. */
+    fetchAd(): Promise<WidgetAdResponse>;
+    getBarsPage(params: VNIBarsParams): Promise<VNIBarsPageResponse>;
+    static __resetBarsHotWindowCacheForTests(): void;
+    static getBarsHotWindowTelemetry(): BarsHotWindowTelemetry;
+    static __getBarsHotWindowTelemetryForTests(): BarsHotWindowTelemetry;
+    getStocks(query?: string, exchange?: string): Promise<StockItem[]>;
+    getWhaleFeed(symbol: string): Promise<WhaleFeedResponse | null>;
+    getOrderFlow(symbol: string, window?: "5m" | "15m" | "30m" | "1h"): Promise<OrderFlowResponse | null>;
+    /** Shared GET/POST fetch for the native advisory session endpoint. */
+    private fetchAdvisorySessionV2;
+    /**
+     * Follow-up advisory V2: read the native AI advisory session.
+     * Returns the session in both empty (`reason: "no_advisory_data"`) and record states;
+     * null only on transport/auth failure. Never throws for empty sessions.
+     */
+    getAdvisorySessionV2(symbol: string): Promise<AdvisorySessionV2 | null>;
+    /**
+     * Follow-up advisory V2: trigger a manual refresh (queues generation server-side).
+     * Returns the updated session payload; null on transport/auth failure.
+     */
+    refreshAdvisorySession(symbol: string): Promise<AdvisorySessionV2 | null>;
+    /** @deprecated Legacy POST path 404s on current backends — use getAdvisorySessionV2. */
+    getAdvisorySession(symbol: string): Promise<AdvisorySessionResponse | null>;
+    getTapeEntries(symbol: string, pageSize?: number): Promise<TapeResponse | null>;
+    private _revalidateBarsHotWindow;
+}

package/dist/dts/widget/adapters/VNInvestDataAdapter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * WP-04: VNInvestDataAdapter
+ *
+ * Implements `StockDataAdapter` interface, wrapping VNInvestClient (REST)
+ * and VNInvestWebSocketClient (WebSocket) into a single cohesive adapter.
+ *
+ * This is the OPTIONAL subpath import — NOT bundled in core IIFE.
+ * Usage:
+ *   import { VNInvestDataAdapter } from '@vninvestcharts/widget/adapters';
+ */
+import type { StockDataAdapter, Unsubscribe, Timeframe, Trade, OrderbookSnapshot, SymbolInfo } from "../../lib/types/adapter";
+import type { OHLCVBar } from "../../lib/types/ohlcv";
+import type { CoverageFragment, SourceSemanticsDescriptor } from "@vninvestcharts/engine-core";
+import { VNInvestClient, type WidgetAuthHandler } from "./VNInvestClient";
+/** Configuration for VNInvestDataAdapter. */
+export interface VNInvestDataAdapterConfig {
+    /** Personal Access Token — never hardcoded, always passed by host app. */
+    patToken: string;
+    /** API base URL. Falls back to resolveApiBase() if not provided. */
+    apiBase?: string;
+}
+/**
+ * Full-featured data adapter for the VNInvest platform.
+ *
+ * Implements:
+ *   - fetchBarsInRange / fetchBarsBefore (cursor-paged /bars/ endpoint)
+ *   - subscribeToBar (WebSocket ticker_update)
+ *   - searchSymbols (GET /stocks/)
+ *
+ * Not implemented (VNInvest does not provide these endpoints):
+ *   - subscribeToTrades → returns no-op unsubscribe
+ *   - subscribeToOrderbook → returns no-op unsubscribe
+ */
+export declare class VNInvestDataAdapter implements StockDataAdapter {
+    readonly name = "vninvest";
+    private client;
+    private wsClient;
+    private readonly barSubscribers;
+    private readonly snapshotIds;
+    private readonly lastBackfillCoverageMap;
+    private readonly lastRangeCoverageMap;
+    constructor(config: VNInvestDataAdapterConfig);
+    setAuthHandler(handler: WidgetAuthHandler): void;
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    private coverageKey;
+    getLastBackfillCoverage(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+    getLastRangeCoverage(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+    /** Expose the underlying REST client for advanced use cases. */
+    get restClient(): VNInvestClient;
+    /**
+     * Fetch bars in a date range.
+     * Uses the cursor-paged /bars/ endpoint with backward pagination.
+     *
+     * 504-guard: a single wide intraday window (e.g. 90d of 1H) times the server
+     * out — each request is capped to MAX_INTRADAY_SPAN_MS and the existing
+     * hasMoreAfter/nextAfter loop walks the remainder. Daily+ ranges are unaffected.
+     */
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date, chartId?: string, signal?: AbortSignal): Promise<readonly OHLCVBar[]>;
+    /**
+     * Fetch bars before a given anchor date (backward pagination).
+     */
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number, chartId?: string): Promise<readonly OHLCVBar[]>;
+    /**
+     * Subscribe to real-time bar updates via WebSocket.
+     * Maps ticker_update events to OHLCVBar callbacks.
+     */
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    /** Not supported by VNInvest — returns no-op. */
+    subscribeToTrades(_symbol: string, _onTrade: (trade: Trade) => void): Unsubscribe;
+    /** Not supported by VNInvest — returns no-op. */
+    subscribeToOrderbook(_symbol: string, _onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    /** Search symbols via GET /stocks/ endpoint. */
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+    /** Clean up: destroy WebSocket connection. */
+    destroy(): void;
+    private handleTickerUpdate;
+}

package/dist/dts/widget/adapters/VNInvestWebSocketClient.d.ts

@@ -0,0 +1,79 @@
+/**
+ * WP-03: VNInvestWebSocketClient — moved from src/demo/dataSources/
+ * WebSocket client for the VNInvest Realtime channel.
+ */
+export interface TickerUpdateEvent {
+    event_type: "ticker_update";
+    symbol: string;
+    price: number;
+    current_price: number;
+    volume: number;
+    vwap?: number;
+    ts: string;
+    last_date?: string;
+    stale?: boolean;
+    seq?: number;
+    rsi_14?: number;
+    ma20_dist_pct?: number;
+    rvol?: number;
+    open_price?: number;
+    high_price?: number;
+    low_price?: number;
+    prev_price?: number | null;
+    change_value?: number | null;
+    change_pct?: number | null;
+}
+/**
+ * BE-02b: unwrap the backend WS envelope (WEBSOCKET_EVENT_CONTRACT.md §2).
+ * Server sends `{contract_version, event_type, symbol, ts, seq, source, data:{...}}`;
+ * consumers want the inner `data` with envelope `ts`/`seq`/`symbol` backfilled when missing.
+ * Non-envelope payloads pass through untouched. Pure function — unit tested.
+ */
+export declare function unwrapWsEnvelope(parsed: Record<string, unknown>): Record<string, unknown>;
+export interface WhaleAlertWSEvent {
+    event_type: "whale_alert";
+    symbol: string;
+    side?: "buy" | "sell";
+    value?: number;
+    price?: number;
+    ts?: string;
+}
+export type VNIWSEvent = TickerUpdateEvent | WhaleAlertWSEvent | {
+    event_type: string;
+    [key: string]: unknown;
+};
+export declare class VNInvestWebSocketClient {
+    private static readonly MAX_RECONNECT_ATTEMPTS;
+    private static readonly RECONNECT_DELAY_MS;
+    private static readonly WS_PATH_CANDIDATES;
+    private ws;
+    private readonly pat;
+    private readonly apiBase;
+    private selectedWsPath;
+    private wsUnavailable;
+    private wsProbePromise;
+    private readonly subscribedSymbols;
+    private onTickerUpdateCb;
+    private onWhaleAlertCb;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private _isConnected;
+    private _destroyed;
+    constructor(pat: string, apiBase?: string);
+    get isConnected(): boolean;
+    get destroyed(): boolean;
+    buildWsUrl(path?: string): string;
+    private buildHttpProbeUrl;
+    private probeWsPath;
+    private resolveWsPath;
+    connect(): void;
+    private openConnection;
+    subscribe(symbols: string[]): void;
+    unsubscribe(symbols: string[]): void;
+    setOnTickerUpdate(cb: ((event: TickerUpdateEvent) => void) | null): void;
+    setOnWhaleAlert(cb: ((event: WhaleAlertWSEvent) => void) | null): void;
+    destroy(): void;
+    private handleRawMessage;
+    private scheduleReconnect;
+    private sendJson;
+}

package/dist/dts/widget/adapters/barsPagingPolicy.d.ts

@@ -0,0 +1,18 @@
+/**
+ * WP-02: Bars paging policy — moved from src/demo/dataSources/
+ * Cursor-paged /bars/ endpoint response normalization.
+ */
+import type { RawOHLCVBar } from "../../lib/types/vninvest";
+export interface BarsPagingMeta {
+    hasMoreBefore: boolean;
+    hasMoreAfter: boolean;
+    nextBefore: number | null;
+    nextAfter: number | null;
+    snapshotId: string | null;
+}
+export declare function normalizeBarsPagingMeta(payload: Record<string, unknown>, bars: readonly RawOHLCVBar[]): BarsPagingMeta;
+export declare function buildBackwardPageRequest(meta: BarsPagingMeta, fallbackBefore: number, limit: number): {
+    before: number;
+    limit: number;
+    snapshotId?: string;
+} | null;

package/dist/dts/widget/adapters/corporateEvents.d.ts

@@ -0,0 +1,13 @@
+import { type StockDataAdapter } from "../../lib/types/adapter";
+import { type CorporateEvent } from "../components/events/CorporateEventsOverlay";
+export declare function shouldEnableCorporateEvents(symbol: string): boolean;
+export interface CorporateEventsFetchOptions {
+    /**
+     * Demo-only escape hatch. Production must leave this false/undefined so a
+     * missing or failed adapter returns no events instead of fabricated ones.
+     */
+    allowMockEvents?: boolean;
+}
+export declare function fetchCorporateEvents(adapter: StockDataAdapter | undefined | null, symbol: string, from: number, to: number, plotData?: any[], options?: CorporateEventsFetchOptions): Promise<CorporateEvent[]>;
+/** Demo-only fixture. Never render this as production market data. */
+export declare function generateMockEvents(plotData: any[]): CorporateEvent[];

package/dist/dts/widget/adapters/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * WP-05: Widget adapters index.
+ *
+ * Optional subpath import — NOT bundled in core IIFE.
+ * Usage:
+ *   import { VNInvestDataAdapter } from '@vninvestcharts/widget/adapters';
+ */
+export { VNInvestClient, resolveApiBase, TIMEFRAME_MAP } from "./VNInvestClient";
+export type { VNIBarsParams, VNIBarsPageResponse, BarsHotWindowTelemetry, BarsHotWindowLoadGateStatus, BarsHotWindowLoadGateThresholds, BarsHotWindowLoadGateReport, } from "./VNInvestClient";
+export { VNInvestWebSocketClient } from "./VNInvestWebSocketClient";
+export type { TickerUpdateEvent, WhaleAlertWSEvent, VNIWSEvent, } from "./VNInvestWebSocketClient";
+export { VNInvestDataAdapter } from "./VNInvestDataAdapter";
+export type { VNInvestDataAdapterConfig } from "./VNInvestDataAdapter";
+export { normalizeBarsPagingMeta, buildBackwardPageRequest } from "./barsPagingPolicy";
+export type { BarsPagingMeta } from "./barsPagingPolicy";
+export { useWatchlistRealtimeSync } from "./watchlistRealtimeSync";
+export type { UseWatchlistRealtimeSyncOptions } from "./watchlistRealtimeSync";
+export { ContinuousFuturesStockDataAdapter } from "./ContinuousFuturesStockDataAdapter";
+export { MultiSourceDataAdapter } from "./MultiSourceDataAdapter";
+export type { MultiSourceDataAdapterConfig, SourceRoute } from "./MultiSourceDataAdapter";

package/dist/dts/widget/adapters/nativeShapes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * BE-01/BE-03/BE-04b — Native backend shape mappings (verified live 2026-09-21).
+ *
+ * The backend serves shapes that differ from the legacy ok-wrapped contracts:
+ * bars limit max 1000, tape as {symbol, trades[]}, order-flow without `ok`.
+ * This module holds the clamps and mappers so VNInvestClient stays within budget.
+ * Only derivable fields are mapped — nothing is fabricated (see mapNativeTape notes).
+ */
+import type { OrderFlowResponse, TapeResponse, WhaleFeedResponse } from "../../lib/types/vninvest";
+/** Backend `_OHLCV_BAR_LIMIT_MAX` — requests above it get HTTP 400 LIMIT_EXCEEDED. */
+export declare const BARS_LIMIT_MAX = 1000;
+/** Clamp any caller-supplied bars limit into the backend-accepted range. */
+export declare function clampBarsLimit(raw: number | undefined): number | undefined;
+/**
+ * Map the native order-flow shape (no `ok` wrapper) into OrderFlowResponse.
+ * Series the backend does not send (cvd_series) stay empty — never fabricated.
+ */
+export declare function mapNativeOrderFlow(obj: Record<string, unknown>, window: string): OrderFlowResponse;
+/**
+ * Map the native whale-feed shape ({symbol, alerts[]}, verified live 2026-09-21)
+ * into WhaleFeedResponse. Alerts are passed through verbatim (no price/volume on
+ * the wire — never coerced into WhaleOrder); orders/summary stay empty-zero so the
+ * summary table renders an honest empty state while the alerts list shows data.
+ */
+export declare function mapNativeWhaleFeed(obj: Record<string, unknown>): WhaleFeedResponse;
+/**
+ * Map the native tape shape ({symbol, trades:[{time,ts,price,volume,side,match_type}]})
+ * into TapeResponse. `value` is derived (price × volume); `id` is client-generated
+ * (allowed by TapeEntry docs); `is_whale` defaults false — whale highlighting needs
+ * a threshold the mapping layer does not own.
+ */
+export declare function mapNativeTape(obj: Record<string, unknown>): TapeResponse;

package/dist/dts/widget/adapters/watchlistRealtimeSync.d.ts

@@ -0,0 +1,16 @@
+import { VNInvestWebSocketClient, type TickerUpdateEvent } from "./VNInvestWebSocketClient";
+export interface UseWatchlistRealtimeSyncOptions {
+    /** Instance of the VNInvest WebSocket client. */
+    wsClient: VNInvestWebSocketClient | null;
+    /** Array of symbols to subscribe to in the watchlist/heatmap. */
+    symbols: string[];
+    /** Optional callback triggered on each state flush with the accumulated updates. */
+    onUpdate?: (updatedData: Map<string, TickerUpdateEvent>) => void;
+    /** Throttle duration in milliseconds. Defaults to 500ms. */
+    throttleMs?: number;
+}
+/**
+ * Hook to synchronize a list of symbols in real-time using VNInvestWebSocketClient.
+ * Uses throttled state updates to ensure smooth rendering of large watchlists/heatmaps.
+ */
+export declare function useWatchlistRealtimeSync({ wsClient, symbols, onUpdate, throttleMs, }: UseWatchlistRealtimeSyncOptions): Map<string, TickerUpdateEvent>;