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

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

@@ -17,161 +17,161 @@ import { computeValueArea } from '../valueArea'
 import { findPOCIndex } from '../poc'
 
 function f(arr: number[]): Float64Array {
-    return Float64Array.from(arr)
+  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('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)
-    })
+  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 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)
-    })
+  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 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)
-    })
+  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('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('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)
-    })
+  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

@@ -53,81 +53,81 @@ import type { BinningMode, VolumeProfileBar } from './types'
  *   Closes API audit BLOCKER-002 (export * leakage taxonomy).
  */
 export function binBarToBuckets(
-    bar: VolumeProfileBar,
-    buckets: Float64Array,
-    binMin: number,
-    binSize: number,
-    binCount: number,
-    mode: BinningMode,
+  bar: VolumeProfileBar,
+  buckets: Float64Array,
+  binMin: number,
+  binSize: number,
+  binCount: number,
+  mode: BinningMode,
 ): void {
-    if (bar.volume === 0 || binCount === 0 || binSize <= 0) return
+  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
-    }
+  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
+  // 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
+  // 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
-    }
+  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
+  // 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
+  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
+  // 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)
+  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
-    }
+  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
+  }
 }