@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/lib/core/replay/BarReplayController.d.ts

@@ -0,0 +1,62 @@
+export type ReplaySpeed = 0.5 | 1 | 2 | 5 | 10 | "max";
+/** SSOT: user-facing replay speeds (excluding internal "max") */
+export declare const REPLAY_SPEEDS: readonly Exclude<ReplaySpeed, "max">[];
+export interface ReplayBarLike {
+    date: Date | number;
+}
+export interface BarReplayState<T extends ReplayBarLike> {
+    allData: readonly T[];
+    currentIndex: number;
+    speed: ReplaySpeed;
+    isPlaying: boolean;
+    visibleData: readonly T[];
+    currentBar?: T;
+    progress: number;
+    canStepBack: boolean;
+    canStepForward: boolean;
+}
+export interface BarReplayControllerOptions<T extends ReplayBarLike> {
+    allData: readonly T[];
+    startIndex?: number;
+    speed?: ReplaySpeed;
+    baseIntervalMs?: number;
+    maxIntervalMs?: number;
+}
+type ReplayListener<T extends ReplayBarLike> = (state: BarReplayState<T>) => void;
+export declare class BarReplayController<T extends ReplayBarLike> {
+    private allData;
+    private currentIndex;
+    private speed;
+    private baseIntervalMs;
+    private maxIntervalMs;
+    private isPlaying;
+    private timer;
+    private readonly listeners;
+    constructor(options: BarReplayControllerOptions<T>);
+    getState(): BarReplayState<T>;
+    getVisibleData(): readonly T[];
+    getCurrentBar(): T | undefined;
+    isPlayingNow(): boolean;
+    getCurrentIndex(): number;
+    getSpeed(): ReplaySpeed;
+    setData(allData: readonly T[], startIndex?: number): void;
+    setSpeed(speed: ReplaySpeed): void;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    stepForward(): void;
+    stepBack(): void;
+    jumpToIndex(barIndex: number): void;
+    jumpToLatest(): void;
+    jumpToDate(date: Date | number): void;
+    rewind(): void;
+    dispose(): void;
+    subscribe(listener: ReplayListener<T>): () => void;
+    private tick;
+    private finish;
+    private scheduleTimer;
+    private restartTimer;
+    private clearTimer;
+    private emit;
+}
+export {};

package/dist/dts/lib/core/replay/ReplayEventBus.d.ts

@@ -0,0 +1,68 @@
+/**
+ * ReplayEventBus — cross-instance replay synchronization via CustomEvent.
+ *
+ * Protocol (active types only):
+ * - MASTER_ANNOUNCE: chart announces itself as master
+ * - REPLAY_SEEK: master seeked to a specific barIndex+timestamp
+ * - REPLAY_START: master started playing from a bar (slaves catch up at once)
+ * - REPLAY_TOGGLE: replay was toggled on/off
+ * - REPLAY_END: replay session ended or sync toggled off
+ *
+ * Channel namespace: "vninvestcharts-widget-replay-"
+ * Transport: window CustomEvent
+ */
+export declare const REPLAY_EVENT_NS: "vninvestcharts-widget-replay";
+export type ReplayEventType = "MASTER_ANNOUNCE" | "REPLAY_SEEK" | "REPLAY_START" | "REPLAY_TOGGLE" | "REPLAY_END";
+export interface ReplayEventBase {
+    type: ReplayEventType;
+    chartId: string;
+    timestamp: number;
+    /** F-S2: Alt+click forceBroadcast — slave handler treats this as authoritative master regardless of election. */
+    forceBroadcast?: boolean;
+}
+export interface MasterAnnounceEvent extends ReplayEventBase {
+    type: "MASTER_ANNOUNCE";
+    tf: string;
+    barIndex: number;
+}
+export interface ReplaySeekEvent extends ReplayEventBase {
+    type: "REPLAY_SEEK";
+    barIndex: number;
+    currentBarDate: number;
+}
+/**
+ * R1-c: master started playing — slaves catch up immediately (cursor +
+ * camera) instead of waiting for the first tick. Fire-and-forget.
+ */
+export interface ReplayStartEvent extends ReplayEventBase {
+    type: "REPLAY_START";
+    startTimestamp: number;
+}
+export interface ReplayToggleEvent extends ReplayEventBase {
+    type: "REPLAY_TOGGLE";
+    playing: boolean;
+}
+export interface ReplayEndEvent extends ReplayEventBase {
+    type: "REPLAY_END";
+}
+export type ReplayBusEvent = MasterAnnounceEvent | ReplaySeekEvent | ReplayStartEvent | ReplayToggleEvent | ReplayEndEvent;
+export type ReplayEventHandler = (event: ReplayBusEvent) => void;
+/**
+ * Parse timeframe string to minutes for master election (lower = more granular = master).
+ */
+export declare function parseReplayTimeframeToMinutes(tf: string): number;
+/**
+ * Subscribe to a specific replay event type on the window.
+ * Returns an unsubscribe function.
+ */
+export declare function onReplayEvent(type: ReplayEventType, handler: ReplayEventHandler, instanceId?: string): () => void;
+/**
+ * Emit a replay event on the window.
+ * The event payload is serialized as CustomEvent.detail.
+ */
+export declare function emitReplayEvent(event: ReplayBusEvent, instanceId?: string): void;
+/**
+ * Subscribe to ALL replay event types on the window.
+ * Returns an unsubscribe function.
+ */
+export declare function onAnyReplayEvent(handler: ReplayEventHandler, instanceId?: string): () => void;

package/dist/dts/lib/core/replay/ReplayFillSimulator.d.ts

@@ -0,0 +1,33 @@
+import type { FillResult, ReplayOHLCBar, ReplayOrder } from "./replayTradingTypes";
+export interface ReplayFillSimulatorOptions {
+    useOHLC?: boolean;
+    /** H2 v2: use spread-aware fills (buy at high/ask, sell at low/bid) instead of single price + bps.
+     * Default true for realistic fills. When false, uses legacy behavior (close price + slippageBps). */
+    useSpreadFill?: boolean;
+    /** H2: simple slippage (bps). buy = +, sell = -. Applied as buffer on top of spread fill.
+     * Default 0 (no extra slippage). When useSpreadFill=true, this is added to high/low. */
+    slippageBps?: number;
+    /** F-03: when true, triggered limit/stop orders fill at next bar's open instead of trigger bar.
+     * Default false (retail convention: fill at trigger price/high/low). */
+    fillOnNextBar?: boolean;
+}
+export declare class ReplayFillSimulator {
+    private useOHLC;
+    private slippageBps;
+    readonly fillOnNextBar: boolean;
+    constructor(options?: ReplayFillSimulatorOptions);
+    simulateFill(order: ReplayOrder, bar: ReplayOHLCBar, now: number): FillResult;
+    private fillMarket;
+    private fillLimit;
+    private fillStop;
+    private resolveMarketPrice;
+    /** F-03: check if order would trigger on this bar (without filling). Used by fillOnNextBar mode. */
+    checkTrigger(order: ReplayOrder, bar: ReplayOHLCBar): boolean;
+    /** F-03: fill triggered order at next bar's open (± slippage). Fallback to close if open unavailable. */
+    resolveFillFromNextBar(order: ReplayOrder, nextBar: ReplayOHLCBar, now: number): FillResult;
+    /** F-01: apply configured slippage to a base price adverse to the given side. buy = +, sell = -. */
+    applySlippage(side: "buy" | "sell", base: number): number;
+    private filled;
+    private pending;
+    private reject;
+}

package/dist/dts/lib/core/replay/ReplayOrderBook.d.ts

@@ -0,0 +1,24 @@
+import type { FillResult, ReplayOHLCBar, ReplayOrder } from "./replayTradingTypes";
+import { ReplayFillSimulator } from "./ReplayFillSimulator";
+import { ReplayPositionManager } from "./ReplayPositionManager";
+export declare class ReplayOrderBook {
+    private orders;
+    private filledOrders;
+    private cancelledOrders;
+    private pendingTriggers;
+    private fillSimulator;
+    private positionManager;
+    private realisticSlTpFill;
+    private nextOrderId;
+    constructor(fillSimulator?: ReplayFillSimulator, positionManager?: ReplayPositionManager, realisticSlTpFill?: boolean);
+    addOrder(order: Omit<ReplayOrder, "id">): ReplayOrder;
+    cancelOrder(orderId: string): boolean;
+    processBar(bar: ReplayOHLCBar, barIndex: number, now: number): FillResult[];
+    private resolveRealisticSlTpFill;
+    private handleNewPositionOrder;
+    private handleReduceOnlyOrder;
+    getOpenOrders(): ReplayOrder[];
+    getFilledOrders(): ReplayOrder[];
+    getPositionManager(): ReplayPositionManager;
+    reset(): void;
+}

package/dist/dts/lib/core/replay/ReplayPositionManager.d.ts

@@ -0,0 +1,30 @@
+import type { ReplayExecutedTrade, ReplayPosition } from "./replayTradingTypes";
+export interface TriggeredSLTP {
+    positionId: string;
+    reason: "tp" | "sl";
+    fillPrice: number;
+}
+export declare class ReplayPositionManager {
+    private positions;
+    private closedTrades;
+    private nextId;
+    openPosition(side: "long" | "short", quantity: number, price: number, barIndex: number, timestamp: number, stopLoss?: number, takeProfit?: number, symbol?: string, feeRate?: number): ReplayPosition;
+    closePosition(positionId: string, exitPrice: number, barIndex: number, exitReason: "tp" | "sl" | "manual" | "session-end", timestamp?: number): ReplayExecutedTrade | null;
+    updateCurrentPrice(bar: {
+        high: number;
+        low: number;
+        close: number;
+    }): void;
+    checkStopLossTakeProfit(bar: {
+        high: number;
+        low: number;
+    }): TriggeredSLTP[];
+    closeAllPositions(barIndex: number, reason: "tp" | "sl" | "manual" | "session-end", timestamp?: number): ReplayExecutedTrade[];
+    getPositions(): ReplayPosition[];
+    getPosition(id: string): ReplayPosition | undefined;
+    getClosedTrades(): ReplayExecutedTrade[];
+    getTotalPnl(): number;
+    setStopLoss(positionId: string, price: number): boolean;
+    setTakeProfit(positionId: string, price: number): boolean;
+    reset(): void;
+}

package/dist/dts/lib/core/replay/ReplaySessionAnalytics.d.ts

@@ -0,0 +1,31 @@
+import type { ReplayExecutedTrade } from "./replayTradingTypes";
+export interface EquityPoint {
+    barIndex: number;
+    equity: number;
+}
+export interface ReplayAnalyticsStats {
+    totalTrades: number;
+    winningTrades: number;
+    losingTrades: number;
+    winRate: number;
+    grossProfit: number;
+    grossLoss: number;
+    profitFactor: number;
+    netProfit: number;
+    maxDrawdown: number;
+    maxDrawdownPercent: number;
+    sharpeRatio: number;
+    avgWin: number;
+    avgLoss: number;
+    expectancy: number;
+}
+export declare class ReplaySessionAnalytics {
+    private equityCurve;
+    private initialEquity;
+    private periodsPerYear;
+    constructor(periodsPerYear?: number);
+    reset(initialEquity?: number): void;
+    recordEquity(barIndex: number, totalPnl: number): void;
+    private computeDrawdown;
+    getStats(externalTrades?: readonly ReplayExecutedTrade[]): ReplayAnalyticsStats;
+}

package/dist/dts/lib/core/replay/createReplayTradeMarkerPrimitives.d.ts

@@ -0,0 +1,7 @@
+import type { EngineOverlayDrawingPrimitiveInput, PaneRuntimeSnapshot, VisibleRange as EngineVisibleRange } from "@vninvestcharts/engine-core";
+import type { ReplayExecutedTrade, ReplayPosition } from "./replayTradingTypes";
+export interface TradeMarkerInput {
+    positions: readonly ReplayPosition[];
+    closedTrades: readonly ReplayExecutedTrade[];
+}
+export declare function createReplayTradeMarkerInputs(input: TradeMarkerInput, paneSnapshot: PaneRuntimeSnapshot, visibleRange: EngineVisibleRange, scaleSlotId: string): EngineOverlayDrawingPrimitiveInput[];

package/dist/dts/lib/core/replay/pnlUtils.d.ts

@@ -0,0 +1,2 @@
+export declare function computePnl(side: "long" | "short", entry: number, exit: number, qty: number): number;
+export declare function computeNetPnl(side: "long" | "short", entry: number, exit: number, qty: number, feeRate: number): number;

package/dist/dts/lib/core/replay/replayBrokerAdapters.d.ts

@@ -0,0 +1,51 @@
+import { type MarketRules } from "../trading/MarketRules";
+import type { ExecutionTicket, OrderValidationInput, PositionSide, TradingPosition } from "../trading/types";
+import type { ReplayExecutedTrade, ReplayOHLCBar, ReplayOrder, ReplayPosition } from "./replayTradingTypes";
+/**
+ * Replay mô phỏng chiến thuật, không mô phỏng thanh toán T+2: nếu giữ
+ * settlementDays = 2, TP khớp nến kế tiếp bị throw (available 0) — regression
+ * nặng so với legacy (đóng ngay). Override có chủ đích, khóa bằng test.
+ */
+export declare const REPLAY_SPOT_RULES: MarketRules;
+export interface ReplayEntryInfo {
+    entryPrice: number;
+    entryTimestamp: number;
+    entryBarIndex: number;
+}
+export declare function mapPositionToReplay(position: TradingPosition, opts: {
+    mark: number;
+    contractMultiplier?: number;
+    stopLoss?: number;
+    takeProfit?: number;
+    entryBarIndex?: number;
+}): ReplayPosition;
+export declare function mapTicketToReplayTrade(ticket: ExecutionTicket, entry: ReplayEntryInfo & {
+    positionSide: PositionSide;
+}, exitBarIndex: number): ReplayExecutedTrade;
+export interface PreBatchPosition {
+    id: string;
+    symbol: string;
+    side: "long" | "short";
+    quantity: number;
+}
+export interface CloseLegMatch {
+    closeQuantity: number;
+    entry: ReplayEntryInfo & {
+        positionSide: "long" | "short";
+    };
+}
+/**
+ * Một fill chỉ sinh journal khi nó ĐÓNG (toàn phần/bộ phận) vị thế đối ứng
+ * tồn tại trước batch. Fill mở vị thế -> null (legacy journal chỉ ghi closes).
+ * Reversal: close leg tách theo min(fillQty, preQty), phần dôi mở mới không ghi journal.
+ */
+export declare function matchCloseLeg(ticket: {
+    symbol: string;
+    side: "buy" | "sell";
+    fillQuantity: number;
+    fillPrice: number;
+    timestamp: number;
+}, preBatch: PreBatchPosition[] | null, ledger: Map<string, ReplayEntryInfo>, fallbackBarIndex: number): CloseLegMatch | null;
+/** ReplayOrder legacy -> broker input. reduceOnly/clamp do hook xử lý (cần net position). */
+export declare function mapReplayOrderToBrokerInput(order: Omit<ReplayOrder, "id" | "timestamp">): OrderValidationInput;
+export declare function replayBarTimestamp(bar: ReplayOHLCBar, fallback: number): number;

package/dist/dts/lib/core/replay/replayTradingTypes.d.ts

@@ -0,0 +1,61 @@
+export interface ReplayOrder {
+    id: string;
+    type: "market" | "limit" | "stop";
+    side: "buy" | "sell";
+    quantity: number;
+    price?: number;
+    stopPrice?: number;
+    timestamp: number;
+    reduceOnly?: boolean;
+    symbol?: string;
+    feeRate?: number;
+}
+export interface FillResult {
+    filled: boolean;
+    fillPrice: number;
+    fillQuantity: number;
+    fillTimestamp: number;
+    partial: boolean;
+    remainingQuantity: number;
+    error?: string;
+}
+export interface ReplayPosition {
+    id: string;
+    side: "long" | "short";
+    entryPrice: number;
+    quantity: number;
+    currentPrice: number;
+    unrealizedPnl: number;
+    realizedPnl: number;
+    stopLoss?: number;
+    takeProfit?: number;
+    entryTimestamp: number;
+    entryBarIndex: number;
+    symbol?: string;
+    feeRate?: number;
+}
+export interface ReplayExecutedTrade {
+    id: string;
+    orderId: string;
+    symbol: string;
+    side: "buy" | "sell";
+    type: "market" | "limit" | "stop";
+    entryPrice: number;
+    exitPrice: number;
+    quantity: number;
+    pnl: number;
+    pnlPercent: number;
+    entryTimestamp: number;
+    exitTimestamp: number;
+    entryBarIndex: number;
+    exitBarIndex: number;
+    barsHeld: number;
+    exitReason: "tp" | "sl" | "manual" | "session-end";
+}
+export interface ReplayOHLCBar {
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    date: Date | number;
+}

package/dist/dts/lib/core/scales/computeScales.d.ts

@@ -0,0 +1,8 @@
+import { type ScaleLinear } from "d3-scale";
+import type { OHLCVBar } from "../../types/ohlcv";
+import type { PaneConfig } from "../../types/pane";
+export interface PaneScales {
+    leftScale: ScaleLinear<number, number>;
+    rightScale?: ScaleLinear<number, number>;
+}
+export declare function computeScales(pane: PaneConfig, data: readonly OHLCVBar[], canvasHeight: number): PaneScales;

package/dist/dts/lib/core/seriesValueResolver.d.ts

@@ -0,0 +1,27 @@
+import type { EnrichedDatum, IndicatorBandValue, IndicatorBrarValue, IndicatorCrValue, IndicatorDmaValue, IndicatorDmiValue, IndicatorEmvValue, IndicatorDatumValue, IndicatorKdjValue, IndicatorMacdValue, IndicatorMtmValue, IndicatorPsyValue, IndicatorTrixValue, IndicatorWhaleValue, IndicatorStrengthElderValue, IndicatorIchimokuValue, IndicatorSupertrendValue, IndicatorMARibbonValue, IndicatorAlligatorValue, IndicatorFractalValue, IndicatorGatorValue, IndicatorPivotValue, IndicatorVwapValue, IndicatorAcValue, MarketProfileData, VolumeProfileData, FootprintBar, IndicatorDeltaProfileValue, IndicatorWyckoffValue } from "./calculators/types";
+import type { SeriesConfig } from "./types/pane-descriptor";
+/**
+ * The Pine series-type prefix, and the only place that parses it.
+ *
+ * A Pine script produces a series whose type id is generated at runtime, so it is absent from
+ * every closed lookup table in this file. Both the producer (PineEditorPanel) and the consumer
+ * (buildIndicatorBaseKey) must agree on the format; when they disagreed, the series resolved to
+ * no key and vanished. One exported pair, one format, no second spelling.
+ *
+ * `scriptId` is the persisted script id (base36 + timestamp), which never contains a dot — that
+ * matters, because the engine treats a type containing "." as a derived sub-series.
+ */
+export declare const PINE_SERIES_TYPE_PREFIX = "pine_";
+/**
+ * Idempotent on purpose: `useScriptPersistence.generateId()` already emits ids beginning with
+ * `pine_`, so the script id and the series type are the same string in practice. Making this
+ * idempotent means a caller can pass either form without producing `pine_pine_...`.
+ */
+export declare function pineSeriesTypeFor(scriptId: string): string;
+/** Returns the script id, or null when the type is not a Pine series type. */
+export declare function pineScriptIdFromSeriesType(type: string): string | null;
+export declare function buildIndicatorSeriesKey(series: SeriesConfig): string | undefined;
+export declare function resolveSeriesDatumValue(datum: EnrichedDatum, series: SeriesConfig): IndicatorDatumValue | undefined;
+export declare function resolveSeriesValue(datum: EnrichedDatum, series: SeriesConfig): number | undefined;
+export declare function resolveSeriesStructuredValue(datum: EnrichedDatum, series: SeriesConfig): number | IndicatorBandValue | IndicatorMacdValue | IndicatorWhaleValue | IndicatorKdjValue | IndicatorDmiValue | IndicatorBrarValue | IndicatorMtmValue | IndicatorEmvValue | IndicatorTrixValue | IndicatorDmaValue | IndicatorPsyValue | IndicatorCrValue | IndicatorStrengthElderValue | IndicatorIchimokuValue | IndicatorSupertrendValue | IndicatorMARibbonValue | IndicatorAlligatorValue | IndicatorFractalValue | IndicatorGatorValue | IndicatorPivotValue | IndicatorVwapValue | IndicatorAcValue | MarketProfileData | VolumeProfileData | FootprintBar | import("./calculators/types").DeltaProfileData | IndicatorDeltaProfileValue | IndicatorWyckoffValue | undefined;
+export declare function resolveSeriesValueAccessors(series: SeriesConfig): Array<(datum: EnrichedDatum) => number | undefined>;

package/dist/dts/lib/core/sets/builtins.d.ts

@@ -0,0 +1,2 @@
+import type { IndicatorSet } from "../types/indicator-set";
+export declare const BUILTIN_INDICATOR_SETS: readonly IndicatorSet[];

package/dist/dts/lib/core/sets/indicatorSetCodec.d.ts

@@ -0,0 +1,15 @@
+import type { PaneDescriptor, SeriesTypeId } from "../types/pane-descriptor";
+import type { IndicatorSet, IndicatorSetStorageLike } from "../types/indicator-set";
+export declare function cloneIndicatorSet(set: IndicatorSet): IndicatorSet;
+export declare function createIndicatorSet(name: string, panes: readonly PaneDescriptor[], now?: number): IndicatorSet;
+export interface IndicatorSetValidationOptions {
+    allowedSeriesTypes?: readonly SeriesTypeId[];
+    preserveBuiltin?: boolean;
+}
+export declare function sanitizeIndicatorSet(candidate: unknown, options?: IndicatorSetValidationOptions): IndicatorSet | null;
+export declare function sanitizeIndicatorSetsStorage(candidate: unknown, options?: IndicatorSetValidationOptions): IndicatorSet[] | null;
+export declare function loadIndicatorSets(storage?: IndicatorSetStorageLike, options?: IndicatorSetValidationOptions): IndicatorSet[];
+export declare function saveIndicatorSets(storage: IndicatorSetStorageLike | undefined, sets: readonly IndicatorSet[]): void;
+export declare function indicatorSetToPaneLayout(set: IndicatorSet): PaneDescriptor[];
+export declare function buildIndicatorSetFileName(name: string, createdAt: number): string;
+export declare function stringifyIndicatorSet(set: IndicatorSet): string;

package/dist/dts/lib/core/trading/AnalyticsEngine.d.ts

@@ -0,0 +1,56 @@
+import type { ExitReason, PositionSide } from "./types";
+export interface ClosedTradeRecord {
+    timestamp: number;
+    realizedPnl: number;
+    commission: number;
+    tax: number;
+    /** TVP-A3: chi tiết vị thế đóng cho tab Trade History (additive, optional). */
+    symbol?: string;
+    side?: PositionSide;
+    quantity?: number;
+    entryPrice?: number;
+    exitPrice?: number;
+    exitReason?: ExitReason;
+}
+export interface EquityPoint {
+    timestamp: number;
+    equity: number;
+}
+export interface TradingAnalytics {
+    totalTrades: number;
+    winningTrades: number;
+    losingTrades: number;
+    winRate: number;
+    grossProfit: number;
+    grossLoss: number;
+    netProfit: number;
+    /** 0 khi chưa có trade; = grossProfit khi chưa từng lỗ (tránh Infinity). */
+    profitFactor: number;
+    maxDrawdown: number;
+    maxDrawdownPercent: number;
+    equityCurve: EquityPoint[];
+    /** TVP-A3: trades đã đóng (có entry/exit khi settleFill điền đủ) cho tab Trade History. */
+    closedTrades: ClosedTradeRecord[];
+    /** TVP-A4: Sharpe annualized, port exact từ legacy (sample variance, prev !== 0). */
+    sharpeRatio: number;
+}
+export declare class AnalyticsEngine {
+    private trades;
+    private curve;
+    recordClosedTrade(trade: ClosedTradeRecord): void;
+    recordEquityPoint(timestamp: number, equity: number): void;
+    getClosedTrades(): ClosedTradeRecord[];
+    getEquityCurve(): EquityPoint[];
+    restoreClosedTrades(trades: ClosedTradeRecord[]): void;
+    restoreEquityCurve(curve: EquityPoint[]): void;
+    clear(): void;
+    getAnalytics(): TradingAnalytics;
+}
+/**
+ * TVP-A4: port EXACT công thức legacy (ReplaySessionAnalytics):
+ * sample variance (n-1), skip prev === 0, annualized √252.
+ * Giữ `!== 0` như legacy (parity) thay vì E ≤ 0 nghiêm ngặt — chia cho số âm
+ * hữu hạn không sinh NaN/Infinity nên an toàn; mọi đường NaN/Infinity
+ * (length<3, stdDev 0) đều đã khóa về 0.
+ */
+export declare function computeSharpeRatio(curve: EquityPoint[], periodsPerYear?: number): number;

package/dist/dts/lib/core/trading/BrokerAPI.d.ts

@@ -0,0 +1,40 @@
+import type { BrokerAccount, ExecutionTicket, OrderValidationInput, TradingOrder, TradingPosition } from "./types";
+export interface TradingEventMap {
+    positionChange: TradingPosition[];
+    orderChange: TradingOrder[];
+    accountChange: BrokerAccount;
+    fill: ExecutionTicket;
+}
+export type TradingEventKey = keyof TradingEventMap;
+export type TradingEventCallback<K extends TradingEventKey> = (payload: TradingEventMap[K]) => void;
+export declare class TradingEventBus {
+    private readonly listeners;
+    on<K extends TradingEventKey>(event: K, callback: TradingEventCallback<K>): () => void;
+    emit<K extends TradingEventKey>(event: K, payload: TradingEventMap[K]): void;
+}
+export interface ClosePositionOptions {
+    quantity?: number;
+    reason?: string;
+}
+export interface PlaceOrderOptions {
+    /** Bỏ qua rules/availability/risk — chỉ dùng cho replay-compat (legacy accept-everything). */
+    skipValidation?: boolean;
+}
+export interface IBrokerAPI {
+    getAccount(): BrokerAccount;
+    getPositions(): TradingPosition[];
+    getOrders(): TradingOrder[];
+    placeOrder(request: OrderValidationInput & {
+        clientOrderId?: string;
+    }, options?: PlaceOrderOptions): TradingOrder;
+    cancelOrder(orderId: string): boolean;
+    modifyOrder(orderId: string, patch: {
+        price?: number;
+        stopPrice?: number;
+        quantity?: number;
+    }): TradingOrder;
+    closePosition(positionId: string, options?: ClosePositionOptions): boolean;
+    closeAllPositions(reason?: string, symbol?: string): number;
+    resetAccount(initialBalance: number): void;
+    on<K extends TradingEventKey>(event: K, callback: TradingEventCallback<K>): () => void;
+}

package/dist/dts/lib/core/trading/ExecutionSimulator.d.ts

@@ -0,0 +1,53 @@
+import type { ExecutionTicket, ExitReason, OrderSide, PositionSide, TradingOrder } from "./types";
+import type { MarketRules } from "./MarketRules";
+export interface ExecutionSimulatorOptions {
+    slippageTicks?: number;
+    brokerFeeRate?: number;
+    commissionPerContract?: number;
+    taxRate?: number;
+}
+export interface PositionBasis {
+    entryPrice: number;
+    side: PositionSide;
+}
+export interface ExecuteFillRequest {
+    order: TradingOrder;
+    basePrice: number;
+    quantity: number;
+    timestamp: number;
+    positionBasis?: PositionBasis;
+    exitReason?: ExitReason;
+    ambiguousIntrabarFill?: boolean;
+    tieBreakReason?: string;
+}
+export interface OrderCostEstimate {
+    estimatedCost: number;
+    commission: number;
+    estimatedTax: number;
+    totalOutflow: number;
+}
+export declare class ExecutionSimulator {
+    private slippageTicks;
+    private brokerFeeRate;
+    private commissionPerContract;
+    private taxRate;
+    constructor(options?: ExecutionSimulatorOptions);
+    /**
+     * S2: live-update pricing knobs without recreating the broker (positions,
+     * orders and WS subscriptions survive). Prospective-only: booked fills keep
+     * old values. Returns the effective options for UI logging.
+     */
+    updateOptions(patch: ExecutionSimulatorOptions): Required<ExecutionSimulatorOptions>;
+    executeFill(request: ExecuteFillRequest, rules: MarketRules): ExecutionTicket;
+    applySlippage(basePrice: number, side: OrderSide, rules: MarketRules): number;
+    calculateCommission(price: number, quantity: number, rules: MarketRules): number;
+    calculateTax(price: number, quantity: number, rules: MarketRules, side: OrderSide): number;
+    checkIntrabarAmbiguity(tpPrice: number, slPrice: number, bar: {
+        high: number;
+        low: number;
+    }, side: PositionSide): boolean;
+    estimateOrderCost(order: {
+        side: OrderSide;
+        quantity: number;
+    }, price: number, rules: MarketRules): OrderCostEstimate;
+}

package/dist/dts/lib/core/trading/FillSettlement.d.ts

@@ -0,0 +1,38 @@
+import type { BrokerAccount, ExecutionTicket, ExitReason, OrderSide } from "./types";
+import type { MarketRules } from "./MarketRules";
+import type { OrderManagementSystem } from "./OrderManagementSystem";
+import type { PositionManager } from "./PositionManager";
+import type { ExecutionSimulator } from "./ExecutionSimulator";
+import type { AnalyticsEngine } from "./AnalyticsEngine";
+export interface SettlementBooks {
+    account: BrokerAccount;
+    history: ExecutionTicket[];
+    analytics: AnalyticsEngine;
+}
+export interface SettleFillArgs {
+    symbol: string;
+    side: OrderSide;
+    quantity: number;
+    price: number;
+    timestamp: number;
+    orderId?: string;
+    exitReason?: ExitReason;
+    bar?: {
+        high: number;
+        low: number;
+    };
+}
+export declare class FillSettlement {
+    private readonly oms;
+    private readonly pms;
+    private readonly sim;
+    private rules;
+    private mktSeq;
+    constructor(oms: OrderManagementSystem, pms: PositionManager, sim: ExecutionSimulator, rules: MarketRules);
+    /** S2: swap the rules reference (prospective fills only; booked history untouched). */
+    updateRules(rules: MarketRules): void;
+    settle(books: SettlementBooks, args: SettleFillArgs): ExecutionTicket;
+    private openFresh;
+    private applyCashflow;
+    private flagAmbiguity;
+}