@vninvestcharts/widget 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,23 @@
+/**
+ * Re-registers saved Pine scripts at WIDGET mount (plan item 1.6b).
+ *
+ * WHY THIS IS NOT IN THE PANEL. `PineEditorPanel` is `lazy()`-loaded, so a restore living there
+ * only runs when the user opens the Pine tab. After a plain page reload the plugin registry is
+ * empty while the persisted pane layout still names `pine_<scriptId>`; the tier gate then drops
+ * those series as unregistered and they stay invisible until something unrelated recomputes the
+ * panes. The independent code audit found this — the E2E could not, because the demo opens the
+ * tab and always compiles.
+ *
+ * WHY A VERSION COUNTER. `renderPanes` is memoised on `[resolvedPanes, seriesTierGate]`, and the
+ * registry is a module-level Map — mutating it does not invalidate any memo. So registration alone
+ * is not enough: the gate must be recomputed once afterwards. Returning a counter and feeding it
+ * into that memo's deps makes the second pass explicit instead of accidental.
+ *
+ * The counter only moves when something was actually restored, so a steady state costs no
+ * re-renders. `restorePineScripts` is idempotent (Map writes), so the double-invoke React
+ * StrictMode guarantees on mount is harmless.
+ *
+ * @param wantedTypes Pine series types currently referenced by the pane layout.
+ * @returns a monotonically increasing version, to be used as a memo dependency.
+ */
+export declare function usePineScriptRestore(wantedTypes: readonly string[]): number;

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

@@ -0,0 +1,8 @@
+import type { PortalAdapter } from "@vninvestcharts/engine-react";
+export interface UsePortalAdapterOptions {
+    portalAdapter: PortalAdapter;
+}
+export declare function usePortalAdapter(options: UsePortalAdapterOptions): {
+    portalTarget: Element | null;
+    createPortal: (children: React.ReactNode) => Element | null;
+};

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

@@ -0,0 +1,3 @@
+import type { SymbolSearchItem } from "../types/symbolSearch";
+/** Reads recent items once + appends with dedupe (most-recent-first, capped). */
+export declare function useRecentSymbols(): [SymbolSearchItem[], (item: SymbolSearchItem) => void];

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

@@ -0,0 +1,28 @@
+import { type EnrichedDatum } from "../../lib/core/calculators/types";
+export interface ReplayState {
+    playing: boolean;
+    speed: number;
+    currentBar: number;
+    currentBarTimestamp: number | undefined;
+    totalBars: number;
+    replayData: readonly EnrichedDatum[] | undefined;
+    replayActive: boolean;
+    onReplayPlay: () => void;
+    onReplayPause: () => void;
+    onReplayStop: () => void;
+    onReplayStepForward: () => void;
+    onReplayStepBack: () => void;
+    onReplayRewind: () => void;
+    onReplaySpeedChange: (speed: number) => void;
+    onReplaySeek: (barIndex: number) => void;
+    onReplaySeekByDate: (date: Date | number) => void;
+}
+export interface UseReplayStateOptions {
+    /** R3.1: fired on every controller index change (tick/seek/step). */
+    onTick?: (barIndex: number, currentBarDate: number | undefined) => void;
+    /** R3.1: bus-originated change — consume once and skip onTick (echo suppression). */
+    suppressTickRef?: {
+        current: boolean;
+    };
+}
+export declare function useReplayState(plotData: readonly EnrichedDatum[], options?: UseReplayStateOptions): ReplayState;

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

@@ -0,0 +1,26 @@
+import type { ReplayAnalyticsStats } from "../../lib/core/replay/ReplaySessionAnalytics";
+import type { ReplayExecutedTrade, ReplayOHLCBar, ReplayOrder, ReplayPosition } from "../../lib/core/replay/replayTradingTypes";
+export interface UseReplayTradingOptions {
+    currentBar: number;
+    currentBarTimestamp?: number;
+    bars: readonly ReplayOHLCBar[];
+    enabled: boolean;
+    slippageBps?: number;
+    fillOnNextBar?: boolean;
+    realisticSlTpFill?: boolean;
+    onTradeExecuted?: (trade: ReplayExecutedTrade) => void;
+}
+export interface UseReplayTradingResult {
+    positions: ReplayPosition[];
+    closedTrades: ReplayExecutedTrade[];
+    totalPnl: number;
+    orderCount: number;
+    analytics: ReplayAnalyticsStats;
+    placeOrder: (order: Omit<ReplayOrder, "id" | "timestamp">) => void;
+    closePosition: (positionId: string) => void;
+    setStopLoss: (positionId: string, price: number) => boolean;
+    setTakeProfit: (positionId: string, price: number) => boolean;
+    closeAllPositions: () => void;
+    reset: () => void;
+}
+export declare function useReplayTrading(options: UseReplayTradingOptions): UseReplayTradingResult;

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

@@ -0,0 +1,13 @@
+import type { ResizeAdapter } from "@vninvestcharts/engine-react";
+export interface CanvasSize {
+    width: number;
+    height: number;
+}
+export interface UseResizeAdapterOptions {
+    resizeAdapter?: ResizeAdapter;
+    onResize?: (size: CanvasSize) => void;
+}
+export declare function useResizeAdapter<TElement extends HTMLElement = HTMLDivElement>(options?: UseResizeAdapterOptions): {
+    ref: (node: TElement | null) => void;
+    size: CanvasSize;
+};

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

@@ -0,0 +1,62 @@
+import type React from "react";
+import type { PriceScaleMode } from "@vninvestcharts/engine-core";
+import type { PriceScaleMenuState } from "../components/canvas/PriceScaleMenu";
+import type { WidgetPaneRuntimeSnapshot } from "../utils/widgetHelpers";
+import type { EnrichedDatum } from "../../lib/core/calculators/types";
+/** Minimal engine surface P2b needs (structural — no EngineInstance import). */
+export interface ScaleOverlayEngine {
+    zoomToRange(range: {
+        from: number;
+        to: number;
+    }): void;
+    setPriceScaleMode(mode: PriceScaleMode, scaleSlotId?: string): void;
+    resetYAxisZoom(scaleSlotId?: string): void;
+    hitTestDrawingPrimitive?(localX: number, localY: number): unknown;
+}
+export interface ScaleOverlaysOptions {
+    enabled: boolean;
+    snapshots: readonly WidgetPaneRuntimeSnapshot[];
+    plotData: readonly EnrichedDatum[];
+    /** Fork visible range ({from,to} indices) — drives the scrollbar window. */
+    visibleRange: {
+        from: number;
+        to: number;
+    } | null;
+    getEngine: () => ScaleOverlayEngine | null | undefined;
+    /**
+     * Alt-shortcut latch (replay passthrough). When held, right-click always
+     * falls through — even on an axis (locked pointer contract).
+     */
+    altPressedRef?: React.RefObject<boolean>;
+    /** Own chart id for settings-sync filtering (absent = single-chart legacy). */
+    chartId?: string | null;
+}
+/** Main price slot of a pane: prefers a "price" slot, else first right slot, else first. */
+export declare function resolveMainPriceSlotId(snapshot: WidgetPaneRuntimeSnapshot): string | null;
+export interface ScaleOverlays {
+    priceMenu: PriceScaleMenuState | null;
+    /** Right-click handler: opens the scale menu when on a Y axis, else false (caller falls through). */
+    openMenuAt: (localX: number, localY: number, clientX: number, clientY: number, flip?: {
+        right?: number;
+        bottom?: number;
+    }) => boolean;
+    /**
+     * Surface onContextMenu wrapper: routes axis right-clicks to the scale
+     * menu, everything else to the drawing canvas menu fallback.
+     */
+    handleSurfaceContextMenu: (event: React.MouseEvent<HTMLDivElement>, fallback: (event: React.MouseEvent<HTMLDivElement>) => void) => void;
+    closeMenu: () => void;
+    applyMenuMode: (mode: PriceScaleMode) => void;
+    resetMenuZoom: () => void;
+    /** Footer mirror: main price-pane mode as linear (Auto UI) + applier. */
+    mainSlotMode: PriceScaleMode;
+    applyMainSlotMode: (mode: PriceScaleMode) => void;
+    /** Scrollbar navigator props (null when disabled/empty). */
+    scrollbar: {
+        dataLength: number;
+        from: number;
+        to: number;
+        onWindowChange: (from: number, to: number) => void;
+    } | null;
+}
+export declare function useScaleOverlays(options: ScaleOverlaysOptions): ScaleOverlays;

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

@@ -0,0 +1,72 @@
+export interface ScriptData {
+    id: string;
+    name: string;
+    source: string;
+    created: string;
+    lastModified: string;
+    /**
+     * Tamper EVIDENCE, not tamper PROOF.
+     *
+     * This is an FNV-1a checksum of `source` with its length, stored so a load can tell
+     * whether the text still matches what was saved. It catches an accidental edit, a
+     * truncated autosave, a half-written localStorage value, or a hand-edited devtools
+     * payload. It does **NOT** stop anyone who recomputes it, and it is not a signature:
+     * there is no key in this repo and inventing one would only be security theatre.
+     * `plan/SPEC §3.7 A25` asks for HMAC keyed off the license, which is a key-distribution
+     * decision for backend/ops and is deliberately not faked here.
+     *
+     * Absent on stores written before this field existed — those load without a warning,
+     * because there is nothing to compare against and warning on every legacy script would
+     * be noise, not signal.
+     */
+    integrity?: {
+        checksum: string;
+        sourceLength: number;
+    };
+}
+export interface ScriptStore {
+    formatVersion: number;
+    scripts: Record<string, ScriptData>;
+    lastActiveId: string | null;
+}
+export type SaveStatus = "saved" | "unsaved" | "saving" | "error";
+/**
+ * Read-only view of the persisted scripts, for callers outside the editor panel.
+ *
+ * The panel is `lazy()`-loaded (see `VNInvestCharts.tsx`), so anything that must happen on a
+ * plain page reload — most importantly re-registering saved Pine scripts with the plugin registry
+ * — cannot live inside it. Doing the restore there meant it only ran if the user happened to open
+ * the Pine tab, and the saved series stayed invisible until some unrelated layout invalidation
+ * recomputed the render panes.
+ *
+ * SSR-safe: it touches `localStorage` only when called, never at module scope.
+ */
+export declare function readStoredScripts(): ScriptData[];
+export declare function defaultTemplate(index: number): string;
+/** FNV-1a, 32-bit. Cheap, synchronous, and good enough to notice a changed byte. */
+export declare function scriptChecksum(source: string): string;
+/** True when `integrity` is absent (legacy, nothing to compare) or still matches. */
+export declare function isScriptIntact(script: ScriptData): boolean;
+/**
+ * Ids whose stored text no longer matches their checksum.
+ *
+ * A script can fail to PARSE and still be intact, and can be intact and still be
+ * wrong; this only says the bytes moved underneath us.
+ */
+export declare function findAlteredScripts(scripts: Record<string, ScriptData>): string[];
+export declare function generateExportData(script: ScriptData): string;
+export declare function parseImportData(json: string): ScriptData | null;
+export declare function useScriptPersistence(): {
+    scripts: Record<string, ScriptData>;
+    activeId: string | null;
+    getActiveScript: () => ScriptData | null;
+    saveStatus: SaveStatus;
+    initDone: boolean;
+    setScriptSource: (source: string) => void;
+    createScript: (name?: string, source?: string) => string;
+    selectScript: (id: string) => void;
+    deleteScript: (id: string) => void;
+    renameScript: (id: string, newName: string) => void;
+    exportScript: (id: string) => boolean;
+    importScript: (json: string) => boolean;
+};

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

@@ -0,0 +1,30 @@
+import type { StockDataAdapter } from "../../lib/types/adapter";
+import type { VNInvestClient } from "../adapters/VNInvestClient";
+import type { SymbolSearchItem } from "../types/symbolSearch";
+import { type ExchangeFilter } from "../constants/symbolSearch";
+export interface UseSymbolSearchOptions {
+    adapter?: StockDataAdapter;
+    client?: VNInvestClient;
+    exchangeFilter: ExchangeFilter;
+    /** Symbols to exclude from results (compare mode: already-compared). */
+    compareExisting?: string[];
+}
+export interface UseSymbolSearchResult {
+    query: string;
+    setQuery: (q: string) => void;
+    results: SymbolSearchItem[];
+    loading: boolean;
+    highlightIndex: number;
+    setHighlightIndex: (n: number) => void;
+    /**
+     * Runs one search pass. Resolves with the combined result count,
+     * or null when the query is empty (no-op — caller keeps dropdown state).
+     */
+    search: (q: string, exFilter?: ExchangeFilter) => Promise<number | null>;
+}
+/**
+ * Facade (D-S08): single search entry — legacy client first, adapter fallback.
+ * The component never branches on client vs adapter itself.
+ */
+export declare function useStockSearchAdapter(adapter?: StockDataAdapter, client?: VNInvestClient): (q: string, exchange?: string) => Promise<SymbolSearchItem[]>;
+export declare function useSymbolSearch(opts: UseSymbolSearchOptions): UseSymbolSearchResult;

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

@@ -0,0 +1,15 @@
+import { type RefObject } from "react";
+export type ViewportMode = "mobile" | "tablet" | "desktop";
+/**
+ * UX-04: responsive mode for the WIDGET, not for the page.
+ *
+ * The previous implementation observed `document.documentElement`, so a chart
+ * embedded in a 600px sidebar on a 1920px screen still resolved to `desktop`
+ * and rendered the full desktop chrome. Passing the widget's own container ref
+ * makes the breakpoint follow the box the chart actually occupies, which is
+ * what matters for embeds and iframes.
+ *
+ * Falls back to viewport width when no ref is supplied, preserving the old
+ * behaviour for every existing call site.
+ */
+export declare function useViewportBreakpoint(containerRef?: RefObject<HTMLElement | null>): ViewportMode;

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

@@ -0,0 +1,70 @@
+import { type WidgetPaneRuntimeSnapshot, type WidgetCoordinateBridge } from '../utils/widgetHelpers';
+import { createForkChartRenderContextValue, createForkStockChartContextValue } from '../utils/coordinateBridge';
+import type { VisibleRange as EngineVisibleRange, EngineInstance } from '@vninvestcharts/engine-core';
+import type { VisibleRange, PaneDescriptor } from '../../lib/core';
+import type { StorageAdapter } from "@vninvestcharts/engine-react";
+import type { EnrichedDatum } from '../../lib/core/calculators/types';
+import type { IRuntimeScale } from '../runtime/IRuntimeEngine';
+interface UseWidgetCoordinateBridgeOptions {
+    useForkRuntime: boolean;
+    plotData: readonly EnrichedDatum[];
+    enrichedData: readonly EnrichedDatum[];
+    bars: readonly any[];
+    visiblePanes: readonly PaneDescriptor[];
+    size: {
+        width: number;
+        height: number;
+    };
+    scaleSlotDomains: Record<string, [number, number]>;
+    activeHeights: number[];
+    forkEngineInstance: EngineInstance | null;
+    forkVisibleRange: EngineVisibleRange | null;
+    setForkVisibleRange: React.Dispatch<React.SetStateAction<EngineVisibleRange | null>>;
+    forkVisibleRangeRef: React.MutableRefObject<EngineVisibleRange | null>;
+    forkPaneSnapshotsRef: React.MutableRefObject<readonly WidgetPaneRuntimeSnapshot[]>;
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    setPaneSnapshots: React.Dispatch<React.SetStateAction<readonly WidgetPaneRuntimeSnapshot[]>>;
+    snapshotRevision: number;
+    incrementSnapshotRevision: () => void;
+    legacyVisibleRange: VisibleRange | null;
+    setLegacyVisibleRange: React.Dispatch<React.SetStateAction<VisibleRange | null>>;
+    onCoordinateBridgeChange: ((bridge: WidgetCoordinateBridge | null) => void) | undefined;
+    onPaneSnapshotsChange: ((snapshots: readonly WidgetPaneRuntimeSnapshot[]) => void) | undefined;
+    onVisibleDomainChange: ((domain: [Date | number, Date | number]) => void) | undefined;
+    onVisibleRangeChange: ((range: VisibleRange) => void) | undefined;
+    controlledXExtents: readonly [Date | number, Date | number] | undefined;
+    internalXExtents: readonly [Date | number, Date | number] | undefined;
+    setInternalXExtents: React.Dispatch<React.SetStateAction<readonly [Date | number, Date | number] | undefined>>;
+    symbol: string | undefined;
+    localRange: string | undefined;
+    showNonTradingDays: boolean;
+    chartSurfaceReady: boolean;
+    pendingForkVisibleRangeRef: React.MutableRefObject<EngineVisibleRange | null>;
+    pendingForkVisibleRangeRafRef: React.MutableRefObject<number | null>;
+    lastStableForkSpanRef: React.MutableRefObject<number | null>;
+    pendingHistoryPatchRef: React.MutableRefObject<any>;
+    lastEmittedPaneSnapshotsRef: React.MutableRefObject<readonly WidgetPaneRuntimeSnapshot[]>;
+    lastPaneSnapshotsSubscriberRef: React.MutableRefObject<((snapshots: readonly WidgetPaneRuntimeSnapshot[]) => void) | undefined>;
+    resolvedLegacyVisibleRangeRef: React.MutableRefObject<VisibleRange | null>;
+    engineInstanceRef: React.MutableRefObject<EngineInstance | null>;
+    storageAdapter?: StorageAdapter;
+}
+interface UseWidgetCoordinateBridgeReturn {
+    legacyCoordinateBridge: WidgetCoordinateBridge | null;
+    forkChartRenderContextValue: ReturnType<typeof createForkChartRenderContextValue> | null;
+    forkStockChartContextValue: ReturnType<typeof createForkStockChartContextValue> | null;
+    legacyPaneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    resolvedLegacyVisibleRange: VisibleRange | null;
+    paneSnapshotMap: Map<string, WidgetPaneRuntimeSnapshot>;
+    emitPaneSnapshots: (nextSnapshots: readonly WidgetPaneRuntimeSnapshot[]) => void;
+    handleVisibleDomainChange: (domain: [Date | number, Date | number]) => void;
+    emitCoordinateBridge: (snapshots: readonly WidgetPaneRuntimeSnapshot[], range: EngineVisibleRange | null) => void;
+    /**
+     * Typed `IRuntimeScale`, not `any` (2026-10-05). This is what makes removing the unread
+     * `xScale` field a compiler-checked change instead of a grep claim: while this was `any`,
+     * `tsc` could not see a read of a field that does not exist. See `IRuntimeEngine.ts`.
+     */
+    legacyChartScale: IRuntimeScale;
+}
+export declare function useWidgetCoordinateBridge({ useForkRuntime, plotData, enrichedData, visiblePanes, size, scaleSlotDomains, activeHeights, forkEngineInstance, forkVisibleRange, setForkVisibleRange, forkVisibleRangeRef, forkPaneSnapshotsRef, paneSnapshots, setPaneSnapshots, snapshotRevision, incrementSnapshotRevision, legacyVisibleRange, setLegacyVisibleRange, onCoordinateBridgeChange, onPaneSnapshotsChange, onVisibleDomainChange, onVisibleRangeChange, controlledXExtents, internalXExtents, setInternalXExtents, symbol, localRange, showNonTradingDays, chartSurfaceReady, pendingForkVisibleRangeRef, pendingForkVisibleRangeRafRef, lastStableForkSpanRef, pendingHistoryPatchRef, lastEmittedPaneSnapshotsRef, lastPaneSnapshotsSubscriberRef, resolvedLegacyVisibleRangeRef, engineInstanceRef, storageAdapter, }: UseWidgetCoordinateBridgeOptions): UseWidgetCoordinateBridgeReturn;
+export type { UseWidgetCoordinateBridgeOptions, UseWidgetCoordinateBridgeReturn };

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

@@ -0,0 +1,138 @@
+import { type EngineInstance, type VisibleRange as EngineVisibleRange } from "@vninvestcharts/engine-core";
+import { type StockDataAdapter, type Timeframe } from "../../lib/types/adapter";
+import { type OHLCVBar } from "../../lib/types/ohlcv";
+import { type EnrichedDatum } from "../../lib/core/calculators/types";
+import { type WhaleOrder } from "../../lib/types/vninvest";
+import { type WidgetPaneRuntimeSnapshot, type WidgetHistorySessionState } from "../utils/widgetHelpers";
+import { type CanaryLevel } from "../CanaryRolloutConfig";
+export interface UseWidgetDataProps {
+    /**
+     * 1.3b: ordered list of Pine series types currently on the chart ("" when there is none).
+     * `hashEnrichedData` below hashes date/OHLCV only, so it cannot see `indicatorValues`; without
+     * this signal, adding or removing a Pine script leaves the engine holding a stale enriched
+     * array even though React state has the new values.
+     */
+    pineSeriesSignature?: string;
+    data?: readonly OHLCVBar[] | null;
+    symbol?: string;
+    timeframe?: Timeframe;
+    canaryLevel?: CanaryLevel;
+    backfillWorkerFlags?: any;
+    localCacheRoot?: string;
+    onBarsChange?: (bars: readonly OHLCVBar[]) => void;
+    onHistorySyncBusyChange?: (busy: boolean) => void;
+    onCanaryGateDecision?: (decision: any) => void;
+    onCanaryRollbackEvent?: (event: any) => void;
+    enableWhale?: boolean;
+    whaleOrders?: readonly WhaleOrder[] | null;
+    historyMinResidentBars?: number;
+    useForkRuntime?: boolean;
+    engineInstanceRef: React.RefObject<EngineInstance | null>;
+    forkEngineInstance?: EngineInstance | null;
+    forkVisibleRangeRef: React.MutableRefObject<EngineVisibleRange | null>;
+    forkVisibleRange: EngineVisibleRange | null;
+    setForkVisibleRange: React.Dispatch<React.SetStateAction<EngineVisibleRange | null>>;
+    incrementSnapshotRevision: () => void;
+    emitCoordinateBridge: (snapshots: readonly WidgetPaneRuntimeSnapshot[], range: EngineVisibleRange) => void;
+    forkPaneSnapshotsRef: React.MutableRefObject<readonly WidgetPaneRuntimeSnapshot[]>;
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    panes?: readonly any[];
+    adapter?: StockDataAdapter;
+    onVisibleRangeChange?: (range: any) => void;
+    onVisibleDomainChange?: (domain: [Date, Date]) => void;
+    controlledXExtents?: readonly [Date | number, Date | number];
+    initialXExtents?: readonly [Date | number, Date | number];
+    sharedPlotDataRef?: React.MutableRefObject<readonly EnrichedDatum[]>;
+    authHandler?: any;
+    pendingForkVisibleRangeRef: React.MutableRefObject<EngineVisibleRange | null>;
+    pendingForkVisibleRangeRafRef: React.MutableRefObject<number | null>;
+    lastStableForkSpanRef: React.MutableRefObject<number | null>;
+    pendingHistoryPatchRef: React.MutableRefObject<any>;
+    pendingSyncTimeRangeRef?: React.MutableRefObject<{
+        from: number;
+        to: number;
+    } | null>;
+    overlayTimeframe?: string;
+    searchParams?: URLSearchParams;
+    id?: string;
+    isActiveChart?: boolean;
+    replayActiveRef?: React.MutableRefObject<boolean>;
+}
+export declare function useWidgetData({ pineSeriesSignature, data, symbol, timeframe, canaryLevel, backfillWorkerFlags, localCacheRoot, onBarsChange, onHistorySyncBusyChange, onCanaryGateDecision, onCanaryRollbackEvent, enableWhale, whaleOrders, historyMinResidentBars, useForkRuntime, engineInstanceRef, forkEngineInstance, forkVisibleRangeRef, forkVisibleRange, setForkVisibleRange, incrementSnapshotRevision, emitCoordinateBridge, forkPaneSnapshotsRef, paneSnapshots, panes, adapter, onVisibleRangeChange, onVisibleDomainChange, controlledXExtents, initialXExtents, sharedPlotDataRef, authHandler, pendingForkVisibleRangeRef, pendingForkVisibleRangeRafRef, lastStableForkSpanRef, pendingHistoryPatchRef, pendingSyncTimeRangeRef, overlayTimeframe, searchParams, id, isActiveChart, replayActiveRef, }: UseWidgetDataProps): {
+    bars: readonly OHLCVBar[];
+    setBars: import("react").Dispatch<import("react").SetStateAction<readonly OHLCVBar[]>>;
+    loading: boolean;
+    setLoading: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    error: Error | null;
+    setError: import("react").Dispatch<import("react").SetStateAction<Error | null>>;
+    reload: () => void;
+    compareStatusBySymbol: Record<string, "error" | "idle" | "loading" | "loaded">;
+    canaryFilteredBars: readonly OHLCVBar[];
+    resolvedCanaryLevel: CanaryLevel;
+    enrichedData: (EnrichedDatum | {
+        htf: any;
+        aoColor?: string;
+        indicatorValues?: Record<string, import("../../lib/core/calculators/types").IndicatorDatumValue | undefined>;
+        symbolData?: Record<string, {
+            open: number;
+            high: number;
+            low: number;
+            close: number;
+            volume: number;
+        }>;
+        normalizedPrices?: Record<string, number>;
+        renkoOpen?: number;
+        renkoClose?: number;
+        renkoUp?: boolean;
+        fullyFormed?: boolean;
+        startAs?: import("../../lib/core/calculators/types").KagiDirection;
+        changeTo?: import("../../lib/core/calculators/types").KagiDirection;
+        changePoint?: number;
+        reverseAt?: number;
+        current?: number;
+        boxes?: readonly import("../../lib/core/calculators/types").PnfBox[];
+        pnfColumnStart?: number;
+        pnfDirection?: import("../../lib/core/calculators/types").PnfDirection;
+        lineBreakOpen?: number;
+        lineBreakClose?: number;
+        lineBreakUp?: boolean;
+        date: Date;
+        open: number;
+        high: number;
+        low: number;
+        close: number;
+        volume: number;
+    })[];
+    plotData: EnrichedDatum[];
+    plotDataRef: import("react").RefObject<readonly EnrichedDatum[]>;
+    plotDataLengthRef: import("react").RefObject<number>;
+    whaleEvents: import("../../lib/indicators/overlays/whaleDetector").WhaleEvent[];
+    activeSymbol: string;
+    activeTimeframe: string;
+    activeCacheKey: string;
+    activeCacheSemanticScope: import("../history/cache").CacheSemanticScope | undefined;
+    activeSourceSemantics: any;
+    activeSourceRevisionKey: string;
+    activeHistoryRequestKey: string;
+    isControlledHistorySession: boolean;
+    requestVisibleHistoryWindowSync: (visibleDomain: [Date, Date], options?: {
+        force?: boolean;
+        updateVisibleDomainRef?: boolean;
+    }) => boolean;
+    reconcileVisibleHistoryWindow: (visibleDomain: [Date, Date]) => Promise<void>;
+    totalBarsFetchedRef: import("react").RefObject<number>;
+    consecutiveEmptyBackfillRef: import("react").RefObject<number>;
+    historyBackfillBeforeRef: import("react").RefObject<number | null>;
+    historyForwardAfterRef: import("react").RefObject<number | null>;
+    pendingHistoryPatchRef: import("react").MutableRefObject<any>;
+    visibleDomainRef: import("react").RefObject<[Date, Date] | null>;
+    pendingVisibleDomainRef: import("react").RefObject<[Date, Date] | null>;
+    lastQueuedVisibleDomainRef: import("react").RefObject<[Date, Date] | null>;
+    resetHistorySessionControllerRefs: () => void;
+    liveEdgeMsRef: import("react").RefObject<number | null>;
+    historySessionRef: import("react").RefObject<WidgetHistorySessionState>;
+    forkCameraEnvelopeMode: "shared" | "extended";
+    setForkCameraEnvelopeMode: import("react").Dispatch<import("react").SetStateAction<"shared" | "extended">>;
+    handleForkVisibleRangeChange: (range: EngineVisibleRange) => void;
+    adapterLabel: string;
+};

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

@@ -0,0 +1,67 @@
+import { type EngineInstance, type EngineHistoryPatch, type VisibleRange as EngineVisibleRange } from "@vninvestcharts/engine-core";
+import { type StockDataAdapter, type Timeframe } from "../../lib/types/adapter";
+import { type OHLCVBar } from "../../lib/types/ohlcv";
+import { type WidgetPaneRuntimeSnapshot } from "../utils/widgetHelpers";
+export interface UseWidgetDataBackfillProps {
+    adapter: StockDataAdapter;
+    activeSymbol: string;
+    activeTimeframe: Timeframe;
+    activeCacheKey: string;
+    activeCacheSemanticScope: string | undefined;
+    activeSourceSemantics: any;
+    isControlledHistorySession: boolean;
+    loading: boolean;
+    useForkRuntime?: boolean;
+    engineInstanceRef: React.RefObject<EngineInstance | null>;
+    forkVisibleRangeRef: React.MutableRefObject<EngineVisibleRange | null>;
+    forkVisibleRange: EngineVisibleRange | null;
+    setForkVisibleRange: React.Dispatch<React.SetStateAction<EngineVisibleRange | null>>;
+    incrementSnapshotRevision: () => void;
+    emitCoordinateBridge: (snapshots: readonly WidgetPaneRuntimeSnapshot[], range: EngineVisibleRange) => void;
+    forkPaneSnapshotsRef: React.MutableRefObject<readonly WidgetPaneRuntimeSnapshot[]>;
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    historyMinResidentBars?: number;
+    onHistorySyncBusyChange?: (busy: boolean) => void;
+    chartId?: string;
+    bars: readonly OHLCVBar[];
+    setBars: React.Dispatch<React.SetStateAction<readonly OHLCVBar[]>>;
+    historyBackfillBeforeRef: React.MutableRefObject<number | null>;
+    historyForwardAfterRef: React.MutableRefObject<number | null>;
+    consecutiveEmptyBackfillRef: React.MutableRefObject<number>;
+    pendingHistoryPatchRef: React.MutableRefObject<EngineHistoryPatch | null>;
+    activeHistoryRequestKeyRef: React.MutableRefObject<string>;
+    activeHistorySessionRevisionRef: React.MutableRefObject<number>;
+    historyChunkStoreRef: React.MutableRefObject<any>;
+    historyMergeLaneRef: React.MutableRefObject<any>;
+    cacheMatrixRef: React.MutableRefObject<any>;
+    liveEdgeMsRef: React.MutableRefObject<number | null>;
+    prevVisibleSpanMsRef: React.MutableRefObject<number | null>;
+    prevVisibleStartMsRef: React.MutableRefObject<number | null>;
+    maxInflightRef: React.MutableRefObject<number>;
+    debounceMsRef: React.MutableRefObject<number>;
+    chunkBarsRef: React.MutableRefObject<number>;
+    retentionFactorRef: React.MutableRefObject<number>;
+    overfetchRatioRef: React.MutableRefObject<number>;
+    queueDepthRef: React.MutableRefObject<number>;
+    activeRequestsRef: React.MutableRefObject<Set<Promise<any>>>;
+    abortControllersRef: React.MutableRefObject<Map<string, AbortController>>;
+    historySyncBusyRef: React.MutableRefObject<boolean>;
+    historyWindowSyncInFlightRef: React.MutableRefObject<boolean>;
+    pendingVisibleDomainRef: React.MutableRefObject<[Date, Date] | null>;
+    visibleDomainRef: React.MutableRefObject<[Date, Date] | null>;
+    lastQueuedVisibleDomainRef: React.MutableRefObject<[Date, Date] | null>;
+    isHistorySessionRequestCurrent: (requestKey: string, sessionRevision: number, signal?: AbortSignal) => boolean;
+    runHistoryMergeLane: <T>(writer: () => T | Promise<T>) => Promise<T>;
+    syncHistoryBusyState: () => void;
+    isTestEnv: boolean;
+    EMPTY_BACKFILL_LOCK_THRESHOLD: number;
+}
+export declare function useWidgetDataBackfill({ adapter, activeSymbol, activeTimeframe, activeCacheKey, activeCacheSemanticScope, activeSourceSemantics, isControlledHistorySession, loading, useForkRuntime, engineInstanceRef, forkVisibleRangeRef, forkVisibleRange, setForkVisibleRange, incrementSnapshotRevision, emitCoordinateBridge, forkPaneSnapshotsRef, paneSnapshots, historyMinResidentBars, onHistorySyncBusyChange, chartId, bars, setBars, historyBackfillBeforeRef, historyForwardAfterRef, consecutiveEmptyBackfillRef, pendingHistoryPatchRef, activeHistoryRequestKeyRef, activeHistorySessionRevisionRef, historyChunkStoreRef, historyMergeLaneRef, cacheMatrixRef, liveEdgeMsRef, prevVisibleSpanMsRef, prevVisibleStartMsRef, maxInflightRef, debounceMsRef, chunkBarsRef, retentionFactorRef, overfetchRatioRef, queueDepthRef, activeRequestsRef, abortControllersRef, historySyncBusyRef, historyWindowSyncInFlightRef, pendingVisibleDomainRef, visibleDomainRef, lastQueuedVisibleDomainRef, isHistorySessionRequestCurrent, runHistoryMergeLane, syncHistoryBusyState, isTestEnv, EMPTY_BACKFILL_LOCK_THRESHOLD, }: UseWidgetDataBackfillProps): {
+    reconcileVisibleHistoryWindow: (visibleDomain: [Date, Date]) => Promise<void>;
+    queueVisibleHistoryWindowSync: (visibleDomain: [Date, Date], force?: boolean) => void;
+    requestVisibleHistoryWindowSync: (visibleDomain: [Date, Date], options?: {
+        force?: boolean;
+        updateVisibleDomainRef?: boolean;
+    }) => boolean;
+    totalBarsFetchedRef: import("react").RefObject<number>;
+};

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

@@ -0,0 +1,32 @@
+import { type OHLCVBar } from "../../lib/types/ohlcv";
+import { type EnrichedDatum, type VolumeProfileData } from "../../lib/core/calculators/types";
+import { type WhaleOrder } from "../../lib/types/vninvest";
+import { type WhaleEvent } from "../../lib/indicators/overlays/whaleDetector";
+import { type resolveVisiblePanes } from "../utils/widgetHelpers";
+export type VisiblePaneLike = ReturnType<typeof resolveVisiblePanes>;
+/**
+ * BL-01 extraction from useWidgetData.ts (behavior-identical move).
+ * Progressive higher-timeframe aggregation over base bars.
+ */
+export declare function computeProgressiveHTFData(baseBars: readonly OHLCVBar[], timeframe: string, overlayTimeframe: string): any[];
+export interface WhaleMappingInput {
+    enableWhale?: boolean;
+    whaleOrders?: readonly WhaleOrder[] | null;
+    plotData: readonly EnrichedDatum[];
+}
+/**
+ * BL-01 extraction from useWidgetData.ts (behavior-identical move).
+ * Maps external/internal whale orders to nearest bar indices.
+ */
+export declare function mapWhaleEventsToBars({ enableWhale, whaleOrders, plotData }: WhaleMappingInput): WhaleEvent[];
+export interface AsyncVolumeProfilesInput {
+    symbol?: string;
+    canaryFilteredBars: readonly OHLCVBar[];
+    mtfBarsByTimeframe: Record<string, readonly OHLCVBar[]>;
+    visiblePanes: VisiblePaneLike;
+}
+/**
+ * BL-01 extraction from useWidgetData.ts (behavior-identical move).
+ * Worker-backed VolumeProfile computation for visible VolumeProfile series.
+ */
+export declare function useAsyncVolumeProfiles({ symbol, canaryFilteredBars, mtfBarsByTimeframe, visiblePanes, }: AsyncVolumeProfilesInput): Record<string, VolumeProfileData>;

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

@@ -0,0 +1,38 @@
+import type { DrawingObject, DrawingStorageAdapter } from "@vninvestcharts/engine-drawing";
+import type { DrawingWorkspaceController, DrawingDockTab } from "@vninvestcharts/engine-react";
+import { type EnrichedDatum } from "../../lib/core/calculators/types";
+import { type Timeframe } from "../../lib/types/adapter";
+import type { KeyboardAdapter, StorageAdapter } from "@vninvestcharts/engine-react";
+export interface UseWidgetDrawingsProps {
+    defaultDrawings?: readonly DrawingObject[];
+    drawings?: readonly DrawingObject[];
+    drawingStorageKey?: string;
+    drawingStorageAdapter?: DrawingStorageAdapter;
+    /** P1-09: opt-in instance namespace for the default storage prefix. */
+    instanceId?: string;
+    /** P1-03/05: surfaced for UI feedback (toast) on storage failures. */
+    onStorageError?: (info: {
+        operation: "load" | "save" | "import" | "clear" | "dock-save";
+        error: unknown;
+    }) => void;
+    defaultDrawingDockTab?: DrawingDockTab;
+    onDrawingsChange?: (drawings: readonly DrawingObject[]) => void;
+    drawingUiEnabled?: boolean;
+    selectedDrawing?: DrawingObject | null;
+    onSelectedDrawingChange?: (drawing: DrawingObject | null) => void;
+    onDrawingWorkspaceChange?: (workspace: DrawingWorkspaceController | null) => void;
+    plotData: readonly EnrichedDatum[];
+    useForkRuntime?: boolean;
+    symbol: string;
+    timeframe: Timeframe;
+    keyboardAdapter?: KeyboardAdapter;
+    storageAdapter?: StorageAdapter;
+    isEditingText?: boolean;
+}
+export declare function useWidgetDrawings({ defaultDrawings, drawings, drawingStorageKey, drawingStorageAdapter, instanceId, onStorageError, defaultDrawingDockTab, onDrawingsChange, drawingUiEnabled, selectedDrawing, onSelectedDrawingChange, onDrawingWorkspaceChange, plotData, useForkRuntime, symbol, timeframe, keyboardAdapter, storageAdapter, isEditingText, }: UseWidgetDrawingsProps): {
+    drawingWorkspace: DrawingWorkspaceController;
+    resolvedDrawings: import("@vninvestcharts/engine-react").DrawingObject[];
+    resolvedSelectedDrawing: DrawingObject | null;
+    hasMultipleDrawingsSelected: boolean;
+    resolvedForkSingleSelection: DrawingObject | null;
+};