@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/grid/MemoryBudgetManager.d.ts

@@ -0,0 +1,63 @@
+export interface MemoryReport {
+    totalHeapEstimate: number;
+    activeContexts: number;
+    status: 'normal' | 'warning' | 'critical' | 'emergency';
+}
+export interface DeviceProfile {
+    maxWebGLContexts: number;
+    maxHeapBudget: number;
+    isMobile: boolean;
+    isLowEnd: boolean;
+    deviceType: 'ios-safari' | 'android-chrome' | 'desktop' | 'unknown';
+}
+export declare class MemoryBudgetManager {
+    private static lruList;
+    private static MAX_HEAP_BUDGET;
+    private static MAX_WEBGL_CONTEXTS;
+    private static deviceProfile;
+    static register(id: string): void;
+    static unregister(id: string): void;
+    static touch(id: string): void;
+    /**
+     * Detect device performance profile based on user agent and hardware concurrency
+     * Returns dynamic limits for WebGL contexts and heap budget
+     * Uses DeviceProfiles for centralized configuration
+     */
+    static getDevicePerformanceProfile(): DeviceProfile;
+    /**
+     * Get the current device profile (computes if not cached)
+     */
+    static getCurrentProfile(): DeviceProfile;
+    /**
+     * Reset device profile cache (useful for testing)
+     */
+    static resetDeviceProfile(): void;
+    static getEstimate(): MemoryReport;
+    static enforceBudget(activeChartId: string | null): void;
+    /**
+     * Freeze a specific chart context (called by IntersectionObserver)
+     * Captures snapshot before freezing for visual continuity
+     */
+    static freezeContext(chartId: string): Promise<void>;
+    /**
+     * Thaw a specific chart context (called by IntersectionObserver)
+     * Restores from snapshot for seamless visual transition
+     */
+    static thawContext(chartId: string): Promise<void>;
+    /**
+     * Get performance metrics for devtools
+     */
+    static getPerformanceMetrics(): import("./PerformanceMonitor").PerformanceReport;
+    /**
+     * Start frame time monitoring
+     */
+    static startPerformanceMonitoring(): void;
+    /**
+     * Stop frame time monitoring
+     */
+    static stopPerformanceMonitoring(): void;
+    /**
+     * Log performance report to console
+     */
+    static logPerformanceReport(): void;
+}

package/dist/dts/widget/grid/PerformanceMonitor.d.ts

@@ -0,0 +1,70 @@
+/**
+ * PerformanceMonitor - Tracks freeze/thaw performance metrics for WebGL management
+ * Exposes metrics to devtools for debugging and optimization
+ */
+export interface FreezeThawMetrics {
+    freezeCount: number;
+    thawCount: number;
+    totalFreezeLatencyMs: number;
+    totalThawLatencyMs: number;
+    totalSnapshotCaptureMs: number;
+    totalSnapshotRestoreMs: number;
+    totalMemoryReclaimedBytes: number;
+    lastFreezeTimestamp: number | null;
+    lastThawTimestamp: number | null;
+    averageFreezeLatencyMs: number;
+    averageThawLatencyMs: number;
+    averageSnapshotCaptureMs: number;
+    averageSnapshotRestoreMs: number;
+}
+export interface FrameTimeMetrics {
+    frameCount: number;
+    totalFrameTimeMs: number;
+    averageFrameTimeMs: number;
+    maxFrameTimeMs: number;
+    minFrameTimeMs: number;
+    droppedFrames: number;
+}
+export interface PerformanceReport {
+    freezeThaw: FreezeThawMetrics;
+    frameTime: FrameTimeMetrics;
+    memory: {
+        currentHeapUsed: number;
+        currentHeapTotal: number;
+        peakHeapUsed: number;
+        webglContextsActive: number;
+    };
+    timestamp: number;
+}
+declare class PerformanceMonitor {
+    private static instance;
+    private freezeThawMetrics;
+    private frameTimeMetrics;
+    private frameTimeHistory;
+    private maxHistorySize;
+    private rafId;
+    private lastFrameTime;
+    private isMonitoring;
+    private constructor();
+    static getInstance(): PerformanceMonitor;
+    recordFreezeStart(): number;
+    recordFreezeEnd(startTime: number, memoryReclaimed?: number, snapshotCaptureMs?: number): void;
+    recordThawStart(): number;
+    recordThawEnd(startTime: number, snapshotRestoreMs?: number): void;
+    startFrameMonitoring(): void;
+    stopFrameMonitoring(): void;
+    private tick;
+    getReport(): PerformanceReport;
+    logReport(): void;
+    exposeToDevTools(): void;
+    reset(): void;
+    getFrameTimePercentile(percentile: number): number;
+    getFrameTimeStats(): {
+        p50: number;
+        p90: number;
+        p95: number;
+        p99: number;
+    };
+}
+export declare const performanceMonitor: PerformanceMonitor;
+export default PerformanceMonitor;

package/dist/dts/widget/grid/customPresets.d.ts

@@ -0,0 +1,42 @@
+import type { LayoutPreset } from "./types";
+/**
+ * P0 — lưu layout preset do người dùng định nghĩa.
+ *
+ * Trước P0: `LayoutDesigner.handleSavePreset` build preset rồi gọi
+ * `onSaveAsPreset?.(preset)`, mà call site duy nhất là `onSaveAsPreset={() => {}}` +
+ * `availablePresets={[]}` (`VNInvestMultiCharts.tsx:1455-1456`). Người dùng đặt tên, bấm
+ * Save, modal đóng, **không có gì được lưu và không có báo lỗi** ⇒ vi phạm Rule 15
+ * (cấm nuốt im lặng).
+ *
+ * Hàm thuần, không React, nhận `StorageLike` ⇒ test được trong node. Dùng storage **tiêm
+ * vào** (`storageAdapter`) chứ không `localStorage` trực tiếp, khác với
+ * `ChartSerializer` — vì raw `localStorage` làm hỏng SSR/iframe/host-injected storage.
+ *
+ * Capability: `layout_user` là **pro** (`engine capabilities.ts:140`). Vì vậy gate thuộc
+ * về call site (`VNInvestMultiCharts`), không gate ở đây — store chỉ lo "lưu/đọc đúng".
+ */
+export declare const CUSTOM_PRESETS_KEY = "vnsc.layout.customPresets";
+/** Chỉ cần đúng hai phép; `StorageAdapter` của widget thỏa cả hai. */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface StoredPresetShape {
+    id: string;
+    name: string;
+    layout: unknown;
+    category?: string;
+}
+/**
+ * Đọc danh sách preset đã lưu. **Luôn trả mảng** — JSON hỏng hoặc storage lỗi thì trả
+ * `[]`, không ném. Người dùng phải còn dùng được chart khi storage hỏng.
+ */
+export declare function readCustomPresets(storage: StorageLike | null | undefined): LayoutPreset[];
+/**
+ * Ghi thêm một preset. Trả `false` nếu không lưu được (storage lỗi) — **không** im lặng
+ * thành công, vì đó chính là lỗi mà P0 đang sửa.
+ */
+export declare function addCustomPreset(storage: StorageLike | null | undefined, preset: LayoutPreset): boolean;
+/** Xoá preset theo id. Trả `true` nếu thực sự có thay đổi. */
+export declare function removeCustomPreset(storage: StorageLike | null | undefined, id: string): boolean;

package/dist/dts/widget/grid/presets.d.ts

@@ -0,0 +1,18 @@
+import { LayoutPreset } from "./types";
+import type { ChartLayout } from "@vninvestcharts/engine-react";
+export declare const L_SHAPE_PRESET: LayoutPreset;
+export declare const T_SHAPE_PRESET: LayoutPreset;
+export declare const MAIN_3_SIDEBAR_PRESET: LayoutPreset;
+export declare const QUAD_FOCUS_PRESET: LayoutPreset;
+export declare const SYMMETRIC_PRESETS: LayoutPreset[];
+export declare const ASYMMETRIC_PRESETS: LayoutPreset[];
+export declare const CUSTOM_PRESET: LayoutPreset;
+export declare const ALL_PRESETS: LayoutPreset[];
+export declare const PRESETS_BY_CATEGORY: {
+    symmetric: LayoutPreset[];
+    asymmetric: LayoutPreset[];
+    focus: LayoutPreset[];
+    custom: LayoutPreset[];
+};
+export declare function findMatchingPreset(layout: ChartLayout): LayoutPreset;
+export default ALL_PRESETS;

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

@@ -0,0 +1,39 @@
+import { SymbolLinkGroupId } from '@vninvestcharts/engine-react';
+export interface SlotConfig {
+    id: string;
+    rowStart: number;
+    rowEnd: number;
+    colStart: number;
+    colEnd: number;
+    symbol?: string;
+    timeframe?: string;
+    symbolLinkGroup?: SymbolLinkGroupId | null;
+    areaName?: string;
+    zIndex?: number;
+}
+export interface GridLayout {
+    rows: number;
+    cols: number;
+    slots: SlotConfig[];
+    rowSizes: string[];
+    colSizes: string[];
+    templateAreas?: string[];
+    areas?: Record<string, SlotConfig>;
+}
+export interface SplitterConfig {
+    id: string;
+    orientation: 'vertical' | 'horizontal';
+    gridIndex: number;
+    minSizeBeforePx: number;
+    minSizeAfterPx: number;
+}
+export interface LayoutPreset {
+    id: string;
+    name: string;
+    nameKey?: string;
+    layout: GridLayout;
+    description?: string;
+    descriptionKey?: string;
+    thumbnail?: string;
+    category?: 'symmetric' | 'asymmetric' | 'focus' | 'custom';
+}

package/dist/dts/widget/history/BackfillDedupContext.d.ts

@@ -0,0 +1,63 @@
+import React from "react";
+import type { StockDataAdapter } from "../../lib/types/adapter";
+import { createHistoryChunkStore, type ResidentWindow } from "./chunkStore";
+import { createSingleWriterLane } from "./singleWriterLane";
+/**
+ * Cross-chart backfill deduplication (Layer B).
+ *
+ * Backfill (reconcileVisibleHistoryWindow) calls `adapter.fetchBarsBefore` /
+ * `fetchBarsInRange` directly and does NOT go through `RequestCoordinator`
+ * (Layer A). When several charts in a MultiChart view the same symbol@tf and
+ * pan simultaneously, each fires its own identical request → N× API calls.
+ *
+ * This context holds an in-flight map keyed by request signature so that
+ * concurrent identical backfill requests from different charts share a single
+ * network call. It is intentionally SEPARATE from `RequestCoordinator` (which
+ * only coordinates initial load / MTF / compare).
+ *
+ * The dedup key excludes `chartId`: if the underlying adapter returns different
+ * data for the same range depending on chartId, dedup must NOT be applied (see
+ * test "dedup respects chartId independence").
+ */
+export type BackfillDedupValue = {
+    register(key: string, p: Promise<readonly any[]>): void;
+    get(key: string): Promise<readonly any[]> | undefined;
+};
+export declare function BackfillDedupProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+export declare function useBackfillDedup(): BackfillDedupValue | null;
+/**
+ * Run `fn` once per `key`. Concurrent callers with the same key share the same
+ * promise. When no dedup context is present (SingleChart standalone), `fn`
+ * runs normally.
+ */
+export declare function withBackfillDedup(ctx: BackfillDedupValue | null, key: string, fn: () => Promise<readonly any[] | null>): Promise<readonly any[] | null>;
+/**
+ * Wrap an adapter so that `fetchBarsBefore` / `fetchBarsInRange` participate in
+ * cross-chart backfill dedup. The dedup key is derived purely from the request
+ * arguments (symbol, tf, range) and deliberately EXCLUDES chartId.
+ */
+export declare function dedupWrapAdapter(adapter: StockDataAdapter, ctx: BackfillDedupValue): StockDataAdapter;
+interface SharedStoreEntry {
+    store: ReturnType<typeof createHistoryChunkStore>;
+    lane: ReturnType<typeof createSingleWriterLane>;
+    refCount: number;
+    residents: Map<string, ResidentWindow>;
+}
+type SharedBarStoreValue = {
+    getOrCreate(key: string): SharedStoreEntry;
+    release(key: string, subscriberId: string): void;
+    registerResident(key: string, subscriberId: string, resident: ResidentWindow): void;
+    getUnionResident(key: string): ResidentWindow | null;
+    updateResident(key: string, subscriberId: string, resident: ResidentWindow): void;
+};
+export declare function SharedBarStoreProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+export declare function useSharedBarStore(): SharedBarStoreValue | null;
+export declare function useSharedBarStoreSubscription(key: string, subscriberId: string, _initialResident?: ResidentWindow): {
+    store: ReturnType<typeof createHistoryChunkStore>;
+    lane: ReturnType<typeof createSingleWriterLane>;
+} | null;
+export {};

package/dist/dts/widget/history/RequestCoordinator.d.ts

@@ -0,0 +1,59 @@
+import React from "react";
+export interface CoordinatorFetchParams {
+    symbol: string;
+    timeframe: string;
+    from: Date;
+    to: Date;
+    chartId?: string;
+    /**
+     * DATA-03: data-source identity. Without it the cache/dedup key was
+     * `symbol|timeframe|from|to`, so two widgets pointing at DIFFERENT adapters
+     * (e.g. two tenants, or live vs demo) shared one cache entry and could serve
+     * each other's bars. Callers pass a stable, non-secret identifier of the
+     * source (e.g. adapter class + base). Never put a raw PAT in here.
+     */
+    scope?: string;
+}
+/**
+ * Cross-chart request coordinator.
+ *
+ * - Global max inflight: 4 requests across all charts
+ * - Per-adapter rate limit: token bucket (2 requests / 500ms sliding window)
+ * - Cross-chart dedup via coarse key (symbol|tf|rounded-hour-from|rounded-hour-to)
+ *   for historical data; exact timestamps used when `to` is within 1h of "now"
+ *   to prevent stale current-candle from cache.
+ * - Near-now requests (to within 1h of now) bypass cache entirely — current
+ *   candle is mutable and will be updated by WS ticker_update.
+ * - Subscriber tracking: only abort inflight when ALL subscribers have unmounted
+ * - Result cache with 30s TTL + LRU eviction (max 50 entries)
+ */
+export declare class RequestCoordinator {
+    readonly maxGlobalInflight = 4;
+    readonly perAdapterTokens = 2;
+    private inflight;
+    private subscribers;
+    private cache;
+    private adapterTokenBuckets;
+    private pendingQueue;
+    private processing;
+    private makeKey;
+    private getAdapterLabel;
+    private checkAdapterTokens;
+    private evictStaleCache;
+    private processQueue;
+    enqueue<T>(fetchFn: (signal: AbortSignal) => Promise<T>, params: CoordinatorFetchParams, priority: number, callerId: string, signal?: AbortSignal): Promise<T>;
+    getInflightCount(): number;
+    getPendingCount(): number;
+    reset(): void;
+}
+export declare function useRequestCoordinator(): RequestCoordinator;
+/**
+ * Test isolation hook: reset the module-level fallback coordinator between
+ * tests. Contract tests render without a RequestCoordinatorProvider (like
+ * single-chart embeds), so they share this instance — without a reset,
+ * token-bucket + cache state leaks across tests and starves later fetches.
+ */
+export declare function resetFallbackRequestCoordinatorForTests(): void;
+export declare function RequestCoordinatorProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;

package/dist/dts/widget/history/SharedBarStoreContext.d.ts

@@ -0,0 +1,22 @@
+import React from "react";
+import type { ResidentWindow } from "./chunkStore";
+import { createHistoryChunkStore } from "./chunkStore";
+import { createSingleWriterLane } from "./singleWriterLane";
+interface SharedBarStoreContextValue {
+    /**
+     * Get or create a shared store for the given cache key.
+     * Returns the shared store and a release function to call on unmount or key change.
+     */
+    getOrCreate: (cacheKey: string, chartId: string, initialResident: ResidentWindow) => {
+        store: ReturnType<typeof createHistoryChunkStore>;
+        lane: ReturnType<typeof createSingleWriterLane>;
+        release: () => void;
+        updateResident: (resident: ResidentWindow) => void;
+        trimToSharedWindow: (resident: ResidentWindow, maxBars?: number, trimLeft?: boolean, trimRight?: boolean) => void;
+    };
+}
+export declare function useSharedBarStore(): SharedBarStoreContextValue | null;
+export declare function SharedBarStoreProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+export {};

package/dist/dts/widget/history/cache/IndexedDBCacheMatrix.d.ts

@@ -0,0 +1,16 @@
+import type { LocalCacheMatrix, LocalCacheMatrixFactory, TimeRange } from "./LocalCacheMatrix";
+/**
+ * Normalizes an array of ranges by union-merging overlapping or contiguous intervals.
+ * Expects ranges to be sorted or will sort them internally.
+ */
+export declare function normalizeRanges(ranges: readonly TimeRange[]): readonly TimeRange[];
+/**
+ * Computes missing segments (gaps) in targetRange not covered by coverageRanges.
+ */
+export declare function computeMissingTimeRanges(targetRange: TimeRange, coverageRanges: readonly TimeRange[]): TimeRange[];
+/**
+ * Native factory class matching barrel exports
+ */
+export declare class LocalCacheMatrixFactoryImpl implements LocalCacheMatrixFactory {
+    create(cacheRoot: string): LocalCacheMatrix;
+}

package/dist/dts/widget/history/cache/LocalCacheMatrix.d.ts

@@ -0,0 +1,86 @@
+import type { SourceSemanticsDescriptor } from "../../../lib/adapters";
+import type { OHLCVBar } from "../../../lib/types/ohlcv";
+export interface CacheKeyParts {
+    readonly source: string;
+    readonly symbol: string;
+    readonly timeframe: string;
+    readonly adjustmentPolicy: string;
+    readonly schemaVersion: string;
+}
+export type CacheKey = string;
+export interface TimeRange {
+    readonly fromTs: number;
+    readonly toTs: number;
+}
+export interface CacheSegmentMeta {
+    readonly file: string;
+    readonly fromTs: number;
+    readonly toTs: number;
+    readonly barCount: number;
+    readonly checksum: string;
+    readonly lastAccessedAt: string;
+}
+export interface CacheSemanticScope {
+    readonly sourceContractVersion: SourceSemanticsDescriptor["sourceContractVersion"];
+    readonly instrumentClass: SourceSemanticsDescriptor["instrumentClass"];
+    readonly sessionModel: SourceSemanticsDescriptor["sessionModel"];
+    readonly sessionCalendarId?: SourceSemanticsDescriptor["sessionCalendarId"];
+    readonly timezone: SourceSemanticsDescriptor["timezone"];
+    readonly finalityMode: SourceSemanticsDescriptor["finalityMode"];
+    readonly correctionLookbackMs?: SourceSemanticsDescriptor["correctionLookbackMs"];
+}
+export interface CacheCoverageIndex {
+    readonly schemaVersion: string;
+    readonly cacheKey: CacheKey;
+    readonly revision: number;
+    readonly semanticScope?: CacheSemanticScope;
+    readonly ranges: readonly TimeRange[];
+    readonly segments: readonly CacheSegmentMeta[];
+}
+export interface CacheReadResult {
+    readonly bars: readonly OHLCVBar[];
+    readonly missingRanges: readonly TimeRange[];
+}
+export interface CacheWriteMeta {
+    readonly requestId: string;
+    readonly sessionRevision: number;
+    readonly reason: "remote-fill" | "warmup" | "repair";
+    readonly semanticScope?: CacheSemanticScope;
+}
+export interface CacheWriteResult {
+    readonly cacheKey: CacheKey;
+    readonly revision: number;
+    readonly writtenBarCount: number;
+    readonly affectedRanges: readonly TimeRange[];
+}
+export type CacheInvalidateReason = "schema-mismatch" | "adjustment-policy-changed" | "source-contract-changed" | "manual";
+export interface CacheEvictPolicy {
+    readonly globalQuotaMb: number;
+    readonly symbolSoftCapMb: number;
+}
+export interface CacheEvictResult {
+    readonly reclaimedBytes: number;
+    readonly deletedSegmentCount: number;
+}
+/**
+ * Runtime abstraction for local file-cache matrix.
+ *
+ * Notes:
+ * - readRanges must not throw on cache misses; it should return missingRanges.
+ * - writePatch is expected to enforce validation + dedupe + sort before commit.
+ */
+export interface LocalCacheMatrix {
+    getCoverage(cacheKey: CacheKey, expectedScope?: CacheSemanticScope): Promise<CacheCoverageIndex | null>;
+    readRanges(cacheKey: CacheKey, ranges: readonly TimeRange[], expectedScope?: CacheSemanticScope): Promise<CacheReadResult>;
+    writePatch(cacheKey: CacheKey, bars: readonly OHLCVBar[], meta: CacheWriteMeta): Promise<CacheWriteResult>;
+    invalidate(cacheKey: CacheKey, reason: CacheInvalidateReason): Promise<void>;
+    evict(policy: CacheEvictPolicy): Promise<CacheEvictResult>;
+}
+export interface LocalCacheMatrixFactory {
+    create(cacheRoot: string): LocalCacheMatrix;
+}
+/**
+ * Canonical cache key formatter matching CACHE_FILE_CONTRACT.
+ */
+export declare function toCacheKey(parts: CacheKeyParts): CacheKey;
+export declare function toCacheSemanticScope(sourceSemantics: SourceSemanticsDescriptor): CacheSemanticScope;

package/dist/dts/widget/history/cache/index.d.ts

@@ -0,0 +1,3 @@
+export type { CacheCoverageIndex, CacheEvictPolicy, CacheEvictResult, CacheInvalidateReason, CacheKey, CacheKeyParts, CacheReadResult, CacheSemanticScope, CacheSegmentMeta, CacheWriteMeta, CacheWriteResult, LocalCacheMatrix, LocalCacheMatrixFactory, TimeRange, } from "./LocalCacheMatrix";
+export { toCacheKey, toCacheSemanticScope } from "./LocalCacheMatrix";
+export { LocalCacheMatrixFactoryImpl } from "./IndexedDBCacheMatrix";

package/dist/dts/widget/history/chunkStore.d.ts

@@ -0,0 +1,77 @@
+import type { OHLCVBar } from "../../lib/types/ohlcv";
+/** A time window defined by inclusive epoch-millisecond bounds. */
+export interface ResidentWindow {
+    readonly startMs: number;
+    readonly endMs: number;
+}
+/** The kind of mutation that produced a HistoryPatch. */
+export type HistoryPatchKind = "replace" | "prepend" | "append" | "trim";
+/**
+ * An immutable snapshot of the full resident bar set at a given revision.
+ * Consumers may hold onto this without worrying about the store mutating it.
+ */
+export interface HistorySnapshot {
+    readonly bars: readonly OHLCVBar[];
+    readonly revision: number;
+}
+/**
+ * A description of one mutation applied to a HistoryChunkStore.
+ * `snapshot` reflects the store state AFTER the mutation.
+ */
+export interface HistoryPatch {
+    readonly kind: HistoryPatchKind;
+    readonly snapshot: HistorySnapshot;
+    /** Number of bars added at the head (prepend / replace that extends head). */
+    readonly prependedCount: number;
+    /** Number of bars added at the tail (append / replace that extends tail). */
+    readonly appendedCount: number;
+    /** Number of bars removed from the head (trim). */
+    readonly trimmedFromHead: number;
+    /** Number of bars removed from the tail (trim). */
+    readonly trimmedFromTail: number;
+}
+/**
+ * HistoryChunkStore manages the resident OHLCV bar set for a single
+ * symbol/timeframe session.  It enforces:
+ *   - Chronological sort order (by `date` ascending)
+ *   - No duplicate timestamps
+ *   - Stable logical timeline: prepend/trim never shift existing bar positions
+ *
+ * The store is intentionally synchronous and mutation-safe.  All mutating
+ * methods return the resulting HistorySnapshot or HistoryPatch so callers
+ * can decide when to flush the change into React state.
+ */
+export interface HistoryChunkStore {
+    /**
+     * Replace the entire resident set with `bars`.  Bars are sorted by date;
+     * duplicates are deduplicated (last occurrence wins).
+     * Returns the new snapshot.
+     */
+    replaceAll(bars: readonly OHLCVBar[]): HistorySnapshot;
+    /**
+     * Prepend bars that are OLDER than the current head.
+     * Bars with timestamps >= current head are silently dropped to preserve
+     * logical timeline stability (no re-ordering of existing bars).
+     * Returns a HistoryPatch describing what changed.
+     */
+    prepend(bars: readonly OHLCVBar[]): HistoryPatch;
+    /**
+     * Append one or more bars newer than the current tail, or update/insert
+     * a single bar at any position (for live tick updates).
+     * Returns a HistoryPatch describing what changed.
+     */
+    append(bars: readonly OHLCVBar[]): HistoryPatch;
+    /**
+     * Remove bars outside `window`.  Returns null when nothing was trimmed,
+     * or a HistoryPatch with trimmedFromHead / trimmedFromTail counts.
+     * Optionally caps the remaining bars at `maxBars` to protect memory.
+     */
+    trimToWindow(window: ResidentWindow, maxBars?: number, trimLeft?: boolean, trimRight?: boolean): HistoryPatch | null;
+    /** Return the current snapshot without mutating the store. */
+    toSnapshot(): HistorySnapshot;
+}
+/**
+ * Create a new, empty HistoryChunkStore.
+ * Call once per widget history session; reset via `replaceAll([])`.
+ */
+export declare function createHistoryChunkStore(): HistoryChunkStore;

package/dist/dts/widget/history/externalBarsNormalization.d.ts

@@ -0,0 +1,9 @@
+import type { OHLCVBar } from "../../lib/types/ohlcv";
+export interface ExternalBarsNormalizationResult {
+    bars: OHLCVBar[];
+    invalidCount: number;
+    firstError: string | null;
+}
+export declare function buildExternalDataValidationError(result: ExternalBarsNormalizationResult): Error | null;
+export declare function normalizeExternalBar(bar: unknown, index: number): OHLCVBar;
+export declare function normalizeExternalBars(data: readonly unknown[] | undefined | null): ExternalBarsNormalizationResult;

package/dist/dts/widget/history/externalBarsNormalization.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/widget/history/externalBarsNormalizationAsync.d.ts

@@ -0,0 +1,25 @@
+import { type ExternalBarsNormalizationResult } from "./externalBarsNormalization";
+export declare const EXTERNAL_BARS_WORKER_THRESHOLD = 10000;
+export interface ExternalBarsNormalizationWorkerRequest {
+    readonly requestId: number;
+    readonly data: readonly unknown[] | undefined | null;
+}
+export interface ExternalBarsNormalizationWorkerResponse {
+    readonly requestId: number;
+    readonly result?: ExternalBarsNormalizationResult;
+    readonly error?: string;
+}
+export interface ExternalBarsNormalizationWorkerLike {
+    onmessage: ((this: Worker, event: MessageEvent<ExternalBarsNormalizationWorkerResponse>) => void) | null;
+    onerror: ((this: AbstractWorker, event: ErrorEvent) => void) | null;
+    postMessage(message: ExternalBarsNormalizationWorkerRequest): void;
+    terminate(): void;
+}
+export interface NormalizeExternalBarsAsyncOptions {
+    readonly signal?: AbortSignal;
+    readonly workerFactory?: () => ExternalBarsNormalizationWorkerLike;
+    readonly useWorker?: boolean;
+}
+export declare const EMPTY_EXTERNAL_BARS_NORMALIZATION_RESULT: ExternalBarsNormalizationResult;
+export declare function shouldUseExternalBarsWorker(data: readonly unknown[] | undefined | null): boolean;
+export declare function normalizeExternalBarsAsync(data: readonly unknown[] | undefined | null, options?: NormalizeExternalBarsAsyncOptions): Promise<ExternalBarsNormalizationResult>;