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

package/src/components/footprint/createFootprintController.ts

@@ -0,0 +1,338 @@
+/**
+ * FootprintController — framework-agnostic, signal-based.
+ *
+ * Streams trades in, materialises a `FootprintBar[]` out. Composes:
+ *
+ *   - `classifyExplicit`  (try exchange flag first)
+ *   - `classifyTickRule` / `classifyLeeReady` (fallback per config)
+ *   - `computeDelta`, `computeDiagonalImbalances`, `computeCumulativeDelta`
+ *
+ * Internal storage is hot-path-friendly:
+ *
+ *   buckets: Map<barIndex, Map<priceTickKey, { askVol, bidVol }>>
+ *
+ * Materialisation (sorting + array build) is deferred to `bars` / `cumulativeDelta`
+ * signal reads. A `dirty` flag invalidates the cache on every `ingestTrade`.
+ *
+ * Classifier state carry-over: the `TickRuleState` / `LeeReadyState` records
+ * are MAINTAINED ACROSS BAR BOUNDARIES — i.e. the last trade's price/side of
+ * bar N is used as the prior for the first trade of bar N+1. This is the
+ * documented choice (see ROADMAP §3.3): per-bar reset would flag every bar's
+ * first trade as `unknown`, which inflates dropped volume and breaks the
+ * Lee-Ready zero-tick fallback at every minute boundary. The tested behaviour
+ * relies on this carry-over.
+ *
+ * Dispose-guard pattern mirrors `createIndicatorSelectorController.ts`.
+ */
+
+import { createSignal, type Signal } from '../../reactivity'
+import { KLineChartError } from '../../errors'
+import {
+    classifyExplicit,
+    classifyLeeReady,
+    classifyTickRule,
+    type AggressorResult,
+    type LeeReadyState,
+    type TickRuleState,
+} from './aggressor'
+import {
+    computeCumulativeDelta,
+    computeDelta,
+    computeDiagonalImbalances,
+} from './perBarStats'
+import type {
+    FootprintBar,
+    FootprintBarCell,
+    FootprintConfig,
+    FootprintController,
+    FootprintImbalance,
+    TradeWithFlag,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Defaults & validation
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONFIG: FootprintConfig = {
+    tickSize: 0.01,
+    barIntervalMs: 60_000,
+    imbalanceRatio: 3,
+    fallbackClassifier: 'tick-rule',
+}
+
+function validateConfig(c: FootprintConfig): void {
+    if (!(c.tickSize > 0)) {
+        throw new KLineChartError('FOOTPRINT_TICKSIZE_INVALID', 'FootprintController: tickSize must be > 0')
+    }
+    if (!(c.barIntervalMs > 0) || !Number.isFinite(c.barIntervalMs)) {
+        throw new KLineChartError('FOOTPRINT_BAR_INTERVAL_INVALID', 'FootprintController: barIntervalMs must be > 0')
+    }
+    if (!(c.imbalanceRatio > 0)) {
+        throw new KLineChartError('FOOTPRINT_RATIO_INVALID', 'FootprintController: imbalanceRatio must be > 0')
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Internal cell shape (mutable counterpart of the readonly public cell)
+// ---------------------------------------------------------------------------
+
+interface MutableCell {
+    askVol: number
+    bidVol: number
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createFootprintController(
+    init: Partial<FootprintConfig>,
+): FootprintController {
+    const initialConfig: FootprintConfig = { ...DEFAULT_CONFIG, ...init }
+    validateConfig(initialConfig)
+
+    const config: Signal<FootprintConfig> = createSignal(initialConfig)
+    const bars: Signal<ReadonlyArray<FootprintBar>> = createSignal<
+        ReadonlyArray<FootprintBar>
+    >([])
+    const cumulativeDelta: Signal<ReadonlyArray<number>> = createSignal<
+        ReadonlyArray<number>
+    >([])
+
+    // ---- Internal state ------------------------------------------------
+
+    /**
+     * barIndex → (priceTickKey → mutable cell).
+     *
+     * We use Maps so insertion order is preserved per-bar (for debug-time
+     * inspection); the public materialisation sorts deterministically.
+     */
+    let buckets: Map<number, Map<number, MutableCell>> = new Map()
+
+    /**
+     * Classifier carry-over. One record shared by tick rule and Lee-Ready —
+     * they have the same field surface. NEVER reset on bar boundary
+     * (see header comment).
+     */
+    const tickState: TickRuleState & LeeReadyState = {
+        prevPrice: null,
+        prevSide: null,
+    }
+
+    /** Set to true on every successful `ingestTrade`; cleared on materialise. */
+    let dirty = false
+    /** Disposal guard. */
+    let disposed = false
+
+    // ---- Helpers -------------------------------------------------------
+
+    function classify(
+        trade: TradeWithFlag,
+        bid: number | undefined,
+        ask: number | undefined,
+    ): AggressorResult {
+        // 1. Try the explicit exchange flag first (zero error).
+        const explicit = classifyExplicit(trade)
+        if (explicit !== null) {
+            // Even when we don't consume the heuristic, advance the
+            // carry-over so a later fallback-classified trade still has a
+            // useful prevPrice/prevSide. We commit prevSide only for known
+            // explicit sides.
+            tickState.prevPrice = trade.price
+            tickState.prevSide = explicit.side === 'unknown' ? null : explicit.side
+            return explicit
+        }
+        // 2. Fall back to the configured heuristic.
+        const mode = config.peek().fallbackClassifier
+        if (mode === 'lee-ready') {
+            // If quotes are missing, classifyLeeReady will degrade to the
+            // tick rule itself — same state record.
+            const b = bid ?? Number.NaN
+            const a = ask ?? Number.NaN
+            return classifyLeeReady(tickState, trade, b, a)
+        }
+        return classifyTickRule(tickState, trade)
+    }
+
+    function bucketFor(barIndex: number): Map<number, MutableCell> {
+        let bar = buckets.get(barIndex)
+        if (bar === undefined) {
+            bar = new Map()
+            buckets.set(barIndex, bar)
+        }
+        return bar
+    }
+
+    function cellFor(
+        bar: Map<number, MutableCell>,
+        priceTickKey: number,
+    ): MutableCell {
+        let cell = bar.get(priceTickKey)
+        if (cell === undefined) {
+            cell = { askVol: 0, bidVol: 0 }
+            bar.set(priceTickKey, cell)
+        }
+        return cell
+    }
+
+    /**
+     * Build the materialised view from `buckets`. Sorts bars ascending by
+     * barIndex; within each bar, sorts cells ascending by price.
+     */
+    function materialise(): {
+        bars: FootprintBar[]
+        cumulative: number[]
+    } {
+        const cfg = config.peek()
+        const sortedBarIndices = [...buckets.keys()].sort((a, b) => a - b)
+
+        const outBars: FootprintBar[] = []
+        const perBarDeltas: number[] = []
+
+        for (const barIndex of sortedBarIndices) {
+            const internal = buckets.get(barIndex)
+            if (internal === undefined) continue
+
+            const sortedKeys = [...internal.keys()].sort((a, b) => a - b)
+            const cells: FootprintBarCell[] = sortedKeys.map((k) => {
+                const c = internal.get(k) as MutableCell
+                return {
+                    price: k * cfg.tickSize,
+                    askVol: c.askVol,
+                    bidVol: c.bidVol,
+                }
+            })
+
+            const delta = computeDelta(cells)
+            let totalVolume = 0
+            for (let i = 0; i < cells.length; i++) {
+                const cell = cells[i]
+                if (cell === undefined) continue
+                totalVolume += cell.askVol + cell.bidVol
+            }
+
+            const imbalances: ReadonlyArray<FootprintImbalance> =
+                computeDiagonalImbalances(cells, cfg.imbalanceRatio)
+
+            const startTime = barIndex * cfg.barIntervalMs
+            const endTime = startTime + cfg.barIntervalMs - 1
+
+            outBars.push({
+                barIndex,
+                startTime,
+                endTime,
+                cells,
+                delta,
+                totalVolume,
+                imbalances,
+            })
+            perBarDeltas.push(delta)
+        }
+
+        return { bars: outBars, cumulative: computeCumulativeDelta(perBarDeltas) }
+    }
+
+    function publishIfDirty(): void {
+        if (!dirty) return
+        const { bars: nextBars, cumulative } = materialise()
+        bars.set(nextBars)
+        cumulativeDelta.set(cumulative)
+        dirty = false
+    }
+
+    // ---- Mutators ------------------------------------------------------
+
+    function ingestTrade(
+        trade: TradeWithFlag,
+        bid?: number,
+        ask?: number,
+    ): void {
+        if (disposed) return
+        // Defensive: reject malformed trades. We do not throw — a single bad
+        // print should not poison the live stream.
+        if (!Number.isFinite(trade.price) || !Number.isFinite(trade.size)) {
+            return
+        }
+        if (!Number.isFinite(trade.timestamp)) return
+        if (trade.size <= 0) return
+
+        const result = classify(trade, bid, ask)
+        if (result.side === 'unknown') {
+            // Drop from the aggregate (the documented contract). We've still
+            // updated tickState inside `classify` so the next trade has
+            // context.
+            return
+        }
+
+        const cfg = config.peek()
+        const barIndex = Math.floor(trade.timestamp / cfg.barIntervalMs)
+        const priceTickKey = Math.round(trade.price / cfg.tickSize)
+
+        const bar = bucketFor(barIndex)
+        const cell = cellFor(bar, priceTickKey)
+        if (result.side === 'buy') {
+            cell.askVol += trade.size
+        } else {
+            cell.bidVol += trade.size
+        }
+        dirty = true
+        publishIfDirty()
+    }
+
+    function setConfig(next: Partial<FootprintConfig>): void {
+        if (disposed) return
+        const cur = config.peek()
+        const merged: FootprintConfig = { ...cur, ...next }
+        validateConfig(merged)
+
+        // Changing tickSize or barIntervalMs invalidates the buckets — the
+        // priceTickKey and barIndex of every accumulated cell would be wrong
+        // under the new partitioning. Clear them and let the caller re-feed
+        // history if needed.
+        const partitionChanged =
+            merged.tickSize !== cur.tickSize ||
+            merged.barIntervalMs !== cur.barIntervalMs
+        if (partitionChanged) {
+            buckets = new Map()
+            // We do NOT reset tickState — the next trade's carry-over is
+            // still valid because the classifier only depends on price
+            // history, not on the bucket partitioning.
+        }
+        config.set(merged)
+        // Re-materialise. If partition changed, bars/cumulative now empty.
+        // If only imbalanceRatio changed, we still want to re-flag.
+        dirty = true
+        publishIfDirty()
+    }
+
+    function reset(): void {
+        if (disposed) return
+        buckets = new Map()
+        tickState.prevPrice = null
+        tickState.prevSide = null
+        bars.set([])
+        cumulativeDelta.set([])
+        dirty = false
+    }
+
+    function dispose(): void {
+        if (disposed) return
+        disposed = true
+        // Mutators check `disposed` so no further writes will fire — existing
+        // subscribers receive no further notifications.
+    }
+
+    return {
+        config,
+        bars,
+        cumulativeDelta,
+        // Canonical verb (API audit BLOCKER-001 harmonisation across
+        // VolumeProfile / OrderBookHeatmap / Footprint). Wired to the same
+        // implementation as `ingestTrade` so existing consumers keep working.
+        ingest: ingestTrade,
+        ingestTrade,
+        setConfig,
+        reset,
+        dispose,
+    }
+}

package/src/components/footprint/index.ts

@@ -0,0 +1,21 @@
+export type {
+    AggressorSide,
+    Trade,
+    TradeWithFlag,
+    FootprintBar,
+    FootprintConfig,
+    FootprintController,
+} from './types'
+export type { AggressorResult, TickRuleState, LeeReadyState } from './aggressor'
+export {
+    classifyExplicit,
+    classifyTickRule,
+    classifyLeeReady,
+} from './aggressor'
+export type { FootprintBarCell, FootprintImbalance } from './perBarStats'
+export {
+    computeDelta,
+    computeCumulativeDelta,
+    computeDiagonalImbalances,
+} from './perBarStats'
+export { createFootprintController } from './createFootprintController'

package/src/components/footprint/perBarStats.ts

@@ -0,0 +1,137 @@
+/**
+ * Per-bar derived statistics for the footprint data model.
+ *
+ *   - `computeDelta`             — Σ(askVol − bidVol) across a bar's cells
+ *   - `computeCumulativeDelta`   — running sum of per-bar deltas
+ *   - `computeDiagonalImbalances` — Bookmap/Sierra-style 3× diagonal flags
+ *
+ * These are the lightweight CPU-side helpers. The compute-shader path
+ * (`computeShader.wgsl.md`) parallelises them per-bar in a single dispatch
+ * for the heavy historical scan; the values produced here are byte-identical
+ * to that GPU path's eventual output.
+ *
+ * See `docs/ROADMAP.md` §3.3 for the diagonal-imbalance rationale.
+ */
+
+import type { FootprintBarCell, FootprintImbalance } from './types'
+
+export type { FootprintBarCell, FootprintImbalance }
+
+// ---------------------------------------------------------------------------
+// Delta and cumulative delta
+// ---------------------------------------------------------------------------
+
+/**
+ * Net buy-vs-sell volume for one bar. Positive values are buyer-dominated.
+ *
+ * Iterates the cells once; the order of cells does not affect the result.
+ * An empty cell list yields 0 (the additive identity, sensible for a no-trade
+ * bar so it does not break the running cumulative sum downstream).
+ */
+export function computeDelta(cells: ReadonlyArray<FootprintBarCell>): number {
+    let sum = 0
+    for (let i = 0; i < cells.length; i++) {
+        const c = cells[i]
+        if (c === undefined) continue
+        sum += c.askVol - c.bidVol
+    }
+    return sum
+}
+
+/**
+ * Running sum of per-bar deltas. `result[i] = Σ deltas[0..i]`.
+ *
+ * Empty input yields an empty array. We allocate a fresh array (not a typed
+ * array) so consumers can splice/copy cheaply at the controller boundary.
+ */
+export function computeCumulativeDelta(
+    perBarDeltas: ReadonlyArray<number>,
+): number[] {
+    const out: number[] = new Array(perBarDeltas.length)
+    let running = 0
+    for (let i = 0; i < perBarDeltas.length; i++) {
+        running += perBarDeltas[i] ?? 0
+        out[i] = running
+    }
+    return out
+}
+
+// ---------------------------------------------------------------------------
+// Diagonal imbalance
+// ---------------------------------------------------------------------------
+
+/**
+ * Diagonal imbalance detection.
+ *
+ *   Aggressive buyers eat the ASK at a price they cross — the ASK at price
+ *   p is filled by buyers who were willing to pay p, and conversely, sellers
+ *   who hit the BID at price p-1 (one tick below) were also "leaning"
+ *   against that same level. So the right comparison is *diagonal*:
+ *
+ *     buy-imbalance at cell i:
+ *       cell[i].askVol >= ratio * cell[i-1].bidVol  AND  cell[i-1].bidVol > 0
+ *
+ *     sell-imbalance at cell i:
+ *       cell[i].bidVol >= ratio * cell[i+1].askVol  AND  cell[i+1].askVol > 0
+ *
+ * Edge handling: a buy-imbalance at i=0 has no `i-1` so it is never reported;
+ * a sell-imbalance at the last index has no `i+1` so it is never reported.
+ *
+ * The `priceIndex` in the result is the index of the *dominant* cell — the
+ * one carrying the heavy volume — not its diagonal counterpart.
+ *
+ * `ratio` is `dominant / weaker`, capped at `Number.POSITIVE_INFINITY` when
+ * the weaker side is zero (caller can choose to render that as "∞").
+ *
+ * Default threshold: 3.0 (Bookmap / Sierra Chart convention). Pass any
+ * positive ratio. A ratio of 1.0 would degenerate to "every diagonal pair
+ * with non-zero asymmetry is an imbalance" — usually too noisy for display.
+ *
+ * @param cells           bar cells, ascending by price
+ * @param ratioThreshold  minimum dominant/weaker ratio to flag
+ */
+export function computeDiagonalImbalances(
+    cells: ReadonlyArray<FootprintBarCell>,
+    ratioThreshold: number,
+): ReadonlyArray<FootprintImbalance> {
+    const out: FootprintImbalance[] = []
+    const n = cells.length
+    if (n === 0) return out
+
+    for (let i = 0; i < n; i++) {
+        const c = cells[i]
+        if (c === undefined) continue
+
+        // Buy imbalance: compare ask at i to bid at i-1 (the diagonal below).
+        if (i > 0) {
+            const below = cells[i - 1]
+            if (below !== undefined && below.bidVol > 0) {
+                const ratio = c.askVol / below.bidVol
+                if (ratio >= ratioThreshold) {
+                    out.push({
+                        priceIndex: i,
+                        direction: 'buy-imbalance',
+                        ratio,
+                    })
+                }
+            }
+        }
+
+        // Sell imbalance: compare bid at i to ask at i+1 (the diagonal above).
+        if (i < n - 1) {
+            const above = cells[i + 1]
+            if (above !== undefined && above.askVol > 0) {
+                const ratio = c.bidVol / above.askVol
+                if (ratio >= ratioThreshold) {
+                    out.push({
+                        priceIndex: i,
+                        direction: 'sell-imbalance',
+                        ratio,
+                    })
+                }
+            }
+        }
+    }
+
+    return out
+}