@liberfi.io/ui-tradingview 0.1.225 → 0.1.227

package/README.md

@@ -7,6 +7,7 @@ TradingView K-line charting component for Liberfi React SDK. This package wraps
 - **Multi-instance isolation** — Every chart instance is keyed by a `storageId` (prefix). State atoms use `atomFamily(prefix)` so multiple charts coexist without creating extra jotai Providers or stores.
 - **No RxJS** — All reactive state lives in jotai atoms. Internal bridge-level events (symbol changes, crosshair moves) use a lightweight `EventEmitter`.
 - **Injectable DataFeed** — The consumer provides the `ITvChartDataFeedModule` implementation and the TradingView `Widget` constructor. This package does not bundle the charting library or data-fetching logic.
+- **Stable datafeed seam** — `TradingViewDatafeedAdapter` separates history candles from live subscribe/unsubscribe, pins timestamp unit mapping, drops out-of-order ticks, and makes unsubscribe idempotent.
 - **Composable toolbar** — The built-in toolbar ships default controls (resolutions, kline style, indicators, settings, fullscreen, snapshot) that can be individually toggled or fully replaced via slots.
 
 ## Installation
@@ -98,17 +99,18 @@ Composable toolbar with slot-based customization.
 
 ### Types & Enums
 
-| Type / Enum              | Description                                        |
-| ------------------------ | -------------------------------------------------- |
-| `TvChartConfig`          | Configuration passed to `initConfig`               |
-| `TvChartResolution`      | `"1s" \| "5s" \| ... \| "1d"`                      |
-| `TvChartKlineStyle`      | Candles, Bars, Line, Area, HeikenAshi, etc.        |
-| `TvChartLayout`          | Layout presets (1A, 2A, 3A, etc.)                  |
-| `TvChartTheme`           | `"light" \| "dark"`                                |
-| `TvChartFeature`         | Feature flags (MultiCharts, VolumeForceOverlay...) |
-| `ITvChartDataFeedModule` | Interface consumers implement for data fetching    |
-| `ITvChartSymbolResolver` | Interface for symbol info resolution               |
-| `ChartAreaState`         | Shape of per-area state in atoms                   |
+| Type / Enum                  | Description                                                                     |
+| ---------------------------- | ------------------------------------------------------------------------------- |
+| `TvChartConfig`              | Configuration passed to `initConfig`                                            |
+| `TvChartResolution`          | `"1s" \| "5s" \| ... \| "1d"`                                                   |
+| `TvChartKlineStyle`          | Candles, Bars, Line, Area, HeikenAshi, etc.                                     |
+| `TvChartLayout`              | Layout presets (1A, 2A, 3A, etc.)                                               |
+| `TvChartTheme`               | `"light" \| "dark"`                                                             |
+| `TvChartFeature`             | Feature flags (MultiCharts, VolumeForceOverlay...)                              |
+| `ITvChartDataFeedModule`     | Interface consumers implement for data fetching                                 |
+| `TradingViewDatafeedAdapter` | Recommended seam over a `CandleSource` `{ getHistory, subscribe, unsubscribe }` |
+| `ITvChartSymbolResolver`     | Interface for symbol info resolution                                            |
+| `ChartAreaState`             | Shape of per-area state in atoms                                                |
 
 ### Atoms
 
@@ -133,6 +135,35 @@ All atoms are `atomFamily` instances keyed by `prefix` (storageId). Advanced con
 
 ## Usage Examples
 
+### Candle source via `TradingViewDatafeedAdapter`
+
+`ChartDataFeed` remains the TradingView library class. Implement candles with `TradingViewDatafeedAdapter` and pass the adapter as `initConfig.datafeed`.
+
+```ts
+import {
+  TradingViewDatafeedAdapter,
+  type CandleSource,
+} from "@liberfi.io/ui-tradingview";
+
+const source: CandleSource = {
+  async getHistory({ periodParams }) {
+    return fetchHistory(periodParams); // `[]` if empty
+  },
+  subscribe(request, onCandle) {
+    listenLive(request, onCandle);
+  },
+  unsubscribe(listenerGuid) {
+    stopLive(listenerGuid);
+  },
+};
+
+const datafeed = new TradingViewDatafeedAdapter(source, {
+  resolveSymbol: (symbolName) => resolve(symbolName),
+});
+```
+
+Numeric timestamps with 10 or fewer digits are unix seconds; longer values and `Date` objects are milliseconds. Unsubscribe is idempotent: a second `unsubscribeBars(guid)` does not call the source again.
+
 ### Basic Usage
 
 ```tsx
@@ -226,7 +257,7 @@ function App() {
 
 - Add `TradingViewAreaTitle` injection into TradingView widget iframe for multi-chart layouts
 - Support consumer-provided color palettes via props
-- Add built-in `ITvChartDataFeedModule` implementation for common REST/WebSocket patterns
+- Wire Storybook `ClientDataFeedModule` through `TradingViewDatafeedAdapter`
 - Support chart comparison mode
 - Add keyboard shortcut customization
 - Expose drawing tools API

package/dist/index.d.mts

@@ -340,8 +340,8 @@ declare class ChartWidget {
     get chartWidget(): IChartWidgetApi | null;
     setChartStyle(chartType: SeriesType): void;
     getChartStyle(): SeriesType;
-    handleSymbolChange(symbol: string, _prevSymbol: string): Promise<void>;
-    handleResolutionChange(resolution: TvChartResolution, _prevResolution: string): Promise<void>;
+    handleSymbolChange(symbol: string, prevSymbol: string): Promise<void>;
+    handleResolutionChange(resolution: TvChartResolution, prevResolution: string): Promise<void>;
     setPrecision(precision: number | null): void;
     dataReady(): Promise<void>;
     timeScaleWidth(): number;
@@ -403,7 +403,7 @@ declare class ChartLibraryWidget {
     openSettingsDialog(): void;
     takeClientScreenshot(): Promise<HTMLCanvasElement> | undefined;
     onLayoutChange(layout: TvChartLayout): void;
-    onThemeChange(theme: string, _reverseColor: boolean): Promise<void>;
+    onThemeChange(theme: string, reverseColor: boolean): Promise<void>;
 }
 
 /**
@@ -560,6 +560,10 @@ interface TvChartSymbolInfo extends LibrarySymbolInfo {
     quote: TvChartQuoteType;
     precision: number;
 }
+/**
+ * Injectable history + live datafeed. Prefer {@link TradingViewDatafeedAdapter}
+ * as the stable seam; ChartManager.datafeed remains this interface.
+ */
 interface ITvChartDataFeedModule {
     onReady(options: {
         setting: ChartSettings;
@@ -658,9 +662,10 @@ declare class TvChartHandle {
     getSetting(): ChartSettings;
     getChartManager(): ChartManager;
 }
-interface TradingViewProviderProps extends PropsWithChildren<TradingViewConfigProps> {
-}
-declare const TradingViewProvider: react.ForwardRefExoticComponent<TradingViewProviderProps & react.RefAttributes<TvChartHandle>>;
+type TradingViewProviderProps = PropsWithChildren<TradingViewConfigProps>;
+declare const TradingViewProvider: react.ForwardRefExoticComponent<TradingViewConfigProps & {
+    children?: react.ReactNode | undefined;
+} & react.RefAttributes<TvChartHandle>>;
 
 interface TradingViewToolbarProps {
     /** Extra elements to render before the default toolbar items */
@@ -778,8 +783,10 @@ declare function useActiveAreaManager(): ChartAreaManager | null;
 declare function useSymbolInfo(): LibrarySymbolInfo | null;
 
 /**
- * DataFeed adapter that conforms to the TradingView Datafeed API.
- * Delegates actual data fetching to the injectable ITvChartDataFeedModule.
+ * TradingView Charting Library Datafeed API class.
+ * Delegates history, live subscribe/unsubscribe, and symbol resolve to the
+ * injectable {@link ITvChartDataFeedModule}. Consumers should implement that
+ * module with {@link TradingViewDatafeedAdapter} rather than changing this class.
  */
 declare class ChartDataFeed {
     private settings;
@@ -803,15 +810,108 @@ declare class ChartDataFeed {
      * TradingView that the datafeed supports the quotes API but has no quote data
      * beyond what is already on the chart, which suppresses the internal errors.
      */
-    getQuotes(symbols: string[], onDataCallback: (data: any[]) => void, _onErrorCallback: (reason: string) => void): void;
+    getQuotes(symbols: string[], onDataCallback: (data: any[]) => void, onErrorCallback: (reason: string) => void): void;
     /**
      * TradingView calls subscribeQuotes to receive real-time price ticks for the
      * header display. We return a no-op here because the chart already receives
      * real-time data via subscribeBars. Implementing this stub prevents the
      * internal qs_* session from remaining in a pending/broken state.
      */
-    subscribeQuotes(_symbols: string[], _fastSymbols: string[], _onRealtimeCallback: (data: any[]) => void, _listenerGuid: string): void;
-    unsubscribeQuotes(_listenerGuid: string): void;
+    subscribeQuotes(symbols: string[], fastSymbols: string[], onRealtimeCallback: (data: any[]) => void, listenerGuid: string): void;
+    unsubscribeQuotes(listenerGuid: string): void;
+}
+
+/**
+ * Raw candle the consumer source returns. `time` may be unix seconds
+ * (≤10 digits), milliseconds (>10 digits), or a `Date`.
+ * {@link TradingViewDatafeedAdapter} owns unit mapping via
+ * {@link getTvChartTickTimestamp}.
+ */
+interface TradingViewCandle {
+    time: number | Date;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+interface TradingViewHistoryRequest {
+    symbolInfo: LibrarySymbolInfo;
+    resolution: ResolutionString;
+    periodParams: PeriodParams;
+}
+interface TradingViewLiveSubscribeRequest {
+    symbolInfo: LibrarySymbolInfo;
+    resolution: ResolutionString;
+    listenerGuid: string;
+    onResetCacheNeededCallback: () => void;
+}
+/**
+ * Consumer candle backend. The adapter wraps this with timestamp mapping,
+ * out-of-order live-bar filtering, and idempotent unsubscribe.
+ */
+interface CandleSource {
+    getHistory(request: TradingViewHistoryRequest): Promise<readonly TradingViewCandle[]>;
+    subscribe(request: TradingViewLiveSubscribeRequest, onCandle: (candle: TradingViewCandle) => void): void;
+    unsubscribe(listenerGuid: string): void;
+}
+interface TradingViewDatafeedAdapterOptions {
+    resolveSymbol?: ITvChartDataFeedModule["resolveSymbol"];
+    onReady?: ITvChartDataFeedModule["onReady"];
+    onDestroy?: ITvChartDataFeedModule["onDestroy"];
+    getMarks?: ITvChartDataFeedModule["getMarks"];
+    getFirstBarTime?: ITvChartDataFeedModule["getFirstBarTime"];
+    /** Viewport width (px) below which {@link isTvChartMobileViewport} is true. */
+    mobileBreakpointPx?: number;
+}
+/** Tailwind `md` — unit-level mobile/resize seam, no widget required. */
+declare const DEFAULT_TV_CHART_MOBILE_BREAKPOINT_PX = 768;
+declare function isTvChartMobileViewport(widthPx: number, breakpointPx?: number): boolean;
+/**
+ * Consumer-facing TradingView datafeed seam.
+ *
+ * Implements {@link ITvChartDataFeedModule} so `ChartManager.datafeed` and
+ * `ChartDataFeed` stay unchanged. History, live subscribe, and unsubscribe
+ * are explicit methods; symbol resolve / onReady / onDestroy are delegated.
+ */
+declare class TradingViewDatafeedAdapter implements ITvChartDataFeedModule {
+    private readonly source;
+    private readonly options;
+    private readonly liveListeners;
+    private readonly lastHistoryBarTime;
+    private liveGeneration;
+    constructor(source: CandleSource, options?: TradingViewDatafeedAdapterOptions);
+    isMobileViewport(widthPx: number): boolean;
+    onReady(options: {
+        setting: ChartSettings;
+        chartManager: ChartManager;
+        instance: ChartWidgetBridge;
+    }): Promise<void>;
+    onDestroy(): void;
+    resolveSymbol(symbolName: string, extension?: SymbolResolveExtension): Promise<LibrarySymbolInfo | null>;
+    getBars(symbolInfo: LibrarySymbolInfo, resolution: ResolutionString, periodParams: PeriodParams): Promise<Bar[]>;
+    subscribeBars(symbolInfo: LibrarySymbolInfo, resolution: ResolutionString, onTick: SubscribeBarsCallback, listenerGuid: string, onResetCacheNeededCallback: () => void): void;
+    unsubscribeBars(listenerGuid: string): void;
+    getMarks(symbolInfo: LibrarySymbolInfo, from: number, to: number, onDataCallback: GetMarksCallback<Mark>, resolution: ResolutionString): void;
+    getFirstBarTime(symbolInfo: LibrarySymbolInfo, resolution: string, options: {
+        timezone: Timezone;
+    }): Promise<void>;
+    /**
+     * Fetch history candles, map timestamps, and return `[]` when the source
+     * has no data. {@link ChartDataFeed} maps `[]` to `{ noData: true }`.
+     */
+    getHistoryBars(symbolInfo: LibrarySymbolInfo, resolution: ResolutionString, periodParams: PeriodParams): Promise<Bar[]>;
+    /**
+     * Subscribe to live candles. Out-of-order ticks (`time < last bar time`)
+     * are dropped. Re-subscribing the same guid unsubscribes the previous
+     * source listener first.
+     */
+    subscribeLiveBars(symbolInfo: LibrarySymbolInfo, resolution: ResolutionString, onTick: SubscribeBarsCallback, listenerGuid: string, onResetCacheNeededCallback: () => void): void;
+    /**
+     * Unsubscribe a live listener. The source is called at most once per guid;
+     * a second call is a no-op (Map delete).
+     */
+    unsubscribeLiveBars(listenerGuid: string): void;
 }
 
 /**
@@ -842,9 +942,9 @@ declare class ChartSaveLoadAdapter {
     get shouldResetColorPalette(): boolean;
     toJSON(): null;
     getAllCharts(): Promise<any[]>;
-    removeChart(_index: number): void;
+    removeChart(index: number): void;
     saveChart(chart: any): Promise<string>;
-    getChartContent(_: any): Promise<string>;
+    getChartContent(content: any): Promise<string>;
     saveLineToolsAndGroups(_storageId: string, chartIndex: string, data: any): Promise<void>;
     loadLineToolsAndGroups(_storageId: string, chartIndex: string, _tool: string, symbolToLoad?: {
         symbol?: string;
@@ -862,12 +962,35 @@ declare class ChartSaveLoadAdapter {
 declare class ChartSettingsAdapter {
     private storagePrefix;
     initialSettings: Record<string, any>;
-    constructor(settings: ChartSettings, _chartManager: ChartManager, _bridge: ChartWidgetBridge);
+    constructor(settings: ChartSettings, chartManager: ChartManager, bridge: ChartWidgetBridge);
     toJSON(): null;
     removeValue(key: string): void;
     setValue(key: string, value: any): void;
 }
 
+declare const ENABLED_TV_CHART_FEATURES: TvChartFeature[];
+declare const DEFAULT_TV_CHART_RESOLUTIONS: TvChartResolution[];
+declare const ALL_TV_CHART_RESOLUTIONS: TvChartResolution[];
+declare const SUPPORTED_TV_CHART_LAYOUTS: TvChartLayout[];
+declare const TV_CHART_THEME_COLORS: {
+    decrease: string;
+    increase: string;
+    chartBg: string;
+    card: string;
+};
+
+declare function parseSymbol(symbol: string): TvChartSymbol;
+declare function stringifySymbol(symbol: TvChartSymbol): string;
+declare function stringifySymbolShort(symbol: TvChartSymbol): string;
+declare function getTvChartLibraryTheme(theme: string): ThemeName;
+declare function getTvChartLibraryResolution(resolution?: TvChartResolution): ResolutionString;
+declare function getTvChartResolutionReverse(resolution: string): TvChartResolution;
+declare function getTvChartLibraryLocale(locale: string): LanguageCode;
+declare function getTvChartLibraryLayout(layout: TvChartLayout): LayoutType;
+declare function getTvChartLayoutReverse(layout: LayoutType): TvChartLayout;
+declare function getTvChartResolutionFrame(resolution: TvChartResolution): number;
+declare function getTvChartTickTimestamp(time: number, timeframe: number): number;
+
 declare const chartLoadingFamily: jotai_vanilla_utils_atomFamily.AtomFamily<string, jotai.PrimitiveAtom<boolean> & {
     init: boolean;
 }>;
@@ -931,27 +1054,4 @@ declare const settingsDataFamily: jotai_vanilla_utils_atomFamily.AtomFamily<stri
     areaContents: ChartAreaState[];
 }>>;
 
-declare const ENABLED_TV_CHART_FEATURES: TvChartFeature[];
-declare const DEFAULT_TV_CHART_RESOLUTIONS: TvChartResolution[];
-declare const ALL_TV_CHART_RESOLUTIONS: TvChartResolution[];
-declare const SUPPORTED_TV_CHART_LAYOUTS: TvChartLayout[];
-declare const TV_CHART_THEME_COLORS: {
-    decrease: string;
-    increase: string;
-    chartBg: string;
-    card: string;
-};
-
-declare function parseSymbol(symbol: string): TvChartSymbol;
-declare function stringifySymbol(symbol: TvChartSymbol): string;
-declare function stringifySymbolShort(symbol: TvChartSymbol): string;
-declare function getTvChartLibraryTheme(theme: string): ThemeName;
-declare function getTvChartLibraryResolution(resolution?: TvChartResolution): ResolutionString;
-declare function getTvChartResolutionReverse(resolution: string): TvChartResolution;
-declare function getTvChartLibraryLocale(locale: string): LanguageCode;
-declare function getTvChartLibraryLayout(layout: TvChartLayout): LayoutType;
-declare function getTvChartLayoutReverse(layout: LayoutType): TvChartLayout;
-declare function getTvChartResolutionFrame(resolution: TvChartResolution): number;
-declare function getTvChartTickTimestamp(time: number, timeframe: number): number;
-
-export { ALL_TV_CHART_RESOLUTIONS, type Bar, ChartAreaManager, type ChartAreaState, ChartDataFeed, ChartLibraryWidget, ChartManager, ChartSaveLoadAdapter, ChartSettings, ChartSettingsAdapter, ChartSettingsStore, ChartSymbolResolver, ChartWidget, ChartWidgetBridge, type ChartingLibraryWidgetOptions, DEFAULT_TV_CHART_RESOLUTIONS, ENABLED_TV_CHART_FEATURES, EventEmitter, type HistoryMetaInfo, type IChartWidgetApi, type IChartingLibraryWidget, type ITvChartDataFeedModule, type ITvChartSymbolResolver, type LanguageCode, type LibrarySymbolInfo, type Mark, type PeriodParams, type ResolutionString, SUPPORTED_TV_CHART_LAYOUTS, type SeriesFormatterFactory, type SubscribeBarsCallback, type SymbolResolveExtension, TV_CHART_THEME_COLORS, type ThemeName, type Timezone, TradingView, TradingViewAreaTitle, TradingViewConfig, type TradingViewConfigProps, TradingViewFullscreen, type TradingViewInstance, TradingViewKlineStyleSelect, TradingViewLayout, TradingViewOpenIndicator, TradingViewOpenSettings, type TradingViewProps, TradingViewProvider, type TradingViewProviderProps, TradingViewResolutions, TradingViewSnapshot, TradingViewToolbar, type TradingViewToolbarProps, TradingViewToolbarProvider, TradingViewWidgetContainer, TradingViewWidgetProvider, type TvChartConfig, type TvChartContextValue, TvChartErrorResetType, TvChartFeature, TvChartHandle, TvChartKlineStyle, TvChartLayout, TvChartPriceType, TvChartQuoteType, type TvChartResolution, type TvChartSymbol, type TvChartSymbolChange, type TvChartSymbolInfo, TvChartTheme, TvChartType, type WidgetConstructor, chartAreasFamily, chartFullscreenFamily, chartLoadingFamily, chartPinnedResolutionsFamily, chartSelectedIndexFamily, chartShowDrawingToolbarFamily, getTvChartLayoutReverse, getTvChartLibraryLayout, getTvChartLibraryLocale, getTvChartLibraryResolution, getTvChartLibraryTheme, getTvChartResolutionFrame, getTvChartResolutionReverse, getTvChartTickTimestamp, parseSymbol, settingsBackgroundColorFamily, settingsChartTypeFamily, settingsDataFamily, settingsDisabledFeaturesFamily, settingsEnabledFeaturesFamily, settingsLayoutFamily, settingsLocaleFamily, settingsReverseColorFamily, settingsStorageIdFamily, settingsThemeFamily, settingsTickerSymbolFamily, settingsTimezoneFamily, stringifySymbol, stringifySymbolShort, useActiveAreaManager, useChartManager, useSymbolInfo, useTvChartContext, useTvChartManager, useTvChartPrefix, useTvChartToolbarContext, widgetReadyFamily };
+export { ALL_TV_CHART_RESOLUTIONS, type Bar, type CandleSource, ChartAreaManager, type ChartAreaState, ChartDataFeed, ChartLibraryWidget, ChartManager, ChartSaveLoadAdapter, ChartSettings, ChartSettingsAdapter, ChartSettingsStore, ChartSymbolResolver, ChartWidget, ChartWidgetBridge, type ChartingLibraryWidgetOptions, DEFAULT_TV_CHART_MOBILE_BREAKPOINT_PX, DEFAULT_TV_CHART_RESOLUTIONS, ENABLED_TV_CHART_FEATURES, EventEmitter, type HistoryMetaInfo, type IChartWidgetApi, type IChartingLibraryWidget, type ITvChartDataFeedModule, type ITvChartSymbolResolver, type LanguageCode, type LibrarySymbolInfo, type Mark, type PeriodParams, type ResolutionString, SUPPORTED_TV_CHART_LAYOUTS, type SeriesFormatterFactory, type SubscribeBarsCallback, type SymbolResolveExtension, TV_CHART_THEME_COLORS, type ThemeName, type Timezone, TradingView, TradingViewAreaTitle, type TradingViewCandle, TradingViewConfig, type TradingViewConfigProps, TradingViewDatafeedAdapter, type TradingViewDatafeedAdapterOptions, TradingViewFullscreen, type TradingViewHistoryRequest, type TradingViewInstance, TradingViewKlineStyleSelect, TradingViewLayout, type TradingViewLiveSubscribeRequest, TradingViewOpenIndicator, TradingViewOpenSettings, type TradingViewProps, TradingViewProvider, type TradingViewProviderProps, TradingViewResolutions, TradingViewSnapshot, TradingViewToolbar, type TradingViewToolbarProps, TradingViewToolbarProvider, TradingViewWidgetContainer, TradingViewWidgetProvider, type TvChartConfig, type TvChartContextValue, TvChartErrorResetType, TvChartFeature, TvChartHandle, TvChartKlineStyle, TvChartLayout, TvChartPriceType, TvChartQuoteType, type TvChartResolution, type TvChartSymbol, type TvChartSymbolChange, type TvChartSymbolInfo, TvChartTheme, TvChartType, type WidgetConstructor, chartAreasFamily, chartFullscreenFamily, chartLoadingFamily, chartPinnedResolutionsFamily, chartSelectedIndexFamily, chartShowDrawingToolbarFamily, getTvChartLayoutReverse, getTvChartLibraryLayout, getTvChartLibraryLocale, getTvChartLibraryResolution, getTvChartLibraryTheme, getTvChartResolutionFrame, getTvChartResolutionReverse, getTvChartTickTimestamp, isTvChartMobileViewport, parseSymbol, settingsBackgroundColorFamily, settingsChartTypeFamily, settingsDataFamily, settingsDisabledFeaturesFamily, settingsEnabledFeaturesFamily, settingsLayoutFamily, settingsLocaleFamily, settingsReverseColorFamily, settingsStorageIdFamily, settingsThemeFamily, settingsTickerSymbolFamily, settingsTimezoneFamily, stringifySymbol, stringifySymbolShort, useActiveAreaManager, useChartManager, useSymbolInfo, useTvChartContext, useTvChartManager, useTvChartPrefix, useTvChartToolbarContext, widgetReadyFamily };

package/dist/index.d.ts

@@ -340,8 +340,8 @@ declare class ChartWidget {
     get chartWidget(): IChartWidgetApi | null;
     setChartStyle(chartType: SeriesType): void;
     getChartStyle(): SeriesType;
-    handleSymbolChange(symbol: string, _prevSymbol: string): Promise<void>;
-    handleResolutionChange(resolution: TvChartResolution, _prevResolution: string): Promise<void>;
+    handleSymbolChange(symbol: string, prevSymbol: string): Promise<void>;
+    handleResolutionChange(resolution: TvChartResolution, prevResolution: string): Promise<void>;
     setPrecision(precision: number | null): void;
     dataReady(): Promise<void>;
     timeScaleWidth(): number;
@@ -403,7 +403,7 @@ declare class ChartLibraryWidget {
     openSettingsDialog(): void;
     takeClientScreenshot(): Promise<HTMLCanvasElement> | undefined;
     onLayoutChange(layout: TvChartLayout): void;
-    onThemeChange(theme: string, _reverseColor: boolean): Promise<void>;
+    onThemeChange(theme: string, reverseColor: boolean): Promise<void>;
 }
 
 /**
@@ -560,6 +560,10 @@ interface TvChartSymbolInfo extends LibrarySymbolInfo {
     quote: TvChartQuoteType;
     precision: number;
 }
+/**
+ * Injectable history + live datafeed. Prefer {@link TradingViewDatafeedAdapter}
+ * as the stable seam; ChartManager.datafeed remains this interface.
+ */
 interface ITvChartDataFeedModule {
     onReady(options: {
         setting: ChartSettings;
@@ -658,9 +662,10 @@ declare class TvChartHandle {
     getSetting(): ChartSettings;
     getChartManager(): ChartManager;
 }
-interface TradingViewProviderProps extends PropsWithChildren<TradingViewConfigProps> {
-}
-declare const TradingViewProvider: react.ForwardRefExoticComponent<TradingViewProviderProps & react.RefAttributes<TvChartHandle>>;
+type TradingViewProviderProps = PropsWithChildren<TradingViewConfigProps>;
+declare const TradingViewProvider: react.ForwardRefExoticComponent<TradingViewConfigProps & {
+    children?: react.ReactNode | undefined;
+} & react.RefAttributes<TvChartHandle>>;
 
 interface TradingViewToolbarProps {
     /** Extra elements to render before the default toolbar items */
@@ -778,8 +783,10 @@ declare function useActiveAreaManager(): ChartAreaManager | null;
 declare function useSymbolInfo(): LibrarySymbolInfo | null;
 
 /**
- * DataFeed adapter that conforms to the TradingView Datafeed API.
- * Delegates actual data fetching to the injectable ITvChartDataFeedModule.
+ * TradingView Charting Library Datafeed API class.
+ * Delegates history, live subscribe/unsubscribe, and symbol resolve to the
+ * injectable {@link ITvChartDataFeedModule}. Consumers should implement that
+ * module with {@link TradingViewDatafeedAdapter} rather than changing this class.
  */
 declare class ChartDataFeed {
     private settings;
@@ -803,15 +810,108 @@ declare class ChartDataFeed {
      * TradingView that the datafeed supports the quotes API but has no quote data
      * beyond what is already on the chart, which suppresses the internal errors.
      */
-    getQuotes(symbols: string[], onDataCallback: (data: any[]) => void, _onErrorCallback: (reason: string) => void): void;
+    getQuotes(symbols: string[], onDataCallback: (data: any[]) => void, onErrorCallback: (reason: string) => void): void;
     /**
      * TradingView calls subscribeQuotes to receive real-time price ticks for the
      * header display. We return a no-op here because the chart already receives
      * real-time data via subscribeBars. Implementing this stub prevents the
      * internal qs_* session from remaining in a pending/broken state.
      */
-    subscribeQuotes(_symbols: string[], _fastSymbols: string[], _onRealtimeCallback: (data: any[]) => void, _listenerGuid: string): void;
-    unsubscribeQuotes(_listenerGuid: string): void;
+    subscribeQuotes(symbols: string[], fastSymbols: string[], onRealtimeCallback: (data: any[]) => void, listenerGuid: string): void;
+    unsubscribeQuotes(listenerGuid: string): void;
+}
+
+/**
+ * Raw candle the consumer source returns. `time` may be unix seconds
+ * (≤10 digits), milliseconds (>10 digits), or a `Date`.
+ * {@link TradingViewDatafeedAdapter} owns unit mapping via
+ * {@link getTvChartTickTimestamp}.
+ */
+interface TradingViewCandle {
+    time: number | Date;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+interface TradingViewHistoryRequest {
+    symbolInfo: LibrarySymbolInfo;
+    resolution: ResolutionString;
+    periodParams: PeriodParams;
+}
+interface TradingViewLiveSubscribeRequest {
+    symbolInfo: LibrarySymbolInfo;
+    resolution: ResolutionString;
+    listenerGuid: string;
+    onResetCacheNeededCallback: () => void;
+}
+/**
+ * Consumer candle backend. The adapter wraps this with timestamp mapping,
+ * out-of-order live-bar filtering, and idempotent unsubscribe.
+ */
+interface CandleSource {
+    getHistory(request: TradingViewHistoryRequest): Promise<readonly TradingViewCandle[]>;
+    subscribe(request: TradingViewLiveSubscribeRequest, onCandle: (candle: TradingViewCandle) => void): void;
+    unsubscribe(listenerGuid: string): void;
+}
+interface TradingViewDatafeedAdapterOptions {
+    resolveSymbol?: ITvChartDataFeedModule["resolveSymbol"];
+    onReady?: ITvChartDataFeedModule["onReady"];
+    onDestroy?: ITvChartDataFeedModule["onDestroy"];
+    getMarks?: ITvChartDataFeedModule["getMarks"];
+    getFirstBarTime?: ITvChartDataFeedModule["getFirstBarTime"];
+    /** Viewport width (px) below which {@link isTvChartMobileViewport} is true. */
+    mobileBreakpointPx?: number;
+}
+/** Tailwind `md` — unit-level mobile/resize seam, no widget required. */
+declare const DEFAULT_TV_CHART_MOBILE_BREAKPOINT_PX = 768;
+declare function isTvChartMobileViewport(widthPx: number, breakpointPx?: number): boolean;
+/**
+ * Consumer-facing TradingView datafeed seam.
+ *
+ * Implements {@link ITvChartDataFeedModule} so `ChartManager.datafeed` and
+ * `ChartDataFeed` stay unchanged. History, live subscribe, and unsubscribe
+ * are explicit methods; symbol resolve / onReady / onDestroy are delegated.
+ */
+declare class TradingViewDatafeedAdapter implements ITvChartDataFeedModule {
+    private readonly source;
+    private readonly options;
+    private readonly liveListeners;
+    private readonly lastHistoryBarTime;
+    private liveGeneration;
+    constructor(source: CandleSource, options?: TradingViewDatafeedAdapterOptions);
+    isMobileViewport(widthPx: number): boolean;
+    onReady(options: {
+        setting: ChartSettings;
+        chartManager: ChartManager;
+        instance: ChartWidgetBridge;
+    }): Promise<void>;
+    onDestroy(): void;
+    resolveSymbol(symbolName: string, extension?: SymbolResolveExtension): Promise<LibrarySymbolInfo | null>;
+    getBars(symbolInfo: LibrarySymbolInfo, resolution: ResolutionString, periodParams: PeriodParams): Promise<Bar[]>;
+    subscribeBars(symbolInfo: LibrarySymbolInfo, resolution: ResolutionString, onTick: SubscribeBarsCallback, listenerGuid: string, onResetCacheNeededCallback: () => void): void;
+    unsubscribeBars(listenerGuid: string): void;
+    getMarks(symbolInfo: LibrarySymbolInfo, from: number, to: number, onDataCallback: GetMarksCallback<Mark>, resolution: ResolutionString): void;
+    getFirstBarTime(symbolInfo: LibrarySymbolInfo, resolution: string, options: {
+        timezone: Timezone;
+    }): Promise<void>;
+    /**
+     * Fetch history candles, map timestamps, and return `[]` when the source
+     * has no data. {@link ChartDataFeed} maps `[]` to `{ noData: true }`.
+     */
+    getHistoryBars(symbolInfo: LibrarySymbolInfo, resolution: ResolutionString, periodParams: PeriodParams): Promise<Bar[]>;
+    /**
+     * Subscribe to live candles. Out-of-order ticks (`time < last bar time`)
+     * are dropped. Re-subscribing the same guid unsubscribes the previous
+     * source listener first.
+     */
+    subscribeLiveBars(symbolInfo: LibrarySymbolInfo, resolution: ResolutionString, onTick: SubscribeBarsCallback, listenerGuid: string, onResetCacheNeededCallback: () => void): void;
+    /**
+     * Unsubscribe a live listener. The source is called at most once per guid;
+     * a second call is a no-op (Map delete).
+     */
+    unsubscribeLiveBars(listenerGuid: string): void;
 }
 
 /**
@@ -842,9 +942,9 @@ declare class ChartSaveLoadAdapter {
     get shouldResetColorPalette(): boolean;
     toJSON(): null;
     getAllCharts(): Promise<any[]>;
-    removeChart(_index: number): void;
+    removeChart(index: number): void;
     saveChart(chart: any): Promise<string>;
-    getChartContent(_: any): Promise<string>;
+    getChartContent(content: any): Promise<string>;
     saveLineToolsAndGroups(_storageId: string, chartIndex: string, data: any): Promise<void>;
     loadLineToolsAndGroups(_storageId: string, chartIndex: string, _tool: string, symbolToLoad?: {
         symbol?: string;
@@ -862,12 +962,35 @@ declare class ChartSaveLoadAdapter {
 declare class ChartSettingsAdapter {
     private storagePrefix;
     initialSettings: Record<string, any>;
-    constructor(settings: ChartSettings, _chartManager: ChartManager, _bridge: ChartWidgetBridge);
+    constructor(settings: ChartSettings, chartManager: ChartManager, bridge: ChartWidgetBridge);
     toJSON(): null;
     removeValue(key: string): void;
     setValue(key: string, value: any): void;
 }
 
+declare const ENABLED_TV_CHART_FEATURES: TvChartFeature[];
+declare const DEFAULT_TV_CHART_RESOLUTIONS: TvChartResolution[];
+declare const ALL_TV_CHART_RESOLUTIONS: TvChartResolution[];
+declare const SUPPORTED_TV_CHART_LAYOUTS: TvChartLayout[];
+declare const TV_CHART_THEME_COLORS: {
+    decrease: string;
+    increase: string;
+    chartBg: string;
+    card: string;
+};
+
+declare function parseSymbol(symbol: string): TvChartSymbol;
+declare function stringifySymbol(symbol: TvChartSymbol): string;
+declare function stringifySymbolShort(symbol: TvChartSymbol): string;
+declare function getTvChartLibraryTheme(theme: string): ThemeName;
+declare function getTvChartLibraryResolution(resolution?: TvChartResolution): ResolutionString;
+declare function getTvChartResolutionReverse(resolution: string): TvChartResolution;
+declare function getTvChartLibraryLocale(locale: string): LanguageCode;
+declare function getTvChartLibraryLayout(layout: TvChartLayout): LayoutType;
+declare function getTvChartLayoutReverse(layout: LayoutType): TvChartLayout;
+declare function getTvChartResolutionFrame(resolution: TvChartResolution): number;
+declare function getTvChartTickTimestamp(time: number, timeframe: number): number;
+
 declare const chartLoadingFamily: jotai_vanilla_utils_atomFamily.AtomFamily<string, jotai.PrimitiveAtom<boolean> & {
     init: boolean;
 }>;
@@ -931,27 +1054,4 @@ declare const settingsDataFamily: jotai_vanilla_utils_atomFamily.AtomFamily<stri
     areaContents: ChartAreaState[];
 }>>;
 
-declare const ENABLED_TV_CHART_FEATURES: TvChartFeature[];
-declare const DEFAULT_TV_CHART_RESOLUTIONS: TvChartResolution[];
-declare const ALL_TV_CHART_RESOLUTIONS: TvChartResolution[];
-declare const SUPPORTED_TV_CHART_LAYOUTS: TvChartLayout[];
-declare const TV_CHART_THEME_COLORS: {
-    decrease: string;
-    increase: string;
-    chartBg: string;
-    card: string;
-};
-
-declare function parseSymbol(symbol: string): TvChartSymbol;
-declare function stringifySymbol(symbol: TvChartSymbol): string;
-declare function stringifySymbolShort(symbol: TvChartSymbol): string;
-declare function getTvChartLibraryTheme(theme: string): ThemeName;
-declare function getTvChartLibraryResolution(resolution?: TvChartResolution): ResolutionString;
-declare function getTvChartResolutionReverse(resolution: string): TvChartResolution;
-declare function getTvChartLibraryLocale(locale: string): LanguageCode;
-declare function getTvChartLibraryLayout(layout: TvChartLayout): LayoutType;
-declare function getTvChartLayoutReverse(layout: LayoutType): TvChartLayout;
-declare function getTvChartResolutionFrame(resolution: TvChartResolution): number;
-declare function getTvChartTickTimestamp(time: number, timeframe: number): number;
-
-export { ALL_TV_CHART_RESOLUTIONS, type Bar, ChartAreaManager, type ChartAreaState, ChartDataFeed, ChartLibraryWidget, ChartManager, ChartSaveLoadAdapter, ChartSettings, ChartSettingsAdapter, ChartSettingsStore, ChartSymbolResolver, ChartWidget, ChartWidgetBridge, type ChartingLibraryWidgetOptions, DEFAULT_TV_CHART_RESOLUTIONS, ENABLED_TV_CHART_FEATURES, EventEmitter, type HistoryMetaInfo, type IChartWidgetApi, type IChartingLibraryWidget, type ITvChartDataFeedModule, type ITvChartSymbolResolver, type LanguageCode, type LibrarySymbolInfo, type Mark, type PeriodParams, type ResolutionString, SUPPORTED_TV_CHART_LAYOUTS, type SeriesFormatterFactory, type SubscribeBarsCallback, type SymbolResolveExtension, TV_CHART_THEME_COLORS, type ThemeName, type Timezone, TradingView, TradingViewAreaTitle, TradingViewConfig, type TradingViewConfigProps, TradingViewFullscreen, type TradingViewInstance, TradingViewKlineStyleSelect, TradingViewLayout, TradingViewOpenIndicator, TradingViewOpenSettings, type TradingViewProps, TradingViewProvider, type TradingViewProviderProps, TradingViewResolutions, TradingViewSnapshot, TradingViewToolbar, type TradingViewToolbarProps, TradingViewToolbarProvider, TradingViewWidgetContainer, TradingViewWidgetProvider, type TvChartConfig, type TvChartContextValue, TvChartErrorResetType, TvChartFeature, TvChartHandle, TvChartKlineStyle, TvChartLayout, TvChartPriceType, TvChartQuoteType, type TvChartResolution, type TvChartSymbol, type TvChartSymbolChange, type TvChartSymbolInfo, TvChartTheme, TvChartType, type WidgetConstructor, chartAreasFamily, chartFullscreenFamily, chartLoadingFamily, chartPinnedResolutionsFamily, chartSelectedIndexFamily, chartShowDrawingToolbarFamily, getTvChartLayoutReverse, getTvChartLibraryLayout, getTvChartLibraryLocale, getTvChartLibraryResolution, getTvChartLibraryTheme, getTvChartResolutionFrame, getTvChartResolutionReverse, getTvChartTickTimestamp, parseSymbol, settingsBackgroundColorFamily, settingsChartTypeFamily, settingsDataFamily, settingsDisabledFeaturesFamily, settingsEnabledFeaturesFamily, settingsLayoutFamily, settingsLocaleFamily, settingsReverseColorFamily, settingsStorageIdFamily, settingsThemeFamily, settingsTickerSymbolFamily, settingsTimezoneFamily, stringifySymbol, stringifySymbolShort, useActiveAreaManager, useChartManager, useSymbolInfo, useTvChartContext, useTvChartManager, useTvChartPrefix, useTvChartToolbarContext, widgetReadyFamily };
+export { ALL_TV_CHART_RESOLUTIONS, type Bar, type CandleSource, ChartAreaManager, type ChartAreaState, ChartDataFeed, ChartLibraryWidget, ChartManager, ChartSaveLoadAdapter, ChartSettings, ChartSettingsAdapter, ChartSettingsStore, ChartSymbolResolver, ChartWidget, ChartWidgetBridge, type ChartingLibraryWidgetOptions, DEFAULT_TV_CHART_MOBILE_BREAKPOINT_PX, DEFAULT_TV_CHART_RESOLUTIONS, ENABLED_TV_CHART_FEATURES, EventEmitter, type HistoryMetaInfo, type IChartWidgetApi, type IChartingLibraryWidget, type ITvChartDataFeedModule, type ITvChartSymbolResolver, type LanguageCode, type LibrarySymbolInfo, type Mark, type PeriodParams, type ResolutionString, SUPPORTED_TV_CHART_LAYOUTS, type SeriesFormatterFactory, type SubscribeBarsCallback, type SymbolResolveExtension, TV_CHART_THEME_COLORS, type ThemeName, type Timezone, TradingView, TradingViewAreaTitle, type TradingViewCandle, TradingViewConfig, type TradingViewConfigProps, TradingViewDatafeedAdapter, type TradingViewDatafeedAdapterOptions, TradingViewFullscreen, type TradingViewHistoryRequest, type TradingViewInstance, TradingViewKlineStyleSelect, TradingViewLayout, type TradingViewLiveSubscribeRequest, TradingViewOpenIndicator, TradingViewOpenSettings, type TradingViewProps, TradingViewProvider, type TradingViewProviderProps, TradingViewResolutions, TradingViewSnapshot, TradingViewToolbar, type TradingViewToolbarProps, TradingViewToolbarProvider, TradingViewWidgetContainer, TradingViewWidgetProvider, type TvChartConfig, type TvChartContextValue, TvChartErrorResetType, TvChartFeature, TvChartHandle, TvChartKlineStyle, TvChartLayout, TvChartPriceType, TvChartQuoteType, type TvChartResolution, type TvChartSymbol, type TvChartSymbolChange, type TvChartSymbolInfo, TvChartTheme, TvChartType, type WidgetConstructor, chartAreasFamily, chartFullscreenFamily, chartLoadingFamily, chartPinnedResolutionsFamily, chartSelectedIndexFamily, chartShowDrawingToolbarFamily, getTvChartLayoutReverse, getTvChartLibraryLayout, getTvChartLibraryLocale, getTvChartLibraryResolution, getTvChartLibraryTheme, getTvChartResolutionFrame, getTvChartResolutionReverse, getTvChartTickTimestamp, isTvChartMobileViewport, parseSymbol, settingsBackgroundColorFamily, settingsChartTypeFamily, settingsDataFamily, settingsDisabledFeaturesFamily, settingsEnabledFeaturesFamily, settingsLayoutFamily, settingsLocaleFamily, settingsReverseColorFamily, settingsStorageIdFamily, settingsThemeFamily, settingsTickerSymbolFamily, settingsTimezoneFamily, stringifySymbol, stringifySymbolShort, useActiveAreaManager, useChartManager, useSymbolInfo, useTvChartContext, useTvChartManager, useTvChartPrefix, useTvChartToolbarContext, widgetReadyFamily };