@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/trading/ticket/TradingDockPanel.d.ts

@@ -0,0 +1,36 @@
+import { type MarketRules } from "../../../lib/core/trading/MarketRules";
+import type { OrderSide, OrderValidationInput, TradingPosition } from "../../../lib/core/trading/types";
+import type { OrderTicketAccount } from "./OrderTicketForm";
+export type ExitUnit = "price" | "ticks" | "percent";
+export interface TradingDockPanelProps {
+    side?: OrderSide;
+    symbol: string;
+    lastPrice: number;
+    rules: MarketRules;
+    account: OrderTicketAccount;
+    currentPosition?: TradingPosition | null;
+    onSubmit: (order: OrderValidationInput) => void;
+    onClose?: () => void;
+    /**
+     * Unified paper-trading gate: when false the submit button is disabled
+     * (same TradingContext.tradingEnabled source as the quick-trade header).
+     */
+    disabled?: boolean;
+    /**
+     * S5b/S1: quyền đặt lệnh nâng cao (trailing_stop cần `paper_advanced`).
+     * `undefined` = legacy (không gate). Truyền `tierGated.allows("paper_advanced")`
+     * để license `caps` cũng được tôn trọng — suy ra từ `toSeriesTier(tier)` sẽ bỏ
+     * qua narrowing, đó chính là bug hai-nguồn-sự-thật của S1.
+     */
+    canUseAdvancedOrders?: boolean;
+    /**
+     * O6/replay_trading (13.03 §4): sub-gate ô đặt lệnh khi chạy trong replay.
+     * Chỉ khóa đúng một chiều (replay === true && grant === false); live không
+     * ảnh hưởng, `undefined` = legacy (không gate) — cùng quy ước với
+     * `canUseAdvancedOrders`. Truyền `tierGated.allows("replay_trading")`.
+     */
+    canUseReplayTrading?: boolean;
+    /** Chế độ replay của chart chứa ticket (host truyền, xem VNInvestCharts). */
+    isReplayMode?: boolean;
+}
+export declare function TradingDockPanel({ side: initialSide, symbol, lastPrice, rules, account, currentPosition, onSubmit, onClose, disabled, canUseAdvancedOrders, canUseReplayTrading, isReplayMode, }: TradingDockPanelProps): import("react").JSX.Element;

package/dist/dts/widget/trading/ticket/orderTicketModel.d.ts

@@ -0,0 +1,49 @@
+import type { MarketRules } from "../../../lib/core/trading/MarketRules";
+import type { OrderSide, OrderType, OrderValidationInput, TimeInForce, TradingPosition } from "../../../lib/core/trading/types";
+export interface TicketAccountPreview {
+    equity: number;
+    freeMargin: number;
+    buyingPower: number;
+    baseCurrency: string;
+}
+export interface TicketValidation {
+    ruleOk: boolean;
+    ruleReason?: string;
+    riskOk: boolean;
+    riskReason?: string;
+    requiredMargin?: number;
+}
+/** Validate dùng chung Modal + Dock (Dock tự render text lỗi theo ngôn ngữ của nó). */
+export declare function validateCandidate(candidate: OrderValidationInput, rules: MarketRules, account: TicketAccountPreview, markPrice: number, currentPosition?: TradingPosition | null): TicketValidation;
+export declare function parseNumber(text: string): number | undefined;
+export interface TicketDraft {
+    symbol: string;
+    side: OrderSide;
+    type: OrderType;
+    quantity: number;
+    limitPrice?: number;
+    stopPrice?: number;
+    takeProfitPrice?: number;
+    stopLossPrice?: number;
+    trailingStopDeltaTicks?: number;
+    /** P1.2b: TIF do user chọn (default GTC giữ nguyên mọi callsite cũ). */
+    timeInForce?: TimeInForce;
+}
+export interface BuiltCandidate {
+    candidate: OrderValidationInput;
+    entryPrice?: number;
+}
+export declare function buildCandidate(draft: TicketDraft): BuiltCandidate;
+/** Quy offset ticks về giá tuyệt đối theo hướng lệnh (mua: ask + n; bán: bid - n). */
+export declare function offsetTicksToPrice(markPrice: number, side: OrderSide, offsetTicks: number, tickSize: number): number;
+/** Đổi % equity rủi ro ra khoảng giá SL: pct% * equity / (qty * multiplier). */
+export declare function riskPercentToDistance(equityPercent: number, accountEquity: number, quantity: number, contractMultiplier: number): number | undefined;
+/** Dòng tóm tắt nút submit kiểu TV: "MUA 100 FPT @ 128.500 GIỚI HẠN". */
+export declare function formatSubmitSummary(input: {
+    side: OrderSide;
+    quantity: number;
+    symbol: string;
+    price?: number;
+    type: OrderType;
+    locale?: "vi" | "en";
+}): string;

package/dist/dts/widget/trading/visibility/paperVisibility.d.ts

@@ -0,0 +1,38 @@
+import { type PatTier } from "@vninvestcharts/engine-core";
+export interface PaperVisibilityInput {
+    /** Toggle runtime trong session (mắt/CTA) — thắng cả prop (hợp đồng TVP-A0). */
+    localOverride?: boolean;
+    defaultEnabled?: boolean;
+    chartId?: string;
+    perChart?: Record<string, boolean>;
+    master?: boolean;
+    legacyEnabled?: boolean;
+}
+/**
+ * Thứ tự ưu tiên: toggle runtime > prop tường minh > override riêng chart
+ * > master workspace > localStorage cũ > mặc định bật.
+ */
+export declare function resolvePaperEnabled(input: PaperVisibilityInput): boolean;
+/** Đọc legacy key `vnsc.paper.enabled` ("1"/"0") — single-chart + fallback. */
+export declare function readLegacyPaperEnabled(): boolean | undefined;
+/**
+ * Paper trading có 2 mức (AGENTS.md Rule 15 + quy tắc phân gói):
+ *  - `paper_market_limit` (Community): market + limit. **Luôn mở**, kể cả `none`.
+ *  - `paper_advanced` (pro): stop, stop-limit, trailing, PLO + panel quản trị rủi ro.
+ *
+ * Gọi ở UI khi render, KHÔNG gọi trong `resolvePaperEnabled` (hàm đó thuần và
+ * đã có test ma trận cũ — giữ nguyên hợp đồng).
+ *
+ * S1: `capabilityGated` là kết quả `tierGated.allows(...)` (đã tính cả tier VÀ
+ * allowlist `caps` của license). `hasCapability(tier, cap)` chỉ biết tier, **không biết**
+ * license caps — nên nếu gate lệnh nâng cao chỉ suy ra từ tier thì license thu hẹp gói
+ * bị bỏ qua đúng ở tầng UI. Truyền `undefined` giữ hành vi cũ (chỉ theo tier).
+ */
+export declare function canUsePaperTrading(tier: PatTier | null | undefined, advanced: boolean, capabilityGated?: boolean): boolean;
+/** Lọc danh sách loại lệnh theo capability. Community chỉ thấy market/limit. */
+export declare function filterOrderTypesByTier<T extends {
+    type: string;
+}>(types: readonly T[], tier: PatTier | null | undefined, capabilityGated?: {
+    paperAdvanced: boolean;
+    paperMarketLimit: boolean;
+}): T[];

package/dist/dts/widget/types/dataProvider.d.ts

@@ -0,0 +1,8 @@
+import { type OHLCVBar, type SymbolInfo } from "../../lib/types/adapter";
+export interface IChartDataProvider {
+    fetchBars(symbol: string, timeframe: string, from: number, to: number): Promise<readonly OHLCVBar[]>;
+    subscribeBars(symbol: string, timeframe: string, onBar: (bar: OHLCVBar) => void): () => void;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+    getServerTime?(): Promise<number>;
+    fetchCorporateEvents?(symbol: string, from: number, to: number): Promise<any[]>;
+}

package/dist/dts/widget/types/fullChartHandle.d.ts

@@ -0,0 +1,25 @@
+import type { DrawingWorkspaceController } from "@vninvestcharts/engine-react";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import type { VNInvestChartsRef, WidgetChartHandle } from "../utils/widgetHelpers";
+declare module "../utils/widgetHelpers" {
+    interface WidgetChartHandle {
+        _frozenSnapshot?: ImageBitmap | HTMLCanvasElement | null;
+        openSettings?(): void;
+        saveAsImage?(): void;
+        saveTemplate?(): void;
+        loadTemplate?(): void;
+        cycleMagnet?(): void;
+        getMagnetSensitivity?(): number;
+        getDrawingWorkspace?(): DrawingWorkspaceController | null;
+        getDrawingObjects?(): DrawingObject[];
+        importDrawingObjects?(drawings: DrawingObject[]): void;
+        freeze?(): Promise<void> | void;
+        thaw?(): Promise<void> | void;
+        captureSnapshot?(): Promise<ImageBitmap | HTMLCanvasElement | null>;
+        restoreFromSnapshot?(snapshot: ImageBitmap | HTMLCanvasElement): Promise<void>;
+        openAlerts?(): void;
+        setTimeframe(timeframe: string, sourceChartId?: string): void;
+        setChartType(chartType: string, sourceChartId?: string): void;
+    }
+}
+export type FullChartHandle = VNInvestChartsRef & WidgetChartHandle;

package/dist/dts/widget/types/saas.d.ts

@@ -0,0 +1,83 @@
+export interface SaaSFeatureFlags {
+    isWhalePanelEnabled: boolean;
+    isReplayEnabled: boolean;
+    isAdvisoryEnabled: boolean;
+    hideTrademark: boolean;
+    showWidgetAds: boolean;
+}
+export interface TenantMetadata {
+    tenantCode: string;
+    tenantName: string;
+    plan: 'free' | 'starter' | 'pro' | 'enterprise' | 'custom' | 'internal';
+    status: 'active' | 'suspended' | 'expired';
+    features: SaaSFeatureFlags;
+    domainWhitelist: string[];
+}
+export interface AdImageSource {
+    default: string;
+    retina?: string;
+    svg?: string;
+}
+export interface AdCampaign {
+    campaign_id: string;
+    image_source: AdImageSource;
+    video_url?: string;
+    click_url: string;
+    click_tracking_url: string;
+    impression_tracking_url: string;
+    width: number;
+    height: number;
+}
+export interface AdServerResponse {
+    show_ads: boolean;
+    hide_trademark: boolean;
+    ad?: AdCampaign;
+}
+export interface SaaSFeatureContextValue {
+    isLoading: boolean;
+    isValid: boolean;
+    tenantMetadata: TenantMetadata | null;
+    flags: SaaSFeatureFlags;
+    error: string | null;
+    invalidateCache: () => void;
+    adCampaign: AdCampaign | null;
+    isAdLoading: boolean;
+    adError: string | null;
+    refetchAd: () => Promise<void>;
+    /** Whether SaaS config was successfully fetched from server. */
+    isSaaSConfigAvailable: boolean;
+    userPat: string;
+    /** Returns false when the credential was REFUSED and nothing was persisted. Callers
+     *  must not report a save in that case. */
+    setUserPat: (pat: string) => boolean;
+    effectivePat: string;
+    /**
+     * The offline license channel (host-pinned key, local slot, or host PAT that
+     * parses as a license). Never shadowed by tenantPat. Empty when no license.
+     * The toolbar auth hook reads this alongside effectivePat so a license-only
+     * customer is not reported free.
+     */
+    effectiveLicense: string;
+    /**
+     * Last server rejection detail (verbatim from /auth/me error body), or null.
+     * Optional because it lives in dedicated state outside the main setState
+     * objects; the provider memo always supplies the live value.
+     */
+    serverRejectReason?: string | null;
+    /**
+     * CS-3 — which grants produced the current tier. Used by support ("why Pro?")
+     * and by the CS-6 degraded banner. Never empty; ["none"] when free.
+     */
+    sources: ("license" | "server" | "server-cache" | "host" | "none")[];
+    /**
+     * CS-3 — why data features are degraded, or null when fully usable.
+     * Never reports a valid token as rejected; low plan is "plan-limited".
+     */
+    degradedReason: "no-pat" | "plan-limited" | "offline" | "grace-expired" | null;
+}
+/** CS-6: payload for the host licensing observer. */
+export interface LicenseDiagnosticInfo {
+    sources: ("license" | "server" | "server-cache" | "host" | "none")[];
+    degradedReason: "no-pat" | "plan-limited" | "offline" | "grace-expired" | null;
+    diagnosticReason: "insecure-context" | "subtle-unavailable" | null;
+}

package/dist/dts/widget/types/symbolSearch.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Symbol search SSOT types (SYMBOL_SEARCH P1).
+ * Single shared item shape for VNSymbolSearch + compare picker.
+ */
+export interface SymbolSearchItem {
+    symbol: string;
+    company_name: string;
+    exchange: string;
+}

package/dist/dts/widget/types/watchlist.d.ts

@@ -0,0 +1,26 @@
+/**
+ * P4b: WatchlistAdapter contract (F1 approved).
+ *
+ * Host apps provide an adapter for live quotes; without one the widget
+ * falls back to the static VN30 basket (symbols only, no prices).
+ * Mirrors the StockDataAdapter pattern used by VNSymbolSearch.
+ */
+export interface WatchlistItem {
+    symbol: string;
+    name?: string;
+    price?: number;
+    change?: number;
+    changePercent?: number;
+    sparkline?: number[];
+}
+export interface WatchlistQuoteUpdate {
+    symbol: string;
+    price?: number;
+    change?: number;
+    changePercent?: number;
+    sparkline?: number[];
+}
+export interface WatchlistAdapter {
+    getWatchlist: () => Promise<WatchlistItem[]> | WatchlistItem[];
+    subscribeQuotes?: (symbols: string[], onUpdate: (update: WatchlistQuoteUpdate) => void) => (() => void) | void;
+}

package/dist/dts/widget/utils/axisHit.d.ts

@@ -0,0 +1,16 @@
+import type { WidgetPaneRuntimeSnapshot } from "./widgetHelpers";
+export interface AxisSlotHit {
+    paneId: string;
+    scaleSlotId: string;
+    side: "left" | "right";
+    /** Current slot domain (for the log-availability guard). */
+    domain?: readonly [number, number];
+}
+/**
+ * P2 (W1): mirror of the engine `findScaleSlotAt` — map a chart-local point
+ * to the Y-axis scale slot under it (for the price-scale context menu).
+ * Returns null for plot/time-axis/empty regions. Total function.
+ */
+export declare function findAxisSlotAt(snapshots: readonly WidgetPaneRuntimeSnapshot[] | null | undefined, localX: number, localY: number): AxisSlotHit | null;
+/** Log scale needs a strictly positive domain (engine falls back + warns otherwise). */
+export declare function isLogScaleAvailable(domain: readonly [number, number] | undefined): boolean;

package/dist/dts/widget/utils/chartRange.d.ts

@@ -0,0 +1,12 @@
+export declare const CHART_RANGES: readonly ["1D", "5D", "1M", "3M", "6M", "YTD", "1Y", "All"];
+export type ChartRange = typeof CHART_RANGES[number];
+export declare const DEFAULT_CHART_RANGE: ChartRange;
+export declare const CHART_RANGE_LABEL_KEYS: Record<ChartRange, string>;
+type RangeDatum = {
+    date: Date | number;
+};
+export declare function resolveChartRangeStart(endDate: Date, range: ChartRange): Date;
+export declare function resolveChartRangeFetchStart(endDate: Date, range: ChartRange): Date;
+export declare function resolveChartRangeExtents(data: readonly RangeDatum[], range: ChartRange): [Date, Date] | null;
+export declare function isChartRangeSatisfied(data: readonly RangeDatum[], range: ChartRange): boolean;
+export {};

package/dist/dts/widget/utils/chartTypeOptions.d.ts

@@ -0,0 +1,38 @@
+import { type Capability } from "@vninvestcharts/engine-core";
+/**
+ * Bảng chart type dùng chung cho MỌI picker (status line `OHLCHeader` và
+ * `MultiChartTopbar`).
+ *
+ * Trước đây mỗi picker có một bản riêng và chúng đã trôi lệch: `OHLCHeader`
+ * có `bar`, `MultiChartTopbar` có `renko`/`kagi` đánh dấu `comingSoon`. Một
+ * chart type mà chỉ xuất hiện ở một nửa UI là chart type mà user không tìm thấy.
+ * Một bảng, hai nơi import ⇒ không còn chỗ để trôi.
+ *
+ * `capability` là cổng TẦN 1 (UI): dùng `hasCapability` — cùng hàm và cùng cách
+ * fail-closed như `components/dock/dockAccess.ts:29`. `tier` chưa biết (`null`)
+ * nghĩa là khoá, không phải mở.
+ *
+ * Tần 2 là CỔNG RENDER: `RegistryEntry.tier = "pro"` trong
+ * `core/registry/priceChartTypes.ts`, đọc bởi `filterAvailableSeries` trước khi
+ * series tới engine. UI cho user thấy nút Pro; engine không bao giờ nhận series
+ * đó ở tier thấp. `chartTypeCapability.test.tsx` khoá việc hai tầng phải cùng
+ * một capability.
+ */
+export interface ChartTypeOption {
+    /** Khóa của `CHART_TYPE_MAP` trong `VNInvestCharts.tsx`. */
+    value: string;
+    labelKey: string;
+    /** Capability phải có mới chọn được. Vắng ⇒ ai cũng chọn được. */
+    capability?: Capability;
+    /**
+     * CHƯA build xong. Hiện tên + badge nhưng không chọn được, và tuyệt đối
+     * không được có trong `CHART_TYPE_MAP`: map tới một `SeriesTypeId` chưa có
+     * producer thì chart vẽ y hệt Line dưới nhãn khác.
+     */
+    comingSoon?: boolean;
+}
+export declare const CHART_TYPE_OPTIONS: readonly ChartTypeOption[];
+/** Tier chưa xác minh được (`null`/`undefined`) ⇒ khoá, không phải mở. */
+export declare function isChartTypeLocked(option: ChartTypeOption, patTier: string | null | undefined): boolean;
+/** Đã khai báo trong `CHART_TYPE_OPTIONS` nhưng chưa build (khác với "bị khoá theo tier"). */
+export declare function isChartTypeComingSoon(option: ChartTypeOption): boolean;

package/dist/dts/widget/utils/clickOutside.d.ts

@@ -0,0 +1 @@
+export declare function isClickOutside(element: HTMLElement | null, event: MouseEvent | PointerEvent): boolean;

package/dist/dts/widget/utils/coordinateBridge.d.ts

@@ -0,0 +1,31 @@
+import { type VisibleRange as EngineVisibleRange } from "@vninvestcharts/engine-core";
+import { type WidgetCoordinateBridge, type WidgetPaneRuntimeSnapshot } from "./widgetHelpers";
+import { type VisibleRange } from "../../lib/core";
+import { type EnrichedDatum } from "../../lib/core/calculators/types";
+import { type ChartRenderContextValue } from "../../lib/core/canvas/ChartRenderContext";
+import { type StockChartContextValue } from "../../lib/StockChartContext";
+import type { ResolvedWidgetRuntime } from "../runtimePolicy";
+export declare function createWidgetCoordinateBridge(paneSnapshotsOrOptions: readonly WidgetPaneRuntimeSnapshot[] | {
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    visibleRange: EngineVisibleRange | VisibleRange | null;
+    plotData: readonly EnrichedDatum[];
+    engineRuntime?: ResolvedWidgetRuntime;
+    pixelRatio?: number;
+}, visibleRangeArg?: EngineVisibleRange | VisibleRange | null, plotDataArg?: readonly EnrichedDatum[], engineRuntimeArg?: ResolvedWidgetRuntime, pixelRatioArg?: number): WidgetCoordinateBridge | null;
+export declare function createForkChartRenderContextValue({ paneSnapshots, visibleRange, plotData, width, height, pixelRatio, }: {
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    visibleRange: EngineVisibleRange | null;
+    plotData: readonly EnrichedDatum[];
+    width: number;
+    height: number;
+    pixelRatio?: number;
+}): ChartRenderContextValue | null;
+export declare function createForkStockChartContextValue(paneSnapshotsOrOptions: readonly WidgetPaneRuntimeSnapshot[] | {
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    plotData: readonly EnrichedDatum[];
+    chartRenderContextValue: ChartRenderContextValue | null;
+    width: number;
+    height: number;
+    generateSubscriptionId: () => number;
+    pixelRatio?: number;
+}, plotDataArg?: readonly EnrichedDatum[], chartRenderContextValueArg?: ChartRenderContextValue | null, widthArg?: number, heightArg?: number, generateSubscriptionIdArg?: () => number, pixelRatioArg?: number): StockChartContextValue;

package/dist/dts/widget/utils/crosshairSync.d.ts

@@ -0,0 +1,50 @@
+/**
+ * crosshairSync.ts — Shared helper for resolving crosshair position from timestamp.
+ *
+ * When two charts have different data (different symbol/timeframe/bar-count),
+ * the source chart's xIndexFloat is NOT valid as a local index on the target chart.
+ * This helper resolves the correct local index by binary-searching for the timestamp
+ * in the target chart's plotData, then interpolating a fractional position within the bar.
+ */
+interface PlotDatum {
+    date: Date;
+}
+/**
+ * Resolve a FRACTIONAL local x-index on the TARGET chart from a remote timestamp.
+ *
+ * The crosshair on the source chart sits at a concrete point in time T (the
+ * mouse position on the source time axis, not necessarily a bar boundary). To
+ * mirror it exactly, the target chart needs `index + fraction` where `index` is
+ * the target bar covering T and `fraction ∈ [0,1)` is where inside that bar T
+ * falls — this reproduces the precise pixel position of the cursor, not just the
+ * bar's left edge.
+ *
+ * Two data sources may stamp the same logical bar at different clock offsets
+ * (e.g. a VN-exchange chart stamps a 1D bar at 00:00 Asia/Ho_Chi_Minh = 17:00
+ * UTC of the previous day, while a crypto chart stamps 00:00 UTC). We therefore
+ * align T onto the target chart's OWN bar grid (phase = the target bars' offset
+ * within a bar-duration) before computing the bucket + fraction. This keeps the
+ * cursor position accurate while absorbing the timezone offset.
+ *
+ * Returns `null` when T falls in a real gap the target chart does not cover
+ * (weekend/holiday for an exchange-calendar chart) so the caller hides the
+ * crosshair; it reappears when T lands within a real target bar. A continuous
+ * target (crypto) has a bar in every bucket, so it always resolves.
+ *
+ * @param plotData  - target chart's plotData array (sorted by date ascending)
+ * @param timestamp - source chart's crosshair timestamp (ms since epoch)
+ * @param sourceFraction - cursor's fractional position INSIDE the source bar
+ *        (0 = bar start, ~0.5 = center), taken from the source `xIndexFloat`.
+ *        This carries the true cursor position independent of any timezone
+ *        offset between the two data sources. When omitted, the fraction is
+ *        derived from where T sits inside the nearest target bar (less accurate
+ *        across a tz offset, kept for callers that have no source index).
+ * @returns fractional local x-index (index + fraction), or null if no target bar covers T
+ */
+export declare function resolveLocalXIndexFromTimestamp(plotData: readonly PlotDatum[], timestamp: number, sourceFraction?: number): number | null;
+export interface CrosshairPriceRemote {
+    price?: number | null;
+    symbol?: string | null;
+}
+export declare function resolveCrosshairPrice(remote: CrosshairPriceRemote, localSymbol: unknown, localClose: number | null): number | null;
+export {};

package/dist/dts/widget/utils/drawingSync.d.ts

@@ -0,0 +1,198 @@
+/** Stamp the origin symbol on an outgoing op (emit side). */
+export declare function withDrawingSourceSymbol<T extends object>(op: T, symbol: string | undefined): T;
+/**
+ * Receive-side gate: apply only same-symbol ops.
+ * Legacy ops without a symbol pass through (backward compatible).
+ */
+export declare function shouldApplyRemoteDrawing(opSymbol: unknown, localSymbol: unknown): boolean;
+export interface SyncPointInput {
+    timeMsHint?: unknown;
+    xIndexFloat?: unknown;
+}
+/**
+ * P2/D-SYNC-23: resolve a sync timestamp without `Date.now()` garbage. Anchor
+ * hints win; indexed plotData second; deterministic 0 when unanchorable
+ * (renders off-chart) instead of a fake "now" that collides with live bars.
+ */
+export declare function drawingPointToSyncTimestamp(point: SyncPointInput, plotData?: ReadonlyArray<{
+    date?: unknown;
+}>): number;
+export interface DrawingConflictInfo {
+    drawingId: string;
+    winner: unknown;
+    localOp?: {
+        symbol?: unknown;
+    } | null;
+    remoteOp?: {
+        symbol?: unknown;
+    } | null;
+}
+export declare function shouldNotifyDrawingConflict(info: DrawingConflictInfo | null | undefined, slotSymbol: unknown, isActiveSlot: boolean): boolean;
+export declare function nextDrawingOpTimestamp(lastTimestamp: number, now?: number): number;
+export interface SyncDrawingPointInput {
+    x?: unknown;
+    y?: unknown;
+    timeMsHint?: unknown;
+    xIndexFloat?: unknown;
+    yPrice?: unknown;
+}
+/**
+ * Emit-side point normalization (eraser/brush/ABCD stretch fix).
+ * Freehand and multi-step drafts carry bare `{x, y}` points (unix ms + price)
+ * until render-path enrichment runs — but sync emit reads the raw workspace
+ * points, so `drawingPointToSyncTimestamp(p, ...)` saw no `timeMsHint` and
+ * emitted `timestamp: 0` for real points. Receivers then built
+ * `{x: 0, timeMsHint: 0}` → `chartPointToPixel` NaN → the clip helper replaced
+ * the NaN endpoint with the viewport edge: a full-width stretched line.
+ * Normalizing through `resolvePointAnchor` first (which falls back to
+ * `p.x > 10000` as the time hint, mirroring the local render path) keeps the
+ * wire timestamp real. Genuinely unanchorable points still emit `0`
+ * (off-chart by design, P2/D-SYNC-23).
+ */
+export declare function drawingPointToSyncFields(point: SyncDrawingPointInput, plotData?: ReadonlyArray<{
+    date?: unknown;
+}>): {
+    timestamp: number;
+    price: number;
+    xIndexFloat?: number;
+    yPrice?: number;
+};
+/**
+ * Receive-side point mapping (defense for the same stretch bug).
+ * A `timestamp: 0` (or missing/non-finite) timestamp must stay absent —
+ * fabricating `timeMsHint: 0` creates a NaN projection that the clip helper
+ * stretches to the viewport edge. `xIndexFloat` passes through untouched
+ * (receiver resolves it in its own index space).
+ */
+export declare function syncPointToDrawingPoint(p: {
+    timestamp?: unknown;
+    price?: unknown;
+    xIndexFloat?: unknown;
+}): {
+    x?: number;
+    y?: unknown;
+    timeMsHint?: number;
+    yPrice?: unknown;
+    xIndexFloat?: unknown;
+};
+/** Minimal shape of a synced point source, so this file stays free of chart types. */
+export type SyncPlotData = ReadonlyArray<{
+    date?: unknown;
+}>;
+/** Minimal shape of `DrawingObject` used here; keeps the engine type out of the import graph. */
+interface SyncableDrawing {
+    id: string;
+    type: string;
+    symbol?: string;
+    timeframe?: string;
+    points: ReadonlyArray<SyncDrawingPointInput>;
+    style?: SyncableStyle;
+    label?: string;
+    locked?: boolean;
+    zIndex?: number;
+}
+interface SyncableStyle {
+    stroke?: string;
+    strokeWidth?: number;
+    strokeDasharray?: SyncableDash;
+    fill?: string;
+    opacity?: number;
+    fontSize?: number;
+    fontFamily?: string;
+}
+type SyncableDash = string | number[] | undefined;
+export interface SyncStyleOut {
+    color?: string;
+    lineWidth?: number;
+    lineStyle?: string;
+    fillColor?: string;
+    opacity?: number;
+    fontSize?: number;
+    fontFamily?: string;
+}
+/**
+ * `DrawingObject.style` -> `DrawingStyle`. THE single mapping.
+ *
+ * `opacity` is included, which two of the three original literals omitted — see the
+ * table above. Fixing it here rather than at the three call sites is deliberate: a
+ * fix applied to two of three literals is the bug, restated.
+ *
+ * `zIndex` is deliberately NOT copied into the style. `DrawingData` and `DrawingStyle`
+ * both declare it, but the drawings path already carries it as a top-level field, and
+ * populating both would create a second source of truth for one value.
+ */
+export declare function toSyncStyle(style: SyncableStyle | undefined): SyncStyleOut | undefined;
+/** `TrendLine` -> `trend-line`. Used by `onDrawingChange` only; ops keep the raw type. */
+export declare function toDrawingDataType(type: string): string;
+/** Anchor-normalised points -> `{timestamp, price}`, using the rule above. */
+export declare function toSyncPoints(points: ReadonlyArray<SyncDrawingPointInput>, plotData: SyncPlotData | undefined): Array<{
+    timestamp: number;
+    price: number;
+}>;
+export interface ConvertScope {
+    fallbackSymbol: string | undefined;
+    fallbackTimeframe: string | undefined;
+    plotData: SyncPlotData | undefined;
+}
+export interface SyncDrawingDataOut {
+    id: string;
+    type: string;
+    symbol: string;
+    timeframe: string;
+    points: Array<{
+        timestamp: number;
+        price: number;
+    }>;
+    style: SyncStyleOut | undefined;
+    label: string | undefined;
+    locked: boolean | undefined;
+    zIndex: number | undefined;
+}
+/**
+ * `DrawingObject[]` -> `DrawingData[]` for `onDrawingChange` (workspace persistence).
+ *
+ * Fallbacks are explicit arguments rather than closure reads. The original read
+ * `localSymbol`, `props.timeframe` and `dataResult.plotData` out of the component
+ * scope, which is exactly why the literal could not be tested without mounting a
+ * 2 900-line component.
+ */
+export declare function convertToDrawingData(drawings: readonly SyncableDrawing[], scope: ConvertScope): SyncDrawingDataOut[];
+export interface DrawingOpOut {
+    id: string;
+    drawingId: string;
+    type: "create" | "update" | "delete" | "move-point";
+    version: Record<string, number>;
+    timestamp: number;
+    authorId: string;
+    symbol: string;
+    data?: SyncDrawingDataOut & {
+        type: string;
+    };
+}
+export interface BuildOpsInput {
+    prev: readonly SyncableDrawing[];
+    next: readonly SyncableDrawing[];
+    /** Chart id; also the writer key for the per-writer monotonic clock. */
+    writerKey: string;
+    symbol: string;
+    timeframe: string;
+    plotData: SyncPlotData | undefined;
+    /** From `nextDrawingOpTimestamp(lastTs)`. Passed in so the clock stays in the component. */
+    now: number;
+    /** Raw type for ops — deliberately NOT kebab-cased. See the header note. */
+    opType: (drawing: SyncableDrawing) => string;
+}
+/**
+ * Diff two drawing sets into CRDT operations. Pure: same two arrays in, same
+ * operations out.
+ *
+ * Ordering create -> delete -> update is load-bearing: a delete must never win over a
+ * create for the same id, and an update must not be emitted for a drawing that only
+ * just appeared in `next` (it has no `prev` to diff against).
+ *
+ * The per-writer clock is NOT applied here — it lives in the component, which owns the
+ * ref, and this function is handed the timestamp to use. A pure diff is testable; a
+ * closure that mutates a ref is not, and this rule set is where a real CRDT bug lived.
+ */
+export declare function buildDrawingOperations(input: BuildOpsInput): DrawingOpOut[];
+export {};

package/dist/dts/widget/utils/enrichedHash.d.ts

@@ -0,0 +1,15 @@
+import type { EnrichedDatum } from "../../lib/core/calculators/types";
+export interface EnrichedHashOptions {
+    /**
+     * Include per-bar comparison overlay closes (`symbolData`) in the hash so
+     * `setEnrichedData` fires when a comparison symbol is added/removed.
+     * VNInvestCharts passes true; useWidgetData passes false (its items carry
+     * no symbolData) — preserving each call-site's exact legacy semantics.
+     */
+    includeComparison?: boolean;
+}
+/**
+ * Shared change-detection hash for enriched bars (BL-07 dedup).
+ * Previously duplicated in VNInvestCharts.tsx and useWidgetData.ts.
+ */
+export declare function hashEnrichedData(data: readonly EnrichedDatum[], options?: EnrichedHashOptions): string;