@forgecharts/sdk 1.1.23 → 1.1.28

package/dist/engine/CandleEngine.js

@@ -0,0 +1,318 @@
+/**
+ * CandleEngine — the single source of truth for live candle data.
+ *
+ * Architecture:
+ *
+ *   WebSocket feed
+ *       ↓
+ *   Market Data Normalizer  (normalizeOhlcv — handles strings, ms vs s)
+ *       ↓
+ *   CandleEngine            (applyCandleUpdate — O(1) update path)
+ *       ↓
+ *   Chart Update Adapter    (onBarUpdated / onResync callbacks)
+ *       ↓
+ *   Chart Library           (series.update / series.setData)
+ *
+ * Guarantees:
+ *   - open  is never overwritten on an existing live candle
+ *   - high  can only increase within a candle
+ *   - low   can only decrease within a candle
+ *   - close updates on every tick
+ *   - out-of-order ticks are silently discarded
+ *   - gaps are detected and reported for async REST backfill
+ *   - the engine is framework-agnostic (no DOM, React, or chart-lib imports)
+ */
+import { timeframeToMs, getCalendarBucketStart } from './timeframeUtils';
+import { getMissingBarCount, mergeBars } from './mergeUtils';
+import { assertOhlcRelationships, assertBucketAlignment, assertNotFinalized, assertOpenImmutability, assertNoDuplicateAppend, assertFinalizedUnchanged, } from './candleInvariants';
+// ─── Internal normalizer ─────────────────────────────────────────────────────
+/**
+ * Normalise a raw OHLCV object into a CandleBar.
+ *
+ * - Coerces all fields to `number` (handles numeric strings from the feed).
+ * - Auto-detects ms vs s timestamps: values > 1e12 are treated as milliseconds.
+ * - Aligns `timeMs` to the correct candle-open boundary, with calendar
+ *   alignment for `1w` (Monday) and `1M` (first of month).
+ *
+ * Never use `Date.now()` for candle time — always use the feed-provided value.
+ */
+function normalizeOhlcv(raw, intervalMs, tf) {
+    const rawTime = Number(raw.time);
+    // Auto-detect: Unix ms timestamps are > 1e12 (year 2001+).
+    // If the value is smaller, treat it as seconds and convert.
+    const timeMs = rawTime > 1e12 ? rawTime : rawTime * 1000;
+    // Calendar-aware bucket alignment (handles 1w/1M specially)
+    const bucketMs = getCalendarBucketStart(timeMs, tf);
+    const timeSec = Math.floor(bucketMs / 1000);
+    return {
+        timeMs: bucketMs,
+        time: timeSec,
+        open: Number(raw.open),
+        high: Number(raw.high),
+        low: Number(raw.low),
+        close: Number(raw.close),
+        volume: Number(raw.volume ?? 0),
+        isClosed: raw.isClosed ?? false,
+    };
+}
+// ─── CandleEngine ─────────────────────────────────────────────────────────────
+export class CandleEngine {
+    /** Authoritative ordered bar array. Only the rightmost bar may be open. */
+    _bars = [];
+    _timeframe = '1m';
+    _intervalMs = 60_000;
+    _opts;
+    constructor(options = {}) {
+        this._opts = options;
+    }
+    // ── Initialisation ──────────────────────────────────────────────────────────
+    /**
+     * Seed the engine with historical bars and set the active timeframe.
+     * All existing bars are replaced.
+     *
+     * Historical bars loaded from REST are assumed closed, except possibly
+     * the last one (which may represent the still-forming candle).
+     *
+     * @param history   Raw bars from a REST endpoint (oldest → newest).
+     * @param timeframe The active timeframe label (e.g. '1m', '1h').
+     */
+    initialize(history, timeframe) {
+        this._timeframe = timeframe;
+        this._intervalMs = timeframeToMs(timeframe);
+        // Normalise, deduplicate by timeMs (latest entry wins), sort newest-last
+        const seen = new Map();
+        for (const raw of history) {
+            const bar = normalizeOhlcv(raw, this._intervalMs, this._timeframe);
+            seen.set(bar.timeMs, bar);
+        }
+        this._bars = Array.from(seen.values()).sort((a, b) => a.timeMs - b.timeMs);
+        // Mark all bars except the last as closed
+        for (let i = 0; i < this._bars.length - 1; i++) {
+            this._bars[i].isClosed = true;
+        }
+        this._debugLog('initialize', {
+            timeframe,
+            intervalMs: this._intervalMs,
+            barCount: this._bars.length,
+            firstTime: this._bars[0]?.timeMs,
+            lastTime: this._bars[this._bars.length - 1]?.timeMs,
+        });
+    }
+    // ── Live updates ────────────────────────────────────────────────────────────
+    /**
+     * Process a single live OHLCV tick from the WebSocket feed.
+     *
+     * Algorithm (mirrors TradingView / Binance candle engine behaviour):
+     *
+     *  1. Normalise: coerce strings to numbers, detect ms vs s, align to bucket.
+     *  2. Empty array → append as first bar.
+     *  3. incoming.timeMs === last.timeMs  → SAME CANDLE (update in-place):
+     *       open   = unchanged               (first tick's open is authoritative)
+     *       high   = max(last.high, inc.high, inc.close)
+     *       low    = min(last.low,  inc.low,  inc.close)
+     *       close  = inc.close
+     *       volume = inc.volume
+     *  4. incoming.timeMs  > last.timeMs  → NEW CANDLE:
+     *       - Detect and report any gap (missing buckets between last and incoming).
+     *       - Mark last bar as closed, fire onBarClosed.
+     *       - Append incoming as a fresh live candle.
+     *  5. incoming.timeMs  < last.timeMs  → OUT-OF-ORDER: discard silently.
+     *
+     * @returns UpdateResult indicating what was done — the chart adapter uses
+     *   this to choose between series.update() and series.setData().
+     */
+    applyLiveUpdate(raw) {
+        const incoming = normalizeOhlcv(raw, this._intervalMs, this._timeframe);
+        // Invariant: incoming bar must be bucket-aligned and OHLC-valid
+        assertBucketAlignment(incoming, this._timeframe, 'applyLiveUpdate:normalize');
+        assertOhlcRelationships(incoming, 'applyLiveUpdate:normalize');
+        // ── First bar ever ─────────────────────────────────────────────────────
+        if (this._bars.length === 0) {
+            this._bars.push(incoming);
+            const result = { type: 'append', bar: incoming, previousBarClosed: false };
+            this._debugLog('append:first', incoming);
+            this._opts.onBarUpdated?.(incoming, result);
+            return result;
+        }
+        const last = this._bars[this._bars.length - 1];
+        // ── Same candle: update in-place (O(1)) ────────────────────────────────
+        if (incoming.timeMs === last.timeMs) {
+            // Invariant: must not mutate a finalized candle
+            assertNotFinalized(last, 'applyLiveUpdate:same-bucket');
+            const prevOpen = last.open;
+            const prevCount = this._bars.length;
+            // open is intentionally not updated — the first tick's open is correct
+            last.high = Math.max(last.high, incoming.high, incoming.close);
+            last.low = Math.min(last.low, incoming.low, incoming.close);
+            last.close = incoming.close;
+            last.volume = incoming.volume;
+            // Invariant: open must be unchanged, no spurious append must have occurred
+            assertOpenImmutability(prevOpen, last, 'applyLiveUpdate:same-bucket');
+            assertOhlcRelationships(last, 'applyLiveUpdate:same-bucket');
+            assertNoDuplicateAppend(prevCount, this._bars.length, 'applyLiveUpdate:same-bucket');
+            const result = { type: 'update', bar: last };
+            this._debugLog('update', last);
+            this._opts.onBarUpdated?.(last, result);
+            return result;
+        }
+        // ── Out-of-order: older than the current live candle ──────────────────
+        if (incoming.timeMs < last.timeMs) {
+            this._debugLog('ignore', {
+                incomingTimeMs: incoming.timeMs,
+                lastTimeMs: last.timeMs,
+                delta: last.timeMs - incoming.timeMs,
+            });
+            return { type: 'ignore' };
+        }
+        // ── New candle (incoming.timeMs > last.timeMs) ─────────────────────────
+        // Gap detection: how many candle buckets are missing between last and new?
+        const missingCount = getMissingBarCount(last.timeMs, incoming.timeMs, this._intervalMs);
+        if (missingCount > 0) {
+            const gapInfo = { fromTimeMs: last.timeMs, toTimeMs: incoming.timeMs, missingCount };
+            this._debugLog('gap', gapInfo);
+            this._opts.onGapDetected?.(gapInfo);
+        }
+        // Finalise the previous live candle
+        const prevLastBar = { ...last }; // snapshot for post-append invariant check
+        last.isClosed = true;
+        this._opts.onBarClosed?.(last);
+        // Append the new candle
+        this._bars.push(incoming);
+        // Invariant: previous bar must be closed and not mutated after the append
+        assertFinalizedUnchanged(prevLastBar, this._bars, 'applyLiveUpdate:new-bucket');
+        assertOhlcRelationships(incoming, 'applyLiveUpdate:new-bucket');
+        const result = missingCount > 0
+            ? { type: 'gap', bar: incoming, missingCount }
+            : { type: 'append', bar: incoming, previousBarClosed: true };
+        this._debugLog(result.type, incoming);
+        this._opts.onBarUpdated?.(incoming, result);
+        return result;
+    }
+    // ── Gap backfill ────────────────────────────────────────────────────────────
+    /**
+     * Merge REST-fetched bars into the engine to fill a detected gap.
+     *
+     * Incoming bars are treated as authoritative closed candles.
+     * The current live candle is preserved if present.
+     *
+     * After calling this, `onResync` fires — the chart adapter must call
+     * `series.setData(engine.getBars())` to fully resync the chart.
+     *
+     * @param rawBars  Historical bars from the REST endpoint covering the gap.
+     */
+    backfillGap(rawBars) {
+        const incoming = rawBars.map(r => {
+            const bar = normalizeOhlcv(r, this._intervalMs, this._timeframe);
+            bar.isClosed = true; // REST bars are closed and authoritative
+            return bar;
+        });
+        // Preserve the live candle's open state after merge
+        const liveBefore = this._bars[this._bars.length - 1];
+        this._bars = mergeBars(this._bars, incoming);
+        // Re-apply live candle's isClosed=false if it survived the merge
+        if (liveBefore && !liveBefore.isClosed) {
+            const last = this._bars[this._bars.length - 1];
+            if (last && last.timeMs === liveBefore.timeMs) {
+                last.isClosed = false;
+            }
+        }
+        this._debugLog('backfillGap', { filled: rawBars.length, totalBars: this._bars.length });
+        this._opts.onResync?.(this._bars);
+    }
+    // ── Reconnect reconciliation ────────────────────────────────────────────────
+    /**
+     * Reconcile after a WebSocket reconnect.
+     *
+     * Fetch a rolling overlap window from REST (e.g. last 50 bars or 2 hours)
+     * and pass them here. The engine merges them with the existing bar array,
+     * correcting any candles that were missed or corrupted during the outage.
+     *
+     * After reconciliation, `onResync` fires so the chart adapter can resync
+     * the chart series with `series.setData(engine.getBars())`.
+     *
+     * @param recentBars  REST bars covering the reconnect overlap window.
+     */
+    handleReconnect(recentBars) {
+        const incoming = recentBars.map(r => normalizeOhlcv(r, this._intervalMs, this._timeframe));
+        this._bars = mergeBars(this._bars, incoming);
+        this._debugLog('handleReconnect', { count: recentBars.length, totalBars: this._bars.length });
+        this._opts.onResync?.(this._bars);
+    }
+    // ── Trade-tick stub ─────────────────────────────────────────────────────────
+    /**
+     * Stub for future tick/trade-based candle construction.
+     *
+     * When implemented, this will:
+     *   - Assign the trade to its bucket using `getBucketStart(timeMs, intervalMs)`.
+     *   - Create a new candle if the bucket is absent.
+     *   - Update OHLCV: open/close from trade price, high/low expanded, volume summed.
+     *
+     * Not yet implemented — structure is in place for future extension.
+     */
+    applyTradeTick(_trade) {
+        // TODO: implement tick-based candle construction
+    }
+    // ── Read access ─────────────────────────────────────────────────────────────
+    /**
+     * Returns a readonly view of the authoritative bar array.
+     * Do not mutate — call `applyLiveUpdate`, `backfillGap`, etc. instead.
+     */
+    getBars() {
+        return this._bars;
+    }
+    /** Returns the most recent (possibly still live) bar, or null if empty. */
+    getLastBar() {
+        return this._bars[this._bars.length - 1] ?? null;
+    }
+    /**
+     * Prepend older historical bars fetched during a lazy scroll-left page load.
+     * Only bars older than the current oldest bar are accepted; duplicates and
+     * out-of-range bars are silently dropped.
+     * Fires `onResync` so the chart adapter updates the series with `setData`.
+     *
+     * @param rawBars  Historical bars from the REST endpoint, oldest → newest.
+     */
+    prependHistory(rawBars) {
+        const oldest = this._bars[0];
+        const cutoff = oldest ? oldest.timeMs : Infinity;
+        const incoming = rawBars
+            .map(r => {
+            const bar = normalizeOhlcv(r, this._intervalMs, this._timeframe);
+            bar.isClosed = true;
+            return bar;
+        })
+            .filter(bar => bar.timeMs < cutoff);
+        if (incoming.length === 0)
+            return;
+        incoming.sort((a, b) => a.timeMs - b.timeMs);
+        this._bars = [...incoming, ...this._bars];
+        this._debugLog('prependHistory', {
+            prepended: incoming.length,
+            firstTime: this._bars[0]?.timeMs,
+        });
+        this._opts.onResync?.(this._bars);
+    }
+    /**
+     * Clear all state.
+     * Call before switching symbol or timeframe, or on a hard disconnect.
+     */
+    reset() {
+        this._bars = [];
+        this._debugLog('reset', { timeframe: this._timeframe });
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────────
+    _debugLog(action, data) {
+        if (!this._opts.debug)
+            return;
+        console.debug('[CANDLE_ENGINE]', {
+            action,
+            timeframe: this._timeframe,
+            barCount: this._bars.length,
+            liveBar: this._bars[this._bars.length - 1]
+                ? { open: this._bars[this._bars.length - 1].open, high: this._bars[this._bars.length - 1].high, low: this._bars[this._bars.length - 1].low, close: this._bars[this._bars.length - 1].close }
+                : null,
+            ...data,
+        });
+    }
+}
+//# sourceMappingURL=CandleEngine.js.map

package/dist/engine/CandleEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CandleEngine.js","sourceRoot":"","sources":["../../src/engine/CandleEngine.ts"],"names":[],"mappings":"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"}

package/dist/engine/__tests__/CandleEngine.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=CandleEngine.test.d.ts.map

package/dist/engine/__tests__/CandleEngine.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CandleEngine.test.d.ts","sourceRoot":"","sources":["../../../src/engine/__tests__/CandleEngine.test.ts"],"names":[],"mappings":""}

package/dist/engine/__tests__/CandleEngine.test.js

@@ -0,0 +1,300 @@
+import { describe, it, expect, vi } from 'vitest';
+import { CandleEngine } from '../CandleEngine';
+import { timeframeToMs, getBucketStart } from '../timeframeUtils';
+import { getMissingBarCount, mergeBars } from '../mergeUtils';
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/** Build a minimal raw bar with time in seconds. */
+function rawBar(timeSec, open, high, low, close, volume = 1, isClosed = false) {
+    return { time: timeSec, open, high, low, close, volume, isClosed };
+}
+/** Build a raw bar with time in milliseconds. */
+function rawBarMs(timeSec, open, high, low, close) {
+    return { time: timeSec * 1000, open, high, low, close, volume: 1 };
+}
+// 1-minute boundary: 2024-07-03T10:00:00Z = 1719997200 seconds
+const T0 = 1_719_997_200;
+const T1 = T0 + 60;
+const T2 = T0 + 120;
+const T3 = T0 + 180;
+const T4 = T0 + 240;
+// ─── 1. Same-candle update ────────────────────────────────────────────────────
+describe('same-candle update (3 ticks, same bucket)', () => {
+    it('produces exactly one candle with correct O/H/L/C', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+        engine.applyLiveUpdate(rawBar(T0, 100, 108, 96, 107)); // high rises, low drops
+        engine.applyLiveUpdate(rawBar(T0, 100, 107, 97, 106)); // high recedes — not applied
+        expect(engine.getBars().length).toBe(1);
+        const bar = engine.getLastBar();
+        expect(bar.open).toBe(100); // open preserved from first tick
+        expect(bar.high).toBe(108); // max of all ticks
+        expect(bar.low).toBe(96); // min of all ticks
+        expect(bar.close).toBe(106); // close from latest tick
+    });
+    it('returns UpdateResult type "update" for same-candle ticks', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        const r1 = engine.applyLiveUpdate(rawBar(T0, 100, 100, 100, 100));
+        const r2 = engine.applyLiveUpdate(rawBar(T0, 100, 110, 90, 105));
+        expect(r1.type).toBe('append'); // first tick is an append
+        expect(r2.type).toBe('update');
+    });
+    it('high can never decrease within a candle', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T0, 50, 120, 40, 100));
+        engine.applyLiveUpdate(rawBar(T0, 50, 80, 60, 90)); // high=80 < 120
+        expect(engine.getLastBar().high).toBe(120);
+    });
+    it('low can never increase within a candle', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T0, 50, 120, 40, 100));
+        engine.applyLiveUpdate(rawBar(T0, 50, 110, 75, 105)); // low=75 > 40
+        expect(engine.getLastBar().low).toBe(40);
+    });
+});
+// ─── 2. New-candle append ─────────────────────────────────────────────────────
+describe('new-candle append (time advances)', () => {
+    it('appends a second candle and marks first as closed', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+        const result = engine.applyLiveUpdate(rawBar(T1, 103, 110, 101, 108));
+        expect(result.type).toBe('append');
+        expect(engine.getBars().length).toBe(2);
+        expect(engine.getBars()[0].isClosed).toBe(true);
+        expect(engine.getBars()[1].isClosed).toBe(false);
+    });
+    it('appended candle uses the new tick\'s open price', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+        engine.applyLiveUpdate(rawBar(T1, 200, 210, 195, 205));
+        expect(engine.getBars()[1].open).toBe(200);
+    });
+});
+// ─── 3. Out-of-order discard ──────────────────────────────────────────────────
+describe('out-of-order ticks', () => {
+    it('discards ticks older than the current live candle', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T1, 103, 110, 100, 107)); // at T1
+        const result = engine.applyLiveUpdate(rawBar(T0, 100, 120, 95, 115)); // T0 < T1
+        expect(result.type).toBe('ignore');
+        expect(engine.getBars().length).toBe(1);
+        expect(engine.getLastBar().time).toBe(T1);
+    });
+    it('does not change any OHLCV values after discarding', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T1, 103, 110, 100, 107));
+        const snapBefore = { ...engine.getLastBar() };
+        engine.applyLiveUpdate(rawBar(T0, 999, 999, 1, 999));
+        expect(engine.getLastBar().open).toBe(snapBefore.open);
+        expect(engine.getLastBar().high).toBe(snapBefore.high);
+        expect(engine.getLastBar().low).toBe(snapBefore.low);
+        expect(engine.getLastBar().close).toBe(snapBefore.close);
+    });
+});
+// ─── 4. Gap detection ─────────────────────────────────────────────────────────
+describe('gap detection', () => {
+    it('fires onGapDetected when a bucket is skipped', () => {
+        const gaps = [];
+        const engine = new CandleEngine({ onGapDetected: (g) => gaps.push(g) });
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+        // Jump 3 minutes — T1 and T2 are missing
+        engine.applyLiveUpdate(rawBar(T3, 110, 115, 108, 113));
+        expect(gaps.length).toBe(1);
+        expect(gaps[0].missingCount).toBe(2);
+        expect(gaps[0].fromTimeMs).toBe(T0 * 1000);
+        expect(gaps[0].toTimeMs).toBe(T3 * 1000);
+    });
+    it('returns UpdateResult type "gap" when a gap occurs', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+        const result = engine.applyLiveUpdate(rawBar(T4, 103, 108, 101, 106));
+        expect(result.type).toBe('gap');
+        if (result.type === 'gap') {
+            expect(result.missingCount).toBe(3);
+        }
+    });
+    it('does not fire onGapDetected for consecutive candles', () => {
+        const gapFn = vi.fn();
+        const engine = new CandleEngine({ onGapDetected: gapFn });
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+        engine.applyLiveUpdate(rawBar(T1, 103, 108, 101, 106));
+        expect(gapFn).not.toHaveBeenCalled();
+    });
+});
+// ─── 5. Reconnect reconciliation ─────────────────────────────────────────────
+describe('handleReconnect', () => {
+    it('deduplicates bars correctly when there is overlap', () => {
+        const engine = new CandleEngine();
+        engine.initialize([
+            rawBar(T0, 100, 105, 98, 103, 10, true),
+            rawBar(T1, 103, 108, 101, 106, 12, true),
+            rawBar(T2, 106, 110, 104, 109, 8, false), // live
+        ], '1m');
+        // Reconnect brings T1 and T2 with corrected values
+        engine.handleReconnect([
+            rawBar(T1, 103, 112, 99, 111, 15, true), // corrected T1
+            rawBar(T2, 106, 111, 103, 110, 9, false), // corrected T2 (live)
+        ]);
+        expect(engine.getBars().length).toBe(3);
+        expect(engine.getBars()[1].high).toBe(112); // T1 updated
+        expect(engine.getBars()[2].high).toBe(111); // T2 updated
+    });
+    it('fires onResync after handleReconnect', () => {
+        const resyncFn = vi.fn();
+        const engine = new CandleEngine({ onResync: resyncFn });
+        engine.initialize([rawBar(T0, 100, 105, 98, 103)], '1m');
+        engine.handleReconnect([rawBar(T0, 100, 107, 96, 104)]);
+        expect(resyncFn).toHaveBeenCalledOnce();
+    });
+});
+// ─── 6. ms → s timestamp conversion ─────────────────────────────────────────
+describe('millisecond vs second timestamp normalisation', () => {
+    it('converts ms timestamps to seconds correctly', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        // T0 in ms
+        engine.applyLiveUpdate(rawBarMs(T0, 100, 105, 98, 103));
+        const bar = engine.getLastBar();
+        expect(bar.time).toBe(T0); // chart field = seconds
+        expect(bar.timeMs).toBe(T0 * 1000); // engine field = ms
+    });
+    it('handles both ms and s inputs in the same session without corruption', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(rawBarMs(T0, 100, 105, 98, 103)); // ms
+        engine.applyLiveUpdate(rawBar(T0, 100, 110, 95, 108)); // seconds, same bucket
+        expect(engine.getBars().length).toBe(1); // same bucket → still one candle
+        expect(engine.getLastBar().high).toBe(110);
+    });
+    it('floors ms timestamp to candle boundary', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        // T0 + 30s (mid-candle) in ms → should still map to T0 bucket
+        engine.applyLiveUpdate({ time: (T0 + 30) * 1000, open: 100, high: 105, low: 98, close: 103 });
+        expect(engine.getLastBar().time).toBe(T0);
+    });
+});
+// ─── 7. Custom timeframe aggregation (timeframeUtils) ────────────────────────
+describe('timeframeUtils helpers', () => {
+    it('timeframeToMs returns correct durations', () => {
+        expect(timeframeToMs('1m')).toBe(60_000);
+        expect(timeframeToMs('5m')).toBe(300_000);
+        expect(timeframeToMs('1h')).toBe(3_600_000);
+        expect(timeframeToMs('4h')).toBe(14_400_000);
+        expect(timeframeToMs('1d')).toBe(86_400_000);
+        // 1w and 1M are calendar timeframes — no fixed ms duration.
+        // timeframeUtils returns the 60_000 compat fallback so CandleEngine
+        // always receives a finite number (calendar alignment is handled separately).
+        expect(timeframeToMs('1w')).toBe(60_000);
+    });
+    it('timeframeToMs falls back to 60_000 for unknown labels', () => {
+        // '3h' and '8h' are orphaned (excluded from canonical registry) → 60_000 fallback.
+        // '2m' is now registered (120_000) — use genuinely unknown keys here.
+        expect(timeframeToMs('3h')).toBe(60_000);
+        expect(timeframeToMs('')).toBe(60_000);
+    });
+    it('getBucketStart floors to candle boundary', () => {
+        expect(getBucketStart(62_000, 60_000)).toBe(60_000); // 1m01s → 1m00s
+        expect(getBucketStart(3_720_000, 3_600_000)).toBe(3_600_000); // 1h02m → 1h00m
+        expect(getBucketStart(0, 60_000)).toBe(0);
+    });
+    it('5m candle engine buckets a mid-bar tick to the 5m open', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '5m');
+        const T5m = getBucketStart(T0 * 1000, timeframeToMs('5m')); // floor T0 to 5m
+        const mid = T5m / 1000 + 120; // 2 minutes into the 5m bucket
+        engine.applyLiveUpdate({ time: mid, open: 50, high: 55, low: 48, close: 52 });
+        expect(engine.getLastBar().timeMs).toBe(T5m);
+    });
+});
+// ─── 8. mergeUtils helpers ────────────────────────────────────────────────────
+describe('mergeUtils helpers', () => {
+    const makeBar = (timeSec, close, isClosed) => ({
+        timeMs: timeSec * 1000,
+        time: timeSec,
+        open: 100, high: 110, low: 90, close,
+        volume: 1, isClosed,
+    });
+    it('getMissingBarCount returns 0 for consecutive bars', () => {
+        expect(getMissingBarCount(T0 * 1000, T1 * 1000, 60_000)).toBe(0);
+    });
+    it('getMissingBarCount returns correct count for gap', () => {
+        expect(getMissingBarCount(T0 * 1000, T3 * 1000, 60_000)).toBe(2); // T1 and T2
+        expect(getMissingBarCount(T0 * 1000, T4 * 1000, 60_000)).toBe(3); // T1, T2, T3
+    });
+    it('mergeBars deduplicates by timeMs with incoming winning', () => {
+        const existing = [makeBar(T0, 103, true), makeBar(T1, 106, true)];
+        const incoming = [makeBar(T1, 999, true), makeBar(T2, 110, false)]; // T1 override
+        const merged = mergeBars(existing, incoming);
+        expect(merged.length).toBe(3);
+        expect(merged[1].close).toBe(999); // incoming wins for closed bar
+        expect(merged[2].time).toBe(T2);
+    });
+    it('mergeBars preserves existing live candle when incoming is also live and same time', () => {
+        const existing = [makeBar(T0, 103, false)]; // live, close=103
+        const incoming = [makeBar(T0, 107, false)]; // fresher live tick, close=107
+        const merged = mergeBars(existing, incoming);
+        // Live bar: incoming wins because it is the freshest tick
+        expect(merged[0].close).toBe(107);
+    });
+    it('mergeBars sorts output by timeMs', () => {
+        const bars = [makeBar(T2, 100, true), makeBar(T0, 100, true), makeBar(T1, 100, true)];
+        const sorted = mergeBars(bars, []);
+        expect(sorted.map(b => b.time)).toEqual([T0, T1, T2]);
+    });
+});
+// ─── 9. backfillGap ───────────────────────────────────────────────────────────
+describe('backfillGap', () => {
+    it('fills missing buckets and fires onResync', () => {
+        const resyncFn = vi.fn();
+        const engine = new CandleEngine({ onResync: resyncFn });
+        engine.initialize([
+            rawBar(T0, 100, 105, 98, 103),
+            rawBar(T3, 110, 115, 108, 113), // gap: T1, T2 missing
+        ], '1m');
+        engine.backfillGap([
+            rawBar(T1, 103, 108, 101, 106),
+            rawBar(T2, 106, 110, 104, 109),
+        ]);
+        expect(engine.getBars().length).toBe(4);
+        expect(resyncFn).toHaveBeenCalledOnce();
+        const times = engine.getBars().map(b => b.time);
+        expect(times).toEqual([T0, T1, T2, T3]);
+    });
+});
+// ─── 10. CandleEngine lifecycle ──────────────────────────────────────────────
+describe('lifecycle', () => {
+    it('reset() clears all bars', () => {
+        const engine = new CandleEngine();
+        engine.initialize([rawBar(T0, 100, 105, 98, 103)], '1m');
+        engine.reset();
+        expect(engine.getBars().length).toBe(0);
+        expect(engine.getLastBar()).toBeNull();
+    });
+    it('handles initialize() with empty history', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        expect(engine.getBars().length).toBe(0);
+        expect(engine.getLastBar()).toBeNull();
+    });
+    it('handles duplicate historical bars (keeps last per timeMs)', () => {
+        const engine = new CandleEngine();
+        engine.initialize([
+            rawBar(T0, 100, 105, 98, 103),
+            rawBar(T0, 100, 110, 96, 108), // same time, last should win
+        ], '1m');
+        expect(engine.getBars().length).toBe(1);
+        expect(engine.getLastBar().high).toBe(110);
+    });
+});
+//# sourceMappingURL=CandleEngine.test.js.map