@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/alerts/DrawingAlertsHost.d.ts

@@ -0,0 +1,18 @@
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+/**
+ * W1.1 — host render toast alert + badge "chỉ hoạt động khi tab mở".
+ *
+ * Đây là chỗ duy nhất trong widget gọi `AlertNotificationToast` (trước đó chỉ
+ * được re-export ở `drawing-shim.ts`/`index.ts` nhưng không render ở đâu).
+ */
+export interface DrawingAlertsHostProps {
+    /** Đã gate sẵn bởi `useTierGatedFeatures().allows("alert_drawing")`. */
+    enabled: boolean;
+    drawings: readonly DrawingObject[];
+    plotData: readonly {
+        close?: number | null;
+    }[];
+    updateDrawing: (id: string, patch: Partial<DrawingObject>) => void;
+    muted?: boolean;
+}
+export declare function DrawingAlertsHost({ enabled, drawings, plotData, updateDrawing, muted, }: DrawingAlertsHostProps): import("react").JSX.Element | null;

package/dist/dts/widget/alerts/useDrawingAlerts.d.ts

@@ -0,0 +1,37 @@
+import { type DrawingAlertToastItem } from "@vninvestcharts/engine-react";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+/**
+ * W1.1 — nối alert engine (đã có sẵn trong engine, trước đây không ai render).
+ *
+ * Vì sao đây là việc quan trọng nhất của Wave 1: alert là tính năng người dùng
+ * retail đánh giá cao nhất, engine đã có **đủ** logic (`evaluateDrawingAlerts`,
+ * `useDrawingAlertEvaluator`, `AlertNotificationToast`) nhưng chưa module nào
+ * gọi tới. Ở đây chỉ là nối dây.
+ *
+ * Ràng buộc đã xử lý trước khi nối:
+ *  - `resolveReferencePriceForAlert` từng nội suy bằng `nowMs` (epoch ms) trên
+ *    trục `point.x` là PIXEL ⇒ ra giá vô nghĩa cho đường chéo. Đã sửa ở engine
+ *    (dùng `yPrice` + `timeMsHint`; thiếu mốc thời gian th�� trả null = không
+ *    bắn) và khoá bằng test. Không sửa thì nối vào sẽ bắn sai giá.
+ *  - Alert chỉ chạy trong tab ⇒ badge "chỉ hoạt động khi tab mở" (EP-2 chưa có).
+ *
+ * Gate: capability `alert_drawing` (pro). Community không được bắn alert.
+ */
+export interface UseDrawingAlertsOptions {
+    enabled: boolean;
+    drawings: readonly DrawingObject[];
+    plotData: readonly {
+        close?: number | null;
+    }[];
+    updateDrawing: (id: string, patch: Partial<DrawingObject>) => void;
+    /** Người dùng bật/tắt nhóm alert (UI). Mặc định bật. */
+    muted?: boolean;
+}
+export interface UseDrawingAlertsResult {
+    items: DrawingAlertToastItem[];
+    dismiss: (id: string) => void;
+    clear: () => void;
+    /** Có đang hiện cảnh báo "local only" không. */
+    isLocalOnly: boolean;
+}
+export declare function useDrawingAlerts({ enabled, drawings, plotData, updateDrawing, muted, }: UseDrawingAlertsOptions): UseDrawingAlertsResult;

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

@@ -0,0 +1,35 @@
+/**
+ * Canary bar filtering logic for progressive rollout.
+ * Implements percentage-based visibility of most recent bars.
+ */
+import type { OHLCVBar } from "../lib/types/ohlcv";
+import type { CanaryLevel } from "./CanaryRolloutConfig";
+/**
+ * Apply canary filter to visible bars.
+ * When canaryLevel < 100, returns only the most recent N% of bars.
+ * Maintains temporal order and data integrity.
+ *
+ * @param bars All visible bars from data source
+ * @param canaryLevel Canary percentage (10, 30, or 100)
+ * @returns Filtered bars (subset when canaryLevel < 100)
+ *
+ * @example
+ * const allBars = [bar1, bar2, ..., bar1000];
+ * const canary10 = applyCanaryFilter(allBars, 10);
+ * // => last ~100 bars (10% of 1000)
+ *
+ * const canary100 = applyCanaryFilter(allBars, 100);
+ * // => all bars unchanged
+ */
+export declare function applyCanaryFilter(bars: readonly OHLCVBar[], canaryLevel: CanaryLevel): readonly OHLCVBar[];
+/**
+ * Calculate canary slice statistics (for debugging/logging).
+ * @param totalBars Total bars available
+ * @param canaryLevel Canary percentage
+ * @returns Slice information
+ */
+export declare function getCanarySliceInfo(totalBars: number, canaryLevel: CanaryLevel): {
+    keepCount: number;
+    percentage: number;
+    description: string;
+};

package/dist/dts/widget/capabilities/CapabilityResolver.d.ts

@@ -0,0 +1,71 @@
+import { hasCapability, minTierFor, type Capability, type PatTier } from "@vninvestcharts/engine-core";
+/**
+ * CapabilityResolver — nơi DUY NHẤT quyết định tính năng nào được bật.
+ *
+ * Trước W0.4 có 5 nơi hardcode ngưỡng `"pro"` rải rác. Nay:
+ *   tier (PAT / license offline) ─┐
+ *   backend probe ─────────────────┼─▶ ResolvedCapabilities ─┬─▶ UI gate
+ *   device caps ────────────────────┘                        ├─▶ Engine gate
+ *                                                           └─▶ Upsell CTA
+ *
+ * Ba trạng thái phân biệt rõ (PLAN_FRONTEND_PROPLUS_TRACKA §4.1):
+ *   granted   — đủ quyền VÀ dữ liệu khả dụng ⇒ render thật
+ *   degraded  — đủ quyền nhưng backend chưa sẵn sàng / thiết bị yếu / hết quota
+ *               ⇒ `UnavailableState` (trung thực, KHÔNG upsell)
+ *   locked    — chưa đủ quyền ⇒ `LockedFeature` (upsell)
+ *
+ * Nguyên tắc: **KHÔNG** giả lập dữ liệu (AGENTS.md Rule 15). `degraded` không
+ * bao giờ biến thành dữ liệu 0/skeleton.
+ */
+export type DegradeReason = "backend_missing" | "device_limited" | "perf_budget" | "quota_local" | "data_unavailable";
+export type ResolvedState = {
+    state: "granted";
+} | {
+    state: "degraded";
+    reason: DegradeReason;
+} | {
+    state: "locked";
+    requires: PatTier;
+};
+/** Kết quả probe backend. `null` = chưa biết (probe chưa chạy / lỗi mạng). */
+export interface BackendAvailability {
+    /** Endpoint health có sống không. */
+    healthOk: boolean;
+    /** Có dữ liệu whale-feed (fallback khi whale-campaigns chưa mount). */
+    whaleFeedOk: boolean;
+    /** Đã probe xong chưa (phân biệt "chưa biết" với "biết là không có"). */
+    probed: boolean;
+    probedAt: number;
+}
+export declare const UNKNOWN_AVAILABILITY: BackendAvailability;
+export interface DeviceCaps {
+    /** Mobile / màn hình hẹp ⇒ tắt footprint, auto pattern, deep backtest. */
+    narrow: boolean;
+    /** Số core logic — dùng để quyết định có bật tác vụ nặng. */
+    concurrency: number;
+}
+export declare const UNKNOWN_DEVICE: DeviceCaps;
+export interface ResolverInput {
+    tier: PatTier | null | undefined;
+    backend?: BackendAvailability;
+    device?: DeviceCaps;
+    /** Ghi đè thủ công (ví dụ user đã đọc cảnh báo, hoặc quota đã đo được). */
+    forcedReason?: Partial<Record<Capability, DegradeReason>>;
+    /**
+     * Allowlist do license ký số thu hẹp (payload `caps`). `undefined` = không giới
+     * hạn. CHỈ được thu hẹp, không bao giờ nâng: kết quả luôn là tập con của
+     * `capabilitiesFor(tier)`. Cùng ngữ nghĩa với `TierGateOptions.narrowing` — giữ hai
+     * hệ gate cùng một quy tắc, thay vì một thu hẹp còn một thì không.
+     */
+    narrowing?: readonly Capability[];
+}
+export type ResolvedCapabilities = Readonly<Record<Capability, ResolvedState>>;
+export declare function resolveCapabilities(input: ResolverInput): ResolvedCapabilities;
+/** Tiện ích: capability có dùng được (granted) không. */
+export declare function isUsable(state: ResolvedState | undefined): boolean;
+/** Tiện ích: có cần hiện upsell không (chỉ `locked`). */
+export declare function isLocked(state: ResolvedState | undefined): boolean;
+/** Tiện ích: có phải degraded do backend chưa sẵn sàng không. */
+export declare function isBackendMissing(state: ResolvedState | undefined): boolean;
+export { hasCapability, minTierFor };
+export type { Capability, PatTier };

package/dist/dts/widget/capabilities/capabilityProbe.d.ts

@@ -0,0 +1,28 @@
+import { type BackendAvailability, type DeviceCaps } from "./CapabilityResolver";
+export interface ProbeOptions {
+    /** Base URL backend, ví dụ `http://localhost:8080`. `null` = chưa cấu hình. */
+    baseUrl: string | null | undefined;
+    /** Bearer PAT (nếu có). Không bắt buộc cho health. */
+    token?: string | null;
+    /** Mã dùng cho sentinel quote. */
+    probeSymbol?: string;
+    /** Timeout mỗi request (ms). */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+export interface ProbeResult extends BackendAvailability {
+    /** Lý do cụ thể, để log/diagnostics — không hiển thị cho user. */
+    detail?: string;
+}
+/**
+ * Probe backend. Trả về cache nếu còn hạn.
+ * - `healthOk=false` + `probed=true` ⇒ backend chắc chắn không sống.
+ * - `probed=false` ⇒ **chưa biết** (chưa probe, không có baseUrl, hoặc lỗi mạng) —
+ *   Track A phải vẫn chạy được (client-side).
+ */
+export declare function probeBackend(options: ProbeOptions): Promise<ProbeResult>;
+/** Xoá cache — dùng trong test và khi người dùng đổi PAT. */
+export declare function resetProbeCache(): void;
+/** Phát hiện giới hạn thiết bị. Không bao giờ đoán quá mức (thiếu ⇒ coi như desktop). */
+export declare function detectDeviceCaps(): DeviceCaps;

package/dist/dts/widget/capabilities/useTierGatedFeatures.d.ts

@@ -0,0 +1,48 @@
+import { type Capability, type PatTier } from "@vninvestcharts/engine-core";
+/**
+ * useTierGatedFeatures — W0.5: ép thực thi capability gate cho các cờ
+ * "có trong context nhưng KHÔNG ai gate" (audit F5/F11/F12/F13).
+ *
+ * Vấn đề gốc: `SaaSFeatureFlags` có `isReplayEnabled` nhưng `useReplayState`
+ * không hề hỏi ⇒ replay miễn phí. Tương tự `paperVisibility`, `PineEditorPanel`,
+ * `StrategyTesterPanel` đều không gate tier.
+ *
+ * Nguyên tắc: capability là **điều kiện cần**, cờ SaaS là **điều kiện đủ** (vẫn
+ * phải tôn trọng tenant tắt tính năng). ⇒ `granted = hasCapability(tier, cap) && flag`.
+ * Không dùng `||` — đó là lỗi kinh điển làm lộ Pro.
+ */
+export interface TierGatedFeatures {
+    /** Replay: cần `replay` + cờ `isReplayEnabled`. */
+    canUseReplay: boolean;
+    /**
+     * Paper trading mức thấp (market/limit) — Community, luôn mở.
+     * S1: dùng ở `paperVisibility.filterOrderTypesByTier` để lọc loại lệnh.
+     */
+    canUsePaperMarketLimit: boolean;
+    /**
+     * Paper trading nâng cao (stop/trailing/plo + risk) — cần `paper_advanced`.
+     * S1: nguồn sự thật duy nhất cho gate lệnh nâng cao (thay `toSeriesTier(tier)`).
+     */
+    canUsePaperAdvanced: boolean;
+    /** Trình soạn thảo Pine. */
+    canUsePineEditor: boolean;
+    /** Bộ kiểm thử chiến lược. */
+    canUseStrategyTester: boolean;
+    /**
+     * `allows` là API dùng thật. Trước S1 có thêm `canUseAdvisory` / `canUseWhalePanel`
+     * — **không consumer nào** (grep toàn repo: chỉ 2 hit, đều là chính dòng định
+     * nghĩa). Xoá vì hàm chết ở đây là bẫy cho người sau: tưởng đã gate.
+     * Cần thì gọi `allows("pro_plugin")` kèm cờ SaaS, đúng như `canUseReplay` làm.
+     */
+    allows: (capability: Capability) => boolean;
+}
+export interface TierGateOptions {
+    /**
+     * W0.6 — allowlist do license ký số thu hẹp (payload `caps`).
+     * `undefined` = không giới hạn (mọi license cũ). Danh sách này **chỉ được
+     * thu hẹp**, không bao giờ nâng: kết quả luôn là tập con của `MIN_TIER(tier)`.
+     * Nhờ vậy khách offline gate được Track A mà không cần gọi backend.
+     */
+    narrowing?: readonly Capability[];
+}
+export declare function useTierGatedFeatures(tier: PatTier | null | undefined, options?: TierGateOptions): TierGatedFeatures;

package/dist/dts/widget/components/BottomPanelHost.d.ts

@@ -0,0 +1,80 @@
+import type { SeriesConfig } from "../../lib/core";
+import type { BottomPanelHeightApi } from "../hooks/useBottomPanelHeight";
+export type BottomTab = "strategy_tester" | "pine_editor" | "paper_trade" | null;
+export interface BottomPanelHostProps {
+    /** Currently active tab */
+    activeTab: BottomTab;
+    /** Callback when tab changes */
+    onTabChange: (tab: BottomTab) => void;
+    /** Plot data for strategy tester */
+    plotData: any[];
+    /** Active symbol */
+    symbol: string;
+    /** Active timeframe */
+    timeframe: string;
+    /** Active indicator configs */
+    activeIndicators: any[];
+    /** Dark mode */
+    isDark: boolean;
+    /** Callback to add indicator from Pine Editor to active chart */
+    onAddIndicator?: (config: SeriesConfig) => void;
+    /**
+     * Tier grants for the two paid tabs. FAIL-CLOSED: absent means NOT granted.
+     *
+     * This host is rendered by `VNInvestMultiCharts`, which sits ABOVE the per-chart
+     * `CapabilityProvider`, so reading capability state from context here would resolve
+     * `tier=null` and lock the tabs for paying customers too. The host therefore
+     * resolves `hasCapability(patTier, …)` from its own tier (same idiom as its
+     * `export_png` gate) and passes the booleans in.
+     *
+     * The default is deliberately locked: a future call site that forgets to pass a
+     * grant gets the upsell badge instead of the feature.
+     */
+    canUsePineEditor?: boolean;
+    canUseStrategyTester?: boolean;
+    /** OHLCV bars for PineScript compilation */
+    bars?: {
+        open: number[];
+        high: number[];
+        low: number[];
+        close: number[];
+        volume: number[];
+    };
+    /** Custom render for paper trade panel */
+    renderPaperTradePanel?: (props: {
+        positions: any[];
+        journal: any[];
+        onReset: () => void;
+        onClose: () => void;
+    }) => React.ReactNode;
+    /** Dữ liệu thật từ workspace singleton (H3) — truyền xuống renderPaperTradePanel thay vì hardcode rỗng. */
+    paperTradeData?: {
+        positions: any[];
+        journal: any[];
+        onReset: () => void;
+        onClose: () => void;
+    };
+    /** Show advisory panel */
+    showAdvisoryPanel?: boolean;
+    /** Advisory result */
+    advisoryResult?: any;
+    /** Native advisory session (V2) — renders instead of advisoryResult when provided */
+    advisorySession?: import("../../lib/types/vninvest").AdvisorySessionV2 | null;
+    /** Advisory loading */
+    isAdvisoryLoading?: boolean;
+    /** On advisory refresh */
+    onAdvisoryRefresh?: () => void;
+    /** Show tape panel */
+    showTapePanel?: boolean;
+    /** Tape entries */
+    tapeEntries?: any[];
+    /** Tape loading */
+    isTapeLoading?: boolean;
+    /** Tape filter billions */
+    tapeFilterBillions?: number;
+    /** On tape filter change */
+    onTapeFilterChange?: (value: number) => void;
+    /** Resizable height API (useBottomPanelHeight); omit for fixed var height */
+    panelHeight?: BottomPanelHeightApi;
+}
+export declare function BottomPanelHost({ activeTab, onTabChange, plotData, symbol, timeframe, activeIndicators, isDark, onAddIndicator, renderPaperTradePanel, showAdvisoryPanel, advisoryResult, advisorySession, isAdvisoryLoading, onAdvisoryRefresh, showTapePanel, tapeEntries, isTapeLoading, tapeFilterBillions, onTapeFilterChange, bars, paperTradeData, panelHeight, canUsePineEditor, canUseStrategyTester, }: BottomPanelHostProps): import("react").JSX.Element | null;

package/dist/dts/widget/components/BottomPanelSplitter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * BottomPanelSplitter — drag handle on the panel top edge (TradingView-style).
+ *
+ * Grid-splitter parity for drag speed: absolute-from-origin delta against a
+ * start-height snapshot (immune to browser pointermove coalescing, which made
+ * the old incremental deltas lose distance), direct DOM preview on the panel
+ * container during the move (zero React renders, zero storage I/O), and a
+ * single `resizeTo` commit on pointer-up (one render + one persist).
+ * Pointer capture (grid pattern), double-click reset, ArrowUp/Down nudge.
+ * Pure passthrough over BottomPanelHeightApi (hook owns state + persistence).
+ */
+import type { BottomPanelHeightApi } from "../hooks/useBottomPanelHeight";
+export declare function BottomPanelSplitter({ api }: {
+    api: BottomPanelHeightApi;
+}): import("react").JSX.Element;

package/dist/dts/widget/components/CapabilityGate.d.ts

@@ -0,0 +1,65 @@
+import { type ReactNode } from "react";
+import { type Capability, type PatTier } from "@vninvestcharts/engine-core";
+import { type BackendAvailability, type DegradeReason, type DeviceCaps, type ResolvedCapabilities, type ResolvedState } from "../capabilities/CapabilityResolver";
+/**
+ * CapabilityGate — cổng UI cho 3 trạng thái (W0.4).
+ *
+ *   granted   ⇒ render `children` thật
+ *   locked    ⇒ `LockedFeature` (upsell, có tên + lợi ích từ i18n)
+ *   degraded  ⇒ `UnavailableState` (trung thực, KHÔNG upsell, KHÔNG giả dữ liệu)
+ *
+ * Dùng:
+ *   <CapabilityGate capability="indicator_full">{…}</CapabilityGate>
+ * hoặc kiểm tra thủ công:
+ *   const caps = useResolvedCapabilities();
+ *   if (!isUsable(caps.indicator_full)) …
+ */
+export interface CapabilityContextValue {
+    tier: PatTier | null;
+    backend: BackendAvailability;
+    device: DeviceCaps;
+    caps: ResolvedCapabilities;
+    /** Nguồn quyết định tier, để hiển thị/báo cáo (không dùng để cấp quyền). */
+    tierSource: "license" | "pat" | "none";
+}
+export interface CapabilityProviderProps {
+    tier: PatTier | null | undefined;
+    tierSource?: CapabilityContextValue["tierSource"];
+    backend?: BackendAvailability;
+    device?: DeviceCaps;
+    forcedReason?: Partial<Record<Capability, DegradeReason>>;
+    /** Allowlist license thu hẹp (payload `caps`). Chỉ thu hẹp, không bao giờ nâng. */
+    narrowing?: readonly Capability[];
+    children: ReactNode;
+}
+export declare function CapabilityProvider({ tier, tierSource, backend, device, forcedReason, narrowing, children, }: CapabilityProviderProps): import("react").JSX.Element;
+export declare function useResolvedCapabilities(): CapabilityContextValue;
+/** Hook gate rút gọn: `const can = useCapabilityGate("export_png")`. */
+export declare function useCapabilityGate(capability: Capability): ResolvedState;
+/** `true` khi capability dùng được (granted). */
+export declare function useHasCapability(capability: Capability): boolean;
+/** Tương đương `hasCapability` nhưng đọc tier từ context. */
+export declare function useTierAllows(capability: Capability): boolean;
+declare const REASON_KEY: Readonly<Record<DegradeReason, string>>;
+/** Tên hiển thị của gói cần để mở capability (dùng trong upsell). */
+declare function planLabelKey(tier: PatTier): string;
+export interface LockedFeatureProps {
+    capability: Capability;
+    /** Nội dung thật, chỉ render khi granted. */
+    children: ReactNode;
+    /** Hiển thị nút khoá thay vì render (cho toolbar item). */
+    asLockBadge?: boolean;
+    onLockedClick?: () => void;
+}
+export declare function CapabilityGate({ capability, children }: Omit<LockedFeatureProps, "asLockBadge" | "onLockedClick">): import("react").JSX.Element;
+export declare function LockedFeature({ capability, requiredTier, onLockedClick, }: {
+    capability: Capability;
+    requiredTier: PatTier;
+    onLockedClick?: () => void;
+}): import("react").JSX.Element;
+export declare function UnavailableState({ reason, capability, compact, }: {
+    reason: DegradeReason;
+    capability?: Capability;
+    compact?: boolean;
+}): import("react").JSX.Element;
+export { REASON_KEY, planLabelKey };

package/dist/dts/widget/components/ChartDiagOverlay.d.ts

@@ -0,0 +1,31 @@
+export interface ChartDiagSnapshot {
+    enginePresent: boolean;
+    forkEngineSet: boolean;
+    isForkRuntime: boolean;
+    bars: number;
+    enriched: number;
+    plot: number;
+    panes: string;
+    chartType: string;
+    tier: string;
+    dataError: string;
+    engineRange: string;
+    canvases: string;
+    /** Engine-side scale domains per pane (NaN/garbage domain = render killer). */
+    domains: string;
+    /** Engine paneSpecs ids (empty = specs feed never fired = root cause). */
+    specs: string;
+    /** Non-finite OHLC scan over engine enrichedData (count + first bad index). */
+    nanScan: string;
+    /** Last bar close + date ISO (stale-data check). */
+    lastBar: string;
+}
+export declare function isDiagEnabled(): boolean;
+/**
+ * BLACKSCREEN-DIAG: query-gated runtime readout (?vnsc_diag=1 or localStorage).
+ * Zero production impact: renders nothing unless the flag is set. Used to
+ * capture exact engine/data/pane state from a black-screen browser.
+ */
+export declare function ChartDiagOverlay({ getSnapshot }: {
+    getSnapshot: () => ChartDiagSnapshot;
+}): import("react").JSX.Element | null;

package/dist/dts/widget/components/ConfirmDialog.d.ts

@@ -0,0 +1,12 @@
+export interface ConfirmDialogProps {
+    open: boolean;
+    title?: string;
+    message: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    variant?: "danger" | "default";
+    onConfirm: () => void;
+    onCancel: () => void;
+    portalRoot?: HTMLElement | null;
+}
+export declare function ConfirmDialog({ open, title, message, confirmLabel, cancelLabel, variant, onConfirm, onCancel, portalRoot, }: ConfirmDialogProps): import("react").ReactPortal | null;

package/dist/dts/widget/components/DowngradeBanner.d.ts

@@ -0,0 +1,9 @@
+export interface DowngradeBannerProps {
+    open: boolean;
+    upgradeUrl?: string;
+    onDismiss: () => void;
+    onUpgrade: () => void;
+}
+export declare function DowngradeBanner({ open, upgradeUrl, onDismiss, onUpgrade, portalRoot: portalRootProp }: DowngradeBannerProps & {
+    portalRoot?: HTMLElement | null;
+}): import("react").ReactPortal | null;

package/dist/dts/widget/components/ForkPaneSeparators.d.ts

@@ -0,0 +1,11 @@
+import { type WidgetPaneRuntimeSnapshot } from "../utils/widgetHelpers";
+export interface ForkPaneSeparatorsProps {
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    /** Pane whose bottom edge meets the X-axis strip (no separator there). */
+    lastPaneId?: string;
+}
+/**
+ * UI-C: 1px TradingView-style separators between stacked subpanes.
+ * Widget-only (reads engine paneSnapshots, draws DOM lines, no engine change).
+ */
+export declare function ForkPaneSeparators({ paneSnapshots, lastPaneId, }: ForkPaneSeparatorsProps): import("react").JSX.Element | null;

package/dist/dts/widget/components/ForkPaneTooltips.d.ts

@@ -0,0 +1,23 @@
+import { type EnrichedDatum } from "../../lib/core/calculators/types";
+import { type WidgetPaneRuntimeSnapshot } from "../utils/widgetHelpers";
+import { type PaneDescriptor } from "../../lib/core";
+export interface ForkPaneTooltipsProps {
+    hoveredDatum?: EnrichedDatum | null;
+    lastDatum?: EnrichedDatum | null;
+    symbol?: string;
+    timeframe?: string;
+    isDark: boolean;
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    panes: readonly PaneDescriptor[];
+    onSettingsClick?: () => void;
+    onToggleSeriesVisibility?: (seriesId: string) => void;
+    onRemoveIndicator?: (paneId: string, seriesId: string) => void;
+    /** DECLUTTER_V4: compare legend node rendered below the OHLC row (single-chart). */
+    renderCompareLegend?: (paneId: string) => React.ReactNode;
+    /**
+     * SINGLE-OHLC: hide the statusline symbol+OHLC row (the widget header
+     * already shows it). Compare chips move up just under the chart header.
+     */
+    hideStatusOhlc?: boolean;
+}
+export declare function ForkPaneTooltips({ hoveredDatum, lastDatum, symbol, timeframe, isDark, paneSnapshots, panes, onSettingsClick, onToggleSeriesVisibility, onRemoveIndicator, renderCompareLegend, hideStatusOhlc, }: ForkPaneTooltipsProps): (import("react").JSX.Element | null)[];

package/dist/dts/widget/components/ForkXAxisOverlay.d.ts

@@ -0,0 +1,11 @@
+import { type ForkXAxisTick, type ForkXAxisHoverLabel } from "../utils/widgetHelpers";
+export interface ForkXAxisOverlayProps {
+    ticks: readonly ForkXAxisTick[];
+    hoverLabel?: ForkXAxisHoverLabel;
+    top: number;
+    isDark: boolean;
+    showHoverLabel?: boolean;
+    /** Container width for edge clamping (grid cells are narrower than window). */
+    width?: number;
+}
+export declare function ForkXAxisOverlay({ ticks, hoverLabel, top, isDark, showHoverLabel, width, }: ForkXAxisOverlayProps): import("react").JSX.Element | null;

package/dist/dts/widget/components/ForkYAxisCrosshairLabels.d.ts

@@ -0,0 +1,9 @@
+import { type EngineOverlayState } from "@vninvestcharts/engine-core";
+import { type WidgetPaneRuntimeSnapshot } from "../utils/widgetHelpers";
+export interface ForkYAxisCrosshairLabelsProps {
+    overlayState: EngineOverlayState | null;
+    isDark: boolean;
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    labelColorByPane?: ReadonlyMap<string, string>;
+}
+export declare function ForkYAxisCrosshairLabels({ overlayState, isDark, paneSnapshots, labelColorByPane, }: ForkYAxisCrosshairLabelsProps): import("react").JSX.Element | null;

package/dist/dts/widget/components/LayoutDesigner.d.ts

@@ -0,0 +1,26 @@
+import React from "react";
+import { GridLayout, LayoutPreset } from "../grid/types";
+interface LayoutDesignerProps {
+    layout: GridLayout;
+    onLayoutChange: (layout: GridLayout) => void;
+    /**
+     * P0: trả `false` nếu **chưa lưu được** (storage lỗi/hết quota). `undefined` = không
+     * có handler ⇒ cũng là thất bại. Trước P0 kiểu trả `void` khiến modal đóng dù chưa
+     * lưu gì — dữ liệu người dùng bị nuốt trong im lặng (Rule 15).
+     */
+    onSaveAsPreset?: (preset: LayoutPreset) => boolean | void;
+    /**
+     * P0: danh sách preset đã lưu. Trước đây prop này chỉ tồn tại trong type + default
+     * (`:19`, `:28`) mà **không được render** ⇒ preset lưu được rồi không ai thấy, không
+     * apply, không xoá được. Có `availablePresets` thì phải render.
+     */
+    availablePresets?: LayoutPreset[];
+    /** Áp dụng preset đã lưu (thay layout hiện tại). */
+    onApplyPreset?: (preset: LayoutPreset) => void;
+    /** Xoá preset đã lưu. `undefined` ⇒ không hiện nút xoá. */
+    onDeletePreset?: (preset: LayoutPreset) => void;
+    isOpen: boolean;
+    onClose: () => void;
+}
+export declare const LayoutDesigner: React.FC<LayoutDesignerProps>;
+export default LayoutDesigner;

package/dist/dts/widget/components/PremiumFeatureGate.d.ts

@@ -0,0 +1,10 @@
+import { SaaSFeatureFlags } from '../types/saas';
+import type { ReactNode } from 'react';
+export interface PremiumFeatureGateProps {
+    feature: keyof SaaSFeatureFlags;
+    children: ReactNode;
+    fallback?: ReactNode;
+    upgradeUrl?: string;
+    mode?: 'blur' | 'unmount';
+}
+export declare function PremiumFeatureGate({ feature, children, fallback, upgradeUrl, mode, }: PremiumFeatureGateProps): import("react").JSX.Element;

package/dist/dts/widget/components/ShortcutHelpModal.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Core rows — **DỰA TRÊN NƠI BINDING THẬT**, không phải bản ghi tay.
+ *
+ * Trước 2026-09-30 đây là mảng literal 6 dòng, trong khi docblock dưới nói
+ * "rows are built from the shortcut SSOT so they can never drift" — **không đúng** với
+ * chính 6 dòng đó. Tệ hơn: modal **thiếu** 7 phím đang chạy thật.
+ *
+ * Mỗi dòng khai báo `key` + nơi bind thật, để drift lộ ra khi ai đó đổi binding mà quên
+ * cập nhật modal. `ShortcutManager.collision.test.ts` kiểm phần còn lại (trùng phím).
+ */
+export declare const CORE_ROWS: Array<{
+    keys: string;
+    label: string;
+    binding: string;
+}>;
+/**
+ * BL-16 + BL-21: discoverability for the window-global keyboard UX. Opens on `?`
+ * (Shift+/).
+ *
+ * Tool rows derive from `ALT_TOOL_SHORTCUTS` / `TOOL_SHORTCUT_KEYS` (SSOT, xem phần render
+ * bên dưới). Core rows thì **không** suy ra được từ một danh sách duy nhất — chúng thuộc
+ * nhiều module (`useWidgetDrawings`, `ShortcutManager`, `useTradingHotkeys`, `OHLCHeader`,
+ * `GridContainer`) — nên `CORE_ROWS` khai **kèm `binding` là nơi bind thật**, để khi ai đó
+ * đổi binding mà quên sửa modal thì đó là việc phải sửa tường minh chứ không phải drift
+ * âm thầm. (Trước 2026-09-30 đây là literal 6 dòng, thiếu 7 phím đang chạy, còn docblock
+ * lại khẳng định "derived from SSOT".)
+ *
+ * `CORE_ROWS` export ra để test kiểm **từng dòng có thực sự render** — thay vì đếm tổng
+ * số dòng cứng (xem `ShortcutHelpModal.test.tsx` HELP-COMPACT).
+ *
+ * UI-AUDIT: the first-run hint renders INLINE (no absolute floating) —
+ * mount this component inside the footer right cluster. The modal overlay
+ * itself stays absolutely anchored to .vnsc-root.
+ */
+export declare function ShortcutHelpModal({ hintInline, showHint, }: {
+    hintInline?: boolean;
+    /**
+     * UI-AUDIT / multicharts: hint **mặc định ẩn**. Trước đây mọi ô chart đều render một
+     * chip "? Phím tắt", nên 4 ô là 4 chip lặp lại — rất vô duyên và ăn chiều cao footer.
+     * Modal vẫn mở bằng phím `?` ở bất kỳ đâu, và một modal duy nhất cho cả grid (đã khoá
+     * bằng `openDialogCount`), nên ẩn hint **không** làm mất khả năng tiếp cận.
+     */
+    showHint?: boolean;
+}): import("react").JSX.Element | null;