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

package/src/components/volumeProfile/createVolumeProfileController.ts

@@ -0,0 +1,213 @@
+/**
+ * Volume Profile controller — framework-agnostic, signal-based.
+ *
+ * Mirrors the dispose-guard pattern from `createIndicatorSelectorController`
+ * so React/Vue/Angular adapters bridge identically. The controller is pure
+ * data — no DOM, no rendering, no canvas. It plays the same role as
+ * `src/core/indicators/volumeProfileState.ts` (the maintainer's legacy state
+ * module) but with the new reactive contract; the legacy state file and the
+ * legacy renderer at `src/core/renderers/Indicator/volumeProfile.ts` are
+ * intentionally NOT touched (per branch policy).
+ *
+ * Flow on `ingest`:
+ *   1. Walk the bars once to learn `[minLow, maxHigh]`.
+ *   2. Derive `binMin`/`binSize` from that range + config.binCount.
+ *   3. Allocate a fresh `Float64Array(binCount)` (or reuse if size unchanged).
+ *   4. For each bar, call `binBarToBuckets` (typical-price or proportional).
+ *   5. `findPOCIndex` → `computeValueArea` → assemble `VolumeProfileState`.
+ *
+ * Non-goals:
+ *   - Incremental ingest. `ingest` always recomputes from scratch. The
+ *     incremental path comes with the WebGPU compute shader (see
+ *     `computeShader.wgsl.md`).
+ *   - Auto-binning by tick size. The current heuristic (range / binCount) is
+ *     adequate for visual profiles; tick-snapped binning is a future option.
+ */
+
+import { createSignal, type Signal } from '../../reactivity'
+import { binBarToBuckets } from './binning'
+import { findPOCIndex } from './poc'
+import { computeValueArea } from './valueArea'
+import type {
+    VolumeProfileBar,
+    VolumeProfileConfig,
+    VolumeProfileController,
+    VolumeProfileState,
+} from './types'
+
+const DEFAULT_CONFIG: VolumeProfileConfig = {
+    binCount: 100,
+    binningMode: 'typical-price',
+    valueAreaPercent: 0.7,
+}
+
+// Smallest binSize we will use. Prevents a degenerate "all bars same price"
+// input from producing a division-by-zero. The value is arbitrary but small
+// enough that real markets never hit it.
+const MIN_BIN_SIZE = 1e-12
+
+export interface VolumeProfileControllerInit {
+    config?: Partial<VolumeProfileConfig>
+}
+
+export function createVolumeProfileController(
+    init?: VolumeProfileControllerInit,
+): VolumeProfileController {
+    // -------------------------------------------------------------------
+    // Signals
+    // -------------------------------------------------------------------
+    const initialConfig: VolumeProfileConfig = {
+        ...DEFAULT_CONFIG,
+        ...(init?.config ?? {}),
+    }
+    // Defensive clamp: percent in [0, 1], binCount >= 1.
+    if (initialConfig.valueAreaPercent < 0) initialConfig.valueAreaPercent = 0
+    if (initialConfig.valueAreaPercent > 1) initialConfig.valueAreaPercent = 1
+    if (initialConfig.binCount < 1) initialConfig.binCount = 1
+
+    const config: Signal<VolumeProfileConfig> = createSignal(initialConfig)
+    const state: Signal<VolumeProfileState | null> =
+        createSignal<VolumeProfileState | null>(null)
+
+    // -------------------------------------------------------------------
+    // ingest — full recompute
+    // -------------------------------------------------------------------
+    function ingest(bars: ReadonlyArray<VolumeProfileBar>): void {
+        const cfg = config.peek()
+
+        if (bars.length === 0) {
+            state.set(null)
+            return
+        }
+
+        // First pass: range of the data.
+        let minLow = Infinity
+        let maxHigh = -Infinity
+        for (let i = 0; i < bars.length; i++) {
+            const b = bars[i]
+            if (b === undefined) continue
+            if (b.low < minLow) minLow = b.low
+            if (b.high > maxHigh) maxHigh = b.high
+        }
+
+        if (!Number.isFinite(minLow) || !Number.isFinite(maxHigh)) {
+            state.set(null)
+            return
+        }
+
+        const range = maxHigh - minLow
+        // Degenerate range: every bar at the same price. We still want a
+        // non-zero binSize so the math works; centre a tiny window on the
+        // price so the single bucket captures everything.
+        const binSize =
+            range > MIN_BIN_SIZE ? range / cfg.binCount : MIN_BIN_SIZE
+        const binMin = minLow
+
+        // Allocate or reuse the buckets. Reuse only if the size matches —
+        // changing `binCount` via `setConfig` requires a fresh array.
+        const prev = state.peek()
+        const buckets =
+            prev !== null && prev.buckets.length === cfg.binCount
+                ? prev.buckets
+                : new Float64Array(cfg.binCount)
+        // Zero it (whether reused or freshly allocated) — `fill(0)` is cheap
+        // on typed arrays.
+        buckets.fill(0)
+
+        // Second pass: drop volume into buckets.
+        for (let i = 0; i < bars.length; i++) {
+            const b = bars[i]
+            if (b === undefined) continue
+            binBarToBuckets(
+                b,
+                buckets,
+                binMin,
+                binSize,
+                cfg.binCount,
+                cfg.binningMode,
+            )
+        }
+
+        // POC + VA.
+        const pocIdx = findPOCIndex(buckets)
+        // findPOCIndex returns -1 only on empty arrays — guarded above.
+        const va = computeValueArea(
+            buckets,
+            pocIdx < 0 ? 0 : pocIdx,
+            cfg.valueAreaPercent,
+        )
+
+        // Prices: each bucket spans `[binMin + i*binSize, binMin + (i+1)*binSize)`.
+        // We report POC as the bucket *center*, VAH as the upper bucket's high
+        // edge, VAL as the lower bucket's low edge — this matches how a
+        // renderer wants to draw them: POC as a centerline, VAH/VAL as
+        // envelope edges.
+        const pocPrice = binMin + (va.pocIndex + 0.5) * binSize
+        const vahPrice = binMin + (va.vahIndex + 1) * binSize
+        const valPrice = binMin + va.valIndex * binSize
+
+        const next: VolumeProfileState = {
+            buckets,
+            binMin,
+            binSize,
+            poc: pocPrice,
+            vah: vahPrice,
+            val: valPrice,
+            totalVolume: va.totalVolume,
+            vaVolume: va.vaVolume,
+        }
+        state.set(next)
+    }
+
+    // -------------------------------------------------------------------
+    // setConfig — patch + invalidate
+    // -------------------------------------------------------------------
+    function setConfig(next: Partial<VolumeProfileConfig>): void {
+        const cur = config.peek()
+        const merged: VolumeProfileConfig = { ...cur, ...next }
+        // Re-apply the defensive clamps.
+        if (merged.valueAreaPercent < 0) merged.valueAreaPercent = 0
+        if (merged.valueAreaPercent > 1) merged.valueAreaPercent = 1
+        if (merged.binCount < 1) merged.binCount = 1
+
+        // If binCount changed, the existing buckets are stale (different
+        // resolution) — clear state so callers know to re-ingest. Other
+        // field changes leave the data untouched until next ingest.
+        if (merged.binCount !== cur.binCount) {
+            state.set(null)
+        }
+        config.set(merged)
+    }
+
+    // -------------------------------------------------------------------
+    // reset — clear state, keep config
+    // -------------------------------------------------------------------
+    function reset(): void {
+        state.set(null)
+    }
+
+    // -------------------------------------------------------------------
+    // dispose — silence mutators (same pattern as IndicatorSelectorController)
+    // -------------------------------------------------------------------
+    let disposed = false
+    function dispose(): void {
+        if (disposed) return
+        disposed = true
+    }
+
+    function guard<T extends (...args: never[]) => unknown>(fn: T): T {
+        return ((...args: Parameters<T>): ReturnType<T> => {
+            if (disposed) return undefined as ReturnType<T>
+            return fn(...args) as ReturnType<T>
+        }) as T
+    }
+
+    return {
+        config,
+        state,
+        ingest: guard(ingest),
+        setConfig: guard(setConfig),
+        reset: guard(reset),
+        dispose,
+    }
+}

package/src/components/volumeProfile/index.ts

@@ -0,0 +1,12 @@
+export type {
+    BinningMode,
+    VolumeProfileConfig,
+    VolumeProfileState,
+    VolumeProfileBar,
+    VolumeProfileController,
+    ValueAreaResult,
+} from './types'
+export { binBarToBuckets } from './binning'
+export { findPOCIndex } from './poc'
+export { computeValueArea } from './valueArea'
+export { createVolumeProfileController } from './createVolumeProfileController'

package/src/components/volumeProfile/poc.ts

@@ -0,0 +1,53 @@
+/**
+ * Point of Control — argmax over the bucket histogram.
+ *
+ * The POC is the single bucket with the largest total volume. It is the seed
+ * for the Value Area expansion (`valueArea.ts`) and the most-referenced level
+ * on a volume profile chart.
+ *
+ * Tie-breaker policy (important — make sure it stays stable):
+ *   When two or more buckets share the maximum, the **lowest index wins**.
+ *
+ * Rationale: argmax under ties is otherwise undefined, which leads to
+ * non-deterministic state across runs and breaks snapshot tests. Returning
+ * the lowest index is also the convention KLineCharts and the maintainer's
+ * legacy renderer follow, so the visual placement of the POC line is
+ * consistent across our data model and the existing renderer.
+ *
+ * Edge case: an empty array returns `-1`. Callers (the controller) treat
+ * that as "no profile" and emit `state = null`. We pick -1 (not 0) so the
+ * empty case is impossible to confuse with "argmax happens to be bucket 0".
+ */
+
+/**
+ * Returns the index of the largest bucket. Ties resolve to the lowest index.
+ * Returns -1 if `buckets.length === 0`.
+ *
+ * Single pass, branch-light, O(n).
+ *
+ * @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 findPOCIndex(buckets: Float64Array): number {
+    const n = buckets.length
+    if (n === 0) return -1
+
+    let bestIdx = 0
+    let bestVol = buckets[0] ?? 0
+
+    // Walk buckets[1..]; strictly-greater wins, equal does NOT (keeps the
+    // earliest index — the documented tie-breaker).
+    for (let i = 1; i < n; i++) {
+        const v = buckets[i] ?? 0
+        if (v > bestVol) {
+            bestVol = v
+            bestIdx = i
+        }
+    }
+
+    return bestIdx
+}

package/src/components/volumeProfile/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Volume Profile — public type contract.
+ *
+ * Volume Profile aggregates traded volume by **price** (not time), producing a
+ * horizontal histogram pinned to the price axis. Traders read it for
+ * accumulation zones (POC), the 70% Value Area (VAH/VAL — CME convention),
+ * and developing support/resistance.
+ *
+ * This module owns the **data model + math only**. Rendering belongs to the
+ * `@klinechart-quant/core` Renderer/Scene layer (or the maintainer's legacy
+ * renderer at `src/core/renderers/Indicator/volumeProfile.ts`, which is kept
+ * untouched per branch policy).
+ *
+ * See `docs/ROADMAP.md` §3.1 for the algorithm rationale and §0 for the
+ * controller layering this fits into. See `computeShader.wgsl.md` for the
+ * planned WebGPU compute path of the heavy `binBarToBuckets` work.
+ */
+
+import type { Signal } from '../../reactivity'
+
+/**
+ * How a bar's volume is distributed across price buckets.
+ *
+ * - `typical-price` — the fast default. The entire bar volume is dropped into
+ *   the single bucket containing (high+low+close)/3. O(1) per bar.
+ * - `proportional` — accurate. The bar volume is split across every bucket
+ *   that overlaps `[low, high]`, proportional to that bucket's price-range
+ *   overlap with the bar. O(buckets-spanned) per bar.
+ *
+ * The trade-off is laid out in `docs/ROADMAP.md` §3.1: typical-price is what
+ * you want for live profile rendering at frame rate; proportional is what you
+ * want for "true" historical profiles and TPO-style work.
+ */
+export type BinningMode = 'typical-price' | 'proportional'
+
+/**
+ * Inputs to the controller. All fields are deliberately required at the
+ * controller surface — `createVolumeProfileController` fills missing fields
+ * from sensible defaults so callers can pass `{}`.
+ */
+export interface VolumeProfileConfig {
+    /** Number of price buckets (histogram resolution). Typical 50–200. */
+    binCount: number
+    /** Per-bar binning strategy. See `BinningMode`. */
+    binningMode: BinningMode
+    /**
+     * Fraction of total volume that must be inside the Value Area, in [0, 1].
+     * CME convention is 0.70. Set 1.0 to use the full range, set to e.g. 0.95
+     * for institution-style "value extended" envelopes.
+     */
+    valueAreaPercent: number
+}
+
+/**
+ * The reactive output. `null` while no bars have been ingested.
+ *
+ * Prices are absolute (real, not normalised) so renderers can place them on
+ * the same Y axis as candles. `buckets` is a `Float64Array` rather than
+ * `number[]` for two reasons: (1) contiguous memory layout for cache-friendly
+ * argmax / VA scans, and (2) it is the same format we'll upload to a GPU
+ * storage buffer once the WebGPU compute path lands (see `computeShader.wgsl.md`).
+ */
+export interface VolumeProfileState {
+    /** Histogram. `buckets[i]` is the total volume in bucket i. */
+    buckets: Float64Array
+    /** Low-edge price of bucket 0. */
+    binMin: number
+    /** Price width of one bucket. `buckets.length * binSize = total price span`. */
+    binSize: number
+    /** Point of Control — center price of the highest-volume bucket. */
+    poc: number
+    /** Value Area High — upper edge price of the VAH bucket. */
+    vah: number
+    /** Value Area Low — lower edge price of the VAL bucket. */
+    val: number
+    /** Sum of every bucket. */
+    totalVolume: number
+    /** Volume inside the closed Value Area `[valIndex, vahIndex]`. */
+    vaVolume: number
+}
+
+/**
+ * Minimum bar shape consumed by `ingest`. Matches the cross-renderer KLineData
+ * subset used elsewhere in core. We intentionally do NOT require `open` or
+ * `timestamp` so callers can stream from any source.
+ */
+export interface VolumeProfileBar {
+    high: number
+    low: number
+    close: number
+    volume: number
+}
+
+/**
+ * Framework-agnostic controller — mirrors `IndicatorSelectorController`'s
+ * shape (signals for state, plain functions for mutations, idempotent
+ * `dispose`).
+ */
+export interface VolumeProfileController {
+    /** Current config; re-emits when `setConfig` is called. */
+    readonly config: Signal<VolumeProfileConfig>
+    /** Current state; `null` until the first ingest. */
+    readonly state: Signal<VolumeProfileState | null>
+
+    /**
+     * Recompute the profile from a fresh bar slice. Idempotent: calling this
+     * twice with the same bars yields the same state (it is NOT cumulative —
+     * the prior buckets are discarded). Incremental ingestion will land with
+     * the GPU compute path; see `computeShader.wgsl.md`.
+     */
+    ingest(bars: ReadonlyArray<VolumeProfileBar>): void
+
+    /**
+     * Patch the config. If `binCount` changes the buckets are re-sized on the
+     * next `ingest` (state is cleared immediately because the old buckets are
+     * now meaningless under the new resolution).
+     */
+    setConfig(next: Partial<VolumeProfileConfig>): void
+
+    /** Clear state to null (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
+}
+
+/**
+ * Result of the Value Area greedy expansion. Indices are inclusive bucket
+ * indices; prices are derived by the controller using `binMin + binSize * i`.
+ */
+export interface ValueAreaResult {
+    /** Upper bucket index (inclusive). */
+    vahIndex: number
+    /** Lower bucket index (inclusive). */
+    valIndex: number
+    /** Argmax bucket index used as the seed. */
+    pocIndex: number
+    /** Total of all buckets. */
+    totalVolume: number
+    /** Sum of `buckets[i]` for `i in [valIndex, vahIndex]`. */
+    vaVolume: number
+    /** `vaVolume / totalVolume`. 0 when `totalVolume` is 0. */
+    vaPercent: number
+}

package/src/components/volumeProfile/valueArea.ts

@@ -0,0 +1,187 @@
+/**
+ * Value Area greedy expansion — VAH / VAL computation around the POC.
+ *
+ * Algorithm (CME-traditional, see `docs/ROADMAP.md` §3.1):
+ *   1. Seed the Value Area with the POC bucket.
+ *   2. Compute the target volume `target = totalVolume * percent`.
+ *   3. Repeatedly grow the VA by **one** of its boundary's neighbours:
+ *      compare the volume of `buckets[vahIdx + 1]` (upper neighbour) and
+ *      `buckets[valIdx - 1]` (lower neighbour); annex the side with the
+ *      larger volume.
+ *   4. If one side has no neighbour left (boundary of the histogram), only
+ *      the other side is available.
+ *   5. Stop when `vaVolume >= target` or both sides are exhausted.
+ *
+ * Tie-breakers (critical — get these wrong and the test plan fails):
+ *
+ *   (A) When `upper.vol == lower.vol`, expand toward the POC. "Toward the
+ *       POC" means: pick the side whose current boundary is **closer** to
+ *       `pocIndex`. The intuition is that a symmetric tie should grow the
+ *       VA evenly around the POC instead of drifting whichever way the
+ *       comparison happens to land first. This matches the spirit of the
+ *       CME spec, which expects the VA to be "balanced around POC" when
+ *       data is symmetric, and it's the choice the maintainer's legacy
+ *       renderer makes by default.
+ *
+ *   (B) When `upper.vol == lower.vol` AND both boundaries are equidistant
+ *       from POC, prefer the **upper** side. This is documented because it
+ *       is otherwise underspecified; the rationale is that an upper-side
+ *       preference matches the default direction of price discovery on
+ *       most assets (markets tend to break up out of balance).
+ *
+ *   (C) The CME-style "two-bucket lookahead" tie-breaker is intentionally
+ *       NOT implemented in this pass — it adds complexity for a tiny
+ *       difference in result and is not required by the test plan. It can
+ *       be added behind a `tieBreaker: 'lookahead'` option later without
+ *       breaking the API.
+ *
+ * Edge cases:
+ *   - Empty / all-zero buckets ⇒ `vah = val = poc`, `vaVolume = 0`,
+ *     `vaPercent = 0`. No expansion happens.
+ *   - Single non-zero bucket ⇒ `vah = val = poc` already covers it.
+ *   - POC at index 0 ⇒ only the upper neighbour exists.
+ *   - POC at index N-1 ⇒ only the lower neighbour exists.
+ *   - `targetPercent >= 1.0` ⇒ the loop expands until the full range is
+ *     swept, yielding `valIdx = 0`, `vahIdx = N-1`.
+ *   - `targetPercent <= 0` ⇒ the loop never runs; only the POC bucket is in
+ *     the VA.
+ */
+
+import type { ValueAreaResult } from './types'
+
+/**
+ * @internal — building block used by `createVolumeProfileController`. 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
+ *   for stable user code. Closes API audit BLOCKER-002.
+ */
+export function computeValueArea(
+    buckets: Float64Array,
+    pocIndex: number,
+    targetPercent: number,
+): ValueAreaResult {
+    const n = buckets.length
+
+    // -------------------------------------------------------------------
+    // Empty histogram → degenerate result.
+    // -------------------------------------------------------------------
+    if (n === 0) {
+        return {
+            vahIndex: 0,
+            valIndex: 0,
+            pocIndex: 0,
+            totalVolume: 0,
+            vaVolume: 0,
+            vaPercent: 0,
+        }
+    }
+
+    // Clamp pocIndex defensively. The controller always passes a valid
+    // value, but valueArea.ts is also exported for direct use.
+    const poc = pocIndex < 0 ? 0 : pocIndex >= n ? n - 1 : pocIndex
+
+    // -------------------------------------------------------------------
+    // Total volume — single pass.
+    // -------------------------------------------------------------------
+    let totalVolume = 0
+    for (let i = 0; i < n; i++) {
+        totalVolume += buckets[i] ?? 0
+    }
+
+    // Zero-volume case → degenerate result, VA collapses to POC.
+    if (totalVolume === 0) {
+        return {
+            vahIndex: poc,
+            valIndex: poc,
+            pocIndex: poc,
+            totalVolume: 0,
+            vaVolume: 0,
+            vaPercent: 0,
+        }
+    }
+
+    // -------------------------------------------------------------------
+    // Seed the Value Area with the POC bucket.
+    // -------------------------------------------------------------------
+    let valIdx = poc
+    let vahIdx = poc
+    let vaVolume = buckets[poc] ?? 0
+
+    const pct = targetPercent < 0 ? 0 : targetPercent > 1 ? 1 : targetPercent
+    const target = totalVolume * pct
+
+    // Already covered (rare — happens when POC bucket alone is > target%).
+    // Still proceeds via the loop guard.
+
+    // -------------------------------------------------------------------
+    // Greedy expansion.
+    // -------------------------------------------------------------------
+    while (vaVolume < target) {
+        const canUp = vahIdx < n - 1
+        const canDown = valIdx > 0
+
+        if (!canUp && !canDown) break // exhausted entire histogram
+
+        // Single-side: only one direction has a neighbour.
+        if (canUp && !canDown) {
+            vahIdx += 1
+            vaVolume += buckets[vahIdx] ?? 0
+            continue
+        }
+        if (!canUp && canDown) {
+            valIdx -= 1
+            vaVolume += buckets[valIdx] ?? 0
+            continue
+        }
+
+        const upVol = buckets[vahIdx + 1] ?? 0
+        const downVol = buckets[valIdx - 1] ?? 0
+
+        let goUp: boolean
+
+        if (upVol > downVol) {
+            goUp = true
+        } else if (downVol > upVol) {
+            goUp = false
+        } else {
+            // ----- Tie: expand toward POC (see (A)/(B) in header). -----
+            // Distance from each *current* boundary to the POC. The
+            // boundary that's farther from POC is on the "long" side; we
+            // pull the VA back toward POC by extending the *closer*
+            // boundary (i.e. the side that has further to travel before
+            // it leaves POC's neighbourhood).
+            //
+            // Equivalently: pick the boundary whose distance to POC is
+            // smaller — that side still has room to grow "around" POC,
+            // the other side has already drifted.
+            const distUp = vahIdx - poc // >= 0
+            const distDown = poc - valIdx // >= 0
+            if (distUp < distDown) {
+                goUp = true
+            } else if (distDown < distUp) {
+                goUp = false
+            } else {
+                // Equidistant — documented upper-side preference (B).
+                goUp = true
+            }
+        }
+
+        if (goUp) {
+            vahIdx += 1
+            vaVolume += buckets[vahIdx] ?? 0
+        } else {
+            valIdx -= 1
+            vaVolume += buckets[valIdx] ?? 0
+        }
+    }
+
+    return {
+        vahIndex: vahIdx,
+        valIndex: valIdx,
+        pocIndex: poc,
+        totalVolume,
+        vaVolume,
+        vaPercent: totalVolume === 0 ? 0 : vaVolume / totalVolume,
+    }
+}