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

package/dist/components/footprint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/footprint/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACR,aAAa,EACb,KAAK,EACL,aAAa,EACb,YAAY,EACZ,eAAe,EACf,mBAAmB,GACtB,MAAM,SAAS,CAAA;AAChB,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChF,OAAO,EACH,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACzE,OAAO,EACH,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,GAC5B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAA"}

package/dist/components/footprint/index.js

@@ -0,0 +1,4 @@
+export { classifyExplicit, classifyTickRule, classifyLeeReady, } from './aggressor';
+export { computeDelta, computeCumulativeDelta, computeDiagonalImbalances, } from './perBarStats';
+export { createFootprintController } from './createFootprintController';
+//# sourceMappingURL=index.js.map

package/dist/components/footprint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/footprint/index.ts"],"names":[],"mappings":"AASA,OAAO,EACH,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACH,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,GAC5B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAA"}

package/dist/components/footprint/perBarStats.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 };
+/**
+ * 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 declare function computeDelta(cells: ReadonlyArray<FootprintBarCell>): number;
+/**
+ * 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 declare function computeCumulativeDelta(perBarDeltas: ReadonlyArray<number>): number[];
+/**
+ * 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 declare function computeDiagonalImbalances(cells: ReadonlyArray<FootprintBarCell>, ratioThreshold: number): ReadonlyArray<FootprintImbalance>;
+//# sourceMappingURL=perBarStats.d.ts.map

package/dist/components/footprint/perBarStats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perBarStats.d.ts","sourceRoot":"","sources":["../../../src/components/footprint/perBarStats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAEnE,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,CAAA;AAMpD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAQ3E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAClC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,GACpC,MAAM,EAAE,CAQV;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,yBAAyB,CACrC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,EACtC,cAAc,EAAE,MAAM,GACvB,aAAa,CAAC,kBAAkB,CAAC,CAyCnC"}

package/dist/components/footprint/perBarStats.js

@@ -0,0 +1,123 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// 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) {
+    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) {
+    const out = 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, ratioThreshold) {
+    const out = [];
+    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;
+}
+//# sourceMappingURL=perBarStats.js.map

package/dist/components/footprint/perBarStats.js.map

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

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

@@ -0,0 +1,197 @@
+/**
+ * Footprint Chart — public type contract.
+ *
+ * A Footprint chart expands each candle internally to show, at every price
+ * level, how much aggressive buying (lifting the ASK) and aggressive selling
+ * (hitting the BID) traded. It is the core tool of "order flow" reading:
+ * traders use it to answer "did this bar rise because there were real buyers,
+ * or only because sellers withdrew?".
+ *
+ * This module owns the **data model + classification math only**. Rendering
+ * belongs to the `@klinechart-quant/core` Renderer/Scene layer; the planned
+ * GPU compute path is sketched in `computeShader.wgsl.md`.
+ *
+ * See `docs/ROADMAP.md` §3.3 (Footprint) for the algorithm rationale and §0
+ * for how this controller fits the seven-module core layering.
+ *
+ * Cross-references:
+ *   - `aggressor.ts`   — buy/sell classification (explicit, tick rule, Lee-Ready)
+ *   - `perBarStats.ts` — delta, cumulative delta, diagonal imbalance
+ *   - `createFootprintController.ts` — streaming controller (Signal<bars>)
+ */
+import type { Signal } from '../../reactivity';
+/**
+ * Which side of the resting book a trade hit.
+ *
+ *   - 'buy'  — aggressor lifted the ASK (resting seller was passive)
+ *   - 'sell' — aggressor hit the BID  (resting buyer was passive)
+ *
+ * Note: this is the **aggressor**'s side, NOT the "buyer"'s side. Binance's
+ * `isBuyerMaker=true` means the buyer was the maker (passive) and so the
+ * aggressor is the seller — see `classifyExplicit` in `aggressor.ts`.
+ */
+export type AggressorSide = 'buy' | 'sell';
+/**
+ * A classification's confidence flag.
+ *
+ *   - `inferred: false` — derived from an explicit exchange flag (zero error)
+ *   - `inferred: true`  — derived from a heuristic (tick rule or Lee-Ready);
+ *                         the consumer should mark this as approximate so it
+ *                         can be visually distinguished and excluded from
+ *                         strict order-flow analytics
+ *
+ * Every classifier in `aggressor.ts` must set this honestly. We rely on it
+ * downstream when surfacing "(estimated)" warnings on bars whose flow was
+ * inferred — this is the explicit boundary mandated by ROADMAP §3.3.
+ */
+export interface AggressorWithConfidence {
+    side: AggressorSide;
+    inferred: boolean;
+}
+/**
+ * A single trade print. The minimum shape needed for footprint aggregation.
+ *
+ * `timestamp` is epoch ms (chosen because `Math.floor(ts / barIntervalMs)`
+ * cleanly produces a bar index). `size` is in base units (BTC, AAPL shares,
+ * not USD value).
+ */
+export interface Trade {
+    timestamp: number;
+    price: number;
+    size: number;
+}
+/**
+ * A trade carrying the exchange's aggressor flag. Binance-style:
+ * `isBuyerMaker=true` ⇒ the buyer was the passive maker, so the SELLER was
+ * the aggressor. Optional — if the exchange does not include it the
+ * controller falls back to the configured heuristic classifier.
+ */
+export interface TradeWithFlag extends Trade {
+    isBuyerMaker?: boolean;
+}
+/**
+ * One price level inside a footprint bar.
+ *
+ * Cells are sorted by `price` ascending. `askVol` and `bidVol` are gross
+ * (not net) — the delta is computed separately.
+ */
+export interface FootprintBarCell {
+    /** representative price of the bin (quantised to tickSize). */
+    price: number;
+    /** volume of trades classified as `buy` (aggressor lifted the ASK). */
+    askVol: number;
+    /** volume of trades classified as `sell` (aggressor hit the BID). */
+    bidVol: number;
+}
+/**
+ * Direction of a diagonal imbalance — see `perBarStats.ts` for the math.
+ */
+export type ImbalanceDirection = 'buy-imbalance' | 'sell-imbalance';
+/**
+ * One imbalance flag inside a bar.
+ *
+ * `priceIndex` is the index into `FootprintBar.cells` of the dominant side
+ * (not the cell it was compared against). `ratio` is `dominant / weaker`
+ * (always ≥ the configured threshold; capped at `Number.POSITIVE_INFINITY`
+ * when the weaker side is zero — see `computeDiagonalImbalances`).
+ */
+export interface FootprintImbalance {
+    priceIndex: number;
+    direction: ImbalanceDirection;
+    ratio: number;
+}
+/**
+ * The materialised view of one bar (the unit a renderer consumes).
+ *
+ * All fields are derived from the controller's internal streaming aggregate;
+ * `cells` and `imbalances` are recomputed lazily on `bars` signal read.
+ */
+export interface FootprintBar {
+    /** stable index = `Math.floor(timestamp / barIntervalMs)`. */
+    barIndex: number;
+    /** inclusive start of the bar window (epoch ms). */
+    startTime: number;
+    /** exclusive end of the bar window (epoch ms). */
+    endTime: number;
+    /** per-price-level cells, ascending by `price`. */
+    cells: ReadonlyArray<FootprintBarCell>;
+    /** Σ(askVol − bidVol) across cells. Positive ⇒ buyers led. */
+    delta: number;
+    /** Σ(askVol + bidVol). */
+    totalVolume: number;
+    /** diagonal imbalance flags; usually 0–5 per bar. */
+    imbalances: ReadonlyArray<FootprintImbalance>;
+}
+/**
+ * Controller config. All fields required at the controller surface — the
+ * factory fills missing fields with sensible defaults so callers can pass
+ * a partial.
+ */
+export interface FootprintConfig {
+    /** quantise trade prices to this tick size (e.g. 0.01 for BTCUSDT). */
+    tickSize: number;
+    /** ms per bar (e.g. 60_000 for 1m). */
+    barIntervalMs: number;
+    /**
+     * Diagonal imbalance threshold. Default 3 — i.e. a cell must have at
+     * least 3× the volume of its diagonal counterpart to flag.
+     */
+    imbalanceRatio: number;
+    /**
+     * Classifier to fall back to when a trade has no explicit
+     * `isBuyerMaker` flag.
+     *
+     *   - 'tick-rule' — price-change rule; default. Doesn't need bid/ask.
+     *   - 'lee-ready' — uses bid/ask; controller's `ingestTrade` must
+     *                   receive `bid` and `ask` for this path.
+     */
+    fallbackClassifier: 'tick-rule' | 'lee-ready';
+}
+/**
+ * Framework-agnostic controller — mirrors `IndicatorSelectorController`'s
+ * shape (signals for state, plain functions for mutations, idempotent
+ * `dispose`).
+ */
+export interface FootprintController {
+    /** Current config; re-emits when `setConfig` is called. */
+    readonly config: Signal<FootprintConfig>;
+    /** Materialised bars, ascending by `barIndex`. Empty before first trade. */
+    readonly bars: Signal<ReadonlyArray<FootprintBar>>;
+    /**
+     * Cumulative delta series, parallel to `bars`. `cumulativeDelta[i]`
+     * corresponds to `bars[i]`.
+     */
+    readonly cumulativeDelta: Signal<ReadonlyArray<number>>;
+    /**
+     * Ingest one trade — canonical method, aligned with the cross-controller
+     * `ingest()` convention (VolumeProfile, OrderBookHeatmap). `bid`/`ask` are
+     * optional and only consulted when the trade lacks an explicit
+     * `isBuyerMaker` flag AND the configured fallback is `lee-ready`.
+     *
+     * Closes API-audit BLOCKER-001 (5-verb intake proliferation) by
+     * harmonising on `ingest` as the stream-accumulator verb across
+     * `VolumeProfile`, `OrderBookHeatmap`, and `Footprint`.
+     */
+    ingest(trade: TradeWithFlag, bid?: number, ask?: number): void;
+    /**
+     * @deprecated since 0.1.0-alpha.1 — use {@link FootprintController.ingest}.
+     * Kept as a non-removing alias for at least 6 months for migration. Will
+     * be removed in 0.2.0.
+     */
+    ingestTrade(trade: TradeWithFlag, bid?: number, ask?: number): void;
+    /**
+     * Patch the config. Changing `barIntervalMs` or `tickSize` invalidates
+     * the buckets so the state is cleared. Changing only `imbalanceRatio`
+     * just re-materialises on the next read.
+     */
+    setConfig(next: Partial<FootprintConfig>): void;
+    /** Clear all bars and cumulative delta. 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;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/footprint/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAM9C;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAA;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,uBAAuB;IACpC,IAAI,EAAE,aAAa,CAAA;IACnB,QAAQ,EAAE,OAAO,CAAA;CACpB;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAc,SAAQ,KAAK;IACxC,YAAY,CAAC,EAAE,OAAO,CAAA;CACzB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC7B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,eAAe,GAAG,gBAAgB,CAAA;AAEnE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,kBAAkB,CAAA;IAC7B,KAAK,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAA;IAChB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAA;IACf,mDAAmD;IACnD,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAA;IACtC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,qDAAqD;IACrD,UAAU,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;CAChD;AAMD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB;;;;;;;OAOG;IACH,kBAAkB,EAAE,WAAW,GAAG,WAAW,CAAA;CAChD;AAMD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,eAAe,CAAC,CAAA;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAA;IAClD;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IAEvD;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAE9D;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAEnE;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAA;IAE/C,mEAAmE;IACnE,KAAK,IAAI,IAAI,CAAA;IAEb;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAA;CAClB"}

package/dist/components/footprint/types.js

@@ -0,0 +1,23 @@
+/**
+ * Footprint Chart — public type contract.
+ *
+ * A Footprint chart expands each candle internally to show, at every price
+ * level, how much aggressive buying (lifting the ASK) and aggressive selling
+ * (hitting the BID) traded. It is the core tool of "order flow" reading:
+ * traders use it to answer "did this bar rise because there were real buyers,
+ * or only because sellers withdrew?".
+ *
+ * This module owns the **data model + classification math only**. Rendering
+ * belongs to the `@klinechart-quant/core` Renderer/Scene layer; the planned
+ * GPU compute path is sketched in `computeShader.wgsl.md`.
+ *
+ * See `docs/ROADMAP.md` §3.3 (Footprint) for the algorithm rationale and §0
+ * for how this controller fits the seven-module core layering.
+ *
+ * Cross-references:
+ *   - `aggressor.ts`   — buy/sell classification (explicit, tick rule, Lee-Ready)
+ *   - `perBarStats.ts` — delta, cumulative delta, diagonal imbalance
+ *   - `createFootprintController.ts` — streaming controller (Signal<bars>)
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

package/dist/components/mtfOverlay/alignToBaseIndex.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Forward-fill a higher-timeframe series onto the base bar index, with strict
+ * no-lookahead semantics.
+ *
+ * The rule, restated:
+ *   A higher-tf bar opens at `hbar.timestamp` and covers the half-open
+ *   interval `[hbar.timestamp, hbar.timestamp + targetIntervalMs)`. The
+ *   higher-tf value at that bar is available to every base bar whose
+ *   timestamp falls inside that interval — and only those base bars.
+ *
+ * Forward fill is implicit: because higher-tf bars are contiguous in time
+ * (within the input series), a base bar at time `t` reads the value of the
+ * higher-tf bar whose half-open interval contains `t`. If no such bar exists
+ * (i.e. `t` is before the first higher-tf bar's open), the output is `null`.
+ *
+ * Gap handling: if the higher-tf series has a hole (bar N+1's open is more
+ * than `targetIntervalMs` after bar N's open), base bars in that hole get the
+ * value of bar N. This matches the forward-fill intuition users have — once
+ * a higher-tf value exists, it stays visible until the next bucket opens.
+ *
+ * Lookahead-bias test (spelled out so it survives regressions):
+ *   - hbar opens at 09:00 with value 100, targetIntervalMs = 1h.
+ *   - base bar at 09:00 → value 100 (open of the bucket).
+ *   - base bar at 09:59 → value 100 (still inside the bucket).
+ *   - base bar at 08:55 → null (before the bucket opens — using 100 here
+ *     would be lookahead).
+ *
+ * Performance: O(B + H) using a synced two-pointer walk (both inputs are
+ * sorted by timestamp). Callers typically have B ≫ H (many fine bars per
+ * coarse bar), so we step through `baseBars` linearly while advancing the
+ * higher-tf cursor whenever the next bucket opens at or before `t`.
+ */
+/**
+ * @internal — building block used by `createMtfController`. 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 declare function alignToBaseIndex<TValue>(baseBars: ReadonlyArray<{
+    timestamp: number;
+}>, higherTfBars: ReadonlyArray<{
+    timestamp: number;
+}>, higherTfValues: ReadonlyArray<TValue>, targetIntervalMs: number): ReadonlyArray<TValue | null>;
+//# sourceMappingURL=alignToBaseIndex.d.ts.map

package/dist/components/mtfOverlay/alignToBaseIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignToBaseIndex.d.ts","sourceRoot":"","sources":["../../../src/components/mtfOverlay/alignToBaseIndex.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EACnC,QAAQ,EAAE,aAAa,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9C,YAAY,EAAE,aAAa,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,EAClD,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,EACrC,gBAAgB,EAAE,MAAM,GACzB,aAAa,CAAC,MAAM,GAAG,IAAI,CAAC,CA6D9B"}

package/dist/components/mtfOverlay/alignToBaseIndex.js

@@ -0,0 +1,92 @@
+import { KLineChartError } from '../../errors';
+/**
+ * Forward-fill a higher-timeframe series onto the base bar index, with strict
+ * no-lookahead semantics.
+ *
+ * The rule, restated:
+ *   A higher-tf bar opens at `hbar.timestamp` and covers the half-open
+ *   interval `[hbar.timestamp, hbar.timestamp + targetIntervalMs)`. The
+ *   higher-tf value at that bar is available to every base bar whose
+ *   timestamp falls inside that interval — and only those base bars.
+ *
+ * Forward fill is implicit: because higher-tf bars are contiguous in time
+ * (within the input series), a base bar at time `t` reads the value of the
+ * higher-tf bar whose half-open interval contains `t`. If no such bar exists
+ * (i.e. `t` is before the first higher-tf bar's open), the output is `null`.
+ *
+ * Gap handling: if the higher-tf series has a hole (bar N+1's open is more
+ * than `targetIntervalMs` after bar N's open), base bars in that hole get the
+ * value of bar N. This matches the forward-fill intuition users have — once
+ * a higher-tf value exists, it stays visible until the next bucket opens.
+ *
+ * Lookahead-bias test (spelled out so it survives regressions):
+ *   - hbar opens at 09:00 with value 100, targetIntervalMs = 1h.
+ *   - base bar at 09:00 → value 100 (open of the bucket).
+ *   - base bar at 09:59 → value 100 (still inside the bucket).
+ *   - base bar at 08:55 → null (before the bucket opens — using 100 here
+ *     would be lookahead).
+ *
+ * Performance: O(B + H) using a synced two-pointer walk (both inputs are
+ * sorted by timestamp). Callers typically have B ≫ H (many fine bars per
+ * coarse bar), so we step through `baseBars` linearly while advancing the
+ * higher-tf cursor whenever the next bucket opens at or before `t`.
+ */
+/**
+ * @internal — building block used by `createMtfController`. 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 alignToBaseIndex(baseBars, higherTfBars, higherTfValues, targetIntervalMs) {
+    if (!Number.isFinite(targetIntervalMs) || targetIntervalMs <= 0) {
+        throw new KLineChartError('MTF_CONFIG_INVALID', 'alignToBaseIndex: targetIntervalMs must be a positive finite number');
+    }
+    if (higherTfBars.length !== higherTfValues.length) {
+        throw new KLineChartError('MTF_CONFIG_INVALID', `alignToBaseIndex: higherTfBars.length (${higherTfBars.length}) must ` +
+            `equal higherTfValues.length (${higherTfValues.length})`);
+    }
+    const B = baseBars.length;
+    const H = higherTfBars.length;
+    const out = new Array(B);
+    if (B === 0)
+        return out;
+    if (H === 0) {
+        for (let i = 0; i < B; i++)
+            out[i] = null;
+        return out;
+    }
+    // Two-pointer walk. `h` is the index of the higher-tf bar that COULD
+    // cover the current base bar — meaning `higherTfBars[h].timestamp <= t`.
+    // We advance `h` greedily as base bars march forward.
+    let h = -1; // -1 ≡ "no higher-tf bar has opened yet"
+    for (let i = 0; i < B; i++) {
+        const t = baseBars[i].timestamp;
+        // Advance `h` to the latest higher-tf bar whose open is ≤ t. This is
+        // the "no lookahead" gate: a bar whose open > t is invisible to us.
+        while (h + 1 < H && higherTfBars[h + 1].timestamp <= t) {
+            h++;
+        }
+        if (h < 0) {
+            // No higher-tf bar has opened at or before t → leading null.
+            out[i] = null;
+            continue;
+        }
+        // We have a candidate bar `h`. Final check: is t still inside its
+        // half-open interval? If `higherTfBars[h+1]` exists and its open is
+        // ≤ t, the while loop above would have advanced — so we only need to
+        // check the upper bound for the last bar, or in a gap.
+        const bucketStart = higherTfBars[h].timestamp;
+        if (t < bucketStart + targetIntervalMs) {
+            out[i] = higherTfValues[h];
+        }
+        else {
+            // t falls into a gap after bar h's closed interval and before
+            // the next bar opens (or after the end of the series). Forward
+            // fill: keep bar h's value visible.
+            out[i] = higherTfValues[h];
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=alignToBaseIndex.js.map

package/dist/components/mtfOverlay/alignToBaseIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignToBaseIndex.js","sourceRoot":"","sources":["../../../src/components/mtfOverlay/alignToBaseIndex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC5B,QAA8C,EAC9C,YAAkD,EAClD,cAAqC,EACrC,gBAAwB;IAExB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,IAAI,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,eAAe,CACrB,oBAAoB,EACpB,qEAAqE,CACxE,CAAA;IACL,CAAC;IACD,IAAI,YAAY,CAAC,MAAM,KAAK,cAAc,CAAC,MAAM,EAAE,CAAC;QAChD,MAAM,IAAI,eAAe,CACrB,oBAAoB,EACpB,0CAA0C,YAAY,CAAC,MAAM,SAAS;YAClE,gCAAgC,cAAc,CAAC,MAAM,GAAG,CAC/D,CAAA;IACL,CAAC;IAED,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAA;IACzB,MAAM,CAAC,GAAG,YAAY,CAAC,MAAM,CAAA;IAC7B,MAAM,GAAG,GAAsB,IAAI,KAAK,CAAC,CAAC,CAAC,CAAA;IAE3C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAA;IACvB,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;QACzC,OAAO,GAAG,CAAA;IACd,CAAC;IAED,qEAAqE;IACrE,yEAAyE;IACzE,sDAAsD;IACtD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA,CAAC,yCAAyC;IAEpD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QAE/B,qEAAqE;QACrE,oEAAoE;QACpE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,EAAE,CAAC;YACrD,CAAC,EAAE,CAAA;QACP,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACR,6DAA6D;YAC7D,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;YACb,SAAQ;QACZ,CAAC;QAED,kEAAkE;QAClE,oEAAoE;QACpE,qEAAqE;QACrE,uDAAuD;QACvD,MAAM,WAAW,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QAC7C,IAAI,CAAC,GAAG,WAAW,GAAG,gBAAgB,EAAE,CAAC;YACrC,GAAG,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAA;QAC9B,CAAC;aAAM,CAAC;YACJ,8DAA8D;YAC9D,+DAA+D;YAC/D,oCAAoC;YACpC,GAAG,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAA;QAC9B,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAA;AACd,CAAC"}

package/dist/components/mtfOverlay/createMtfController.d.ts

@@ -0,0 +1,7 @@
+import type { BaseBar, MtfController } from './types';
+export interface CreateMtfControllerInit {
+    initialBars?: ReadonlyArray<BaseBar>;
+    baseIntervalMs?: number;
+}
+export declare function createMtfController(init?: CreateMtfControllerInit): MtfController;
+//# sourceMappingURL=createMtfController.d.ts.map

package/dist/components/mtfOverlay/createMtfController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMtfController.d.ts","sourceRoot":"","sources":["../../../src/components/mtfOverlay/createMtfController.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAER,OAAO,EACP,aAAa,EAGhB,MAAM,SAAS,CAAA;AAEhB,MAAM,WAAW,uBAAuB;IACpC,WAAW,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IACpC,cAAc,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,uBAA4B,GAAG,aAAa,CAoJrF"}