@363045841yyt/klinechart-core 0.8.11-alpha.1 → 0.8.12

package/src/components/footprint/types.ts

@@ -0,0 +1,232 @@
+/**
+ * Footprint Chart — public type contract.
+ *
+ * A Footprint chart expands each candle internally to show, at every price
+ * level, how much aggressive buying (lifting the ASK) and aggressive selling
+ * (hitting the BID) traded. It is the core tool of "order flow" reading:
+ * traders use it to answer "did this bar rise because there were real buyers,
+ * or only because sellers withdrew?".
+ *
+ * This module owns the **data model + classification math only**. Rendering
+ * belongs to the `@klinechart-quant/core` Renderer/Scene layer; the planned
+ * GPU compute path is sketched in `computeShader.wgsl.md`.
+ *
+ * See `docs/ROADMAP.md` §3.3 (Footprint) for the algorithm rationale and §0
+ * for how this controller fits the seven-module core layering.
+ *
+ * Cross-references:
+ *   - `aggressor.ts`   — buy/sell classification (explicit, tick rule, Lee-Ready)
+ *   - `perBarStats.ts` — delta, cumulative delta, diagonal imbalance
+ *   - `createFootprintController.ts` — streaming controller (Signal<bars>)
+ */
+
+import type { Signal } from '../../reactivity'
+
+// ---------------------------------------------------------------------------
+// Aggressor classification — shared with `aggressor.ts`
+// ---------------------------------------------------------------------------
+
+/**
+ * Which side of the resting book a trade hit.
+ *
+ *   - 'buy'  — aggressor lifted the ASK (resting seller was passive)
+ *   - 'sell' — aggressor hit the BID  (resting buyer was passive)
+ *
+ * Note: this is the **aggressor**'s side, NOT the "buyer"'s side. Binance's
+ * `isBuyerMaker=true` means the buyer was the maker (passive) and so the
+ * aggressor is the seller — see `classifyExplicit` in `aggressor.ts`.
+ */
+export type AggressorSide = 'buy' | 'sell'
+
+/**
+ * A classification's confidence flag.
+ *
+ *   - `inferred: false` — derived from an explicit exchange flag (zero error)
+ *   - `inferred: true`  — derived from a heuristic (tick rule or Lee-Ready);
+ *                         the consumer should mark this as approximate so it
+ *                         can be visually distinguished and excluded from
+ *                         strict order-flow analytics
+ *
+ * Every classifier in `aggressor.ts` must set this honestly. We rely on it
+ * downstream when surfacing "(estimated)" warnings on bars whose flow was
+ * inferred — this is the explicit boundary mandated by ROADMAP §3.3.
+ */
+export interface AggressorWithConfidence {
+    side: AggressorSide
+    inferred: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Trade inputs
+// ---------------------------------------------------------------------------
+
+/**
+ * A single trade print. The minimum shape needed for footprint aggregation.
+ *
+ * `timestamp` is epoch ms (chosen because `Math.floor(ts / barIntervalMs)`
+ * cleanly produces a bar index). `size` is in base units (BTC, AAPL shares,
+ * not USD value).
+ */
+export interface Trade {
+    timestamp: number
+    price: number
+    size: number
+}
+
+/**
+ * A trade carrying the exchange's aggressor flag. Binance-style:
+ * `isBuyerMaker=true` ⇒ the buyer was the passive maker, so the SELLER was
+ * the aggressor. Optional — if the exchange does not include it the
+ * controller falls back to the configured heuristic classifier.
+ */
+export interface TradeWithFlag extends Trade {
+    isBuyerMaker?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Bar shape
+// ---------------------------------------------------------------------------
+
+/**
+ * One price level inside a footprint bar.
+ *
+ * Cells are sorted by `price` ascending. `askVol` and `bidVol` are gross
+ * (not net) — the delta is computed separately.
+ */
+export interface FootprintBarCell {
+    /** representative price of the bin (quantised to tickSize). */
+    price: number
+    /** volume of trades classified as `buy` (aggressor lifted the ASK). */
+    askVol: number
+    /** volume of trades classified as `sell` (aggressor hit the BID). */
+    bidVol: number
+}
+
+/**
+ * Direction of a diagonal imbalance — see `perBarStats.ts` for the math.
+ */
+export type ImbalanceDirection = 'buy-imbalance' | 'sell-imbalance'
+
+/**
+ * One imbalance flag inside a bar.
+ *
+ * `priceIndex` is the index into `FootprintBar.cells` of the dominant side
+ * (not the cell it was compared against). `ratio` is `dominant / weaker`
+ * (always ≥ the configured threshold; capped at `Number.POSITIVE_INFINITY`
+ * when the weaker side is zero — see `computeDiagonalImbalances`).
+ */
+export interface FootprintImbalance {
+    priceIndex: number
+    direction: ImbalanceDirection
+    ratio: number
+}
+
+/**
+ * The materialised view of one bar (the unit a renderer consumes).
+ *
+ * All fields are derived from the controller's internal streaming aggregate;
+ * `cells` and `imbalances` are recomputed lazily on `bars` signal read.
+ */
+export interface FootprintBar {
+    /** stable index = `Math.floor(timestamp / barIntervalMs)`. */
+    barIndex: number
+    /** inclusive start of the bar window (epoch ms). */
+    startTime: number
+    /** exclusive end of the bar window (epoch ms). */
+    endTime: number
+    /** per-price-level cells, ascending by `price`. */
+    cells: ReadonlyArray<FootprintBarCell>
+    /** Σ(askVol − bidVol) across cells. Positive ⇒ buyers led. */
+    delta: number
+    /** Σ(askVol + bidVol). */
+    totalVolume: number
+    /** diagonal imbalance flags; usually 0–5 per bar. */
+    imbalances: ReadonlyArray<FootprintImbalance>
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Controller config. All fields required at the controller surface — the
+ * factory fills missing fields with sensible defaults so callers can pass
+ * a partial.
+ */
+export interface FootprintConfig {
+    /** quantise trade prices to this tick size (e.g. 0.01 for BTCUSDT). */
+    tickSize: number
+    /** ms per bar (e.g. 60_000 for 1m). */
+    barIntervalMs: number
+    /**
+     * Diagonal imbalance threshold. Default 3 — i.e. a cell must have at
+     * least 3× the volume of its diagonal counterpart to flag.
+     */
+    imbalanceRatio: number
+    /**
+     * Classifier to fall back to when a trade has no explicit
+     * `isBuyerMaker` flag.
+     *
+     *   - 'tick-rule' — price-change rule; default. Doesn't need bid/ask.
+     *   - 'lee-ready' — uses bid/ask; controller's `ingestTrade` must
+     *                   receive `bid` and `ask` for this path.
+     */
+    fallbackClassifier: 'tick-rule' | 'lee-ready'
+}
+
+// ---------------------------------------------------------------------------
+// Controller interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Framework-agnostic controller — mirrors `IndicatorSelectorController`'s
+ * shape (signals for state, plain functions for mutations, idempotent
+ * `dispose`).
+ */
+export interface FootprintController {
+    /** Current config; re-emits when `setConfig` is called. */
+    readonly config: Signal<FootprintConfig>
+    /** Materialised bars, ascending by `barIndex`. Empty before first trade. */
+    readonly bars: Signal<ReadonlyArray<FootprintBar>>
+    /**
+     * Cumulative delta series, parallel to `bars`. `cumulativeDelta[i]`
+     * corresponds to `bars[i]`.
+     */
+    readonly cumulativeDelta: Signal<ReadonlyArray<number>>
+
+    /**
+     * Ingest one trade — canonical method, aligned with the cross-controller
+     * `ingest()` convention (VolumeProfile, OrderBookHeatmap). `bid`/`ask` are
+     * optional and only consulted when the trade lacks an explicit
+     * `isBuyerMaker` flag AND the configured fallback is `lee-ready`.
+     *
+     * Closes API-audit BLOCKER-001 (5-verb intake proliferation) by
+     * harmonising on `ingest` as the stream-accumulator verb across
+     * `VolumeProfile`, `OrderBookHeatmap`, and `Footprint`.
+     */
+    ingest(trade: TradeWithFlag, bid?: number, ask?: number): void
+
+    /**
+     * @deprecated since 0.1.0-alpha.1 — use {@link FootprintController.ingest}.
+     * Kept as a non-removing alias for at least 6 months for migration. Will
+     * be removed in 0.2.0.
+     */
+    ingestTrade(trade: TradeWithFlag, bid?: number, ask?: number): void
+
+    /**
+     * Patch the config. Changing `barIntervalMs` or `tickSize` invalidates
+     * the buckets so the state is cleared. Changing only `imbalanceRatio`
+     * just re-materialises on the next read.
+     */
+    setConfig(next: Partial<FootprintConfig>): void
+
+    /** Clear all bars and cumulative delta. Does not change config. */
+    reset(): void
+
+    /**
+     * Stop emitting. Subsequent calls to ingest/setConfig/reset are silent
+     * no-ops; previously-attached subscribers receive no further
+     * notifications. Idempotent.
+     */
+    dispose(): void
+}

package/src/components/mtfOverlay/__tests__/alignToBaseIndex.test.ts

@@ -0,0 +1,103 @@
+/**
+ * alignToBaseIndex tests — forward fill + strict no-lookahead.
+ *
+ * The lookahead test is the load-bearing one: a naive implementation that
+ * uses `floor(t / targetIntervalMs) * targetIntervalMs` to pick the bar
+ * would expose future state. This file pins that out.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { alignToBaseIndex } from '../alignToBaseIndex'
+
+const HOUR = 60 * 60_000
+const MIN_5 = 5 * 60_000
+
+const ts = (ms: number): { timestamp: number } => ({ timestamp: ms })
+
+describe('alignToBaseIndex — basic behavior', () => {
+    it('empty base bars → []', () => {
+        expect(alignToBaseIndex([], [ts(0)], [42], HOUR)).toEqual([])
+    })
+
+    it('empty higher-tf series → all nulls', () => {
+        const base = [ts(0), ts(MIN_5), ts(2 * MIN_5)]
+        expect(alignToBaseIndex(base, [], [], HOUR)).toEqual([null, null, null])
+    })
+
+    it('throws if higherTfBars and higherTfValues length differ', () => {
+        expect(() => alignToBaseIndex([ts(0)], [ts(0)], [1, 2], HOUR)).toThrow(/length/)
+    })
+
+    it('throws on non-positive targetIntervalMs', () => {
+        expect(() => alignToBaseIndex([ts(0)], [ts(0)], [1], 0)).toThrow(/positive/)
+    })
+})
+
+describe('alignToBaseIndex — no-lookahead (critical)', () => {
+    it('base bar at hbar.timestamp reads that hbar value', () => {
+        const hbars = [ts(HOUR)] // hbar opens at 09:00 in arbitrary epoch terms
+        const values = [100]
+        const base = [ts(HOUR)]
+        expect(alignToBaseIndex(base, hbars, values, HOUR)).toEqual([100])
+    })
+
+    it('base bar 1ms BEFORE hbar.timestamp gets null (no lookahead)', () => {
+        const hbars = [ts(HOUR)]
+        const values = [100]
+        const base = [ts(HOUR - 1)]
+        expect(alignToBaseIndex(base, hbars, values, HOUR)).toEqual([null])
+    })
+
+    it('base bar deep inside hbar interval reads that hbar value', () => {
+        const hbars = [ts(HOUR)]
+        const values = [100]
+        const base = [ts(HOUR + 30 * 60_000)] // 30 min into the hour
+        expect(alignToBaseIndex(base, hbars, values, HOUR)).toEqual([100])
+    })
+
+    it('base bar at hbar.timestamp + targetIntervalMs (next bucket open) reads NEXT hbar', () => {
+        const hbars = [ts(HOUR), ts(2 * HOUR)]
+        const values = [100, 200]
+        const base = [ts(2 * HOUR)]
+        expect(alignToBaseIndex(base, hbars, values, HOUR)).toEqual([200])
+    })
+})
+
+describe('alignToBaseIndex — forward fill across many base bars', () => {
+    it('a 1h hbar covers all 12 of the 5m base bars inside it', () => {
+        const hbars = [ts(HOUR)]
+        const values = ['hot']
+        const base: { timestamp: number }[] = []
+        for (let i = 0; i < 12; i++) base.push(ts(HOUR + i * MIN_5))
+        const out = alignToBaseIndex(base, hbars, values, HOUR)
+        expect(out).toEqual(new Array(12).fill('hot'))
+    })
+
+    it('multiple hbars switch correctly at boundaries', () => {
+        const hbars = [ts(HOUR), ts(2 * HOUR), ts(3 * HOUR)]
+        const values = ['a', 'b', 'c']
+        const base = [
+            ts(HOUR),
+            ts(HOUR + 30 * 60_000),
+            ts(2 * HOUR),
+            ts(2 * HOUR + 30 * 60_000),
+            ts(3 * HOUR),
+        ]
+        expect(alignToBaseIndex(base, hbars, values, HOUR)).toEqual(['a', 'a', 'b', 'b', 'c'])
+    })
+
+    it('gap in hbars — base bars in the gap forward-fill the prior hbar', () => {
+        // hbar1 at 09:00, hbar2 at 11:00. base bar at 10:30 → forward-fill 'a'.
+        const hbars = [ts(HOUR), ts(3 * HOUR)]
+        const values = ['a', 'b']
+        const base = [ts(2 * HOUR + 30 * 60_000)]
+        expect(alignToBaseIndex(base, hbars, values, HOUR)).toEqual(['a'])
+    })
+
+    it('leading base bars before first hbar are all null', () => {
+        const hbars = [ts(HOUR)]
+        const values = ['x']
+        const base = [ts(0), ts(MIN_5), ts(HOUR)]
+        expect(alignToBaseIndex(base, hbars, values, HOUR)).toEqual([null, null, 'x'])
+    })
+})

package/src/components/mtfOverlay/__tests__/controller.test.ts

@@ -0,0 +1,172 @@
+/**
+ * MTF controller tests — series CRUD, recompute on mutation, EMA on a 1h
+ * overlay against 5m bars.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { createMtfController } from '../createMtfController'
+import type { BaseBar, ResampledBar } from '../types'
+
+const MIN = 60_000
+const FIVE_MIN = 5 * MIN
+const HOUR = 60 * MIN
+
+function bar(tsMs: number, c: number, v = 10): BaseBar {
+    return { timestamp: tsMs, open: c, high: c, low: c, close: c, volume: v }
+}
+
+/** A trivial "last close" compute fn for asserting against. */
+const lastClose = (rs: ReadonlyArray<ResampledBar>): number[] => rs.map((r) => r.close)
+
+describe('createMtfController — CRUD + recompute', () => {
+    it('addSeries returns id and series signal fires', () => {
+        const ctl = createMtfController({
+            initialBars: [bar(0, 100), bar(FIVE_MIN, 101)],
+            baseIntervalMs: FIVE_MIN,
+        })
+        const listener = vi.fn()
+        ctl.series.subscribe(listener)
+        const id = ctl.addSeries({
+            id: 'lastClose-1h',
+            label: 'last close 1h',
+            targetIntervalMs: HOUR,
+            compute: lastClose,
+        })
+        expect(id).toBe('lastClose-1h')
+        expect(listener).toHaveBeenCalled()
+        expect(ctl.series()).toHaveLength(1)
+    })
+
+    it('addSeries with duplicate id throws', () => {
+        const ctl = createMtfController({
+            initialBars: [bar(0, 100)],
+            baseIntervalMs: FIVE_MIN,
+        })
+        ctl.addSeries({ id: 'a', label: 'a', targetIntervalMs: HOUR, compute: lastClose })
+        expect(() =>
+            ctl.addSeries({ id: 'a', label: 'a2', targetIntervalMs: HOUR, compute: lastClose }),
+        ).toThrow(/already in use/)
+    })
+
+    it('addSeries with targetIntervalMs not a multiple of baseIntervalMs throws', () => {
+        const ctl = createMtfController({
+            initialBars: [bar(0, 100)],
+            baseIntervalMs: FIVE_MIN,
+        })
+        expect(() =>
+            ctl.addSeries({ id: 'a', label: 'a', targetIntervalMs: 7 * MIN, compute: lastClose }),
+        ).toThrow(/multiple/)
+    })
+
+    it('removeSeries returns true if found, false otherwise', () => {
+        const ctl = createMtfController({
+            initialBars: [bar(0, 100)],
+            baseIntervalMs: FIVE_MIN,
+        })
+        ctl.addSeries({ id: 'a', label: 'a', targetIntervalMs: HOUR, compute: lastClose })
+        expect(ctl.removeSeries('a')).toBe(true)
+        expect(ctl.removeSeries('a')).toBe(false)
+        expect(ctl.series()).toHaveLength(0)
+    })
+
+    it('updateSeries patches compute fn and re-runs it', () => {
+        const ctl = createMtfController({
+            initialBars: [bar(0, 100), bar(FIVE_MIN, 200)],
+            baseIntervalMs: FIVE_MIN,
+        })
+        ctl.addSeries({ id: 'a', label: 'a', targetIntervalMs: FIVE_MIN, compute: lastClose })
+        const beforeValues = ctl.series()[0]!.alignedValues
+        expect(beforeValues).toEqual([100, 200])
+        ctl.updateSeries('a', { compute: (rs) => rs.map(() => 42) })
+        expect(ctl.series()[0]!.alignedValues).toEqual([42, 42])
+    })
+})
+
+describe('createMtfController — alignment correctness', () => {
+    it('lifts a 1h compute onto 5m base bars (12 base bars share one hbar value)', () => {
+        const base: BaseBar[] = []
+        for (let i = 0; i < 12; i++) base.push(bar(i * FIVE_MIN, 100 + i))
+        const ctl = createMtfController({
+            initialBars: base,
+            baseIntervalMs: FIVE_MIN,
+        })
+        ctl.addSeries({
+            id: 'a',
+            label: 'last close 1h',
+            targetIntervalMs: HOUR,
+            compute: lastClose,
+        })
+        // All 12 base bars should see the same value — the close of the
+        // single 1h resampled bar covering 0..59 min, which is base[11].close = 111
+        const aligned = ctl.series()[0]!.alignedValues
+        expect(aligned).toEqual(new Array(12).fill(111))
+    })
+
+    it('appendBaseBar extends aligned series by exactly one entry', () => {
+        const base: BaseBar[] = [bar(0, 100)]
+        const ctl = createMtfController({ initialBars: base, baseIntervalMs: FIVE_MIN })
+        ctl.addSeries({
+            id: 'a',
+            label: 'a',
+            targetIntervalMs: FIVE_MIN,
+            compute: lastClose,
+        })
+        expect(ctl.series()[0]!.alignedValues).toEqual([100])
+        ctl.appendBaseBar(bar(FIVE_MIN, 200))
+        expect(ctl.series()[0]!.alignedValues).toEqual([100, 200])
+    })
+
+    it('two series at different higher TFs co-exist independently', () => {
+        const base: BaseBar[] = []
+        for (let i = 0; i < 12; i++) base.push(bar(i * FIVE_MIN, 100 + i))
+        const ctl = createMtfController({ initialBars: base, baseIntervalMs: FIVE_MIN })
+        ctl.addSeries({ id: '5m', label: '5m', targetIntervalMs: FIVE_MIN, compute: lastClose })
+        ctl.addSeries({ id: '1h', label: '1h', targetIntervalMs: HOUR, compute: lastClose })
+
+        const series = ctl.series()
+        expect(series).toHaveLength(2)
+        const fiveM = series.find((s) => s.definition.id === '5m')!
+        const oneH = series.find((s) => s.definition.id === '1h')!
+        // 5m series: each base bar reads its own close
+        expect(fiveM.alignedValues).toEqual(base.map((b) => b.close))
+        // 1h series: all 12 read the close of the single 1h bar = 111
+        expect(oneH.alignedValues).toEqual(new Array(12).fill(111))
+    })
+})
+
+describe('createMtfController — config + lifecycle', () => {
+    it('setBaseBars rebuilds all series', () => {
+        const ctl = createMtfController({
+            initialBars: [bar(0, 100)],
+            baseIntervalMs: FIVE_MIN,
+        })
+        ctl.addSeries({ id: 'a', label: 'a', targetIntervalMs: FIVE_MIN, compute: lastClose })
+        expect(ctl.series()[0]!.alignedValues).toEqual([100])
+        ctl.setBaseBars([bar(0, 1), bar(FIVE_MIN, 2)], FIVE_MIN)
+        expect(ctl.series()[0]!.alignedValues).toEqual([1, 2])
+    })
+
+    it('setBaseBars throws if an existing series target no longer cleanly divides', () => {
+        const ctl = createMtfController({
+            initialBars: [bar(0, 100)],
+            baseIntervalMs: FIVE_MIN,
+        })
+        ctl.addSeries({ id: 'a', label: 'a', targetIntervalMs: HOUR, compute: lastClose })
+        // Changing base to 7-minute bars makes 1h (3_600_000) no longer divisible by 7m (420_000)
+        expect(() => ctl.setBaseBars([bar(0, 1)], 7 * MIN)).toThrow(/cleanly divide/)
+    })
+
+    it('dispose silences subsequent mutators', () => {
+        const ctl = createMtfController({
+            initialBars: [bar(0, 100)],
+            baseIntervalMs: FIVE_MIN,
+        })
+        const listener = vi.fn()
+        ctl.series.subscribe(listener)
+        ctl.dispose()
+        const beforeCalls = listener.mock.calls.length
+        ctl.addSeries({ id: 'a', label: 'a', targetIntervalMs: FIVE_MIN, compute: lastClose })
+        ctl.appendBaseBar(bar(FIVE_MIN, 200))
+        expect(listener.mock.calls.length).toBe(beforeCalls)
+    })
+})

package/src/components/mtfOverlay/__tests__/resampleBars.test.ts

@@ -0,0 +1,106 @@
+/**
+ * resampleBars tests — bucketing math, partial bars, gap handling.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { resampleBars } from '../resampleBars'
+import type { BaseBar } from '../types'
+
+const min = 60_000
+const hour = 60 * min
+
+function bar(tsMs: number, o: number, h: number, l: number, c: number, v = 100): BaseBar {
+    return { timestamp: tsMs, open: o, high: h, low: l, close: c, volume: v }
+}
+
+describe('resampleBars — input validation', () => {
+    it('throws when targetIntervalMs is not a multiple of baseIntervalMs', () => {
+        // 1.5 min is not an integer multiple of 1 min
+        expect(() => resampleBars([], min, min + 30_000)).toThrow(/integer multiple/)
+    })
+
+    it('throws on non-positive intervals', () => {
+        expect(() => resampleBars([], 0, hour)).toThrow(/positive/)
+        expect(() => resampleBars([], min, -hour)).toThrow(/positive/)
+    })
+
+    it('returns [] for empty input', () => {
+        expect(resampleBars([], min, hour)).toEqual([])
+    })
+
+    it('targetIntervalMs === baseIntervalMs returns 1-to-1 wrapped bars', () => {
+        const bars = [bar(0, 1, 2, 0.5, 1.5), bar(min, 1.5, 3, 1, 2)]
+        const out = resampleBars(bars, min, min)
+        expect(out).toHaveLength(2)
+        expect(out[0]!.sourceStart).toBe(0)
+        expect(out[0]!.sourceEnd).toBe(0)
+        expect(out[0]!.open).toBe(1)
+        expect(out[1]!.sourceStart).toBe(1)
+    })
+})
+
+describe('resampleBars — aggregation rules', () => {
+    it('60 1m bars → 1 1h bar with correct OHLCV', () => {
+        const bars: BaseBar[] = []
+        for (let i = 0; i < 60; i++) {
+            bars.push(bar(i * min, 100 + i, 101 + i, 99 + i, 100 + i + 0.5, 10))
+        }
+        const out = resampleBars(bars, min, hour)
+        expect(out).toHaveLength(1)
+        expect(out[0]!.open).toBe(100)
+        expect(out[0]!.close).toBe(159.5)
+        expect(out[0]!.high).toBe(160) // 101 + 59
+        expect(out[0]!.low).toBe(99)
+        expect(out[0]!.volume).toBe(600)
+        expect(out[0]!.sourceStart).toBe(0)
+        expect(out[0]!.sourceEnd).toBe(59)
+    })
+
+    it('60 1m bars → 12 5m bars', () => {
+        const bars: BaseBar[] = []
+        for (let i = 0; i < 60; i++) {
+            bars.push(bar(i * min, 100, 101, 99, 100, 10))
+        }
+        const out = resampleBars(bars, min, 5 * min)
+        expect(out).toHaveLength(12)
+        for (const b of out) {
+            expect(b.volume).toBe(50)
+            expect(b.sourceEnd - b.sourceStart + 1).toBe(5)
+        }
+    })
+
+    it('partial final bucket is emitted (forming-bar visibility)', () => {
+        // 65 1m bars → 1 full 1h + 1 partial 1h (5 minutes)
+        const bars: BaseBar[] = []
+        for (let i = 0; i < 65; i++) {
+            bars.push(bar(i * min, 100, 101, 99, 100, 10))
+        }
+        const out = resampleBars(bars, min, hour)
+        expect(out).toHaveLength(2)
+        expect(out[1]!.sourceStart).toBe(60)
+        expect(out[1]!.sourceEnd).toBe(64)
+        expect(out[1]!.volume).toBe(50)
+    })
+
+    it('single base bar produces a single (partial) output bar', () => {
+        const out = resampleBars([bar(0, 1, 2, 0.5, 1.5)], min, hour)
+        expect(out).toHaveLength(1)
+        expect(out[0]!.sourceStart).toBe(0)
+        expect(out[0]!.sourceEnd).toBe(0)
+    })
+
+    it('input gap does not create a synthetic bucket; the missing minute is just absent', () => {
+        // 09:30, 09:31, [skip 09:32], 09:33, 09:34 → all fold into the same 5m bucket starting 09:30
+        const bars = [
+            bar(0, 100, 100, 100, 100, 10),
+            bar(min, 100, 100, 100, 100, 10),
+            bar(3 * min, 100, 100, 100, 100, 10),
+            bar(4 * min, 100, 100, 100, 100, 10),
+        ]
+        const out = resampleBars(bars, min, 5 * min)
+        expect(out).toHaveLength(1)
+        expect(out[0]!.volume).toBe(40) // 4 bars × 10
+        expect(out[0]!.sourceStart).toBe(0)
+        expect(out[0]!.sourceEnd).toBe(3)
+    })
+})