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

package/src/components/orderBookHeatmap/types.ts

@@ -0,0 +1,168 @@
+/**
+ * L2 Order Book Heatmap — public types.
+ *
+ * Implements the data model described in `docs/ROADMAP.md` §3.2.
+ *
+ * Critique addressed (PR23): the live render path uses fixed-cadence
+ * snapshots (cheap to upload to a GPU storage buffer), while a parallel
+ * append-only delta archive preserves the full event stream so that
+ * sub-snapshot "flash orders" can be replayed exactly. Snapshot ring is
+ * the render source; delta archive is the source of truth.
+ *
+ * No file in this module imports from `src/` — this component is part of
+ * the additive `packages/core/` work.
+ */
+
+import type { Signal } from '../../reactivity'
+
+// ---------------------------------------------------------------------------
+// Inbound stream
+// ---------------------------------------------------------------------------
+
+/**
+ * One exchange-pushed delta. `size === 0` means the price level is removed.
+ *
+ * Timestamp is the **exchange** wall-clock in milliseconds — we use it as
+ * the controller's clock so the system is deterministic for tests and
+ * correct under bursty traffic (no setInterval).
+ */
+export interface OrderBookDelta {
+    side: 'bid' | 'ask'
+    price: number
+    size: number
+    timestamp: number
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot
+// ---------------------------------------------------------------------------
+
+/**
+ * Immutable view of the book at one instant. Prices in this object are
+ * always returned in their **dequantized** (real-world) form — clients
+ * never see the integer tick index.
+ *
+ * Bids are sorted descending (best bid first), asks ascending (best ask
+ * first). Each entry is `[price, size]`.
+ */
+export interface BookSnapshot {
+    readonly bids: ReadonlyArray<readonly [number, number]>
+    readonly asks: ReadonlyArray<readonly [number, number]>
+    readonly timestamp: number
+}
+
+// ---------------------------------------------------------------------------
+// State accumulator
+// ---------------------------------------------------------------------------
+
+export interface OrderBookStateOptions {
+    /** quantize all input prices to this tick (e.g. 0.01 = cents) */
+    tickSize: number
+    /** keep at most this many levels per side; oldest-by-distance dropped */
+    maxLevels?: number
+}
+
+export interface OrderBookState {
+    /** Apply one delta. `size === 0` removes the level. */
+    applyDelta(delta: OrderBookDelta): void
+    /** Take a fresh snapshot (prices dequantized). */
+    snapshot(): BookSnapshot
+    /** Empty both sides. */
+    clear(): void
+    /** Latest timestamp seen via {@link applyDelta}. */
+    lastTimestamp(): number
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot ring (live render path)
+// ---------------------------------------------------------------------------
+
+export interface SnapshotRing {
+    readonly capacity: number
+    push(snapshot: BookSnapshot): void
+    /** snapshots oldest → newest; never contains gaps */
+    toArray(): ReadonlyArray<BookSnapshot>
+    size(): number
+    clear(): void
+}
+
+// ---------------------------------------------------------------------------
+// Delta archive (replay path)
+// ---------------------------------------------------------------------------
+
+export interface DeltaArchive {
+    append(delta: OrderBookDelta): void
+    /** inclusive range; deltas with `from <= ts <= to` */
+    range(fromTimestamp: number, toTimestamp: number): ReadonlyArray<OrderBookDelta>
+    size(): number
+    clear(): void
+    /** drop oldest deltas until total size ≤ maxSize */
+    trim(maxSize: number): void
+}
+
+export interface DeltaArchiveOptions {
+    /** when set, the archive self-trims after each {@link DeltaArchive.append} */
+    maxSize?: number
+}
+
+// ---------------------------------------------------------------------------
+// Log color scale
+// ---------------------------------------------------------------------------
+
+export interface LogColorScale {
+    /** returns intensity in [0,1] for the given size */
+    intensity(size: number): number
+    /** swap the size range (does not retroactively rescale anything) */
+    setRange(sizeMin: number, sizeMax: number): void
+    /** current range (for callers that need to mirror it into GPU uniforms) */
+    range(): { sizeMin: number; sizeMax: number }
+}
+
+// ---------------------------------------------------------------------------
+// Top-level controller
+// ---------------------------------------------------------------------------
+
+export interface HeatmapControllerConfig {
+    tickSize: number
+    snapshotIntervalMs: number
+    snapshotRingCapacity: number
+    deltaArchiveMaxSize: number
+    logColorRange: { sizeMin: number; sizeMax: number }
+}
+
+export interface HeatmapState {
+    readonly latestSnapshot: BookSnapshot | null
+    readonly snapshotCount: number
+    readonly deltaCount: number
+}
+
+export interface HeatmapController {
+    readonly state: Signal<HeatmapState>
+
+    /**
+     * Ingest one L2 delta — canonical method, aligned with the cross-controller
+     * `ingest()` convention (VolumeProfile, Footprint). Closes API audit
+     * BLOCKER-001 (5-verb intake proliferation).
+     */
+    ingest(delta: OrderBookDelta): void
+
+    /**
+     * @deprecated since 0.1.0-alpha.1 — use {@link HeatmapController.ingest}.
+     * Kept as a non-removing alias for at least 6 months for migration.
+     */
+    ingestDelta(delta: OrderBookDelta): void
+    /** Force a snapshot now using the controller's current state. */
+    forceSnapshot(): void
+    /**
+     * Reconstruct snapshots at a regular cadence by replaying the delta archive.
+     * `from` is the first snapshot timestamp, `to` is exclusive upper bound.
+     */
+    replay(
+        fromTimestamp: number,
+        toTimestamp: number,
+        snapshotIntervalMs: number,
+    ): ReadonlyArray<BookSnapshot>
+
+    setConfig(next: Partial<HeatmapControllerConfig>): void
+    dispose(): void
+}

package/src/components/volumeProfile/__tests__/binning.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Tests for `binBarToBuckets` — bar → bucket volume distribution.
+ *
+ * Modes covered:
+ *   - `typical-price`: drop entire bar volume into the bucket holding
+ *     `(high+low+close)/3`; silently skip if the typical price falls outside
+ *     `[binMin, binMin + binCount*binSize)`.
+ *   - `proportional`: split the bar's volume across every bucket that
+ *     overlaps `[low, high]`, weighted by per-bucket overlap.
+ *
+ * All assertions are anchored to the actual implementation in
+ * `binning.ts`; if the algorithm diverges from the brief, the test reflects
+ * the implementation (not the brief).
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import { binBarToBuckets } from '../binning'
+import type { VolumeProfileBar } from '../types'
+
+function makeBuckets(n: number): Float64Array {
+    return new Float64Array(n)
+}
+
+describe('binBarToBuckets — typical-price mode', () => {
+    it('drops the entire bar volume into the bucket containing the typical price', () => {
+        // high=100, low=90, close=95 → typical = (100+90+95)/3 = 95
+        const bar: VolumeProfileBar = { high: 100, low: 90, close: 95, volume: 1000 }
+        // Bucket grid: binMin=90, binSize=1, binCount=10 → buckets cover [90, 100).
+        // Typical price 95 → idx = floor((95-90)/1) = 5 → buckets[5].
+        const buckets = makeBuckets(10)
+        binBarToBuckets(bar, buckets, 90, 1, 10, 'typical-price')
+        expect(buckets[5]).toBe(1000)
+        // No other buckets touched.
+        for (let i = 0; i < 10; i++) {
+            if (i !== 5) expect(buckets[i]).toBe(0)
+        }
+    })
+
+    it('silently drops a bar whose typical price is below binMin', () => {
+        // bar fully below the grid: high/low/close all < binMin → typical < binMin.
+        const bar: VolumeProfileBar = { high: 10, low: 5, close: 7, volume: 500 }
+        const buckets = makeBuckets(10)
+        // Grid covers [100, 110).
+        binBarToBuckets(bar, buckets, 100, 1, 10, 'typical-price')
+        // Nothing should have been written.
+        for (let i = 0; i < 10; i++) expect(buckets[i]).toBe(0)
+    })
+
+    it('silently drops a bar whose typical price is at/above binMin + binCount*binSize', () => {
+        // bar fully above the grid: typical >> binMin + binCount*binSize.
+        const bar: VolumeProfileBar = { high: 1000, low: 500, close: 700, volume: 999 }
+        const buckets = makeBuckets(10)
+        // Grid covers [0, 10).
+        binBarToBuckets(bar, buckets, 0, 1, 10, 'typical-price')
+        for (let i = 0; i < 10; i++) expect(buckets[i]).toBe(0)
+    })
+})
+
+describe('binBarToBuckets — proportional mode', () => {
+    it('splits a bar covering exactly 2 buckets 500/500 on equal overlap', () => {
+        // Grid: binMin=0, binSize=1, binCount=10 → buckets [0,1), [1,2), ...
+        // Bar spans [3.0, 5.0) — exactly buckets 3 and 4, each contributing
+        // half the range. volume=1000 → 500 / 500.
+        const bar: VolumeProfileBar = { high: 5, low: 3, close: 4, volume: 1000 }
+        const buckets = makeBuckets(10)
+        binBarToBuckets(bar, buckets, 0, 1, 10, 'proportional')
+        expect(buckets[3]).toBeCloseTo(500, 9)
+        expect(buckets[4]).toBeCloseTo(500, 9)
+        // Everything else zero.
+        for (let i = 0; i < 10; i++) {
+            if (i !== 3 && i !== 4) expect(buckets[i]).toBe(0)
+        }
+    })
+
+    it('puts all volume into a single bucket when the bar exactly spans one bucket', () => {
+        // Bar [4.0, 5.0) exactly equals bucket 4 → all volume there.
+        const bar: VolumeProfileBar = { high: 5, low: 4, close: 4.5, volume: 750 }
+        const buckets = makeBuckets(10)
+        binBarToBuckets(bar, buckets, 0, 1, 10, 'proportional')
+        // Implementation note: `hi = 5`, ceil((5-0)/1) - 1 = 4 → lastIdx = 4.
+        // firstIdx = floor((4-0)/1) = 4. So only bucket 4 gets volume.
+        expect(buckets[4]).toBeCloseTo(750, 9)
+        for (let i = 0; i < 10; i++) {
+            if (i !== 4) expect(buckets[i]).toBe(0)
+        }
+    })
+
+    it('splits across 3 buckets proportional to per-bucket overlap', () => {
+        // Bar [2.5, 5.5), grid binSize=1: overlaps with buckets 2, 3, 4, 5.
+        //   bucket 2 [2, 3): overlap [2.5, 3.0)   = 0.5
+        //   bucket 3 [3, 4): overlap [3.0, 4.0)   = 1.0
+        //   bucket 4 [4, 5): overlap [4.0, 5.0)   = 1.0
+        //   bucket 5 [5, 6): overlap [5.0, 5.5)   = 0.5
+        // Total overlap span = 3.0; barHigh - barLow = 3.0; volPerUnit = 900/3 = 300.
+        // Distribution: 150 / 300 / 300 / 150.
+        const bar: VolumeProfileBar = { high: 5.5, low: 2.5, close: 4, volume: 900 }
+        const buckets = makeBuckets(10)
+        binBarToBuckets(bar, buckets, 0, 1, 10, 'proportional')
+        expect(buckets[2]).toBeCloseTo(150, 9)
+        expect(buckets[3]).toBeCloseTo(300, 9)
+        expect(buckets[4]).toBeCloseTo(300, 9)
+        expect(buckets[5]).toBeCloseTo(150, 9)
+        // Sum equals the bar volume (conservation).
+        const sum = buckets.reduce((a, b) => a + b, 0)
+        expect(sum).toBeCloseTo(900, 9)
+    })
+
+    it('drops a bar fully outside the configured price range (both sides)', () => {
+        // Below the grid: binMin=100, binCount=10, binSize=1 → grid [100, 110).
+        const below: VolumeProfileBar = { high: 50, low: 40, close: 45, volume: 500 }
+        const b1 = makeBuckets(10)
+        binBarToBuckets(below, b1, 100, 1, 10, 'proportional')
+        expect(b1.reduce((a, b) => a + b, 0)).toBe(0)
+
+        // Above the grid.
+        const above: VolumeProfileBar = { high: 500, low: 400, close: 450, volume: 500 }
+        const b2 = makeBuckets(10)
+        binBarToBuckets(above, b2, 100, 1, 10, 'proportional')
+        expect(b2.reduce((a, b) => a + b, 0)).toBe(0)
+    })
+
+    it('treats a zero-range bar (high === low) like typical-price (lands in one bucket)', () => {
+        // Doji: high == low == close = 4.5 → falls in bucket 4.
+        const bar: VolumeProfileBar = { high: 4.5, low: 4.5, close: 4.5, volume: 800 }
+        const buckets = makeBuckets(10)
+        binBarToBuckets(bar, buckets, 0, 1, 10, 'proportional')
+        expect(buckets[4]).toBe(800)
+        for (let i = 0; i < 10; i++) {
+            if (i !== 4) expect(buckets[i]).toBe(0)
+        }
+    })
+})

package/src/components/volumeProfile/__tests__/poc.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Tests for `findPOCIndex` — argmax over the bucket histogram with a
+ * deterministic lowest-index tie-breaker.
+ *
+ * Implementation behaviour (see `poc.ts` header for rationale):
+ *   - Strictly-greater wins → earlier index is preserved on ties.
+ *   - Empty array returns `-1`.
+ *   - All zeros returns `0` (first bucket "wins" because no strictly-greater
+ *     value is ever found).
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import { findPOCIndex } from '../poc'
+
+function f(arr: number[]): Float64Array {
+    return Float64Array.from(arr)
+}
+
+describe('findPOCIndex', () => {
+    it('returns the index of the largest bucket (plain argmax)', () => {
+        // Buckets [10, 50, 30, 20] → max=50 at index 1.
+        expect(findPOCIndex(f([10, 50, 30, 20]))).toBe(1)
+    })
+
+    it('resolves ties to the lowest index', () => {
+        // All equal → first index wins because comparator is strict `>`.
+        expect(findPOCIndex(f([40, 40, 40]))).toBe(0)
+        // Tie between index 2 and 5; the lower (2) wins.
+        expect(findPOCIndex(f([1, 2, 99, 3, 4, 99, 5]))).toBe(2)
+    })
+
+    it('returns 0 for an all-zero histogram (documented edge case)', () => {
+        // bestVol starts at buckets[0] = 0; no later value is strictly greater,
+        // so the index sticks at 0. The controller treats this state via the
+        // Value-Area total-volume zero branch, not by inspecting the POC.
+        expect(findPOCIndex(f([0, 0, 0, 0, 0]))).toBe(0)
+    })
+
+    it('returns -1 for an empty array', () => {
+        // Sanity for the explicit guard at the top of `findPOCIndex`.
+        expect(findPOCIndex(new Float64Array(0))).toBe(-1)
+    })
+})

package/src/components/volumeProfile/__tests__/valueArea.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Tests for `computeValueArea` — greedy expansion around POC.
+ *
+ * Algorithm summary (see `valueArea.ts` header for full rationale):
+ *   - Seed the VA with the POC bucket.
+ *   - Each step compares `buckets[vahIdx+1]` vs `buckets[valIdx-1]` and
+ *     annexes the larger side.
+ *   - Ties → "expand toward POC" rule: pick the side whose CURRENT boundary
+ *     is closer to POC. Equidistant ties → upper side wins.
+ *   - Edge POC, boundary exhaustion, zero-volume, percent clamping all
+ *     covered by dedicated tests below.
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import { computeValueArea } from '../valueArea'
+import { findPOCIndex } from '../poc'
+
+function f(arr: number[]): Float64Array {
+    return Float64Array.from(arr)
+}
+
+describe('computeValueArea — symmetric / skewed distributions', () => {
+    it('centres the VA around the middle bucket on a symmetric distribution at target=0.70', () => {
+        // Buckets: [5,10,20,30,40,30,20,10,5], n=9, total=170, POC=4.
+        // Target = 119. Trace:
+        //   start  vaVol=40 (POC)
+        //   step1  up=30, down=30 tie, equidist → goUp  → vahIdx=5, vaVol=70
+        //   step2  up=20, down=30 → down wins             → valIdx=3, vaVol=100
+        //   step3  up=20, down=20 tie, equidist (distUp=1,distDown=1) → goUp
+        //                                                  → vahIdx=6, vaVol=120
+        //   120 >= 119 → stop.
+        const buckets = f([5, 10, 20, 30, 40, 30, 20, 10, 5])
+        const poc = findPOCIndex(buckets) // 4
+        const res = computeValueArea(buckets, poc, 0.7)
+        expect(res.pocIndex).toBe(4)
+        expect(res.valIndex).toBe(3)
+        expect(res.vahIndex).toBe(6)
+        expect(res.totalVolume).toBe(170)
+        expect(res.vaVolume).toBe(120)
+        expect(res.vaPercent).toBeCloseTo(120 / 170, 9)
+    })
+
+    it('captures the heavy right tail on a right-skewed distribution; tie pulls back toward POC', () => {
+        // [1,1,1,2,3,5,10,40,20,10], n=10, total=92, POC=7 (value 40).
+        // Target = 64.4. Trace:
+        //   vaVol=40                                    (valIdx=7, vahIdx=7)
+        //   step1 up=buckets[8]=20, down=buckets[6]=10 → up wins  → vahIdx=8, vaVol=60
+        //   step2 up=buckets[9]=10, down=buckets[6]=10 → TIE.
+        //         distUp = vahIdx - poc = 1; distDown = poc - valIdx = 0.
+        //         distDown < distUp → extend the side closer to POC (down).
+        //                                                → valIdx=6, vaVol=70
+        //   70 >= 64.4 → stop.
+        // VA = [6, 8]. The heavy right tail is captured in step 1 (the dominant
+        // upper neighbor); the subsequent tie rebalances toward POC per the
+        // CME-traditional "expand toward POC" tie-break — see valueArea.ts header.
+        const buckets = f([1, 1, 1, 2, 3, 5, 10, 40, 20, 10])
+        const poc = findPOCIndex(buckets) // 7
+        const res = computeValueArea(buckets, poc, 0.7)
+        expect(res.pocIndex).toBe(7)
+        expect(res.valIndex).toBe(6)
+        expect(res.vahIndex).toBe(8)
+        expect(res.vaVolume).toBe(70)
+    })
+})
+
+describe('computeValueArea — edge POC (only one expansion direction)', () => {
+    it('expands only upward when POC is at index 0', () => {
+        // POC at the bottom — `canDown` is always false; expansion is forced up.
+        // Buckets: [100, 50, 25, 10, 5], total=190, target=133.
+        // Start vaVol=100; canDown=false branch picks vahIdx=1 → vaVol=150 >= 133.
+        const buckets = f([100, 50, 25, 10, 5])
+        const res = computeValueArea(buckets, 0, 0.7)
+        expect(res.pocIndex).toBe(0)
+        expect(res.valIndex).toBe(0)
+        expect(res.vahIndex).toBe(1)
+        expect(res.vaVolume).toBe(150)
+    })
+
+    it('expands only downward when POC is at index N-1', () => {
+        // POC at the top — `canUp` is always false.
+        // Buckets: [5, 10, 25, 50, 100], total=190, target=133.
+        // Start vaVol=100; canUp=false branch picks valIdx=3 → vaVol=150 >= 133.
+        const buckets = f([5, 10, 25, 50, 100])
+        const res = computeValueArea(buckets, 4, 0.7)
+        expect(res.pocIndex).toBe(4)
+        expect(res.vahIndex).toBe(4) // N-1
+        expect(res.valIndex).toBe(3)
+        expect(res.vaVolume).toBe(150)
+    })
+})
+
+describe('computeValueArea — tie-breaker behaviour (CME-traditional)', () => {
+    it('on an upper==lower tie with asymmetric distances, extends the side whose current boundary is closer to POC', () => {
+        // Construct a state where after two forced upward steps a tie occurs
+        // with distDown < distUp:
+        //
+        // Buckets: [5,5,5,5,30,10,8,5,5], n=9, POC=4, total=78, target=0.7*78=54.6
+        //
+        //   start  vaVol=30  (valIdx=4, vahIdx=4)
+        //   step1  up=10, down=5 → up wins → vahIdx=5, vaVol=40
+        //   step2  up=buckets[6]=8, down=buckets[3]=5 → up wins → vahIdx=6, vaVol=48
+        //          (now distUp=2, distDown=0)
+        //   step3  up=buckets[7]=5, down=buckets[3]=5 → TIE.
+        //          distUp=2, distDown=0  → distDown < distUp → goDown
+        //                                  (closer-to-POC boundary extends away from POC)
+        //          → valIdx=3, vaVol=53
+        //   step4  up=buckets[7]=5, down=buckets[2]=5 → TIE.
+        //          distUp=2, distDown=1  → distDown<distUp → goDown
+        //          → valIdx=2, vaVol=58 >= 54.6 ✓
+        //
+        // Final: valIdx=2, vahIdx=6.
+        const buckets = f([5, 5, 5, 5, 30, 10, 8, 5, 5])
+        const res = computeValueArea(buckets, 4, 0.7)
+        expect(res.pocIndex).toBe(4)
+        // The tie was resolved by extending the boundary CLOSER to POC —
+        // i.e. the down side, which had distance 0 vs the up side's distance 2.
+        // This is the implementation's interpretation of "toward POC".
+        expect(res.valIndex).toBe(2)
+        expect(res.vahIndex).toBe(6)
+        expect(res.vaVolume).toBe(58)
+    })
+
+    it('on an equidistant tie, prefers the upper side (documented rule B)', () => {
+        // Buckets: [2,5,5,10,5,5,2], n=7, POC=3, total=34, target=23.8.
+        //   start  vaVol=10
+        //   step1  up=5, down=5 tie, distUp=0, distDown=0 → goUp → vahIdx=4, vaVol=15
+        //   step2  up=5, down=5 tie, distUp=1, distDown=1 → goUp → vahIdx=5, vaVol=20
+        //   step3  up=2, down=5 → down wins → valIdx=2, vaVol=25 >= 23.8 ✓
+        const buckets = f([2, 5, 5, 10, 5, 5, 2])
+        const res = computeValueArea(buckets, 3, 0.7)
+        expect(res.pocIndex).toBe(3)
+        expect(res.vahIndex).toBe(5)
+        expect(res.valIndex).toBe(2)
+        expect(res.vaVolume).toBe(25)
+    })
+})
+
+describe('computeValueArea — percent clamping & target sweeps', () => {
+    it('sweeps the entire non-zero range at target=1.0', () => {
+        // Buckets: [5,10,5], n=3, POC=1, total=20, target=20.
+        //   vaVol=10; up=5,down=5 tie equidist → goUp → vahIdx=2, vaVol=15
+        //   canUp=false, canDown=true → goDown → valIdx=0, vaVol=20 ✓
+        const buckets = f([5, 10, 5])
+        const res = computeValueArea(buckets, 1, 1.0)
+        expect(res.valIndex).toBe(0)
+        expect(res.vahIndex).toBe(2)
+        expect(res.vaVolume).toBe(20)
+        expect(res.vaPercent).toBeCloseTo(1, 9)
+    })
+
+    it('produces a narrower VA at target=0.5 than at target=0.7 (monotonicity)', () => {
+        const buckets = f([5, 10, 20, 30, 40, 30, 20, 10, 5])
+        const poc = findPOCIndex(buckets) // 4
+        const half = computeValueArea(buckets, poc, 0.5)
+        const seventy = computeValueArea(buckets, poc, 0.7)
+        const halfWidth = half.vahIndex - half.valIndex
+        const seventyWidth = seventy.vahIndex - seventy.valIndex
+        expect(halfWidth).toBeLessThanOrEqual(seventyWidth)
+        // 50% target is 85; 40 + 30 + 30 = 100 reaches it well before 70%
+        // does so the difference must be strictly visible.
+        expect(halfWidth).toBeLessThan(seventyWidth)
+        expect(half.vaPercent).toBeLessThanOrEqual(seventy.vaPercent)
+    })
+
+    it('returns the degenerate result for an all-zero histogram', () => {
+        // Documented zero-volume behaviour: VA collapses to POC, percent 0.
+        const buckets = f([0, 0, 0, 0, 0])
+        const res = computeValueArea(buckets, 2, 0.7)
+        expect(res.vahIndex).toBe(2)
+        expect(res.valIndex).toBe(2)
+        expect(res.pocIndex).toBe(2)
+        expect(res.totalVolume).toBe(0)
+        expect(res.vaVolume).toBe(0)
+        expect(res.vaPercent).toBe(0)
+    })
+})

package/src/components/volumeProfile/binning.ts

@@ -0,0 +1,133 @@
+/**
+ * Bar-to-bucket volume distribution.
+ *
+ * Two modes, both described in `docs/ROADMAP.md` §3.1:
+ *
+ * - `typical-price` (fast, default): the bar's entire volume is added to the
+ *   bucket containing the typical price `(high + low + close) / 3`. O(1) per
+ *   bar. Good enough for live profiles and the case where each bar is small
+ *   relative to the bucket size.
+ *
+ * - `proportional` (accurate): the bar's volume is split across every bucket
+ *   that overlaps `[low, high]`, weighted by that bucket's price-range
+ *   overlap with the bar. O(spanned buckets) per bar. Use this when bars
+ *   span many buckets (e.g. higher timeframes, wide ranges).
+ *
+ * Both modes mutate the `buckets` array in place — the function is called in
+ * a tight loop and we want zero allocations on the hot path. The controller
+ * is responsible for zeroing the buckets before the first call.
+ *
+ * Out-of-range handling:
+ *   - In `typical-price` mode a bar whose typical price falls outside
+ *     `[binMin, binMin + binCount*binSize)` is **dropped silently**. The
+ *     controller is responsible for sizing the price range so this only
+ *     happens for accidentally bad inputs (e.g. zero-volume bars in a
+ *     degenerate range).
+ *   - In `proportional` mode the overlap with `[binMin, binMax]` is the
+ *     effective contribution; a bar fully outside contributes nothing, a bar
+ *     partially overlapping contributes proportionally.
+ */
+
+import type { BinningMode, VolumeProfileBar } from './types'
+
+/**
+ * Distribute one bar's volume into `buckets`.
+ *
+ * Preconditions (not checked, hot path):
+ *   - `buckets.length === binCount`
+ *   - `binSize > 0`
+ *   - `binCount >= 1`
+ *
+ * @param bar       The OHLC bar (only `high`/`low`/`close`/`volume` are read).
+ * @param buckets   Histogram array — written in place.
+ * @param binMin    Low edge of bucket 0.
+ * @param binSize   Price width of one bucket.
+ * @param binCount  Number of buckets (must equal `buckets.length`).
+ * @param mode      `typical-price` (fast) or `proportional` (accurate).
+ *
+ * @internal — building block used by the corresponding controller
+ *   factory. Reachable today via the top-level `@klinechart-quant/core`
+ *   barrel but **NOT part of the supported public API**. typedoc / api-
+ *   extractor hide it from generated docs. Prefer the controller
+ *   factory (e.g. `createVolumeProfileController`) for stable user code.
+ *   Closes API audit BLOCKER-002 (export * leakage taxonomy).
+ */
+export function binBarToBuckets(
+    bar: VolumeProfileBar,
+    buckets: Float64Array,
+    binMin: number,
+    binSize: number,
+    binCount: number,
+    mode: BinningMode,
+): void {
+    if (bar.volume === 0 || binCount === 0 || binSize <= 0) return
+
+    if (mode === 'typical-price') {
+        const tp = (bar.high + bar.low + bar.close) / 3
+        const idx = Math.floor((tp - binMin) / binSize)
+        if (idx < 0 || idx >= binCount) return
+        buckets[idx] = (buckets[idx] ?? 0) + bar.volume
+        return
+    }
+
+    // Proportional mode — split the bar's volume across [low, high] by
+    // per-bucket overlap with the bar's range.
+    //
+    // The bar's price extent is [low, high]; the buckets cover the price
+    // axis at [binMin + i*binSize, binMin + (i+1)*binSize). We compute the
+    // overlap of each touched bucket with [low, high] and weight by it.
+    //
+    // Degenerate-range bars (high === low, e.g. a doji at exactly one
+    // tick) fall back to the typical-price behaviour — putting the volume
+    // in the bucket containing `low` is the correct limit as
+    // `high - low -> 0`.
+    const binMax = binMin + binCount * binSize
+    const barLow = bar.low
+    const barHigh = bar.high
+
+    // Drop bars fully outside the configured price range — they can't
+    // contribute to any bucket.
+    if (barHigh < binMin || barLow >= binMax) return
+
+    if (barHigh === barLow) {
+        const idx = Math.floor((barLow - binMin) / binSize)
+        if (idx < 0 || idx >= binCount) return
+        buckets[idx] = (buckets[idx] ?? 0) + bar.volume
+        return
+    }
+
+    // Clamp the bar's range to the bucket grid so overlap math doesn't
+    // include the out-of-range portion.
+    const lo = barLow < binMin ? binMin : barLow
+    const hi = barHigh > binMax ? binMax : barHigh
+
+    const firstIdx = Math.floor((lo - binMin) / binSize)
+    // For `hi` we use ceiling-of-(hi - binMin)/binSize, minus 1, so the
+    // top boundary `hi === binMin + k*binSize` belongs to bucket k-1
+    // (consistent with the half-open bucket convention `[lo, hi)`).
+    let lastIdx = Math.ceil((hi - binMin) / binSize) - 1
+    if (lastIdx < firstIdx) lastIdx = firstIdx
+
+    // Effective span used as the denominator. We weight against the
+    // *clamped* span (the part actually inside the bucket grid) so a bar
+    // that hangs off the bottom doesn't get "phantom" volume into the
+    // visible buckets. Trade-off: this means a bar partially outside
+    // contributes only its inside-range fraction. This matches the
+    // intuition of "what fraction of the bar's range fell into the
+    // profile window".
+    const span = hi - lo
+    if (span <= 0) return
+
+    const volPerUnit = bar.volume / (barHigh - barLow)
+
+    for (let i = firstIdx; i <= lastIdx; i++) {
+        if (i < 0 || i >= binCount) continue
+        const bucketLow = binMin + i * binSize
+        const bucketHigh = bucketLow + binSize
+        const overlapLow = lo > bucketLow ? lo : bucketLow
+        const overlapHigh = hi < bucketHigh ? hi : bucketHigh
+        const overlap = overlapHigh - overlapLow
+        if (overlap <= 0) continue
+        buckets[i] = (buckets[i] ?? 0) + overlap * volPerUnit
+    }
+}