@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/lib/adapters/LocalCacheAdapter.d.ts

@@ -0,0 +1,18 @@
+import type { CanonicalFetchResult, DataAdapter, GetBarsParams, GetBarsResult, KLineBar } from "./DataAdapter";
+import type { SourceSemanticsDescriptor } from "@vninvestcharts/engine-core";
+/**
+ * In-memory adapter backed by pre-loaded bars (e.g. offline CSV data).
+ * Useful for testing and offline demo mode.
+ */
+export declare class LocalCacheAdapter implements DataAdapter {
+    readonly name = "local";
+    private readonly store;
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    /**
+     * Pre-load bars for a given symbol/interval pair.
+     * Bars are sorted ascending by timestamp after loading.
+     */
+    loadBars(symbol: string, interval: string, bars: KLineBar[]): void;
+    getBars(params: GetBarsParams): Promise<GetBarsResult>;
+    getBarsCanonical(params: GetBarsParams): Promise<CanonicalFetchResult>;
+}

package/dist/dts/lib/adapters/MockAdapter.d.ts

@@ -0,0 +1,22 @@
+import type { OrderbookSnapshot, StockDataAdapter, SymbolInfo, Timeframe, Trade, Unsubscribe } from "../types/adapter";
+import type { OHLCVBar } from "../types/ohlcv";
+export interface MockAdapterOptions {
+    symbols?: readonly SymbolInfo[];
+    bars?: readonly OHLCVBar[];
+    intervalMs?: number;
+}
+export declare class MockAdapter implements StockDataAdapter {
+    private readonly bars;
+    private readonly symbols;
+    private readonly intervalMs;
+    constructor(options?: MockAdapterOptions);
+    fetchBars(symbol: string, timeframe: Timeframe, from: Date, to: Date): Promise<readonly OHLCVBar[]>;
+    fetchMoreBars(symbol: string, timeframe: Timeframe, before: Date, limit?: number): Promise<readonly OHLCVBar[]>;
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    subscribeToTrades(symbol: string, onTrade: (trade: Trade) => void): Unsubscribe;
+    subscribeToOrderbook(symbol: string, onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+}
+export declare function createMockBars(count?: number): OHLCVBar[];

package/dist/dts/lib/adapters/RESTAdapter.d.ts

@@ -0,0 +1,16 @@
+import { BaseAdapter } from "./BaseAdapter";
+import type { OHLCVBar } from "../types/ohlcv";
+import type { OrderbookSnapshot, SymbolInfo, Timeframe, Trade, Unsubscribe } from "../types/adapter";
+/**
+ * RESTAdapter handles standard REST API request logic for OHLCV data.
+ */
+export declare class RESTAdapter extends BaseAdapter {
+    private readonly headers;
+    constructor(baseUrl: string, authHeader?: string, cacheTtlMs?: number);
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    subscribeToTrades(symbol: string, onTrade: (trade: Trade) => void): Unsubscribe;
+    subscribeToOrderbook(symbol: string, onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+}

package/dist/dts/lib/adapters/StockDataAdapter.d.ts

@@ -0,0 +1 @@
+export type { OrderbookLevel, OrderbookSnapshot, StockDataAdapter, SymbolInfo, Timeframe, Trade, Unsubscribe, } from "../types/adapter";

package/dist/dts/lib/adapters/UDFDataAdapter.d.ts

@@ -0,0 +1,29 @@
+import type { StockDataAdapter, Unsubscribe, Timeframe, Trade, OrderbookSnapshot, SymbolInfo } from "../types/adapter";
+import type { OHLCVBar } from "../types/ohlcv";
+import type { SourceSemanticsDescriptor } from "@vninvestcharts/engine-core";
+export interface UDFDataAdapterConfig {
+    baseUrl: string;
+    wsUrl?: string;
+    pollIntervalMs?: number;
+}
+export declare class UDFDataAdapter implements StockDataAdapter {
+    private readonly baseUrl;
+    private readonly wsUrl;
+    private readonly pollIntervalMs;
+    private ws;
+    private wsConnecting;
+    private readonly activeSubscriptions;
+    constructor(config: UDFDataAdapterConfig);
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    private mapTimeframe;
+    private parseHistory;
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    private startHttpPolling;
+    private connectWebSocket;
+    private sendWsMessage;
+    subscribeToTrades(_symbol: string, _onTrade: (trade: Trade) => void): Unsubscribe;
+    subscribeToOrderbook(_symbol: string, _onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+}

package/dist/dts/lib/adapters/VNStocksAdapter.d.ts

@@ -0,0 +1,8 @@
+import type { CanonicalFetchResult, DataAdapter, GetBarsParams, GetBarsResult } from "./DataAdapter";
+import type { SourceSemanticsDescriptor } from "@vninvestcharts/engine-core";
+export declare class VNStocksAdapter implements DataAdapter {
+    readonly name = "vnstocks";
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    getBars(params: GetBarsParams): Promise<GetBarsResult>;
+    getBarsCanonical(params: GetBarsParams): Promise<CanonicalFetchResult>;
+}

package/dist/dts/lib/adapters/WSAdapter.d.ts

@@ -0,0 +1,30 @@
+import { BaseAdapter } from "./BaseAdapter";
+import type { OHLCVBar } from "../types/ohlcv";
+import type { OrderbookSnapshot, SymbolInfo, Timeframe, Trade, Unsubscribe } from "../types/adapter";
+/**
+ * WSAdapter manages a persistent WebSocket connection for real-time market data streaming
+ * with automated exponential backoff reconnection.
+ */
+export declare class WSAdapter extends BaseAdapter {
+    private ws;
+    private isConnecting;
+    private reconnectAttempts;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly wsUrl;
+    private readonly barSubscriptions;
+    private readonly tradeSubscriptions;
+    private readonly orderbookSubscriptions;
+    constructor(baseUrl: string, wsPath?: string, cacheTtlMs?: number);
+    private connect;
+    private scheduleReconnect;
+    private resubscribeAll;
+    private sendWsMessage;
+    private handleMessage;
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    subscribeToTrades(symbol: string, onTrade: (trade: Trade) => void): Unsubscribe;
+    subscribeToOrderbook(symbol: string, onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+}

package/dist/dts/lib/adapters/gapFixture.d.ts

@@ -0,0 +1,71 @@
+/**
+ * W-18 - a fixture with a REAL gap, so lane-switch parity can be proved at all.
+ *
+ * ## Why this file exists
+ *
+ * G0.4 was FAILED and the recorded reason was "the demo uses LIVE, continuous data so
+ * it cannot demonstrate a lane switch". That diagnosis was right, and here is the
+ * measurement behind it.
+ *
+ * `MockAdapter.createSampleBars` emitted:
+ *
+ *     date: new Date(Date.UTC(2024, 0, index + 1))
+ *
+ * Consecutive days, weekends included, no exchange calendar, no gap.
+ *
+ * The discontinuous time scale only diverges between the legacy and fork lanes AT A
+ * GAP. With continuous data there is literally nothing for the two runtimes to
+ * disagree about, so no screenshot could ever have proved a lane switch. The evidence
+ * gap was never a tooling problem - the input could not express the thing being tested.
+ *
+ * ## What this fixture guarantees
+ *
+ * `buildGapFixture` produces a series that crosses a weekend AND a national holiday,
+ * so the whitespace detector has something real to find. `assertHasGap` is the gate:
+ * if a future edit accidentally makes the fixture continuous again, the parity work
+ * that depends on it fails loudly instead of producing screenshots that prove
+ * nothing.
+ *
+ * ## Why the fixture is a separate module rather than a MockAdapter option
+ *
+ * Because it is test and documentation input, not product behaviour. MockAdapter
+ * stays the continuous synthetic series the demo and unit tests use; a demo that
+ * suddenly had holes in it would change what every other test observes. The fixture is
+ * opt-in, and the demo can adopt it explicitly once a lane switch is actually wired to
+ * a UI control.
+ */
+import type { OHLCVBar } from "../types/ohlcv";
+export interface GapFixtureOptions {
+    /** Trading days to emit, counting only sessions that actually trade. */
+    tradingDays?: number;
+    /** Starting price; a gentle drift keeps the series visually plausible. */
+    startPrice?: number;
+}
+export declare const FIXTURE_INCLUDE_HOLIDAYS = false;
+/**
+ * Build a bar series that contains real gaps.
+ *
+ * Trading sessions are taken from the repository's own exchange calendar, so the
+ * fixture and `ExchangeCalendar` cannot drift apart: if the calendar stops or starts
+ * treating a date as a session, the fixture follows.
+ */
+export declare function buildGapFixture(options?: GapFixtureOptions): OHLCVBar[];
+/** Every interval between consecutive bars, in ms. */
+export declare function gapsOf(bars: readonly OHLCVBar[]): number[];
+/** Distinct intervals, ascending. One value means the series is continuous. */
+export declare function distinctGaps(bars: readonly OHLCVBar[]): number[];
+/**
+ * The gate a fixture must pass before any lane-switch screenshot is worth taking.
+ *
+ * Returns the gaps it found. Throws when the series is continuous, because that is
+ * the exact condition that made G0.3/G0.4 produce no evidence - and it fails silently,
+ * the worst way to fail.
+ */
+export declare function assertHasGap(bars: readonly OHLCVBar[]): number[];
+/**
+ * True when the repository's own calendar considers the bar's day a session.
+ *
+ * Exported so a test can cross-check the fixture against the calendar instead of
+ * trusting two copies of the same rule.
+ */
+export declare function fixtureMatchesExchangeCalendar(bars: readonly OHLCVBar[]): boolean;

package/dist/dts/lib/adapters/index.d.ts

@@ -0,0 +1,15 @@
+export type { StockDataAdapter, Timeframe, Trade, OrderbookSnapshot, SymbolInfo, Unsubscribe } from "./StockDataAdapter";
+export { BaseAdapter } from "./BaseAdapter";
+export { DjangoVnstockAdapter, createRestAdapter } from "./DjangoVnstockAdapter";
+export { MockAdapter, createMockBars } from "./MockAdapter";
+export type { CoverageMode, SessionModel, FinalityMode, GapReason, CoverageFragment, SourceSemanticsDescriptor, } from "@vninvestcharts/engine-core";
+export type { DataAdapter, KLineBar, GetBarsType, GetBarsParams, GetBarsResult, CanonicalFetchResult, } from "./DataAdapter";
+export { BinanceAdapter, binanceAdapter } from "./BinanceAdapter";
+export { LocalCacheAdapter } from "./LocalCacheAdapter";
+export { VNStocksAdapter } from "./VNStocksAdapter";
+export { UDFDataAdapter } from "./UDFDataAdapter";
+export type { UDFDataAdapterConfig } from "./UDFDataAdapter";
+export { CSVAdapter } from "./CSVAdapter";
+export { RESTAdapter } from "./RESTAdapter";
+export { WSAdapter } from "./WSAdapter";
+export { DBAdapter } from "./DBAdapter";

package/dist/dts/lib/adapters/rollAlgorithms.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Roll Algorithms - Pure TypeScript Implementation
+ *
+ * Shared between client and server for continuous futures roll adjustment.
+ * Supports three methods: Ratio, Panama (Cumulative Difference), Backward Ratio.
+ *
+ * These are pure functions with no side effects - fully testable.
+ */
+import type { KLineBar } from "./DataAdapter";
+import type { RollMethod, RollPoint, FuturesContract } from "./ContinuousContractTypes";
+/** Result of roll adjustment computation */
+export interface RollAdjustmentResult {
+    /** Adjusted bars */
+    bars: KLineBar[];
+    /** Roll points with adjustment details */
+    rollPoints: RollPoint[];
+    /** Total cumulative adjustment (for Panama) */
+    totalCumulativeAdjustment: number;
+    /** Warnings during computation */
+    warnings: string[];
+}
+/** Input for roll computation */
+export interface RollComputationInput {
+    /** Contracts in chronological order */
+    contracts: FuturesContract[];
+    /** Raw bars for each contract (keyed by contract symbol) */
+    contractBars: Map<string, KLineBar[]>;
+    /** Roll configuration */
+    config: {
+        rollMethod: RollMethod;
+        adjustVolumes: boolean;
+    };
+    /** Requested time range */
+    from: number;
+    to: number;
+}
+/**
+ * Compute roll adjustments for a chain of futures contracts
+ *
+ * This is the core algorithm - pure, deterministic, and fully testable.
+ */
+export declare function computeRollAdjustment(input: RollComputationInput): RollAdjustmentResult;
+/**
+ * Compute roll adjustment for a single roll point (for testing)
+ */
+export declare function computeSingleRollAdjustment(fromPrice: number, toPrice: number, method: RollMethod): {
+    factor: number;
+    offset: number;
+};
+/**
+ * Verify no price gaps at roll dates
+ * Returns true if all roll transitions are smooth (gap < threshold)
+ */
+export declare function verifyNoPriceGaps(rollPoints: RollPoint[], thresholdPercent?: number): {
+    passed: boolean;
+    gaps: Array<{
+        rollPoint: RollPoint;
+        gapPercent: number;
+    }>;
+};
+/**
+ * Generate synthetic contract chain for testing
+ */
+export declare function generateTestContractChain(rootSymbol: string, count: number, startDate: number, intervalDays?: number): FuturesContract[];
+/**
+ * Generate test bars with known roll gap for verification
+ */
+export declare function generateTestBarsWithRollGap(contracts: FuturesContract[], rollMethod: RollMethod, gapPercent?: number): Map<string, KLineBar[]>;

package/dist/dts/lib/advisory/AdvisoryPanel.d.ts

@@ -0,0 +1,5 @@
+/**
+ * P3a-04: Re-export AdvisoryPanel from widget location.
+ * Backward compatibility — import paths from src/lib/advisory/ still work.
+ */
+export { AdvisoryPanel, type AdvisoryPanelProps } from "../../widget/components/overlays/AdvisoryPanel";

package/dist/dts/lib/alerts/AlertEvaluator.d.ts

@@ -0,0 +1,5 @@
+import type { AlertCondition } from "./types";
+export declare class AlertEvaluator {
+    static evaluate(current: any, previous: any, alert: AlertCondition): boolean;
+    private static getValue;
+}

package/dist/dts/lib/alerts/AlertManager.d.ts

@@ -0,0 +1,123 @@
+import { AlertCondition } from "./types";
+import type { SeriesConfig, PaneDescriptor } from "../core/types/pane-descriptor";
+/**
+ * Every series an alert is allowed to reference: those that HAVE a canonical indicator
+ * key, i.e. those the evaluator can actually read out of `indicatorValues`.
+ *
+ * This predicate replaces an eight-entry type blacklist that used to live in
+ * `VNInvestCharts.tsx`. That list was a hand-maintained duplicate of what
+ * `buildIndicatorSeriesKey` already answers, and it had drifted from the thing it was
+ * mirroring: it was applied to `settings.visiblePanes` AND filtered by type, so the
+ * demo's six indicators — which live in `momentum`, `orderflow` and `strength`, all
+ * three `visible: false` — reduced to an EMPTY list. Every indicator-sourced alert then
+ * persisted an instance id nothing could resolve, and no E2E had ever exercised that
+ * branch. Measured, not inferred: the resolver logged `seriesCount: 0` on every tick.
+ *
+ * Spanning every pane is deliberate. A hidden pane is a display concern, not an
+ * evaluation one — measured in the browser, `indicatorValues` still carries
+ * `RSI:period=14`, `MACD:fast=12:slow=26:signal=9`, `Whale:threshold=50000`, `CVDApprox`
+ * and `StrengthElder` while those panes are collapsed.
+ *
+ * "Has a canonical key" needs no maintenance, unlike the blacklist it replaces: a new
+ * chart type or indicator is classified correctly by `buildIndicatorSeriesKey` alone.
+ *
+ * Module-level and exported so it can be tested directly. It is the whole fix, and a
+ * predicate buried in a component's `useMemo` is untestable — which is how the empty
+ * list survived three audit rounds.
+ */
+export declare function selectAlertableSeries(panes: readonly PaneDescriptor[]): SeriesConfig[];
+export declare class AlertManager {
+    private alerts;
+    private onAlertTriggeredCallbacks;
+    /** (alert, side, key) triples already reported by `reportUnreadableSubKey`, so a
+     *  permanently dead alert reports once instead of once per bar for the life of the
+     *  chart. In memory only: a reload re-reports, which is the right behaviour for a
+     *  diagnostic rather than a stored flag the user cannot see. */
+    private reportedUnreadable;
+    constructor();
+    getAlerts(): AlertCondition[];
+    addAlert(alert: AlertCondition): void;
+    removeAlert(id: string): void;
+    toggleAlert(id: string): void;
+    /**
+     * Register a listener. Returns a DISPOSER, and callers are expected to call it.
+     *
+     * This used to be push-only, so a React effect that subscribed without
+     * unsubscribing accumulated one listener per mount. The demo wraps the widget in
+     * `StrictMode` (`src/demo/index.tsx:37`), which mounts effects twice on the same
+     * instance, so ONE alert firing invoked every listener twice — measured in the
+     * browser as `DIALOG COUNT: 2` with two sounds. `indexOf` + `splice` (not
+     * `filter`) keeps repeated subscribe/unsubscribe cycles stable, and `indexOf`
+     * returning -1 makes a double-dispose a no-op rather than a removal of a
+     * different listener.
+     */
+    onAlertTriggered(cb: (alert: AlertCondition) => void): () => void;
+    checkAlerts(symbol: string, timeframe: string, current: any, previous: any, activeSeries: SeriesConfig[]): void;
+    /**
+     * Rewrite an alert's indicator instance ids into the canonical keys that
+     * `indicatorValues` is keyed by.
+     *
+     * Both failure branches below used to be silent, which is why this class of bug
+     * survived: an alert whose id could not be resolved kept the raw uuid, evaluated to
+     * `null`, never fired, and stayed in the list labelled "Active" with no trace of
+     * why. The two ids that reached here — a uuid belonging to a series the caller did
+     * not pass, and a uuid whose series has no canonical key at all — are both real
+     * states, so they are reported rather than swallowed.
+     *
+     * Measured on the demo layout, `strength/StrengthRelative` resolves to
+     * `StrengthRelative:compareSymbol=VNINDEX:period=14`, which no bar ever carries, so
+     * it hits the second branch. That is correct reporting of a genuine defect, not a
+     * new failure introduced here.
+     */
+    /**
+     * Report an indicator alert whose SUB-KEY cannot be read, which `resolveCanonicalKeys`
+     * cannot see and `AlertEvaluator` cannot express.
+     *
+     * An indicator alert has three distinct failure modes and only two were reported. The
+     * instance id may be unresolvable (C2), or its series may have no canonical key (C3) —
+     * both visible in `resolveCanonicalKeys`. But an alert can resolve perfectly and still
+     * be dead: the canonical key IS present in `indicatorValues`, its value IS an object,
+     * and the requested member is not on it — or the member is an array or boolean, or the
+     * key is blank. `getValue` then reads `val[key]` (or `val[""]`), gets undefined, and
+     * `evaluate` returns false on every bar forever with nothing logged anywhere. That is
+     * exactly how the old map's `StrengthElder: ["bull"]` stayed invisible: it offered a
+     * confident choice against a `{bullPower, bearPower}` value.
+     *
+     * Fires only when the value is present AND is an object, so it never duplicates the
+     * id-resolution reports and never fires for a SCALAR — there `getValue` ignores the
+     * sub-key entirely, which is why a blank key is correct rather than broken for RSI.
+     *
+     * Reported once per (alert, side, key). The condition is re-checked on every bar for
+     * the life of the alert, so reporting per evaluation would be a console flood rather
+     * than a diagnostic.
+     */
+    private reportUnreadableSubKey;
+    private resolveCanonicalKeys;
+    private triggerAlert;
+    /**
+     * POST one webhook delivery, reporting the three ways it can silently fail today.
+     *
+     * The old call was `fetch(url, {...}).catch(console.error)`, which has three holes that
+     * all look like success to the user, whose alert list still reads "Active":
+     *
+     *   - `fetch` only REJECTS on a network error. A webhook answering 404 or 500 resolves
+     *     normally, so the request was treated as delivered and nothing was logged. This is
+     *     the worst one: a mistyped or dead endpoint fails silently for the life of the alert.
+     *   - No timeout. An endpoint that accepts the connection and never responds leaves the
+     *     promise pending forever, and one such alert per symbol accumulates them.
+     *   - No `keepalive`, so a page that unloads right after firing — exactly when the user
+     *     most expects delivery — cancels the request in flight.
+     *
+     * The URL is validated before anything is sent, so a malformed value fails immediately
+     * and legibly instead of becoming a network error nobody can attribute.
+     *
+     * Every failure path also RECORDS on the alert (`lastDeliveryError`) and persists it.
+     * The console line is for a developer; the recorded state is for the user, who otherwise
+     * has no way to learn that their endpoint is rejecting deliveries. Both are kept: the
+     * console keeps the stack, the record survives a reload so the alerts list can still
+     * show it later. A successful delivery clears it.
+     */
+    private postWebhook;
+    private loadAlerts;
+    private saveAlerts;
+}

package/dist/dts/lib/alerts/types.d.ts

@@ -0,0 +1,58 @@
+export type AlertConditionType = "crossing" | "crossing_up" | "crossing_down" | "greater_than" | "less_than";
+export interface AlertSource {
+    type: "price" | "indicator" | "value";
+    indicatorId?: string;
+    key?: string;
+    value?: number;
+}
+export interface AlertCondition {
+    id: string;
+    symbol: string;
+    timeframe: string;
+    sourceA: AlertSource;
+    condition: AlertConditionType;
+    sourceB: AlertSource;
+    frequency: "once" | "once_per_bar" | "once_per_bar_close" | "continuous";
+    actions: {
+        popup: boolean;
+        sound: boolean;
+        email: boolean;
+        webhook?: string;
+    };
+    message: string;
+    createdAt: number;
+    isTriggered: boolean;
+    lastTriggeredBarTime?: number;
+    /**
+     * Whether the condition was satisfied at the previous evaluation. Only used by
+     * `frequency: "continuous"`, which fires on a false → true TRANSITION rather than on
+     * every evaluation.
+     *
+     * Persisted deliberately: without it, reloading a tab while the condition happens to be
+     * true would re-fire every continuous alert once on the first tick, which is the same
+     * storm in a smaller window. Only written when the value changes, so a live feed
+     * re-evaluating the same bar does not hammer localStorage.
+     */
+    lastConditionMet?: boolean;
+    /**
+     * Why the last webhook delivery failed, or `undefined` when the last attempt
+     * succeeded or there is no webhook configured.
+     *
+     * Persisted, and deliberately so. A delivery failure is not something the user can
+     * act on inside an eight-second toast — they need to open the alerts list later and
+     * still see that their endpoint is rejecting. Keeping it on the alert itself is what
+     * makes the failure discoverable at all: before this, a 500 from a user's webhook was
+     * indistinguishable from working, because `fetch` only rejects on a network error.
+     *
+     * Cleared on the next successful delivery, so a fixed endpoint does not leave a stale
+     * failure behind.
+     */
+    lastDeliveryError?: {
+        /** epoch ms */
+        at: number;
+        /** HTTP status when the endpoint answered; absent for network/invalid-URL failures. */
+        status?: number;
+        /** Short reason, already localised-agnostic — the UI formats it. */
+        reason: string;
+    };
+}

package/dist/dts/lib/cache/cacheDebug.d.ts

@@ -0,0 +1,3 @@
+export declare function isCacheDisabled(): boolean;
+export declare function getCacheTTL(defaultMs: number): number;
+export declare function enforceMaxSize<K, V>(map: Map<K, V>, maxEntries: number): void;

package/dist/dts/lib/calendars/ExchangeCalendar.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ExchangeCalendar — minimal interface for session-based gap classification.
+ *
+ * Used by the history planner to distinguish "market closed" gaps (weekends,
+ * outside session hours) from "not fetched" gaps that require a backfill request.
+ *
+ * Intentionally minimal: only public holidays are NOT modelled here (they change
+ * annually and require a data-maintenance concern separate from core logic).
+ */
+export interface ExchangeCalendar {
+    readonly calendarId: string;
+    /**
+     * Returns true if ANY trading time exists inside [fromMs, toMs).
+     * A missing segment whose entire range returns false here should be
+     * reclassified as `market-closed` and NOT enqueued for backfill.
+     */
+    hasAnyTradingTime(fromMs: number, toMs: number): boolean;
+}
+/**
+ * VN Exchange Calendar singleton for HOSE/HNX trading hours.
+ */
+export declare const vnExchangeCalendar: ExchangeCalendar;
+export declare function isVNTradingTime(epochMs: number): boolean;

package/dist/dts/lib/calendars/calendarRegistry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Calendar registry: maps sessionCalendarId strings to ExchangeCalendar instances.
+ * Adapters declare their calendar via SourceSemanticsDescriptor.sessionCalendarId;
+ * the widget uses this registry to look up the right calendar for gap classification.
+ */
+import type { ExchangeCalendar } from "./ExchangeCalendar";
+/**
+ * Returns the ExchangeCalendar for the given calendarId, or null if unknown.
+ */
+export declare function getCalendar(calendarId: string | undefined): ExchangeCalendar | null;

package/dist/dts/lib/calendars/index.d.ts

@@ -0,0 +1,3 @@
+export type { ExchangeCalendar } from "./ExchangeCalendar";
+export { vnExchangeCalendar, isVNTradingTime } from "./ExchangeCalendar";
+export { getCalendar } from "./calendarRegistry";

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

@@ -0,0 +1,8 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { PaneConfig } from "../types/pane";
+export interface ChartPaneProps extends HTMLAttributes<HTMLElement> {
+    pane: PaneConfig;
+    children?: ReactNode;
+}
+export declare function ChartPane({ pane, children, className, style, ...rest }: ChartPaneProps): import("react").JSX.Element;
+export type { ChartSyncState } from "./context/ChartSyncContext";

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

@@ -0,0 +1,70 @@
+/**
+ * ChartSplitter
+ * Library-level draggable pane-splitter for use with usePaneSizes.
+ *
+ * Renders as an absolutely-positioned overlay on top of a ChartCanvas container.
+ * During drag: only moves visually via CSS translateY (no React state churn).
+ * On release:  commits total delta to the parent via onCommitDelta (triggers
+ *              ChartCanvas remount via key when heights change).
+ *
+ * Styled by chart-splitter.css (.rsc-splitter). Extra classes can be merged
+ * via the `className` prop for custom styling.
+ *
+ * @example
+ * import { ChartSplitter, usePaneSizes } from "@vninvestcharts/widget";
+ * import "@vninvestcharts/widget/styles/chart-splitter.css";
+ *
+ * const { heights, applyDelta, reset, available } = usePaneSizes(chartHeight, { ... });
+ *
+ * // Between pane[0] and pane[1]:
+ * <ChartSplitter
+ *   splitterIndex={0}
+ *   available={available}
+ *   onCommitDelta={applyDelta}
+ *   onDoubleClick={reset}
+ *   style={{ top: marginTop + heights[0] }}
+ * />
+ */
+import type { CSSProperties, ForwardedRef } from "react";
+export interface ChartSplitterProps {
+    /** Index of this splitter: 0 = between pane[0] and pane[1], 1 = between pane[1] and pane[2], … */
+    splitterIndex: number;
+    /** Total usable height passed back to onCommitDelta. Use the `available` value from usePaneSizes. */
+    available: number;
+    /** Called with the full drag delta (px) when the pointer is released. */
+    onCommitDelta: (splitterIndex: number, deltaY: number, available: number) => void;
+    /** Optional handler for double-click (e.g. reset to default ratios). */
+    onDoubleClick?: () => void;
+    /**
+     * Additional CSS class names merged after the default `rsc-splitter` class.
+     * Use to apply custom styling or override defaults.
+     */
+    className?: string;
+    /** Inline styles merged with the translate preview during drag. */
+    style?: CSSProperties;
+    /** Tooltip/title shown on hover. */
+    title?: string;
+    minDeltaY?: number;
+    maxDeltaY?: number;
+    topHeight?: number;
+    bottomHeight?: number;
+    /** Accessible name for the separator (WCAG). Falls back to title if not provided. */
+    ariaLabel?: string;
+    /** Localized labels for the drag badge (Rule 1). Default to Top/Bottom for EN fallback. */
+    badgeTopLabel?: string;
+    badgeBottomLabel?: string;
+}
+export interface ChartSplitterHandle {
+    /** Synchronize geometry after parent layout commit */
+    syncGeometry: () => void;
+    /** Get current splitter geometry */
+    getGeometry: () => {
+        top: number;
+        height: number;
+    } | null;
+}
+export interface ChartSplitterWithHandleProps extends ChartSplitterProps {
+    /** Optional ref to access imperative methods */
+    handleRef?: ForwardedRef<ChartSplitterHandle>;
+}
+export declare const ChartSplitter: import("react").NamedExoticComponent<ChartSplitterWithHandleProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,12 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { StockDataAdapter } from "../types/adapter";
+import type { OHLCVBar } from "../types/ohlcv";
+import { type PaneInput } from "./hooks/usePaneManager";
+export interface ChartTerminalProps extends HTMLAttributes<HTMLElement> {
+    data: readonly OHLCVBar[];
+    panes: readonly PaneInput[];
+    adapter?: StockDataAdapter;
+    children?: ReactNode;
+}
+export declare function ChartTerminal({ data, panes, adapter, children, className, style, ...rest }: ChartTerminalProps): import("react").JSX.Element;
+export type { PaneInput } from "./hooks/usePaneManager";

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

@@ -0,0 +1,17 @@
+import React, { Component, ErrorInfo, ReactNode } from "react";
+interface Props {
+    fallback?: ReactNode;
+    children: ReactNode;
+    paneId: string;
+}
+interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+export declare class PaneErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
+}
+export {};