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

package/dist/components/orderBookHeatmap/logColorScale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logColorScale.js","sourceRoot":"","sources":["../../../src/components/orderBookHeatmap/logColorScale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C,MAAM,UAAU,mBAAmB,CAC/B,OAAe,EACf,OAAe;IAEf,IAAI,EAAE,GAAG,OAAO,CAAA;IAChB,IAAI,EAAE,GAAG,OAAO,CAAA;IAChB,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,IAAI,MAAM,GAAG,CAAC,CAAA;IAEd,SAAS,SAAS;QACd,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;QAChB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACnB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACnB,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IACxB,CAAC;IAED,SAAS,SAAS,CAAC,IAAY;QAC3B,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;YAAE,OAAO,CAAC,CAAA;QACzB,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;YACf,4DAA4D;YAC5D,OAAO,GAAG,CAAA;QACd,CAAC;QACD,IAAI,IAAI,IAAI,EAAE;YAAE,OAAO,CAAC,CAAA;QACxB,IAAI,IAAI,IAAI,EAAE;YAAE,OAAO,CAAC,CAAA;QACxB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,MAAM,CAAA;QAC1C,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,CAAA;QACpB,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,CAAA;QACpB,OAAO,CAAC,CAAA;IACZ,CAAC;IAED,SAAS,QAAQ,CAAC,OAAe,EAAE,OAAe;QAC9C,EAAE,GAAG,OAAO,CAAA;QACZ,EAAE,GAAG,OAAO,CAAA;QACZ,SAAS,EAAE,CAAA;IACf,CAAC;IAED,SAAS,KAAK;QACV,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;IACvC,CAAC;IAED,SAAS,EAAE,CAAA;IACX,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;AACzC,CAAC;AAED,SAAS,QAAQ,CAAC,EAAU,EAAE,EAAU;IACpC,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,eAAe,CAAC,wBAAwB,EAAE,+DAA+D,CAAC,CAAA;IACxH,CAAC;IACD,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,eAAe,CAAC,wBAAwB,EAAE,+DAA+D,CAAC,CAAA;IACxH,CAAC;IACD,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;QACV,MAAM,IAAI,eAAe,CAAC,wBAAwB,EAAE,gDAAgD,CAAC,CAAA;IACzG,CAAC;AACL,CAAC"}

package/dist/components/orderBookHeatmap/snapshotRing.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fixed-capacity ring buffer of recent book snapshots.
+ *
+ * Live render path: the heatmap shader samples a 2-D grid of intensity
+ * values keyed by (column = snapshot index, row = price). The ring stores
+ * the columns. Capacity is chosen so that ring duration covers the visible
+ * heatmap window — e.g. 600 entries @ 100 ms cadence = 60 s.
+ *
+ * Storage is a pre-allocated array with a head pointer; older entries are
+ * overwritten in place once full. `toArray()` walks the ring in
+ * oldest → newest order so consumers can upload it as a single contiguous
+ * GPU buffer.
+ */
+import type { SnapshotRing } from './types';
+export declare function createSnapshotRing(capacity: number): SnapshotRing;
+//# sourceMappingURL=snapshotRing.d.ts.map

package/dist/components/orderBookHeatmap/snapshotRing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotRing.d.ts","sourceRoot":"","sources":["../../../src/components/orderBookHeatmap/snapshotRing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,SAAS,CAAA;AAGzD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CA+CjE"}

package/dist/components/orderBookHeatmap/snapshotRing.js

@@ -0,0 +1,61 @@
+/**
+ * Fixed-capacity ring buffer of recent book snapshots.
+ *
+ * Live render path: the heatmap shader samples a 2-D grid of intensity
+ * values keyed by (column = snapshot index, row = price). The ring stores
+ * the columns. Capacity is chosen so that ring duration covers the visible
+ * heatmap window — e.g. 600 entries @ 100 ms cadence = 60 s.
+ *
+ * Storage is a pre-allocated array with a head pointer; older entries are
+ * overwritten in place once full. `toArray()` walks the ring in
+ * oldest → newest order so consumers can upload it as a single contiguous
+ * GPU buffer.
+ */
+import { KLineChartError } from '../../errors';
+export function createSnapshotRing(capacity) {
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+        throw new KLineChartError('HEATMAP_CONFIG_INVALID', 'createSnapshotRing: capacity must be a positive integer');
+    }
+    const cap = capacity;
+    const slots = new Array(cap).fill(null);
+    let head = 0; // index of the next write slot
+    let count = 0; // number of populated slots; saturates at cap
+    function push(snapshot) {
+        slots[head] = snapshot;
+        head = (head + 1) % cap;
+        if (count < cap)
+            count++;
+    }
+    function toArray() {
+        if (count === 0)
+            return [];
+        const out = new Array(count);
+        // Oldest index when full = head (next write slot); when not full = 0.
+        const start = count < cap ? 0 : head;
+        for (let i = 0; i < count; i++) {
+            const slot = slots[(start + i) % cap];
+            // Guarded above by count; slots[(start+i)%cap] is non-null.
+            out[i] = slot;
+        }
+        return out;
+    }
+    function size() {
+        return count;
+    }
+    function clear() {
+        for (let i = 0; i < cap; i++)
+            slots[i] = null;
+        head = 0;
+        count = 0;
+    }
+    return {
+        get capacity() {
+            return cap;
+        },
+        push,
+        toArray,
+        size,
+        clear,
+    };
+}
+//# sourceMappingURL=snapshotRing.js.map

package/dist/components/orderBookHeatmap/snapshotRing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotRing.js","sourceRoot":"","sources":["../../../src/components/orderBookHeatmap/snapshotRing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IAC/C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,eAAe,CAAC,wBAAwB,EAAE,yDAAyD,CAAC,CAAA;IAClH,CAAC;IACD,MAAM,GAAG,GAAG,QAAQ,CAAA;IACpB,MAAM,KAAK,GAA+B,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACnE,IAAI,IAAI,GAAG,CAAC,CAAA,CAAC,+BAA+B;IAC5C,IAAI,KAAK,GAAG,CAAC,CAAA,CAAC,8CAA8C;IAE5D,SAAS,IAAI,CAAC,QAAsB;QAChC,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAA;QACtB,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,CAAA;QACvB,IAAI,KAAK,GAAG,GAAG;YAAE,KAAK,EAAE,CAAA;IAC5B,CAAC;IAED,SAAS,OAAO;QACZ,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,EAAE,CAAA;QAC1B,MAAM,GAAG,GAAmB,IAAI,KAAK,CAAC,KAAK,CAAC,CAAA;QAC5C,sEAAsE;QACtE,MAAM,KAAK,GAAG,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAA;YACrC,4DAA4D;YAC5D,GAAG,CAAC,CAAC,CAAC,GAAG,IAAoB,CAAA;QACjC,CAAC;QACD,OAAO,GAAG,CAAA;IACd,CAAC;IAED,SAAS,IAAI;QACT,OAAO,KAAK,CAAA;IAChB,CAAC;IAED,SAAS,KAAK;QACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE;YAAE,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;QAC7C,IAAI,GAAG,CAAC,CAAA;QACR,KAAK,GAAG,CAAC,CAAA;IACb,CAAC;IAED,OAAO;QACH,IAAI,QAAQ;YACR,OAAO,GAAG,CAAA;QACd,CAAC;QACD,IAAI;QACJ,OAAO;QACP,IAAI;QACJ,KAAK;KACR,CAAA;AACL,CAAC"}

package/dist/components/orderBookHeatmap/types.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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';
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+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;
+}
+export interface SnapshotRing {
+    readonly capacity: number;
+    push(snapshot: BookSnapshot): void;
+    /** snapshots oldest → newest; never contains gaps */
+    toArray(): ReadonlyArray<BookSnapshot>;
+    size(): number;
+    clear(): void;
+}
+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;
+}
+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;
+    };
+}
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/orderBookHeatmap/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/orderBookHeatmap/types.ts"],"names":[],"mappings":"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"}

package/dist/components/orderBookHeatmap/types.js

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/components/orderBookHeatmap/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/components/orderBookHeatmap/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/components/volumeProfile/binning.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 declare function binBarToBuckets(bar: VolumeProfileBar, buckets: Float64Array, binMin: number, binSize: number, binCount: number, mode: BinningMode): void;
+//# sourceMappingURL=binning.d.ts.map

package/dist/components/volumeProfile/binning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binning.d.ts","sourceRoot":"","sources":["../../../src/components/volumeProfile/binning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC3B,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,WAAW,GAClB,IAAI,CAuEN"}

package/dist/components/volumeProfile/binning.js

@@ -0,0 +1,123 @@
+/**
+ * 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.
+ */
+/**
+ * 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, buckets, binMin, binSize, binCount, mode) {
+    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;
+    }
+}
+//# sourceMappingURL=binning.js.map

package/dist/components/volumeProfile/binning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binning.js","sourceRoot":"","sources":["../../../src/components/volumeProfile/binning.ts"],"names":[],"mappings":"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"}

package/dist/components/volumeProfile/createVolumeProfileController.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 type { VolumeProfileConfig, VolumeProfileController } from './types';
+export interface VolumeProfileControllerInit {
+    config?: Partial<VolumeProfileConfig>;
+}
+export declare function createVolumeProfileController(init?: VolumeProfileControllerInit): VolumeProfileController;
+//# sourceMappingURL=createVolumeProfileController.d.ts.map

package/dist/components/volumeProfile/createVolumeProfileController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createVolumeProfileController.d.ts","sourceRoot":"","sources":["../../../src/components/volumeProfile/createVolumeProfileController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,KAAK,EAER,mBAAmB,EACnB,uBAAuB,EAE1B,MAAM,SAAS,CAAA;AAahB,MAAM,WAAW,2BAA2B;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAA;CACxC;AAED,wBAAgB,6BAA6B,CACzC,IAAI,CAAC,EAAE,2BAA2B,GACnC,uBAAuB,CA8JzB"}

package/dist/components/volumeProfile/createVolumeProfileController.js

@@ -0,0 +1,179 @@
+/**
+ * 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 } from '../../reactivity';
+import { binBarToBuckets } from './binning';
+import { findPOCIndex } from './poc';
+import { computeValueArea } from './valueArea';
+const DEFAULT_CONFIG = {
+    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 function createVolumeProfileController(init) {
+    // -------------------------------------------------------------------
+    // Signals
+    // -------------------------------------------------------------------
+    const initialConfig = {
+        ...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 = createSignal(initialConfig);
+    const state = createSignal(null);
+    // -------------------------------------------------------------------
+    // ingest — full recompute
+    // -------------------------------------------------------------------
+    function ingest(bars) {
+        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 = {
+            buckets,
+            binMin,
+            binSize,
+            poc: pocPrice,
+            vah: vahPrice,
+            val: valPrice,
+            totalVolume: va.totalVolume,
+            vaVolume: va.vaVolume,
+        };
+        state.set(next);
+    }
+    // -------------------------------------------------------------------
+    // setConfig — patch + invalidate
+    // -------------------------------------------------------------------
+    function setConfig(next) {
+        const cur = config.peek();
+        const merged = { ...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() {
+        state.set(null);
+    }
+    // -------------------------------------------------------------------
+    // dispose — silence mutators (same pattern as IndicatorSelectorController)
+    // -------------------------------------------------------------------
+    let disposed = false;
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+    }
+    function guard(fn) {
+        return ((...args) => {
+            if (disposed)
+                return undefined;
+            return fn(...args);
+        });
+    }
+    return {
+        config,
+        state,
+        ingest: guard(ingest),
+        setConfig: guard(setConfig),
+        reset: guard(reset),
+        dispose,
+    };
+}
+//# sourceMappingURL=createVolumeProfileController.js.map