@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/hooks/useWidgetForkInteraction.d.ts

@@ -0,0 +1,68 @@
+import { type MouseEvent as ReactMouseEvent, type MutableRefObject } from "react";
+import { ForkPointerContext, ForkPointerOwner, ForkRubberBandSelection, WidgetPaneRuntimeSnapshot } from "../utils/widgetHelpers";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import type { DrawingWorkspaceController } from "@vninvestcharts/engine-react";
+import type { MagnetSensitivity } from "@vninvestcharts/engine-drawing";
+import { type EnrichedDatum } from "../../lib/core/calculators/types";
+import { type PaneDescriptor } from "../../lib/core";
+import { type EngineInstance, type VisibleRange as EngineVisibleRange } from "@vninvestcharts/engine-core";
+import { type ForkSurfaceCursor } from "../forkInteractionHelpers";
+import { type WindowEventAdapter } from "@vninvestcharts/engine-react";
+export interface UseWidgetForkInteractionProps {
+    useForkRuntime: boolean;
+    drawingUiEnabled: boolean;
+    activeForkDrawingTool: string | null;
+    drawingWorkspace: DrawingWorkspaceController;
+    resolvedDrawings: readonly DrawingObject[];
+    resolvedSelectedDrawing: DrawingObject | null;
+    resolvedForkSingleSelection: DrawingObject | null;
+    onSelectedDrawingChange?: (drawing: DrawingObject | null) => void;
+    magnetSensitivity: MagnetSensitivity;
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    plotData: readonly EnrichedDatum[];
+    forkMovableSelectionIds: readonly string[];
+    activeForkManipulationDrawing: DrawingObject | null;
+    forkSelectionModifierPressed: boolean;
+    closeForkDrawingContextMenu: () => void;
+    setForkDrawingContextMenu: (menu: any) => void;
+    size: {
+        width: number;
+        height: number;
+    };
+    engineInstanceRef: MutableRefObject<EngineInstance | null>;
+    visiblePanes: readonly PaneDescriptor[];
+    onContextMenu?: (payload: any, nativeEvent: any) => void;
+    onClick?: (payload: any, nativeEvent: any) => void;
+    onTimeAnchor?: (timestamp: number) => void;
+    forkAltShortcutPressedRef: MutableRefObject<boolean>;
+    cloneSelectedDrawing: () => void;
+    toggleSelectedLock: () => void;
+    updateForkReadonlySelection: (drawing: DrawingObject | null) => void;
+    updateForkReadonlySelectionByIds: (ids: readonly string[]) => void;
+    forkVisibleRangeRef: MutableRefObject<EngineVisibleRange | null>;
+    forkPaneSnapshotsRef: MutableRefObject<readonly WidgetPaneRuntimeSnapshot[]>;
+    windowEventAdapter?: WindowEventAdapter;
+    isEditingText?: boolean;
+    handleStartTextEdit?: (draft: string) => void;
+}
+export declare function useWidgetForkInteraction({ useForkRuntime, drawingUiEnabled, activeForkDrawingTool, drawingWorkspace, resolvedDrawings, resolvedSelectedDrawing, resolvedForkSingleSelection, onSelectedDrawingChange, magnetSensitivity, paneSnapshots, plotData, forkMovableSelectionIds, activeForkManipulationDrawing, forkSelectionModifierPressed, closeForkDrawingContextMenu, setForkDrawingContextMenu, size, engineInstanceRef, visiblePanes, onContextMenu, onClick, onTimeAnchor, forkAltShortcutPressedRef, cloneSelectedDrawing, toggleSelectedLock, updateForkReadonlySelection, updateForkReadonlySelectionByIds, forkVisibleRangeRef, forkPaneSnapshotsRef, windowEventAdapter, isEditingText, handleStartTextEdit, }: UseWidgetForkInteractionProps): {
+    forkSurfaceCursor: ForkSurfaceCursor;
+    forkPreviewRevision: number;
+    forkManipulationActive: boolean;
+    forkManipulationActiveRef: import("react").RefObject<boolean>;
+    forkRubberBandSelection: ForkRubberBandSelection | null;
+    forkRenderableDrawings: readonly DrawingObject[];
+    forkPointerOwnerRef: import("react").RefObject<ForkPointerOwner | null>;
+    claimForkPointerOwner: (owner: ForkPointerOwner) => void;
+    releaseForkPointerOwner: (owner: ForkPointerOwner) => void;
+    handleForkPointerDown: (pointerContext: ForkPointerContext) => void;
+    handleForkPointerMove: (pointerContext: ForkPointerContext) => void;
+    handleForkPointerUp: (pointerContext: ForkPointerContext) => void;
+    handleForkPointerLeave: () => void;
+    handleForkClick: (event: ReactMouseEvent<HTMLDivElement>) => void;
+    handleForkContextMenu: (event: ReactMouseEvent<HTMLDivElement>) => void;
+    handleForkHostContextMenu: (pointerContext: ForkPointerContext) => void;
+    handleForkDrawingClick: (pointerContext: ForkPointerContext) => void;
+    handleForkDoubleClick: (pointerContext: ForkPointerContext) => void;
+    cancelForkInteraction: () => void;
+};

package/dist/dts/widget/hooks/useWidgetInteractionActions.d.ts

@@ -0,0 +1,36 @@
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import type { DrawingWorkspaceController } from "@vninvestcharts/engine-react";
+import type { KeyboardAdapter, WindowEventAdapter } from "@vninvestcharts/engine-react";
+export interface UseWidgetInteractionActionsProps {
+    useForkRuntime?: boolean;
+    drawingUiEnabled?: boolean;
+    drawingWorkspace: DrawingWorkspaceController;
+    resolvedDrawings: readonly DrawingObject[];
+    resolvedSelectedDrawing: DrawingObject | null;
+    onSelectedDrawingChange?: (drawing: DrawingObject | null) => void;
+    keyboardAdapter?: KeyboardAdapter;
+    windowEventAdapter: WindowEventAdapter;
+}
+export declare function useWidgetInteractionActions({ useForkRuntime, drawingUiEnabled, drawingWorkspace, resolvedDrawings, resolvedSelectedDrawing, onSelectedDrawingChange, keyboardAdapter, windowEventAdapter, }: UseWidgetInteractionActionsProps): {
+    forkSelectionModifierPressed: boolean;
+    forkDrawingContextMenu: {
+        x: number;
+        y: number;
+        drawingId: string | null;
+    } | null;
+    setForkDrawingContextMenu: import("react").Dispatch<import("react").SetStateAction<{
+        x: number;
+        y: number;
+        drawingId: string | null;
+    } | null>>;
+    forkAltShortcutPressedRef: import("react").RefObject<boolean>;
+    copySelectedDrawing: () => void;
+    pasteCopiedDrawing: () => void;
+    bringSelectedToFront: () => void;
+    sendSelectedToBack: () => void;
+    toggleSelectedLock: () => void;
+    cloneSelectedDrawing: () => void;
+    updateForkReadonlySelection: (nextDrawing: DrawingObject | null) => void;
+    updateForkReadonlySelectionByIds: (nextSelectedIds: readonly string[]) => void;
+    closeForkDrawingContextMenu: () => void;
+};

package/dist/dts/widget/hooks/useWidgetOverlays.d.ts

@@ -0,0 +1,190 @@
+import React from "react";
+import { type PaneDescriptor, type SeriesTier } from "../../lib/core";
+import type { SeriesConfig, SeriesTypeId } from "../../lib/core/types/pane-descriptor";
+import type { SettingsModalProps } from "../components/settings/SettingsModal";
+import { type DrawingObject } from "@vninvestcharts/engine-drawing";
+import { type DrawingWorkspaceController, type DrawingDockTab } from "@vninvestcharts/engine-react";
+import { type WidgetPaneRuntimeSnapshot } from "../utils/widgetHelpers";
+import { type WidgetTimezone } from "../../lib/utils/timezoneFormatter";
+import { type EnrichedDatum } from "../../lib/core/calculators/types";
+import type { PortalAdapter, StorageAdapter } from "@vninvestcharts/engine-react";
+import { buildLegendSeriesValue, resolveGlobalLeftAxisWidth, resolveLeftAxisWidth, type LegendSeriesValue } from "./overlays/overlayHelpers";
+export { buildLegendSeriesValue, resolveGlobalLeftAxisWidth, resolveLeftAxisWidth };
+export type { LegendSeriesValue };
+/** BL-14 group 1/3: pane structure, sizing, splitters and pane chrome. */
+export interface OverlaysPaneOptions {
+    useForkRuntime: boolean;
+    visiblePanes: readonly PaneDescriptor[];
+    paneSnapshotMap: Map<string, WidgetPaneRuntimeSnapshot>;
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    size: {
+        width: number;
+        height: number;
+    };
+    hoveredPaneId: string | null;
+    claimForkPointerOwner: (owner: any) => void;
+    releaseForkPointerOwner: (owner: any) => void;
+    handlePaneToggleVisible: (paneId: string) => void;
+    handlePaneRemove: (paneId: string) => void;
+    handlePaneAddSeries: (paneId: string) => void;
+    handlePaneEditSeries: (paneId: string) => void;
+    handlePaneToggleSeries: (paneId: string, seriesType: any, seriesIndex?: number) => void;
+    handlePaneRemoveSeries: (paneId: string, seriesType: any, seriesIndex?: number) => void;
+    localizePane: (pane: PaneDescriptor) => PaneDescriptor;
+    localAvailable: number;
+    localHeights: number[];
+    localApplyDelta: (splitterIndex: number, delta: number) => void;
+    localEqualizePair?: (splitterIndex: number) => void;
+    localResetToDefault: () => void;
+    renderPaneToolbar?: any;
+    renderPaneSplitter?: any;
+    renderDrawingChrome?: any;
+    /** True while the drawing rail is docked (chart column carries the dock margin). */
+    toolbarLocked?: boolean;
+    showToolbar?: boolean;
+}
+/** BL-14 group 2/3: drawing workspace, selection and drawing dock. */
+export interface OverlaysDrawingOptions {
+    drawingWorkspace: DrawingWorkspaceController;
+    resolvedSelectedDrawing: DrawingObject | null;
+    resolvedLegacyVisibleRange: any;
+    effectiveForkVisibleRange: any;
+    magnetSensitivity: any;
+    isDark: boolean;
+    plotData: readonly EnrichedDatum[];
+    visibleDomainRef: React.MutableRefObject<[Date, Date] | null>;
+    cloneSelectedDrawing: () => void;
+    toggleSelectedLock: () => void;
+    handleStartTextEdit: (draft: string) => void;
+    isEditingText: boolean;
+    drawingTextDraft: string;
+    setDrawingTextDraft: (value: string) => void;
+    handleCommitTextEdit: (commitCallback: (draft: string) => void) => void;
+    handleCancelTextEdit: () => void;
+    bringSelectedToFront: () => void;
+    sendSelectedToBack: () => void;
+    showDrawingDock?: boolean;
+    renderDrawingDock?: any;
+    defaultDrawingDockTab?: DrawingDockTab;
+}
+/** BL-14 group 3/3: settings, dock panels, legend, chart chrome and callbacks. */
+export interface OverlaysSettingsOptions {
+    activeSettingsOpen: boolean;
+    activeOnSettingsClose: () => void;
+    dataAdapterName?: string;
+    onDataAdapterChange?: any;
+    localSelectedPaneId: string;
+    setLocalSelectedPaneId: (id: string) => void;
+    activeMaxVisiblePanes: number;
+    setLocalMaxVisiblePanes: (n: number) => void;
+    activeMaxVisibleBars: number;
+    setLocalMaxVisibleBars: (n: number) => void;
+    activeShowNonTradingDays: boolean;
+    setLocalShowNonTradingDays: (b: boolean) => void;
+    activeShowDrawingPriceMarkers: boolean;
+    setLocalShowDrawingPriceMarkers: (b: boolean) => void;
+    activeEnableWhale: boolean;
+    setLocalEnableWhale: (b: boolean) => void;
+    activeWhaleThreshold: number;
+    setLocalWhaleThreshold: (n: number) => void;
+    activeEnableCVD: boolean;
+    setLocalEnableCVD: (b: boolean) => void;
+    activeCvdMode: "oscillator" | "histogram";
+    setLocalCvdMode: (m: "oscillator" | "histogram") => void;
+    themeState: any;
+    activeTimezone: WidgetTimezone;
+    setLocalTimezone: (tz: WidgetTimezone) => void;
+    onTimezoneChange?: (tz: WidgetTimezone) => void;
+    activeAlertAudioEnabled: boolean;
+    setLocalAlertAudioEnabled: (b: boolean) => void;
+    previewImageDataUrl: string | null;
+    setPreviewImageDataUrl: (url: string | null) => void;
+    renderSettings?: any;
+    renderPaperTradePanel?: any;
+    /**
+     * D2: explicit dock switch. `true` forces the sidebar open (watchlist /
+     * dataWindow alone suffice); `false` forces closed; `undefined` keeps the
+     * legacy behavior (open when drawing/paperTrade/advisory/tape present).
+     */
+    showDock?: boolean;
+    showAdvisoryPanel?: boolean;
+    advisoryResult?: any;
+    isAdvisoryLoading?: boolean;
+    onAdvisoryRefresh?: () => void;
+    showTapePanel?: boolean;
+    tapeEntries?: readonly any[];
+    isTapeLoading?: boolean;
+    tapeFilterBillions?: number;
+    onTapeFilterChange?: (b: number) => void;
+    onPaperTradePanelClose?: () => void;
+    showDrawingPriceMarkers: boolean;
+    resolvedForkPriceMarkerSelection: DrawingObject | null;
+    t: (key: string, options?: any) => string;
+    onDrawingsChange?: any;
+    showTimeScrollbar?: boolean;
+    onShowTimeScrollbarChange?: (next: boolean) => void;
+    overlayTimeframe?: string;
+    comparisonOverlays?: SettingsModalProps["comparisonOverlays"];
+    onComparisonRemove?: SettingsModalProps["onComparisonRemove"];
+    onComparisonUpdate?: SettingsModalProps["onComparisonUpdate"];
+    setOverlayTimeframe: (tf: string | undefined) => void;
+    overlayStyle: "hollow" | "step" | "area" | "candle";
+    setOverlayStyle: (style: "hollow" | "step" | "area" | "candle") => void;
+    onExportLayout?: () => void;
+    onImportLayout?: (layoutJson: string) => void;
+    portalAdapter?: PortalAdapter;
+    storageAdapter?: StorageAdapter;
+    themePreset?: string;
+    chartId?: string;
+    /** Locked-at-open header context (from own chart props, never ambient active). */
+    symbol?: string;
+    /** Locked-at-open header context (from own chart props). */
+    timeframe?: string;
+    /** S3b-2: tier gate cho composer thêm series (undefined = không gate, legacy). */
+    seriesTier?: SeriesTier;
+    /** Optional callback returning a suffix (e.g. "+2.34%") for an indicator legend chip by pane and series index. */
+    legendSeriesSuffix?: (paneId: string, seriesIndex: number) => string | undefined;
+    /** UI-P3: hovered (or last-bar fallback) datum used for legend live values. Fork runtime; undefined hides values. */
+    hoveredDatum?: EnrichedDatum | null;
+    /**
+     * If provided, use these panes for IndicatorLegend rendering instead of visiblePanes.
+     * This allows showing comparison overlays that were injected into the pane series
+     * (e.g. via resolvedPanes in VNInvestCharts.tsx).
+     */
+    legendPanes?: readonly PaneDescriptor[];
+    /** Directly add a series to a pane (bypass SettingsModal) via quick-add picker. */
+    onQuickAddSeries?: (paneId: string, series: SeriesConfig) => void;
+    /** Directly remove a series from a pane via quick-add picker (toggle off). */
+    onQuickRemoveSeries?: (paneId: string, seriesType: SeriesTypeId) => void;
+    /**
+     * DECLUTTER_V4: where compare chips render. `"embedded"` (default) keeps
+     * them in the pane-header legend (multichart). `"statusline"` hides them
+     * from the embedded legend so the caller can render
+     * `renderCompareLegendNode(paneId)` below the OHLC row instead (single).
+     */
+    compareLegendSlot?: "embedded" | "statusline";
+}
+/**
+ * BL-14: backward-compatible union of the three option groups.
+ * Existing flat-object call-sites typecheck unchanged; new code can
+ * construct/pass each group independently.
+ */
+export interface UseWidgetOverlaysOptions extends OverlaysPaneOptions, OverlaysDrawingOptions, OverlaysSettingsOptions {
+}
+export interface UseWidgetOverlaysReturn {
+    paneToolbarNodes: React.ReactNode[];
+    paneSplitterNodes: React.ReactNode[];
+    drawingChromeNode: React.ReactNode;
+    drawingDockNode: React.ReactNode;
+    floatingInspectorNode: React.ReactNode;
+    inlineEditorNode: React.ReactNode;
+    settingsModalNode: React.ReactNode;
+    snapshotPreviewModalNode: React.ReactNode;
+    hasRightSidebar: boolean;
+    sidebarWidth: number;
+    isResizingSidebar: boolean;
+    handleSidebarPointerDown: (e: React.PointerEvent<HTMLDivElement>) => void;
+    /** DECLUTTER_V4: compare-only legend node for the statusline slot (null unless slot is "statusline"). */
+    renderCompareLegendNode: (paneId: string) => React.ReactNode;
+}
+export declare function useWidgetOverlays({ useForkRuntime, visiblePanes, paneSnapshotMap, paneSnapshots, size, hoveredPaneId, hoveredDatum, claimForkPointerOwner, releaseForkPointerOwner, handlePaneToggleVisible, handlePaneRemove, handlePaneAddSeries, handlePaneEditSeries, handlePaneToggleSeries, handlePaneRemoveSeries, localizePane, localAvailable, localHeights, localApplyDelta, localEqualizePair, localResetToDefault, renderPaneToolbar, renderPaneSplitter, renderDrawingChrome, toolbarLocked, showToolbar, drawingWorkspace, resolvedSelectedDrawing, resolvedLegacyVisibleRange, effectiveForkVisibleRange, magnetSensitivity, isDark, plotData, visibleDomainRef, cloneSelectedDrawing, toggleSelectedLock, handleStartTextEdit, isEditingText, drawingTextDraft, setDrawingTextDraft, handleCommitTextEdit, handleCancelTextEdit, bringSelectedToFront, sendSelectedToBack, showDrawingDock, renderDrawingDock, defaultDrawingDockTab, activeSettingsOpen, activeOnSettingsClose, dataAdapterName, onDataAdapterChange, localSelectedPaneId, setLocalSelectedPaneId, activeMaxVisiblePanes, setLocalMaxVisiblePanes, activeMaxVisibleBars, setLocalMaxVisibleBars, activeShowNonTradingDays, setLocalShowNonTradingDays, activeShowDrawingPriceMarkers, setLocalShowDrawingPriceMarkers, activeEnableWhale, setLocalEnableWhale, activeWhaleThreshold, setLocalWhaleThreshold, activeEnableCVD, setLocalEnableCVD, activeCvdMode, setLocalCvdMode, themeState, activeTimezone, setLocalTimezone, onTimezoneChange, activeAlertAudioEnabled, setLocalAlertAudioEnabled, previewImageDataUrl, setPreviewImageDataUrl, renderSettings, renderPaperTradePanel, showDock, showAdvisoryPanel, advisoryResult, isAdvisoryLoading, onAdvisoryRefresh, showTapePanel, tapeEntries, isTapeLoading, tapeFilterBillions, onTapeFilterChange, onPaperTradePanelClose, showDrawingPriceMarkers, resolvedForkPriceMarkerSelection, t, onDrawingsChange, showTimeScrollbar, onShowTimeScrollbarChange, overlayTimeframe, setOverlayTimeframe, overlayStyle, setOverlayStyle, onExportLayout, onImportLayout, portalAdapter, storageAdapter, themePreset, chartId, symbol, timeframe, comparisonOverlays, onComparisonRemove, onComparisonUpdate, legendSeriesSuffix, legendPanes, onQuickAddSeries, onQuickRemoveSeries, compareLegendSlot, seriesTier, }: UseWidgetOverlaysOptions): UseWidgetOverlaysReturn;

package/dist/dts/widget/hooks/useWidgetRuntime.d.ts

@@ -0,0 +1,20 @@
+import { type RequestedWidgetRuntime, type ResolvedWidgetRuntime } from '../runtimePolicy';
+import type { WidgetRuntimeCapabilities, WidgetRuntimeResolutionReason } from '../utils/widgetHelpers';
+interface UseWidgetRuntimeOptions {
+    engineRuntime?: RequestedWidgetRuntime;
+    drawingUiEnabled: boolean;
+    drawingActiveTool?: string;
+    selectedDrawingType: string | null;
+    onRuntimeResolved?: (runtime: ResolvedWidgetRuntime, reason: WidgetRuntimeResolutionReason) => void;
+}
+interface UseWidgetRuntimeReturn {
+    useForkRuntime: boolean;
+    /** Narrowed to fork since the legacy lane was removed 2026-10-03 (G4). */
+    effectiveRuntime: 'fork';
+    runtimeReason: WidgetRuntimeResolutionReason;
+    runtimeCapabilities: WidgetRuntimeCapabilities;
+    contentRuntimeKey: string;
+    handleRuntimeDegraded: (reason: 'fork-no-render-output') => void;
+}
+export declare function useWidgetRuntime({ engineRuntime, drawingUiEnabled, drawingActiveTool, selectedDrawingType, onRuntimeResolved, }: UseWidgetRuntimeOptions): UseWidgetRuntimeReturn;
+export type { UseWidgetRuntimeOptions, UseWidgetRuntimeReturn };

package/dist/dts/widget/hooks/useWidgetSettings.d.ts

@@ -0,0 +1,244 @@
+import { type WidgetLocale, type WidgetMessages } from "../i18n/types";
+import { type ChartTheme, type PaneDescriptor } from "../../lib/core";
+import type { DrawingDockTab } from "@vninvestcharts/engine-react";
+import type { DrawingStorageAdapter } from "@vninvestcharts/engine-drawing";
+import type { MagnetSensitivity } from "@vninvestcharts/engine-drawing";
+import { type Timeframe } from "../../lib/types/adapter";
+import { type OHLCVBar } from "../../lib/types/ohlcv";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import { type WidgetAuthHandler } from "../VNInvestCharts";
+import type { StorageAdapter } from "@vninvestcharts/engine-react";
+import type { CrosshairMode } from "@vninvestcharts/engine-core";
+import { type EnrichedDatum } from "../../lib/core/calculators/types";
+import { type WidgetTimezone } from "../../lib/utils/timezoneFormatter";
+import { type RequestedWidgetRuntime } from "../runtimePolicy";
+export interface UseWidgetSettingsOptions {
+    locale?: WidgetLocale;
+    messages?: Partial<WidgetMessages>;
+    theme?: ChartTheme;
+    timezone?: WidgetTimezone;
+    defaultTimezone?: WidgetTimezone;
+    onTimezoneChange?: (timezone: WidgetTimezone) => void;
+    panes?: readonly any[];
+    drawingUiEnabled?: boolean;
+    drawingActiveTool?: string;
+    drawings?: readonly DrawingObject[];
+    defaultDrawings?: readonly DrawingObject[];
+    drawingStorageKey?: string;
+    drawingStorageAdapter?: DrawingStorageAdapter;
+    defaultDrawingDockTab?: DrawingDockTab;
+    engineRuntime?: RequestedWidgetRuntime;
+    useWebGL?: boolean;
+    measurementEnabled?: boolean;
+    selectedDrawing?: DrawingObject | null;
+    showDrawingPriceMarkers?: boolean;
+    showNonTradingDays?: boolean;
+    showTimeScrollbar?: boolean;
+    enableWhale?: boolean;
+    whaleThreshold?: number;
+    whaleOrders?: readonly any[];
+    enableCVD?: boolean;
+    cvdMode?: "oscillator" | "histogram";
+    externalCvdSeries?: readonly any[];
+    darkFlowStrength?: number | null;
+    darkFlowSignalType?: any;
+    suppressForkCanvasFallback?: boolean;
+    showAdvisoryPanel?: boolean;
+    advisoryResult?: any;
+    isAdvisoryLoading?: boolean;
+    onAdvisoryRefresh?: (() => void) | undefined;
+    showTapePanel?: boolean;
+    tapeEntries?: readonly any[];
+    isTapeLoading?: boolean;
+    tapeFilterBillions?: number;
+    onTapeFilterChange?: ((billions: number) => void) | undefined;
+    showToolbar?: boolean;
+    showHeader?: boolean;
+    showFooter?: boolean;
+    renderToolbar?: any;
+    renderHeader?: any;
+    renderFooter?: any;
+    showDrawingDock?: boolean;
+    settingsOpen?: boolean;
+    onSettingsClose?: (() => void) | undefined;
+    onPaperTradePanelClose?: (() => void) | undefined;
+    renderReplayBar?: any;
+    renderPaperTradePanel?: any;
+    renderSettings?: any;
+    renderDrawingDock?: any;
+    historyMinResidentBars?: number;
+    maxVisibleBars?: number;
+    maxVisiblePanes?: number;
+    localCacheRoot?: string;
+    backfillWorkerFlags?: any;
+    canaryLevel?: 10 | 30 | 100;
+    onCanaryGateDecision?: any;
+    onCanaryRollbackEvent?: any;
+    dataAdapterName?: string;
+    onDataAdapterChange?: any;
+    range?: string;
+    onRangeChange?: any;
+    onTimeframeChange?: any;
+    defaultPeriod?: string;
+    authHandler?: WidgetAuthHandler;
+    onSymbolChange?: any;
+    symbol?: string;
+    timeframe?: Timeframe;
+    data?: readonly OHLCVBar[];
+    adapter?: any;
+    onClick?: any;
+    onContextMenu?: any;
+    onDrawingsChange?: any;
+    onSelectedDrawingChange?: any;
+    onDrawingWorkspaceChange?: any;
+    onVisibleDomainChange?: any;
+    onVisibleRangeChange?: any;
+    syncOverrides?: Record<string, boolean>;
+    onHistorySyncBusyChange?: any;
+    onBarsChange?: any;
+    onPaneSnapshotsChange?: any;
+    onPaneHover?: any;
+    onPaneToggleVisibleRequest?: any;
+    onPaneRemoveRequest?: any;
+    onPaneAddSeriesRequest?: any;
+    onPaneToggleSeriesRequest?: any;
+    onPaneRemoveSeriesRequest?: any;
+    onRuntimeCapabilitiesChange?: any;
+    onRuntimeResolved?: any;
+    onCoordinateBridgeChange?: any;
+    onError?: any;
+    onDrawingAlert?: any;
+    renderPaneToolbar?: any;
+    renderPaneSplitter?: any;
+    renderDrawingChrome?: any;
+    resetKey?: number;
+    className?: string;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+    storageAdapter?: StorageAdapter;
+    /** Chart id (flows via ...props spread as `id`); absent = single-chart legacy. */
+    id?: string;
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    size: {
+        width: number;
+        height: number;
+    };
+    plotData: readonly EnrichedDatum[];
+    /**
+     * Tier for the PNG watermark (A4). A **ref**, not a value, and that is not a style
+     * choice: this hook is constructed at VNInvestCharts.tsx:288 while the tier is only
+     * resolved at :678, so passing the value directly would read it in its temporal dead
+     * zone. The ref is read lazily at export time, long after both are mounted.
+     */
+    tierRef?: React.MutableRefObject<string | undefined>;
+}
+export interface UseWidgetSettingsReturn {
+    localTimeframe: Timeframe;
+    setLocalTimeframe: React.Dispatch<React.SetStateAction<Timeframe>>;
+    localRange: string | undefined;
+    setLocalRange: React.Dispatch<React.SetStateAction<string | undefined>>;
+    internalXExtents: readonly [Date | number, Date | number] | undefined;
+    setInternalXExtents: React.Dispatch<React.SetStateAction<readonly [Date | number, Date | number] | undefined>>;
+    localSelectedPaneId: string;
+    setLocalSelectedPaneId: React.Dispatch<React.SetStateAction<string>>;
+    toolbarLocked: boolean;
+    setToolbarLocked: React.Dispatch<React.SetStateAction<boolean>>;
+    localMaxVisiblePanes: number;
+    setLocalMaxVisiblePanes: React.Dispatch<React.SetStateAction<number>>;
+    activeMaxVisiblePanes: number;
+    localMaxVisibleBars: number;
+    setLocalMaxVisibleBars: React.Dispatch<React.SetStateAction<number>>;
+    activeMaxVisibleBars: number;
+    localShowNonTradingDays: boolean;
+    setLocalShowNonTradingDays: React.Dispatch<React.SetStateAction<boolean>>;
+    activeShowNonTradingDays: boolean;
+    localShowDrawingPriceMarkers: boolean;
+    setLocalShowDrawingPriceMarkers: React.Dispatch<React.SetStateAction<boolean>>;
+    activeShowDrawingPriceMarkers: boolean;
+    localEnableWhale: boolean;
+    setLocalEnableWhale: React.Dispatch<React.SetStateAction<boolean>>;
+    activeEnableWhale: boolean;
+    localWhaleThreshold: number;
+    setLocalWhaleThreshold: React.Dispatch<React.SetStateAction<number>>;
+    activeWhaleThreshold: number;
+    localEnableCVD: boolean;
+    setLocalEnableCVD: React.Dispatch<React.SetStateAction<boolean>>;
+    activeEnableCVD: boolean;
+    localCvdMode: "oscillator" | "histogram";
+    setLocalCvdMode: React.Dispatch<React.SetStateAction<"oscillator" | "histogram">>;
+    activeCvdMode: "oscillator" | "histogram";
+    localTimezone: WidgetTimezone;
+    setLocalTimezone: React.Dispatch<React.SetStateAction<WidgetTimezone>>;
+    activeTimezone: WidgetTimezone;
+    localAlertAudioEnabled: boolean;
+    setLocalAlertAudioEnabled: React.Dispatch<React.SetStateAction<boolean>>;
+    activeAlertAudioEnabled: boolean;
+    localSettingsOpen: boolean;
+    setLocalSettingsOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    activeSettingsOpen: boolean;
+    activeOnSettingsClose: () => void;
+    isFullscreen: boolean;
+    setIsFullscreen: React.Dispatch<React.SetStateAction<boolean>>;
+    searchOpen: boolean;
+    setSearchOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    isEditingText: boolean;
+    setIsEditingText: React.Dispatch<React.SetStateAction<boolean>>;
+    drawingTextDraft: string;
+    setDrawingTextDraft: React.Dispatch<React.SetStateAction<string>>;
+    handleStartTextEdit: (draft: string) => void;
+    handleCommitTextEdit: (commitCallback: (draft: string) => void) => void;
+    handleCancelTextEdit: () => void;
+    handleFullscreenToggle: () => void;
+    handleSnapshot: () => void;
+    handleTimeframeChange: (tf: Timeframe) => void;
+    handleRangeChange: (r: string) => void;
+    getPaneLabel: (id: string, label: string) => string;
+    localizePane: (pane: PaneDescriptor) => PaneDescriptor;
+    handlePaneToggleVisible: (paneId: string) => void;
+    handlePaneRemove: (paneId: string) => void;
+    handlePaneAddSeries: (paneId: string) => void;
+    handlePaneEditSeries: (paneId: string) => void;
+    handlePaneToggleSeries: (paneId: string, seriesType: any, seriesIndex?: number) => void;
+    handlePaneRemoveSeries: (paneId: string, seriesType: any, seriesIndex?: number) => void;
+    visiblePanes: readonly PaneDescriptor[];
+    activeHeights: number[];
+    themeState: any;
+    resolvedTheme: ChartTheme;
+    isDark: boolean;
+    previewImageDataUrl: string | null;
+    setPreviewImageDataUrl: React.Dispatch<React.SetStateAction<string | null>>;
+    activeLocale: WidgetLocale;
+    t: (key: string) => string;
+    localAvailable: number;
+    localApplyDelta: (splitterIndex: number, delta: number) => void;
+    localEqualizePair: (splitterIndex: number) => void;
+    localResetToDefault: () => void;
+    magnetSensitivity: MagnetSensitivity;
+    setMagnetSensitivity: React.Dispatch<React.SetStateAction<MagnetSensitivity>>;
+    /** P2: crosshair display mode — cross (default) | dot | magnet (OHLC snap). Persisted. */
+    crosshairMode: CrosshairMode;
+    setCrosshairMode: React.Dispatch<React.SetStateAction<CrosshairMode>>;
+    overlayTimeframe: string | undefined;
+    setOverlayTimeframe: React.Dispatch<React.SetStateAction<string | undefined>>;
+    overlayStyle: "hollow" | "step" | "area" | "candle";
+    setOverlayStyle: React.Dispatch<React.SetStateAction<"hollow" | "step" | "area" | "candle">>;
+    statusLineSettings: {
+        showLogo: boolean;
+        showTicker: boolean;
+        showOHLC: boolean;
+        showBarChange: boolean;
+        showVolume: boolean;
+        showIndicatorTitles: boolean;
+        showIndicatorArguments: boolean;
+        showIndicatorValues: boolean;
+        backgroundOpacity: number;
+    };
+    scalesSettings: {
+        priceScaleMode: "normal" | "logarithmic" | "percentage";
+        invertScale: boolean;
+        countdownToBarClose: boolean;
+        showTimeScrollbar: boolean;
+        dateFormat?: "yyyy-mm-dd" | "dd/mm/yyyy" | "mm/dd/yyyy";
+    };
+}
+export declare function useWidgetSettings({ locale, theme, timezone, defaultTimezone, onTimezoneChange, panes, maxVisiblePanes, maxVisibleBars, showNonTradingDays, showTimeScrollbar, showDrawingPriceMarkers, enableWhale, whaleThreshold, enableCVD, cvdMode, containerRef, size, tierRef, settingsOpen, onSettingsClose, timeframe, range, symbol, plotData, onTimeframeChange, onRangeChange, onPaneToggleVisibleRequest, onPaneRemoveRequest, onPaneAddSeriesRequest, onPaneToggleSeriesRequest, onPaneRemoveSeriesRequest, storageAdapter, syncOverrides, id, }: UseWidgetSettingsOptions): UseWidgetSettingsReturn;

package/dist/dts/widget/hooks/useWidgetWorkspaceIO.d.ts

@@ -0,0 +1,24 @@
+import type { PortalAdapter } from "@vninvestcharts/engine-react";
+import type { PaneState } from "../context/VNInvestChartsStateContext";
+import type { UseDrawingInteractionReturn } from "@vninvestcharts/engine-react";
+import type { PaneDescriptor } from "../../lib/core";
+import type { EnrichedDatum } from "../../lib/core/calculators/types";
+import type { useWidgetSettings } from "./useWidgetSettings";
+export interface WidgetWorkspaceIODeps {
+    paneState: PaneState;
+    drawingsInteraction: Pick<UseDrawingInteractionReturn, "allDrawings" | "replaceDrawings">;
+    settings: ReturnType<typeof useWidgetSettings>;
+    activeSymbol: string;
+    activeTimeframe: string;
+    enrichedData: readonly EnrichedDatum[];
+    resolvedPanes: readonly PaneDescriptor[];
+    portalAdapter?: PortalAdapter | null;
+    /** BL-17: toast-capable feedback; falls back to alert() when absent. */
+    notify?: (message: string, tone: "success" | "error") => void;
+}
+export interface WidgetWorkspaceIO {
+    handleExportLayout: () => void;
+    handleImportLayout: (layoutJson: string) => void;
+    compareLegendSuffix: (paneId: string, seriesIndex: number) => string | undefined;
+}
+export declare function useWidgetWorkspaceIO(deps: WidgetWorkspaceIODeps): WidgetWorkspaceIO;

package/dist/dts/widget/hooks/useWorkspaceDockPanels.d.ts

@@ -0,0 +1,11 @@
+import type { FullChartHandle } from "../types/fullChartHandle";
+interface UseWorkspaceDockPanelsDeps {
+    activeChartId: string | null;
+    chartRefs: React.MutableRefObject<Map<string, React.RefObject<FullChartHandle | null>>>;
+    /** Bump mỗi khi workspace của active chart notify → đọc lại state mới. */
+    revision: number;
+}
+export declare function useWorkspaceDockPanels({ activeChartId, chartRefs, revision }: UseWorkspaceDockPanelsDeps): {
+    drawingDockNode: import("react").ReactNode;
+};
+export {};

package/dist/dts/widget/hooks/useWorkspaceLiveTrading.d.ts

@@ -0,0 +1,28 @@
+import { VirtualBrokerEngine } from "../../lib/core/trading/VirtualBrokerEngine";
+import { MarketDataPort } from "../../lib/core/trading/MarketDataPort";
+import { type MarketRules } from "../../lib/core/trading/MarketRules";
+import type { AsyncStorageAdapter, BroadcastChannelAdapter } from "@vninvestcharts/engine-react";
+export interface UseWorkspaceLiveTradingOptions {
+    storageAdapter?: AsyncStorageAdapter;
+    workspaceId?: string;
+    rules?: MarketRules;
+    syncAdapter?: BroadcastChannelAdapter | null;
+}
+export interface WorkspaceLivePair {
+    broker: VirtualBrokerEngine;
+    port: MarketDataPort;
+}
+export interface WorkspaceLiveLogEntry {
+    timestamp: number;
+    message: string;
+}
+export declare function useWorkspaceLiveTrading(options?: UseWorkspaceLiveTradingOptions): {
+    broker: VirtualBrokerEngine;
+    port: MarketDataPort;
+    log: WorkspaceLiveLogEntry[];
+    closePosition: (positionId: string) => boolean;
+    reversePosition: (positionId: string) => void;
+    cancelOrder: (orderId: string) => boolean;
+    reset: () => void;
+    brokerFor: (symbol: string) => WorkspaceLivePair | undefined;
+};

package/dist/dts/widget/hooks/useWorkspaceReplayTrading.d.ts

@@ -0,0 +1,22 @@
+/**
+ * WE2 P2-09: useWorkspaceReplayTrading (Task 11 rewired)
+ *
+ * Singleton replay-trading session cho toàn bộ workspace (H3 = workspace-level).
+ * Ruột tính toán chạy bằng VirtualBrokerEngine (REPLAY_SPOT_RULES: T+0, cho short);
+ * shapes legacy (positions/closedTrades/analytics) giữ nguyên cho consumers
+ * (markers, panel, interaction). Legacy ReplayOrderBook không còn chạy ở đây.
+ */
+import type { ReplayExecutedTrade } from "../../lib/core/replay/replayTradingTypes";
+import type { WorkspaceReplayTradingValue } from "../context/WorkspaceReplayTradingContext";
+export interface UseWorkspaceReplayTradingOptions {
+    enabled: boolean;
+    slippageBps?: number;
+    fillOnNextBar?: boolean;
+    realisticSlTpFill?: boolean;
+    onTradeExecuted?: (trade: ReplayExecutedTrade) => void;
+}
+export interface ReplayLogEntry {
+    timestamp: number;
+    message: string;
+}
+export declare function useWorkspaceReplayTrading(options: UseWorkspaceReplayTradingOptions): WorkspaceReplayTradingValue;

package/dist/dts/widget/i18n/a11y.messages.en.d.ts

@@ -0,0 +1,8 @@
+import type { WidgetMessages } from "./types";
+/**
+ * UX-03: labels for the visually-hidden chart summary that acts as the DOM
+ * alternative for the engine canvas. Kept in its own module (like
+ * `dock.messages.*`) because `messages.{en,vi}.ts` sit at their frozen
+ * fat-file budget and new UI text must not push them over.
+ */
+export declare const a11yMessagesEn: WidgetMessages;