@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/context/SyncContextShare.d.ts

@@ -0,0 +1,11 @@
+import React from "react";
+interface SyncContextShareValue {
+    syncContext: ReturnType<typeof import("@vninvestcharts/engine-react").useSyncContext> | null;
+}
+declare const SyncContextShareContext: React.Context<SyncContextShareValue>;
+export declare const SyncContextShareProvider: React.FC<{
+    children: React.ReactNode;
+    syncContext: SyncContextShareValue["syncContext"];
+}>;
+export declare const useSyncContextShare: () => SyncContextShareValue;
+export default SyncContextShareContext;

package/dist/dts/widget/context/VNInvestChartsConfigContext.d.ts

@@ -0,0 +1,24 @@
+/**
+ * WE2 P1-03: VNInvestChartsConfigContext
+ *
+ * Low-frequency configuration context: theme, locale, symbol, timeframe, adapter.
+ * These values change only on user action (not per-frame), so they can safely
+ * live in a single React context without causing re-render storms.
+ */
+import { type ReactNode } from "react";
+import type { ChartTheme } from "../../lib/core";
+import type { WidgetLocale } from "../i18n/types";
+import type { StockDataAdapter, Timeframe } from "../../lib/types/adapter";
+export interface VNInvestChartsConfigContextValue {
+    theme: ChartTheme;
+    locale: WidgetLocale;
+    symbol?: string;
+    timeframe?: Timeframe;
+    adapter: StockDataAdapter;
+}
+export declare const VNInvestChartsConfigContext: import("react").Context<VNInvestChartsConfigContextValue>;
+export declare function useVNInvestChartsConfig(): VNInvestChartsConfigContextValue;
+export declare function VNInvestChartsConfigProvider({ value, children, }: {
+    value: VNInvestChartsConfigContextValue;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/dts/widget/context/VNInvestChartsContext.d.ts

@@ -0,0 +1,70 @@
+/**
+ * WE2 P1-02: VNInvestChartsContext (main provider)
+ *
+ * Composes ConfigContext, StateContext, WidgetI18nContext, and HoverEmitter
+ * into a single provider tree. This is the root context for the compound
+ * component architecture.
+ *
+ * The provider wraps around the existing VNInvestCharts implementation — it does
+ * NOT replace the prop-driven API. Instead, it provides an internal coordination
+ * layer that compound sub-components (Toolbar, Header, Footer, etc.) can consume.
+ *
+ * Architecture:
+ *   VNInvestChartsProvider
+ *     ├── WidgetI18nProvider (already exists)
+ *     ├── VNInvestChartsConfigProvider (theme, locale, symbol, timeframe, adapter)
+ *     ├── VNInvestChartsStateProvider (panes, drawings, activeTool)
+ *     └── HoverEmitter ref (high-frequency hover events via EventTarget)
+ */
+import { type ReactNode } from "react";
+import type { ChartTheme } from "../../lib/core";
+import type { PaneDescriptor } from "../../lib/core/types/pane-descriptor";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import type { StockDataAdapter, Timeframe } from "../../lib/types/adapter";
+import type { WidgetLocale, WidgetMessages } from "../i18n/types";
+import { type HoverEmitter } from "./HoverEmitter";
+export interface VNInvestChartsProviderProps {
+    adapter: StockDataAdapter;
+    symbol?: string;
+    timeframe?: Timeframe;
+    locale?: WidgetLocale;
+    messages?: Partial<WidgetMessages>;
+    theme?: ChartTheme;
+    panes?: readonly PaneDescriptor[];
+    drawings?: readonly DrawingObject[];
+    activeTool?: string;
+    /** Per-chart pane-layout storage namespace (multi-chart cell id). */
+    storageScopeId?: string | null;
+    portalRoot?: HTMLElement | null;
+    shadowRoot?: ShadowRoot | null;
+    onLocaleChange?: (locale: WidgetLocale) => void;
+    children: ReactNode;
+}
+/**
+ * Hook to access the internal portal root for rendering modals/tooltips inside Shadow DOM.
+ * Returns the portal root element, or null if not in Shadow DOM mode.
+ */
+export declare function usePortalRoot(): HTMLElement | null;
+/**
+ * Hook to access the shadow root for registering capture-phase event listeners.
+ * Returns the shadow root element, or null if not in Shadow DOM mode.
+ */
+export declare function useShadowRoot(): ShadowRoot | null;
+/**
+ * Hook to access the hover emitter ref from any descendant component.
+ *
+ * Usage:
+ *   const emitterRef = useHoverEmitterRef();
+ *   emitHover(emitterRef.current, { datum, pixelX, pixelY, paneId });
+ */
+export declare function useHoverEmitterRef(): React.RefObject<HoverEmitter | null>;
+/**
+ * Root provider for the compound component architecture.
+ *
+ * Wraps the existing VNInvestCharts prop-driven implementation — does NOT replace it.
+ * Compound sub-components (Toolbar, Header, Footer, etc.) consume this context.
+ */
+export declare function VNInvestChartsProvider({ adapter, symbol, timeframe, locale, messages, theme, panes, drawings, activeTool, storageScopeId, portalRoot, shadowRoot, onLocaleChange, children, }: VNInvestChartsProviderProps): import("react").JSX.Element;
+export { VNInvestChartsConfigContext, VNInvestChartsConfigProvider, type VNInvestChartsConfigContextValue } from "./VNInvestChartsConfigContext";
+export { VNInvestChartsStateContext, VNInvestChartsStateProvider, useVNInvestChartsState, type VNInvestChartsStateContextValue, type PaneState, type DrawingInteraction, type ActiveToolState } from "./VNInvestChartsStateContext";
+export { createHoverEmitter, emitHover, clearHover, useHoverSubscription, useHoverState, type HoverEventPayload, type HoverEmitter, } from "./HoverEmitter";

package/dist/dts/widget/context/VNInvestChartsStateContext.d.ts

@@ -0,0 +1,50 @@
+/**
+ * WE2 P1-04: VNInvestChartsStateContext
+ *
+ * Medium-frequency state context: panes, drawings, activeTool, selectedDrawing.
+ * These change on user interactions (add pane, select tool, etc.) but not
+ * per-frame like hover coordinates.
+ *
+ * High-frequency data (mouse X/Y, hoveredDatum) must go through the
+ * HoverEmitter (EventTarget ref) — NOT this context — to avoid re-render storms.
+ */
+import { type Dispatch, type ReactNode } from "react";
+import type { PaneDescriptor, SeriesConfig, SeriesTypeId } from "../../lib/core/types/pane-descriptor";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import type { UseDrawingInteractionReturn } from "@vninvestcharts/engine-react";
+import { type DynamicPaneAction } from "../../lib/core/hooks/useDynamicPanes";
+export interface PaneState {
+    panes: readonly PaneDescriptor[];
+    dispatch: Dispatch<DynamicPaneAction>;
+    toggleVisible: (id: string) => void;
+    addPane: (pane: Omit<PaneDescriptor, "id">) => void;
+    removePane: (id: string) => void;
+    deletePane: (id: string) => void;
+    renamePane: (paneId: string, label: string) => void;
+    restorePane: (id: string) => void;
+    addSeries: (paneId: string, series: SeriesConfig) => void;
+    removeSeries: (paneId: string, seriesType: SeriesTypeId, seriesIndex?: number) => void;
+    toggleSeriesVisible: (paneId: string, seriesType: SeriesTypeId, seriesIndex?: number) => void;
+    reorderPanes: (fromVisibleIndex: number, toVisibleIndex: number) => void;
+}
+export type DrawingInteraction = UseDrawingInteractionReturn;
+export interface ActiveToolState {
+    activeTool: string | undefined;
+    setActiveTool: (tool: string | undefined) => void;
+}
+export interface VNInvestChartsStateContextValue {
+    paneState: PaneState;
+    drawingInteraction: DrawingInteraction;
+    activeTool: ActiveToolState;
+}
+export declare const VNInvestChartsStateContext: import("react").Context<VNInvestChartsStateContextValue>;
+export declare function useVNInvestChartsState(): VNInvestChartsStateContextValue;
+export interface VNInvestChartsStateProviderProps {
+    initialPanes?: readonly PaneDescriptor[];
+    initialDrawings?: readonly DrawingObject[];
+    initialActiveTool?: string;
+    /** Per-chart storage namespace (multi-chart cell id). Absent = legacy shared key. */
+    storageScopeId?: string | null;
+    children: ReactNode;
+}
+export declare function VNInvestChartsStateProvider({ initialPanes, initialDrawings, initialActiveTool, storageScopeId, children, }: VNInvestChartsStateProviderProps): import("react").JSX.Element;

package/dist/dts/widget/context/WidgetI18nContext.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from "react";
+import type { WidgetLocale, WidgetMessages } from "../i18n/types";
+type TranslationParams = Record<string, string | number | undefined> & {
+    defaultValue?: string;
+};
+export interface WidgetI18nContextValue {
+    locale: WidgetLocale;
+    setLocale: (locale: WidgetLocale) => void;
+    t: (key: string, params?: TranslationParams) => string;
+}
+export interface WidgetI18nProviderProps {
+    children: ReactNode;
+    locale?: WidgetLocale;
+    messages?: Partial<WidgetMessages>;
+    onLocaleChange?: (locale: WidgetLocale) => void;
+}
+export declare const WidgetI18nContext: import("react").Context<WidgetI18nContextValue>;
+export declare function WidgetI18nProvider({ children, locale, messages, onLocaleChange }: WidgetI18nProviderProps): import("react").JSX.Element;
+export declare function useWidgetI18n(): WidgetI18nContextValue;
+/**
+ * S3/BUG-4: safe fallback helper. `t()` returns the raw key when missing
+ * (never ""), so `t(key) || fallback` NEVER fires — use this instead.
+ */
+export declare function tOr(t: (key: string) => string, key: string, fallback: string): string;
+export {};

package/dist/dts/widget/context/WorkspaceLiveTradingContext.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Task M3: WorkspaceLiveTradingContext — shared LIVE broker cho multi-chart.
+ *
+ * Mirror WorkspaceReplayTradingContext nhưng cho LIVE (không reset theo symbol,
+ * namespace riêng cấp workspace). Single-chart không bị ảnh hưởng (dùng optional hook).
+ */
+import { type ReactNode } from "react";
+import type { VirtualBrokerEngine } from "../../lib/core/trading/VirtualBrokerEngine";
+import type { MarketDataPort } from "../../lib/core/trading/MarketDataPort";
+import type { WorkspaceLiveLogEntry } from "../hooks/useWorkspaceLiveTrading";
+export interface WorkspaceLiveTradingValue {
+    broker: VirtualBrokerEngine;
+    port: MarketDataPort;
+    log: WorkspaceLiveLogEntry[];
+    closePosition: (positionId: string) => boolean;
+    reversePosition: (positionId: string) => void;
+    cancelOrder: (orderId: string) => boolean;
+    reset: () => void;
+    brokerFor: (symbol: string) => {
+        broker: VirtualBrokerEngine;
+        port: MarketDataPort;
+    } | undefined;
+}
+export declare const WorkspaceLiveTradingContext: import("react").Context<WorkspaceLiveTradingValue>;
+export declare function WorkspaceLiveTradingProvider({ value, children, }: {
+    value: WorkspaceLiveTradingValue;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useWorkspaceLiveTradingContext(): WorkspaceLiveTradingValue;
+export declare function useOptionalWorkspaceLiveTrading(): WorkspaceLiveTradingValue | undefined;

package/dist/dts/widget/context/WorkspacePaperVisibilityContext.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+export interface PaperVisibilityChart {
+    id: string;
+    symbol: string;
+}
+export interface WorkspacePaperVisibility {
+    master: boolean;
+    perChart: Record<string, boolean>;
+    charts: PaperVisibilityChart[];
+    setMaster: (enabled: boolean) => void;
+    setChart: (chartId: string, enabled: boolean) => void;
+    clearChart: (chartId: string) => void;
+}
+/** Optional — single-chart (không provider) trả null, giữ hành vi legacy. */
+export declare function useOptionalWorkspacePaperVisibility(): WorkspacePaperVisibility | null;
+export declare function useWorkspacePaperVisibility(options: {
+    workspaceId?: string;
+    charts: PaperVisibilityChart[];
+}): WorkspacePaperVisibility;
+export declare function WorkspacePaperVisibilityProvider(props: {
+    value: WorkspacePaperVisibility;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/dts/widget/context/WorkspaceReplayTradingContext.d.ts

@@ -0,0 +1,36 @@
+/**
+ * WE2 P2-09: WorkspaceReplayTradingContext
+ *
+ * Holds a SINGLE shared replay-trading session (ReplayOrderBook + analytics)
+ * at the VNInvestMultiCharts (parent) level. Per DECISION-1 / H3 (workspace-level,
+ * chốt 2026-07-17): paper trade là 1 session chung cho toàn bộ workspace.
+ *
+ * Chỉ chart ACTIVE mới feed bars vào shared order book (qua `feedBar`), tránh
+ * trộn lẫn bars khi các chart có symbol khác nhau. Mọi chart đọc chung
+ * `positions` / `closedTrades` từ singleton này.
+ */
+import type { UseReplayTradingResult } from "../hooks/useReplayTrading";
+export interface WorkspaceReplayTradingValue extends UseReplayTradingResult {
+    /** Task 11: broker bên dưới (cho multi-chart panel + sync). Luôn set sau render đầu. */
+    broker: import("../../lib/core/trading/VirtualBrokerEngine").VirtualBrokerEngine;
+    /** Task 11: ring buffer log fills/closes (cap 200) cho TradingLogTab. */
+    log: Array<{
+        timestamp: number;
+        message: string;
+    }>;
+    /** Task 11: hủy lệnh chờ theo id. */
+    cancelOrder: (orderId: string) => boolean;
+    /** Task 11: đóng + mở ngược chiều tại mark hiện tại. */
+    reversePosition: (positionId: string) => void;
+    /** Active chart gọi mỗi khi currentBar đổi để xử lý fills vào shared order book. symbol = symbol của chart active (dùng để reset khi đổi symbol). Truyền `bars` để process queue đầy đủ khi tua nhanh (F6 fix). */
+    feedBar: (bar: import("../../lib/core/replay/replayTradingTypes").ReplayOHLCBar, currentBar: number, timestamp?: number, symbol?: string, bars?: readonly import("../../lib/core/replay/replayTradingTypes").ReplayOHLCBar[]) => void;
+    /** Active chart báo cáo replay on/off để singleton reset positions khi tắt hẳn. */
+    reportReplayActive: (active: boolean) => void;
+    /** Chart active hiện tại có đang replay không (để các chart khác biết có feed hay không). */
+    isReplayActive: boolean;
+    /** F-11: reset shared order book + analytics khi master chart đổi (không giữ position của master cũ). */
+    resetForNewMaster: (masterId: string | null) => void;
+}
+export declare const WorkspaceReplayTradingContext: import("react").Context<WorkspaceReplayTradingValue>;
+export declare function useWorkspaceReplayTrading(): WorkspaceReplayTradingValue;
+export declare function useOptionalWorkspaceReplayTrading(): WorkspaceReplayTradingValue | undefined;

package/dist/dts/widget/contexts/SaaSFeatureContext.d.ts

@@ -0,0 +1,23 @@
+import React, { type ReactNode } from 'react';
+import { SaaSFeatureFlags, SaaSFeatureContextValue, LicenseDiagnosticInfo } from '../types/saas';
+import type { VNInvestClient } from '../adapters/VNInvestClient';
+export declare const SaaSFeatureContext: React.Context<SaaSFeatureContextValue | null>;
+/**
+ * LIC-FIX: chuẩn hóa key khi lưu/đọc mà KHÔNG làm hỏng key ký số `vni1.*`
+ * (trước đây prepend `vni_` mù quáng → `vni_vni1.*` → parse fail → FREE vĩnh viễn).
+ * Đồng thời tự chữa key đã bị hỏng trước đây. Bare prefix vẫn giữ hành vi cũ.
+ */
+export declare function normalizeStoredPat(pat: string): string;
+export interface SaaSFeatureProviderProps {
+    tenantPat?: string;
+    /** CS-3: host-pinned offline license. License channel only; never shadowed by tenantPat. */
+    licenseKey?: string;
+    /** CS-6: host observer for licensing state. Silent when unset. See VNInvestChartsProps. */
+    onLicenseDiagnostic?: (info: LicenseDiagnosticInfo) => void;
+    debugFeatures?: Partial<SaaSFeatureFlags>;
+    children: ReactNode;
+    client?: VNInvestClient;
+    /** Override the default ad activation date (ms since epoch). Default: 2027-01-01T00:00:00Z. */
+    advActivationDate?: number;
+}
+export declare const SaaSFeatureProvider: React.FC<SaaSFeatureProviderProps>;

package/dist/dts/widget/data/DataEnvelope.d.ts

@@ -0,0 +1,100 @@
+/**
+ * DataEnvelope — lớp chịu trách nhiệm DUY NHẤT cho việc chuẩn hóa dữ liệu backend.
+ *
+ * Vì sao cần (PLAN_FRONTEND_PROPLUS_TRACKA_2026-09-28 §2.3):
+ * Backend `vninvest` hiện trả **hai contract khác nhau cho cùng dữ liệu OHLCV**:
+ *   - `/core/v1/stock-management/stocks/{s}/bars/` → `{ timestamp: <Unix ms int>, volume: int }`
+ *     (`stock_mgmt_native_views.py:3665-3685`)
+ *   - `/core/v1/stock-management/stocks/{s}/chart/` → `{ date: <ISO string>, volume: float }`
+ *     (`stock_mgmt_native_views.py:943-951`)
+ * Và quote trả `price` là **string** (Decimal) ở một nơi, **number** ở nơi khác
+ * (`market_serving/native_views.py:54-121`); `change_pct` là number nhưng
+ * `price_change_pct` lại là string.
+ *
+ * Nếu để mỗi consumer tự parse ⇒ mọi thay đổi backend lan khắp widget, và parse sai
+ * diễn ra âm thầm (`"0.0" == 0` là `false` trong JS). Lớp này gom hết về một kiểu
+ * `CanonicalBar` / `CanonicalQuote`; consumer chỉ nhìn kiểu canonical.
+ *
+ * Khi backend EP-1 (corporate actions) tới: chỉ cần điền `adjClose` — **không** sửa consumer.
+ *
+ * Nguyên tắc (AGENTS.md Rule 15 — cấm fake dữ liệu production):
+ *   - Thiếu dữ liệu ⇒ `null`, **không** dùng `0` (0 là giá/số 0 thật, sẽ vẽ sai).
+ *   - Không tự bịa giá điều chỉnh cổ tức khi backend chưa cung cấp.
+ *   - Bar không đọc được timestamp ⇒ loại, không tạo bar rỗng.
+ */
+export type BarSource = "bars" | "chart" | "unknown";
+export interface CanonicalBar {
+    /** Unix milliseconds, UTC. Mọi endpoint mới dùng int ms; ISO được parse về ms. */
+    timestamp: number;
+    open: number | null;
+    high: number | null;
+    low: number | null;
+    close: number | null;
+    /** Luôn là number. Backend có thể trả int hoặc float hoặc string — đều ép về number. */
+    volume: number;
+    /** `null` cho tới khi backend cung cấp corporate actions (EP-1). KHÔNG tự tính. */
+    adjClose: number | null;
+    adjFactor: number | null;
+    /** Bar cuối có thể đang chạy (polling) — renderer được phép vẽ nét đứt. */
+    isPartial: boolean;
+    source: BarSource;
+}
+/**
+ * Ép giá trị bất kỳ về number, trả `null` nếu không hợp lệ.
+ * Chấp nhận: number | numeric string (kể cả "1.25e6", "42,5"? no — không đổi dấu phẩy).
+ * Từ chối: null, undefined, boolean, object, array, NaN, Infinity, chuỗi rỗng.
+ */
+export declare function toNum(value: unknown): number | null;
+/**
+ * Parse timestamp về Unix ms (UTC).
+ * Chấp nhận:
+ *   - number: coi là **giây** nếu |v| < 1e11, **ms** nếu >= 1e11 (heuristic chuẩn).
+ *     Ranh giới 1e11 ms ≈ 1973-03-03 ⇒ mọi timestamp thị trường thực tế (>1.7e9 giây)
+ *     nằm an toàn về một phía. Đã khoá bằng test boundary trong `DataEnvelope.test.ts`.
+ *   - ISO "2026-09-18" ⇒ UTC midnight (deterministic, không lệch timezone máy).
+ *   - ISO date-time có `Z`/offset ⇒ tôn trọng offset.
+ *   - ISO date-time không offset ⇒ coi là UTC (KHÔNG dùng local time của client).
+ *   - Date object ⇒ `.getTime()`.
+ * Trả `null` nếu không parse được.
+ */
+export declare function toTimestampMs(value: unknown): number | null;
+/**
+ * Chuẩn hóa 1 bar từ **bất kỳ** shape nào của backend.
+ * Trả `null` nếu không đọc được timestamp (bar vô dụng) — không tạo bar rỗng.
+ */
+export declare function normalizeBar(raw: unknown): CanonicalBar | null;
+/**
+ * Chuẩn hóa mảng bar. Tự bỏ bar hỏng và **giữ nguyên thứ tự** như backend trả về
+ * (sắp xếp lại là việc của tầng camera, tránh phá invariant range in-bounds).
+ */
+export declare function normalizeBars(raw: unknown): CanonicalBar[];
+export type MarketStatus = "PRE_OPEN" | "OPEN" | "LUNCH" | "CLOSED" | "HALTED" | "SUSPENDED" | "NOT_TRADED" | "UNKNOWN";
+export interface CanonicalQuote {
+    symbol: string;
+    price: number | null;
+    prevClose: number | null;
+    /** `change` và `change_pct` luôn là number hoặc null — không bao giờ string. */
+    change: number | null;
+    changePct: number | null;
+    open: number | null;
+    high: number | null;
+    low: number | null;
+    volume: number;
+    turnover: number | null;
+    ceiling: number | null;
+    floor: number | null;
+    marketStatus: MarketStatus;
+    /** `stale` là bắt buộc — UI hiện badge dữ liệu cũ (field này đã có sẵn ở backend). */
+    stale: boolean;
+    source: string | null;
+    fetchedAt: number | null;
+}
+/**
+ * Chuẩn hóa 1 quote. Hấp thụ **cả hai** shape backend:
+ *   - `price` là number (`change_pct: number`)
+ *   - `price` là string-Decimal (`price_change_pct: string`) — `market_serving/native_views.py:54-121`
+ * và bỏ cặp field trùng: `price`/`current_price`, `price_change`/`change_value`.
+ */
+export declare function normalizeQuote(raw: unknown): CanonicalQuote | null;
+/** Chuẩn hóa mảng quote (shape `{ quotes: [...] }` / `{ data: [...] }` hoặc mảng trần). */
+export declare function normalizeQuotes(raw: unknown): CanonicalQuote[];

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

@@ -0,0 +1,3 @@
+import type { EngineOverlayInputs } from "@vninvestcharts/engine-core";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+export declare function createSelectedPriceLabelsInput(drawing: DrawingObject | null, enabled: boolean, fallbackPaneId: string | null): EngineOverlayInputs["selectedPriceLabels"];

package/dist/dts/widget/export/chartCsv.d.ts

@@ -0,0 +1,59 @@
+import type { CanonicalBar } from "../data/DataEnvelope";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+/**
+ * W1.4/A5 — CSV export cho bars, chỉ báo và đối tượng vẽ.
+ *
+ * Đọc từ `CanonicalBar` (W0.3) nên **không phụ thuộc EP backend nào** — chỉ xuất
+ * những gì đang có trong bộ nhớ. Người dùng phải được biết điều đó, nên caller
+ * gắn badge "Chỉ dữ liệu đang tải" (đã có key `data.exportLoaded.badge`).
+ *
+ * Ba ràng buộc đã học được từ dữ liệu thật:
+ *  1. **UTF-8 BOM**: không có BOM thì Excel trên Windows mở tiếng Việt ra mojibake.
+ *  2. **Escape đúng**: giá trị chứa dấu phẩy, xuống dòng, hoặc dấu nháy phải bọc.
+ *  3. **Số là số, không phải chuỗi rỗng**: `null` (thiếu dữ liệu) xuất thành ô
+ *     trống, KHÔNG thành `0` — 0 là giá thật và sẽ làm người dùng tính sai
+ *     (vi phạm AGENTS.md Rule 15).
+ */
+/** Trần số dòng mỗi file; vượt thì tách nhiều file thay vì làm treo trình duyệt. */
+export declare const CSV_MAX_ROWS = 200000;
+export type CsvDataset = "bars" | "indicators" | "drawings";
+export interface CsvSeriesDescriptor {
+    /** Tên cột trong CSV (tiêu đề). */
+    column: string;
+    /** Giá trị tương ứng với từng bar, cùng độ dài với `bars`. */
+    values: readonly (number | null)[];
+}
+export interface BarsCsvOptions {
+    symbol: string;
+    timeframe: string;
+    bars: readonly CanonicalBar[];
+    /** Cột chỉ báo thêm vào sau cột OHLCV. */
+    series?: readonly CsvSeriesDescriptor[];
+}
+export interface DrawingsCsvOptions {
+    drawings: readonly DrawingObject[];
+}
+/** Escape một ô theo RFC 4180. `null`/`undefined` → ô trống (KHÔNG phải "0"). */
+export declare function escapeCsvCell(value: string | number | null | undefined): string;
+export declare function buildBarsCsv(options: BarsCsvOptions): string;
+/** Chia bars thành nhiều file khi vượt trần. */
+export declare function splitBarsForCsv(options: BarsCsvOptions, maxRows?: number): {
+    chunkIndex: number;
+    totalChunks: number;
+    csv: string;
+}[];
+/** Serialize đối tượng vẽ thành JSON gọn, 1 dòng cho mỗi drawing. */
+export declare function buildDrawingsCsv(options: DrawingsCsvOptions): string;
+/** Kích thước file gần đúng, để cảnh báo trước khi tải. */
+export declare function estimateCsvBytes(csv: string): number;
+export interface DownloadResult {
+    filename: string;
+    rowCount: number;
+}
+/**
+ * Tải CSV xuống máy. Không dùng `window` khi không có (SSR/test) — trả về null
+ * thay vì ném, để caller biết mà hiển thị cho người dùng.
+ */
+export declare function downloadCsv(filename: string, csv: string, doc?: Document | null): DownloadResult | null;
+/** Tên file có timestamp để không đè lên nhau. */
+export declare function csvFilename(base: string, ext?: string): string;

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

@@ -0,0 +1,6 @@
+import type { TimeIndexMap } from "@vninvestcharts/engine-core";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+export declare function reconcileForkDrawingIndexAnchors(drawings: readonly DrawingObject[], timeIndexMap: TimeIndexMap): {
+    drawings: readonly DrawingObject[];
+    changed: boolean;
+};

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

@@ -0,0 +1,69 @@
+import type { CSSProperties } from "react";
+import type { DrawingObject, DrawingToolType, Point } from "@vninvestcharts/engine-drawing";
+export declare function isPrimaryPointerPressed(pointerContext: {
+    buttons: number;
+}): boolean;
+/**
+ * Portable cursor type. `CSSProperties["cursor"]` resolves to csstype's
+ * `Cursor` interface, which a published .d.ts cannot name (TS2883), so the
+ * drawing-hook return type would be unnameable. The values are plain CSS
+ * cursor keywords; the `(string & {})` arm keeps editor autocomplete.
+ */
+export type ForkSurfaceCursor = CSSProperties["cursor"] | (string & {});
+export declare const FORK_DRAWING_TOOL_CURSOR_MAP: Partial<Record<DrawingToolType, ForkSurfaceCursor>>;
+export declare function isForkMultiStepTool(toolName: DrawingToolType): toolName is "path" | "polygon" | "polyline" | "triangle" | "channel" | "parallelChannel" | "pitchfork" | "abcdPattern" | "elliottImpulse" | "elliottCorrection" | "elliottTriangle" | "elliottDoubleCombo" | "elliottTripleCombo" | "xabcdPattern" | "cypherPattern" | "headAndShoulders" | "trianglePattern" | "threeDrivesPattern" | "fibChannel" | "trendBasedFibTime" | "fibWedge" | "pitchfan";
+export declare function hasForkDraftProgress(drawing: DrawingObject): boolean;
+export declare function resolveForkMultiStepDraftOnClick(draft: DrawingObject, nextPoint: Point): {
+    nextDraft: {
+        points: Readonly<{
+            x: number;
+            y: number;
+            xIndexFloat?: number;
+            timeMsHint?: number;
+            yPrice?: number;
+        }>[];
+        updatedAt: number;
+        id: string;
+        type: DrawingToolType;
+        style: import("@vninvestcharts/engine-drawing").DrawingStyle;
+        paneId?: string;
+        yScaleId?: string;
+        text?: string;
+        fibLevels?: number[];
+        fibLevelConfigs?: import("@vninvestcharts/engine-drawing").FibLevelConfig[];
+        label?: string;
+        symbol?: string;
+        timeframe?: string;
+        zIndex?: number;
+        clonedFrom?: string;
+        groupId?: string;
+        riskReward?: {
+            entry: number;
+            stop: number;
+            target: number;
+            quantity?: number;
+        };
+        extendLeft?: boolean;
+        extendRight?: boolean;
+        locked?: boolean;
+        visible?: boolean;
+        hidden?: boolean;
+        showMeasurement?: boolean;
+        alertCondition?: import("@vninvestcharts/engine-drawing").DrawingAlertCondition;
+        alertConditions?: import("@vninvestcharts/engine-drawing").DrawingAlertCondition[];
+        waveLabels?: string[];
+        harmonicRatios?: import("@vninvestcharts/engine-drawing").HarmonicRatioConfig;
+        gannSquareSize?: number;
+        cycleParams?: import("@vninvestcharts/engine-drawing").CycleParams;
+        segmentStyles?: Record<string, Partial<import("@vninvestcharts/engine-drawing").DrawingStyle>>;
+        segmentVisible?: Record<string, boolean>;
+        visibility?: {
+            timeframes?: string[];
+            symbols?: string[];
+            hidden?: boolean;
+        };
+        createdAt: number;
+    };
+    shouldComplete: boolean;
+};
+export declare function isForkSinglePointTool(toolName: DrawingToolType): toolName is "text" | "hLine" | "vLine" | "priceLabel";

package/dist/dts/widget/grid/DeviceProfiles.d.ts

@@ -0,0 +1,49 @@
+/**
+ * DeviceProfiles - Device-specific tuning for WebGL freeze/thaw behavior
+ * Implements ADR-0011 device-specific recommendations
+ */
+export type DeviceType = 'ios-safari' | 'android-chrome' | 'desktop' | 'unknown';
+export interface DeviceProfileConfig {
+    freezeThreshold: number;
+    thawThreshold: number;
+    debounceMs: number;
+    minFreezeDuration: number;
+    maxWebGLContexts: number;
+    maxHeapBudget: number;
+    maxSnapshotWidth: number;
+    snapshotQuality: number;
+    aggressiveFreeze: boolean;
+    preThawOnHover: boolean;
+    enableFrameMonitoring: boolean;
+}
+export declare const DEVICE_PROFILES: Record<DeviceType, DeviceProfileConfig>;
+/**
+ * Detect device type from user agent and hardware capabilities
+ */
+export declare function detectDeviceType(): DeviceType;
+/**
+ * Get device profile configuration
+ */
+export declare function getDeviceProfile(deviceType?: DeviceType): DeviceProfileConfig;
+/**
+ * Get device profile with hardware-based adjustments
+ */
+export declare function getAdjustedDeviceProfile(): DeviceProfileConfig;
+/**
+ * Apply device profile to MemoryBudgetManager
+ * This should be called during app initialization
+ */
+export declare function applyDeviceProfile(): DeviceProfileConfig;
+/**
+ * Hook for React components to get device profile
+ */
+export declare function useDeviceProfile(): DeviceProfileConfig;
+declare const _default: {
+    DEVICE_PROFILES: Record<DeviceType, DeviceProfileConfig>;
+    detectDeviceType: typeof detectDeviceType;
+    getDeviceProfile: typeof getDeviceProfile;
+    getAdjustedDeviceProfile: typeof getAdjustedDeviceProfile;
+    applyDeviceProfile: typeof applyDeviceProfile;
+    useDeviceProfile: typeof useDeviceProfile;
+};
+export default _default;

package/dist/dts/widget/grid/GridChartRegistry.d.ts

@@ -0,0 +1,9 @@
+import { ChartHandle } from '@vninvestcharts/engine-react';
+export declare class GridChartRegistry {
+    private static instances;
+    static register(id: string, handle: ChartHandle): void;
+    static unregister(id: string): void;
+    static get(id: string): ChartHandle | undefined;
+    static getAll(): ChartHandle[];
+    static clear(): void;
+}