@vninvestcharts/widget 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,95 @@
+/**
+ * Canary rollback safety validation and emergency response helpers.
+ * Enables operators to safely revert canary levels with confidence via metrics.
+ *
+ * @example
+ * const validation = validateRollbackSafety(beforeMetrics, afterMetrics);
+ * if (!validation.safe) {
+ *   // Log incident, alert operator
+ *   console.warn("[Rollback UNSAFE]", validation.reason);
+ * }
+ */
+export interface RollbackSnapshot {
+    /** Canary level at snapshot time (10, 30, or 100) */
+    level: 10 | 30 | 100;
+    /** Number of visible bars at snapshot time */
+    barCount: number;
+    /** Feature flags state at snapshot time */
+    workersActive: {
+        externalBarsWorker: boolean;
+        lodWorker: boolean;
+    };
+    /** Unix timestamp when snapshot was captured (ms) */
+    timestamp: number;
+}
+export interface RollbackValidation {
+    /** True if rollback appears safe, false otherwise */
+    safe: boolean;
+    /** Human-readable reason for safety assessment */
+    reason: string;
+    /** Absolute bar count difference (after - before) */
+    barCountDifference: number;
+    /** True if potential data loss detected (unexpected bar reduction) */
+    potentialDataLoss: boolean;
+    /** Suggested next action ("MONITOR" | "INVESTIGATE" | "DISABLE_WORKER") */
+    suggestedAction: "MONITOR" | "INVESTIGATE" | "DISABLE_WORKER";
+}
+export interface RollbackEvent {
+    /** Previous canary level before rollback */
+    previousLevel: 10 | 30 | 100;
+    /** New canary level after rollback */
+    newLevel: 10 | 30 | 100;
+    /** Metrics snapshot before rollback */
+    beforeMetrics: RollbackSnapshot;
+    /** Metrics snapshot after rollback */
+    afterMetrics: RollbackSnapshot;
+    /** Safety validation result */
+    validation: RollbackValidation;
+    /** Incident severity: CRITICAL (immediate danger), HIGH (degradation), INFO (normal) */
+    severity: "CRITICAL" | "HIGH" | "INFO";
+    /** Unix timestamp of rollback event (ms) */
+    timestamp: number;
+}
+export interface EmergencyRollbackRecommendation {
+    /** Recommended target canary level to revert to */
+    targetLevel: 10 | 30 | 100;
+    /** Incident severity classification */
+    severity: "CRITICAL" | "HIGH";
+    /** Recommended action for operator */
+    recommendation: string;
+}
+/**
+ * Validate that a rollback was safe and didn't lose data.
+ * Compares bar counts and worker state before/after.
+ *
+ * @param before Metrics snapshot before rollback
+ * @param after Metrics snapshot after rollback
+ * @returns Validation result with safety assessment and suggested action
+ *
+ * @example
+ * const validation = validateRollbackSafety(before, after);
+ * if (!validation.safe) {
+ *   logger.error("[Rollback UNSAFE]", validation.reason);
+ *   // Consider disabling problematic worker
+ * }
+ */
+export declare function validateRollbackSafety(before: RollbackSnapshot, after: RollbackSnapshot): RollbackValidation;
+/**
+ * Generate emergency rollback recommendation based on current canary level.
+ * Used when operator manually triggers rollback due to incident.
+ *
+ * @param currentLevel Current active canary level (10, 30, or 100)
+ * @returns Recommendation with target level and severity
+ *
+ * @example
+ * const rec = createEmergencyRollbackTrigger(100);
+ * // For 100%: recommends immediate rollback to 30% (CRITICAL severity)
+ * // For 30%: recommends wait-and-monitor (no automatic rollback)
+ */
+export declare function createEmergencyRollbackTrigger(currentLevel: 10 | 30 | 100): EmergencyRollbackRecommendation;
+/**
+ * Format rollback event for console logging or telemetry.
+ * @param event Rollback event to format
+ * @returns Human-readable string
+ */
+export declare function formatRollbackEvent(event: RollbackEvent): string;

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

@@ -0,0 +1,100 @@
+/**
+ * Canary rollout configuration and resolver for progressive feature rollout.
+ * Supports props and URL parameters with prop precedence.
+ *
+ * @example
+ * // Via props
+ * <VNInvestCharts {...props} canaryLevel={10} />
+ *
+ * // Via URL params
+ * // ?canaryLevel=10 or ?canaryLevel=30 or ?canaryLevel=100
+ */
+export type CanaryLevel = 10 | 30 | 100;
+export interface CanaryRolloutConfig {
+    /**
+     * Canary level percentage: 10%, 30%, or 100% (full).
+     * Determines what percentage of visible bars to display during rollout.
+     * @default 100 (no canary, full rollout)
+     */
+    canaryLevel?: CanaryLevel;
+}
+export interface CanaryMetrics {
+    /** Total visible bars in dataset */
+    visibleBarsTotal: number;
+    /** Visible bars after canary filter applied */
+    visibleBarsAfterFilter: number;
+    /** Canary percentage active (10, 30, or 100) */
+    canaryPercentage: CanaryLevel;
+    /** Feature flags status */
+    workersActive: {
+        externalBarsWorker: boolean;
+        lodWorker: boolean;
+    };
+    /** Frame time p95 (ms), undefined if not measured */
+    p95FrameTimeMs?: number;
+    /** Request count since canary level change */
+    requestCount?: number;
+    /** Timestamp when canary level was applied (ms since epoch) */
+    timestamp: number;
+}
+export interface CanaryGateDecision {
+    /** Previous canary level */
+    previousLevel: CanaryLevel;
+    /** Current canary level */
+    currentLevel: CanaryLevel;
+    /** Metrics at the time of decision */
+    metrics: CanaryMetrics;
+    /** Recommendation: "GO" to proceed to next level, "NO-GO" to hold or rollback */
+    recommendation: "GO" | "NO-GO";
+    /** Human-readable reason for recommendation */
+    reason: string;
+    /** Timestamp when decision was made (ms since epoch) */
+    timestamp: number;
+}
+export declare const DEFAULT_CANARY_LEVEL: CanaryLevel;
+/**
+ * Parse and validate canary level from value.
+ * @param value Candidate value (number, string, or null)
+ * @returns Valid CanaryLevel or DEFAULT_CANARY_LEVEL if invalid
+ */
+export declare function parseCanaryLevel(value: unknown): CanaryLevel;
+/**
+ * Resolve canary level from props and URL search parameters.
+ * Props override URL params (props take precedence).
+ *
+ * @param props Canary config from component props
+ * @param searchParams URL search parameters (e.g., from useLocation().search)
+ * @returns Resolved canary level
+ *
+ * @example
+ * // Props only
+ * resolveCanaryLevel({ canaryLevel: 30 }) // => 30
+ *
+ * // URL params only
+ * resolveCanaryLevel(undefined, new URLSearchParams("canaryLevel=10")) // => 10
+ *
+ * // Props override URL (props win)
+ * resolveCanaryLevel(
+ *   { canaryLevel: 30 },
+ *   new URLSearchParams("canaryLevel=10")
+ * ) // => 30
+ */
+export declare function resolveCanaryLevel(props?: CanaryRolloutConfig, searchParams?: URLSearchParams): CanaryLevel;
+/**
+ * Create a decision recommendation based on canary metrics.
+ * Currently: simple heuristic (NO-GO if p95 > 50ms, otherwise GO).
+ * In production, this would integrate with real SLO/alerting.
+ *
+ * @param metrics Current canary metrics
+ * @returns GO or NO-GO recommendation with reason
+ */
+export declare function makeCanaryGateRecommendation(metrics: CanaryMetrics): {
+    recommendation: "GO" | "NO-GO";
+    reason: string;
+};
+/**
+ * Format canary metrics for console logging or telemetry.
+ * @param metrics Metrics to format
+ * @returns Human-readable string
+ */
+export declare function formatCanaryMetrics(metrics: CanaryMetrics): string;

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

@@ -0,0 +1,20 @@
+import type { EngineOverlayDrawingPriceLabelsState, PaneRuntimeSnapshot } from "@vninvestcharts/engine-core";
+import { type MeasurementCoordinateBridge } from "@vninvestcharts/engine-drawing";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import type { ResolvedWidgetRuntime } from "./runtimePolicy";
+export interface DrawingPriceLabelsOverlayProps {
+    enabled: boolean;
+    highlighted?: boolean;
+    renderMode?: "engine" | "bridge";
+    runtime?: ResolvedWidgetRuntime;
+    priceFormat: (value: number) => string;
+    enginePriceLabels?: EngineOverlayDrawingPriceLabelsState | null;
+    drawing?: DrawingObject | null;
+    coordinateBridge?: MeasurementCoordinateBridge;
+    paneSnapshots?: readonly PaneRuntimeSnapshot[];
+    height: number;
+    width: number;
+}
+declare function DrawingPriceLabelsOverlay({ enabled, highlighted, renderMode, runtime, priceFormat, enginePriceLabels, drawing, coordinateBridge, paneSnapshots, height, width, }: DrawingPriceLabelsOverlayProps): import("react").JSX.Element | null;
+export default DrawingPriceLabelsOverlay;
+export { DrawingPriceLabelsOverlay };

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

@@ -0,0 +1,16 @@
+import { type EngineOverlayDrawingPrimitiveInput, type PaneRuntimeSnapshot, type VisibleRange as EngineVisibleRange } from "@vninvestcharts/engine-core";
+import type { EnrichedDatum } from "../lib/core/calculators/types";
+import type { ChartScales } from "@vninvestcharts/engine-drawing";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+export interface CreateForkDrawingPrimitiveInputsInput {
+    drawings: readonly DrawingObject[];
+    selectedDrawing?: DrawingObject | null;
+    selectedDrawingIds?: readonly string[];
+    paneSnapshots: readonly PaneRuntimeSnapshot[];
+    visibleRange: EngineVisibleRange | null;
+    plotData: readonly EnrichedDatum[];
+    isEditingText?: boolean;
+}
+export declare function resolveRenderableForkDrawings(drawings: readonly DrawingObject[], selectedDrawing?: DrawingObject | null): DrawingObject[];
+export declare function createForkDrawingScales(snapshot: PaneRuntimeSnapshot, scaleSlotId: string, visibleRange: EngineVisibleRange, plotData: readonly EnrichedDatum[]): ChartScales | null;
+export declare function createForkDrawingPrimitiveInputs({ drawings, selectedDrawing, selectedDrawingIds, paneSnapshots, visibleRange, plotData, isEditingText, }: CreateForkDrawingPrimitiveInputsInput): EngineOverlayDrawingPrimitiveInput[];

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

@@ -0,0 +1,24 @@
+import type { EngineOverlayMeasurementState, PaneRuntimeSnapshot } from "@vninvestcharts/engine-core";
+import { type MeasurementCoordinateBridge } from "@vninvestcharts/engine-drawing";
+export interface MeasurementOverlayLabels {
+    title: string;
+    bars: string;
+    price: string;
+}
+export interface MeasurementOverlayProps {
+    enabled: boolean;
+    isDark: boolean;
+    priceFormat: (value: number) => string;
+    labels: MeasurementOverlayLabels;
+    renderMode?: "engine" | "bridge";
+    engineMeasurementState?: EngineOverlayMeasurementState | null;
+    coordinateBridge?: MeasurementCoordinateBridge | null;
+    paneSnapshots?: readonly PaneRuntimeSnapshot[];
+    width?: number;
+    height?: number;
+    pixelRatio?: number;
+}
+declare function MeasurementOverlayWithI18n(props: Omit<MeasurementOverlayProps, "labels">): import("react").JSX.Element | null;
+declare const MeasurementOverlay: typeof MeasurementOverlayWithI18n;
+export { MeasurementOverlay };
+export default MeasurementOverlayWithI18n;

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

@@ -0,0 +1,5 @@
+export { type WidgetPaneRuntimeSnapshot, type WidgetRuntimeCapabilities, normalizePaneDescriptorsForExplicitScaleSlots } from "./utils/widgetHelpers";
+import type { WidgetAuthHandler, VNInvestChartsProps, VNInvestChartsContentProps } from "./VNInvestChartsProps";
+export type { WidgetAuthHandler, VNInvestChartsProps, VNInvestChartsContentProps };
+export type { VNInvestChartsRef } from "./utils/widgetHelpers";
+export declare const VNInvestCharts: import("react").ForwardRefExoticComponent<VNInvestChartsProps & import("react").RefAttributes<import("./types/fullChartHandle").FullChartHandle>>;

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

@@ -0,0 +1,302 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { CrosshairPayload, DrawingData, DrawingOperation, VisibleRangePayload, SymbolLinkGroupId, KeyboardAdapter, ClockAdapter, StorageAdapter, PortalAdapter, ChartRegistryAdapter, BroadcastChannelAdapter, WindowEventAdapter, NotificationAdapter, AudioAdapter, ResizeAdapter } from "@vninvestcharts/engine-react";
+import type { ChartTheme, PaneDescriptor, SeriesTypeId, VisibleRange } from "../lib/core";
+import type { DrawingDockTab, DrawingWorkspaceController } from "@vninvestcharts/engine-react";
+import type { DrawingStorageAdapter, DrawingAlertCondition } from "@vninvestcharts/engine-drawing";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import type { StockDataAdapter, Timeframe } from "../lib/types/adapter";
+import type { OHLCVBar } from "../lib/types/ohlcv";
+import type { WidgetPaneRuntimeSnapshot, WidgetRuntimeCapabilities, WidgetRuntimeResolutionReason, WidgetCoordinateBridge } from "./utils/widgetHelpers";
+import type { SaaSFeatureFlags } from "./types/saas";
+import type { WatchlistAdapter } from "./types/watchlist";
+import type { VNInvestClient } from "./adapters/VNInvestClient";
+import type { WidgetLocale, WidgetMessages } from "./i18n/types";
+import type { EnrichedDatum } from "../lib/core/calculators/types";
+import type { WidgetTimezone } from "../lib/utils/timezoneFormatter";
+import type { WhaleOrder, CVDPoint, DarkFlowSignalType, AdvisoryResult, TapeEntry } from "../lib/types/vninvest";
+import type { CorporateEvent } from "./components/events/CorporateEventsOverlay";
+import type { RequestedWidgetRuntime, ResolvedWidgetRuntime } from "./runtimePolicy";
+export interface WidgetAuthHandler {
+    getToken: () => string | Promise<string>;
+    getRefreshToken?: () => string | Promise<string>;
+    onTokensUpdated?: (tokens: {
+        patToken: string;
+        refreshToken?: string;
+    }) => void | Promise<void>;
+    onAuthError?: (error: Error) => void;
+}
+export interface VNInvestChartsProps {
+    id?: string;
+    adapter?: StockDataAdapter;
+    data?: readonly OHLCVBar[];
+    symbol?: string;
+    onSymbolChange?: (symbol: string) => void;
+    timeframe?: Timeframe;
+    range?: string;
+    onRangeChange?: (range: string) => void;
+    defaultPeriod?: string;
+    authHandler?: WidgetAuthHandler;
+    onTimeframeChange?: (tf: Timeframe) => void;
+    drawingUiEnabled?: boolean;
+    drawingActiveTool?: string;
+    drawings?: readonly DrawingObject[];
+    defaultDrawings?: readonly DrawingObject[];
+    drawingStorageKey?: string;
+    drawingStorageAdapter?: DrawingStorageAdapter;
+    defaultDrawingDockTab?: DrawingDockTab;
+    engineRuntime?: RequestedWidgetRuntime;
+    useWebGL?: boolean;
+    locale?: WidgetLocale;
+    messages?: Partial<WidgetMessages>;
+    theme?: ChartTheme;
+    timezone?: WidgetTimezone;
+    defaultTimezone?: WidgetTimezone;
+    resizeAdapter?: ResizeAdapter;
+    keyboardAdapter?: KeyboardAdapter;
+    clockAdapter?: ClockAdapter;
+    storageAdapter?: StorageAdapter;
+    portalAdapter?: PortalAdapter;
+    registryAdapter?: ChartRegistryAdapter;
+    broadcastChannelAdapter?: BroadcastChannelAdapter;
+    portalRoot?: HTMLElement | null;
+    shadowRoot?: ShadowRoot | null;
+    windowEventAdapter?: WindowEventAdapter;
+    notificationAdapter?: NotificationAdapter;
+    audioAdapter?: AudioAdapter;
+    pixelRatio?: number;
+    searchParams?: URLSearchParams;
+    onTimezoneChange?: (timezone: WidgetTimezone) => void;
+    panes?: readonly PaneDescriptor[];
+    xExtents?: readonly [Date | number, Date | number];
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    measurementEnabled?: boolean;
+    renderRightPanel?: (chartId: string) => ReactNode;
+    isMobile?: boolean;
+    selectedDrawing?: DrawingObject | null;
+    isActiveChart?: boolean;
+    showCorporateEvents?: boolean;
+    corporateEvents?: readonly CorporateEvent[];
+    /**
+     * Corporate-events data mode. `live` (default) returns empty when the
+     * adapter is missing/fails. `demo` allows the local mock fixture.
+     */
+    corporateEventsMode?: "live" | "demo";
+    tenantPat?: string;
+    /**
+     * CS-3 — offline signed license key (`vni1.*`) injected by the host.
+     * Goes to the LICENSE channel only; `tenantPat` stays on the PAT channel and
+     * can never shadow this. Hosts that pin a license (enterprise self-host) use
+     * this; everyone else leaves it unset and the local slot is read instead.
+     */
+    licenseKey?: string;
+    /**
+     * CS-6 — observed licensing state for hosts. Called after each completed
+     * validation with attribution and degradation info; never on every render.
+     * Silent by default (unset = no calls). Cannot cross the iframe postMessage
+     * boundary by design — functions are not serializable — so the iframe entry
+     * deliberately does not forward it.
+     */
+    onLicenseDiagnostic?: (info: import("./types/saas").LicenseDiagnosticInfo) => void;
+    client?: VNInvestClient;
+    debugFeatures?: Partial<SaaSFeatureFlags>;
+    /**
+     * **H0.9 — chỉ có tác dụng ngoài production build.**
+     *
+     * Ghi đè tier khi kiểm thử hành vi của tính năng Pro (replay, pine, strategy tester)
+     * mà không cần license thật. Ở production build prop này bị **bỏ qua hoàn toàn**:
+     * `VNInvestCharts.tsx` chỉ nhận nó qua nhánh `process.env.NODE_ENV !== "production"`,
+     * nên tier thật và capability narrowing của license ký số luôn được áp dụng.
+     *
+     * KHÔNG phải đường vòng license: engine vẫn re-validate fail-closed qua
+     * `onTierValidated` (`KernelEngine.ts:72`) và chỉ nhận `enginePat` khi credential đã
+     * xác minh (`usePatTierAuthentication.ts:212-218`), nên feature do engine chặn vẫn bị
+     * chặn. Trước H0.9 nhánh này **không** có guard production, và mặt khác nó còn đặt
+     * `narrowing: undefined` ⇒ xoá luôn allowlist capability của license — tức prop vừa
+     * nâng tier vừa gỡ thanh chắn an toàn.
+     *
+     * Giá trị mặc định `undefined` = không ghi đè, dùng tier thật.
+     *
+     * Khoá bằng `src/widget/__tests__/debugTier.production.test.ts`: test đọc **byte**
+     * bundle production và fail nếu nhánh ghi đè còn tồn tại.
+     */
+    debugTier?: import("@vninvestcharts/engine-core").PatTier;
+    showDrawingPriceMarkers?: boolean;
+    showNonTradingDays?: boolean;
+    axisLabelColor?: string;
+    enableWhale?: boolean;
+    whaleThreshold?: number;
+    whaleOrders?: readonly WhaleOrder[];
+    enableCVD?: boolean;
+    cvdMode?: "oscillator" | "histogram";
+    externalCvdSeries?: readonly CVDPoint[];
+    darkFlowStrength?: number | null;
+    darkFlowSignalType?: DarkFlowSignalType;
+    suppressForkCanvasFallback?: boolean;
+    onClick?: (moreProps: {
+        currentItem?: EnrichedDatum;
+        currentCharts?: number[];
+        mouseXY?: [number, number];
+    }, event: unknown) => void;
+    onContextMenu?: (moreProps: {
+        currentItem?: EnrichedDatum;
+        currentCharts?: number[];
+        mouseXY?: [number, number];
+    }, event: unknown) => void;
+    onDrawingsChange?: (drawings: readonly DrawingObject[]) => void;
+    onSelectedDrawingChange?: (drawing: DrawingObject | null) => void;
+    onDrawingWorkspaceChange?: (workspace: DrawingWorkspaceController | null) => void;
+    onVisibleDomainChange?: (domain: [Date | number, Date | number]) => void;
+    onVisibleRangeChange?: (range: VisibleRange) => void;
+    onHistorySyncBusyChange?: (busy: boolean) => void;
+    onBarsChange?: (bars: readonly OHLCVBar[]) => void;
+    resetKey?: number;
+    onPaneSnapshotsChange?: (snapshots: readonly WidgetPaneRuntimeSnapshot[]) => void;
+    onPaneHover?: (paneId: string | null) => void;
+    onPaneToggleVisibleRequest?: (paneId: string) => void;
+    onPaneRemoveRequest?: (paneId: string) => void;
+    onPaneAddSeriesRequest?: (paneId: string) => void;
+    onPaneToggleSeriesRequest?: (paneId: string, seriesType: SeriesTypeId, seriesIndex?: number) => void;
+    onPaneRemoveSeriesRequest?: (paneId: string, seriesType: SeriesTypeId, seriesIndex?: number) => void;
+    onRuntimeCapabilitiesChange?: (capabilities: WidgetRuntimeCapabilities) => void;
+    onRuntimeResolved?: (runtime: ResolvedWidgetRuntime, reason: WidgetRuntimeResolutionReason) => void;
+    onCoordinateBridgeChange?: (bridge: WidgetCoordinateBridge | null) => void;
+    onSyncDrawing?: (operation: DrawingOperation) => void;
+    onTimeAnchor?: (timestamp: number) => void;
+    onSyncViewport?: (payload: VisibleRangePayload | CrosshairPayload) => void;
+    onCrosshairChange?: (crosshair: CrosshairPayload) => void;
+    onDrawingChange?: (drawings: DrawingData[]) => void;
+    renderPaneToolbar?: (context: {
+        pane: PaneDescriptor;
+        snapshot: WidgetPaneRuntimeSnapshot;
+        hovered: boolean;
+        actions: {
+            toggleVisibility: () => void;
+            removePane: () => void;
+            addSeries: () => void;
+            toggleSeries: (seriesType: SeriesTypeId, seriesIndex?: number) => void;
+            removeSeries: (seriesType: SeriesTypeId, seriesIndex?: number) => void;
+        };
+    }) => ReactNode;
+    renderPaneSplitter?: (context: {
+        pane: PaneDescriptor;
+        snapshot: WidgetPaneRuntimeSnapshot;
+        splitterIndex: number;
+        top: number;
+        left: number;
+        right: number;
+    }) => ReactNode;
+    renderDrawingChrome?: (context: {
+        activeTool?: string;
+        drawingWorkspace?: DrawingWorkspaceController;
+        isDark?: boolean;
+        magnetSensitivity?: any;
+        paneSnapshots?: readonly WidgetPaneRuntimeSnapshot[];
+        selectedDrawing?: DrawingObject | null;
+        visibleRange?: any;
+        size?: {
+            width: number;
+            height: number;
+        };
+    }) => ReactNode;
+    onError?: (error: Error) => void;
+    onDrawingAlert?: (drawing: DrawingObject, condition: DrawingAlertCondition, currentPrice: number) => void;
+    showAdvisoryPanel?: boolean;
+    advisoryResult?: AdvisoryResult | null;
+    isAdvisoryLoading?: boolean;
+    onAdvisoryRefresh?: () => void;
+    showTapePanel?: boolean;
+    tapeEntries?: readonly TapeEntry[];
+    isTapeLoading?: boolean;
+    tapeFilterBillions?: number;
+    onTapeFilterChange?: (billions: number) => void;
+    watchlistAdapter?: WatchlistAdapter;
+    adsEnabled?: boolean;
+    showTimeScrollbar?: boolean;
+    showToolbar?: boolean;
+    showHeader?: boolean;
+    showFooter?: boolean;
+    showFloatingBar?: boolean;
+    /**
+     * D2: explicit right-dock switch (forwarded to useWidgetOverlays).
+     * `true` forces open, `false` forces closed, `undefined` = legacy auto.
+     */
+    showDock?: boolean;
+    /**
+     * D6: right-dock tier gate (default true). `false` restores the legacy
+     * full dock for every tier (host opt-out, e.g. internal tools).
+     */
+    dockTierGate?: boolean;
+    onToggleLayout?: () => void;
+    isSoloMode?: boolean;
+    renderToolbar?: (ctx: {
+        activeTool?: string;
+        onToolSelect: (tool: string) => void;
+    }) => ReactNode;
+    renderHeader?: (ctx: {
+        symbol?: string;
+        timeframe?: string;
+    }) => ReactNode;
+    renderFooter?: (ctx: {
+        timeframe?: string;
+        range?: string;
+    }) => ReactNode;
+    showDrawingDock?: boolean;
+    settingsOpen?: boolean;
+    onSettingsClose?: () => void;
+    onPaperTradePanelClose?: () => void;
+    renderReplayBar?: (ctx: any) => ReactNode;
+    renderPaperTradePanel?: (ctx: any) => ReactNode;
+    renderSettings?: (ctx: any) => ReactNode;
+    renderDrawingDock?: (ctx: any) => ReactNode;
+    historyMinResidentBars?: number;
+    maxVisibleBars?: number;
+    /** Phase 2 (ZOOM_SPEED_REDUCTION_PLAN): per-step zoom multiplier (1.05-1.3, default 1.15). */
+    zoomSpeed?: number;
+    maxVisiblePanes?: number;
+    localCacheRoot?: string;
+    backfillWorkerFlags?: any;
+    canaryLevel?: 10 | 30 | 100;
+    onCanaryGateDecision?: (decision: any) => void;
+    onCanaryRollbackEvent?: (event: any) => void;
+    dataAdapterName?: string;
+    onDataAdapterChange?: (name: string) => void;
+    frozenSnapshot?: ImageBitmap | HTMLCanvasElement | null;
+    sizingMode?: "fixed" | "percent";
+    riskPercent?: number;
+    initialEquity?: number;
+    onSizingChange?: (cfg: {
+        mode: "fixed" | "percent";
+        riskPercent: number;
+        initialEquity: number;
+    }) => void;
+    symbolLinkGroup?: SymbolLinkGroupId | null;
+    initialEngineState?: Record<string, unknown>;
+    onChartReady?: (ref: any) => void;
+    onChartTypeChange?: (chartType: string) => void;
+    hoverEmitterRef?: React.RefObject<any>;
+    active?: boolean;
+    onComparisonChange?: (overlays: any[]) => void;
+    syncOverrides?: Record<string, boolean>;
+    /** URL for upgrade CTA when user clicks a premium-gated feature */
+    upgradeUrl?: string;
+    /**
+     * BL-18: opt-in observability sink (host plugs Sentry/Datadog here).
+     * Library-safe: no SDK bundled; no-op when absent.
+     */
+    onTelemetry?: (event: import("./utils/telemetry").WidgetTelemetryEvent) => void;
+    /** URL for trademark badge click-through (default: https://vninvest.edusuccess.vn) */
+    trademarkUrl?: string;
+    /** Override ad activation date (ms since epoch). Default: 2027-01-01T00:00:00Z. */
+    advActivationDate?: number;
+    /** Khi true, Alt+click luôn chọn replay start bar (ngay cả sau Stop). Dùng cho multi-chart truyền từ state cha. */
+    replaySelectionEnabled?: boolean;
+    /** F-12: namespace cho ReplayEventBus khi nhiều instance multi-chart cùng mount. Cha (VNInvestMultiCharts) truyền workspaceId để cô lập event cross-instance. */
+    replayInstanceId?: string;
+}
+interface VNInvestChartsContentProps extends VNInvestChartsProps {
+    adapter: StockDataAdapter;
+    onRuntimeDegraded?: (reason: "fork-no-render-output") => void;
+}
+export type { VNInvestChartsContentProps };

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

@@ -0,0 +1,8 @@
+import React from "react";
+import type { ChartLayout } from "@vninvestcharts/engine-react";
+export type { MultiChartConfig, VNInvestMultiChartsProps, VNInvestMultiChartsRef } from "./VNInvestMultiCharts.types";
+export { DEFAULT_LAYOUTS, resolveMaxChartsForTier, countLayoutCharts, clampChartLayoutToMax, chartLayoutToGridLayout, gridLayoutToChartLayout, } from "./multiChartDefaults";
+import type { VNInvestMultiChartsProps, VNInvestMultiChartsRef } from "./VNInvestMultiCharts.types";
+declare const VNInvestMultiCharts: React.ForwardRefExoticComponent<VNInvestMultiChartsProps & React.RefAttributes<VNInvestMultiChartsRef>>;
+export { VNInvestMultiCharts };
+export type { ChartLayout };