@tradejs/indicators 3.0.0 → 3.0.2

package/README.md

@@ -18,6 +18,10 @@ This package contains the built-in indicator catalog used by strategies and char
 
 It is intended to be connected as an indicator plugin package through `tradejs.config.ts`.
 
+It also exposes strategy-neutral, replay-safe indicator engines through explicit
+subpaths. These modules are libraries and do not register plugin entries by
+themselves.
+
 ## Install
 
 ```bash
@@ -38,6 +42,16 @@ export default defineConfig({
 });
 ```
 
+For a causal range detector that only uses candles available at each call:
+
+```ts
+import { createCausalRangeGeometryEngine } from '@tradejs/indicators/range-geometry';
+```
+
+`@tradejs/indicators/range-geometry` is the public owner of the shared range
+geometry used by the Grid strategy family. It does not depend on either
+strategy or on StrategyAPI.
+
 ## For Custom Indicators
 
 Use `defineIndicatorPlugin(...)` from `@tradejs/core/config` in your own package and add that package to `indicators` in `tradejs.config.ts`.

package/dist/range-geometry.d.mts

@@ -0,0 +1,105 @@
+import { Candle } from '@tradejs/types';
+
+interface CausalRangePivot {
+    kind: 'high' | 'low';
+    barIndex: number;
+    timestamp: number;
+    price: number;
+}
+interface CausalRangeLine {
+    startTimestamp: number;
+    startPrice: number;
+    endTimestamp: number;
+    endPrice: number;
+}
+interface CausalRangeGeometry {
+    ready: boolean;
+    detected: boolean;
+    upperPrice: number | null;
+    lowerPrice: number | null;
+    centerPrice: number | null;
+    position: number | null;
+    widthAtr: number | null;
+    centerSlopeAtrPerBar: number | null;
+    boundaryDivergenceAtr: number | null;
+    containmentRatio: number | null;
+    highPivotCount: number;
+    lowPivotCount: number;
+    rangeAgeBars: number;
+    breakoutDirection: 'UP' | 'DOWN' | null;
+    volatilityExpansionRatio: number | null;
+    volatilityExpansion: boolean;
+    upperLine: CausalRangeLine | null;
+    lowerLine: CausalRangeLine | null;
+    centerLine: CausalRangeLine | null;
+    pivots: CausalRangePivot[];
+    historySize: number;
+    pivotHistorySize: number;
+}
+interface CausalRangeGeometryOptions {
+    pivotLeftBars: number;
+    pivotRightBars: number;
+    lookbackBars: number;
+    minPivotsPerSide: number;
+    minWidthAtr: number;
+    maxWidthAtr: number;
+    maxCenterSlopeAtrPerBar: number;
+    maxBoundaryDivergenceAtr: number;
+    minContainmentRatio: number;
+    containmentToleranceAtr: number;
+    breakoutToleranceAtr: number;
+    minRangeAgeBars: number;
+    maxVolatilityExpansion: number;
+    lineStartMode?: 'history' | 'oldest_pivot';
+}
+declare const createCausalRangeGeometryEngine: ({ options, }: {
+    options: CausalRangeGeometryOptions;
+}) => {
+    next: (candle: Candle, atr: number) => CausalRangeGeometry;
+    getState: () => {
+        pivots: {
+            kind: "high" | "low";
+            barIndex: number;
+            timestamp: number;
+            price: number;
+        }[];
+        upperLine: {
+            startTimestamp: number;
+            startPrice: number;
+            endTimestamp: number;
+            endPrice: number;
+        } | null;
+        lowerLine: {
+            startTimestamp: number;
+            startPrice: number;
+            endTimestamp: number;
+            endPrice: number;
+        } | null;
+        centerLine: {
+            startTimestamp: number;
+            startPrice: number;
+            endTimestamp: number;
+            endPrice: number;
+        } | null;
+        ready: boolean;
+        detected: boolean;
+        upperPrice: number | null;
+        lowerPrice: number | null;
+        centerPrice: number | null;
+        position: number | null;
+        widthAtr: number | null;
+        centerSlopeAtrPerBar: number | null;
+        boundaryDivergenceAtr: number | null;
+        containmentRatio: number | null;
+        highPivotCount: number;
+        lowPivotCount: number;
+        rangeAgeBars: number;
+        breakoutDirection: "UP" | "DOWN" | null;
+        volatilityExpansionRatio: number | null;
+        volatilityExpansion: boolean;
+        historySize: number;
+        pivotHistorySize: number;
+    };
+};
+
+export { type CausalRangeGeometry, type CausalRangeGeometryOptions, type CausalRangeLine, type CausalRangePivot, createCausalRangeGeometryEngine };

package/dist/range-geometry.d.ts

@@ -0,0 +1,105 @@
+import { Candle } from '@tradejs/types';
+
+interface CausalRangePivot {
+    kind: 'high' | 'low';
+    barIndex: number;
+    timestamp: number;
+    price: number;
+}
+interface CausalRangeLine {
+    startTimestamp: number;
+    startPrice: number;
+    endTimestamp: number;
+    endPrice: number;
+}
+interface CausalRangeGeometry {
+    ready: boolean;
+    detected: boolean;
+    upperPrice: number | null;
+    lowerPrice: number | null;
+    centerPrice: number | null;
+    position: number | null;
+    widthAtr: number | null;
+    centerSlopeAtrPerBar: number | null;
+    boundaryDivergenceAtr: number | null;
+    containmentRatio: number | null;
+    highPivotCount: number;
+    lowPivotCount: number;
+    rangeAgeBars: number;
+    breakoutDirection: 'UP' | 'DOWN' | null;
+    volatilityExpansionRatio: number | null;
+    volatilityExpansion: boolean;
+    upperLine: CausalRangeLine | null;
+    lowerLine: CausalRangeLine | null;
+    centerLine: CausalRangeLine | null;
+    pivots: CausalRangePivot[];
+    historySize: number;
+    pivotHistorySize: number;
+}
+interface CausalRangeGeometryOptions {
+    pivotLeftBars: number;
+    pivotRightBars: number;
+    lookbackBars: number;
+    minPivotsPerSide: number;
+    minWidthAtr: number;
+    maxWidthAtr: number;
+    maxCenterSlopeAtrPerBar: number;
+    maxBoundaryDivergenceAtr: number;
+    minContainmentRatio: number;
+    containmentToleranceAtr: number;
+    breakoutToleranceAtr: number;
+    minRangeAgeBars: number;
+    maxVolatilityExpansion: number;
+    lineStartMode?: 'history' | 'oldest_pivot';
+}
+declare const createCausalRangeGeometryEngine: ({ options, }: {
+    options: CausalRangeGeometryOptions;
+}) => {
+    next: (candle: Candle, atr: number) => CausalRangeGeometry;
+    getState: () => {
+        pivots: {
+            kind: "high" | "low";
+            barIndex: number;
+            timestamp: number;
+            price: number;
+        }[];
+        upperLine: {
+            startTimestamp: number;
+            startPrice: number;
+            endTimestamp: number;
+            endPrice: number;
+        } | null;
+        lowerLine: {
+            startTimestamp: number;
+            startPrice: number;
+            endTimestamp: number;
+            endPrice: number;
+        } | null;
+        centerLine: {
+            startTimestamp: number;
+            startPrice: number;
+            endTimestamp: number;
+            endPrice: number;
+        } | null;
+        ready: boolean;
+        detected: boolean;
+        upperPrice: number | null;
+        lowerPrice: number | null;
+        centerPrice: number | null;
+        position: number | null;
+        widthAtr: number | null;
+        centerSlopeAtrPerBar: number | null;
+        boundaryDivergenceAtr: number | null;
+        containmentRatio: number | null;
+        highPivotCount: number;
+        lowPivotCount: number;
+        rangeAgeBars: number;
+        breakoutDirection: "UP" | "DOWN" | null;
+        volatilityExpansionRatio: number | null;
+        volatilityExpansion: boolean;
+        historySize: number;
+        pivotHistorySize: number;
+    };
+};
+
+export { type CausalRangeGeometry, type CausalRangeGeometryOptions, type CausalRangeLine, type CausalRangePivot, createCausalRangeGeometryEngine };

package/dist/range-geometry.js

@@ -0,0 +1,274 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/range-geometry.ts
+var range_geometry_exports = {};
+__export(range_geometry_exports, {
+  createCausalRangeGeometryEngine: () => createCausalRangeGeometryEngine
+});
+module.exports = __toCommonJS(range_geometry_exports);
+var getEmptyGeometry = () => ({
+  ready: false,
+  detected: false,
+  upperPrice: null,
+  lowerPrice: null,
+  centerPrice: null,
+  position: null,
+  widthAtr: null,
+  centerSlopeAtrPerBar: null,
+  boundaryDivergenceAtr: null,
+  containmentRatio: null,
+  highPivotCount: 0,
+  lowPivotCount: 0,
+  rangeAgeBars: 0,
+  breakoutDirection: null,
+  volatilityExpansionRatio: null,
+  volatilityExpansion: false,
+  upperLine: null,
+  lowerLine: null,
+  centerLine: null,
+  pivots: [],
+  historySize: 0,
+  pivotHistorySize: 0
+});
+var fitRegression = (pivots, currentBarIndex) => {
+  if (pivots.length < 2) return null;
+  const points = pivots.map((pivot) => ({
+    x: pivot.barIndex - currentBarIndex,
+    y: pivot.price
+  }));
+  const meanX = points.reduce((sum, point) => sum + point.x, 0) / points.length;
+  const meanY = points.reduce((sum, point) => sum + point.y, 0) / points.length;
+  let covariance = 0;
+  let variance = 0;
+  for (const point of points) {
+    const offsetX = point.x - meanX;
+    covariance += offsetX * (point.y - meanY);
+    variance += offsetX * offsetX;
+  }
+  if (variance <= Number.EPSILON) return null;
+  const slopePerBar = covariance / variance;
+  return {
+    currentValue: meanY - slopePerBar * meanX,
+    slopePerBar
+  };
+};
+var hasConfirmedPivotHigh = ({
+  candles,
+  candidateIndex,
+  leftBars,
+  rightBars
+}) => {
+  const candidate = candles[candidateIndex];
+  if (!candidate) return false;
+  for (let index = candidateIndex - leftBars; index <= candidateIndex + rightBars; index += 1) {
+    if (index === candidateIndex) continue;
+    if ((candles[index]?.high ?? Number.POSITIVE_INFINITY) >= candidate.high) {
+      return false;
+    }
+  }
+  return true;
+};
+var hasConfirmedPivotLow = ({
+  candles,
+  candidateIndex,
+  leftBars,
+  rightBars
+}) => {
+  const candidate = candles[candidateIndex];
+  if (!candidate) return false;
+  for (let index = candidateIndex - leftBars; index <= candidateIndex + rightBars; index += 1) {
+    if (index === candidateIndex) continue;
+    if ((candles[index]?.low ?? Number.NEGATIVE_INFINITY) <= candidate.low) {
+      return false;
+    }
+  }
+  return true;
+};
+var isFiniteCandle = (candle) => [candle.timestamp, candle.open, candle.high, candle.low, candle.close].every(
+  Number.isFinite
+);
+var createCausalRangeGeometryEngine = ({
+  options
+}) => {
+  const candleLimit = Math.max(
+    options.lookbackBars,
+    options.pivotLeftBars + options.pivotRightBars + 1
+  );
+  const candles = [];
+  const pivots = [];
+  const atrHistory = [];
+  let barIndex = -1;
+  let lastTimestamp = null;
+  let geometry = getEmptyGeometry();
+  const next = (candle, atr) => {
+    if (!isFiniteCandle(candle)) return geometry;
+    if (lastTimestamp != null && candle.timestamp <= lastTimestamp) {
+      return geometry;
+    }
+    lastTimestamp = candle.timestamp;
+    barIndex += 1;
+    candles.push({ ...candle, barIndex });
+    if (candles.length > candleLimit) {
+      candles.splice(0, candles.length - candleLimit);
+    }
+    const finiteAtr = Number.isFinite(atr) && atr > 0 ? atr : null;
+    if (finiteAtr != null) {
+      atrHistory.push(finiteAtr);
+      if (atrHistory.length > options.lookbackBars) {
+        atrHistory.splice(0, atrHistory.length - options.lookbackBars);
+      }
+    }
+    const candidateArrayIndex = candles.length - 1 - options.pivotRightBars;
+    if (candidateArrayIndex >= options.pivotLeftBars) {
+      const candidate = candles[candidateArrayIndex];
+      if (hasConfirmedPivotHigh({
+        candles,
+        candidateIndex: candidateArrayIndex,
+        leftBars: options.pivotLeftBars,
+        rightBars: options.pivotRightBars
+      })) {
+        pivots.push({
+          kind: "high",
+          barIndex: candidate.barIndex,
+          timestamp: candidate.timestamp,
+          price: candidate.high
+        });
+      }
+      if (hasConfirmedPivotLow({
+        candles,
+        candidateIndex: candidateArrayIndex,
+        leftBars: options.pivotLeftBars,
+        rightBars: options.pivotRightBars
+      })) {
+        pivots.push({
+          kind: "low",
+          barIndex: candidate.barIndex,
+          timestamp: candidate.timestamp,
+          price: candidate.low
+        });
+      }
+    }
+    const firstRetainedBarIndex = barIndex - options.lookbackBars + 1;
+    while (pivots.length > 0 && pivots[0].barIndex < firstRetainedBarIndex) {
+      pivots.shift();
+    }
+    const highPivots = pivots.filter((pivot) => pivot.kind === "high");
+    const lowPivots = pivots.filter((pivot) => pivot.kind === "low");
+    const upper = fitRegression(highPivots, barIndex);
+    const lower = fitRegression(lowPivots, barIndex);
+    const volatilityBaseline = atrHistory.length > 0 ? atrHistory.reduce((sum, value) => sum + value, 0) / atrHistory.length : null;
+    const volatilityExpansionRatio = finiteAtr != null && volatilityBaseline != null && volatilityBaseline > 0 ? finiteAtr / volatilityBaseline : null;
+    const volatilityExpansion = options.maxVolatilityExpansion > 0 && volatilityExpansionRatio != null && volatilityExpansionRatio > options.maxVolatilityExpansion;
+    if (upper == null || lower == null || finiteAtr == null || upper.currentValue <= lower.currentValue) {
+      geometry = {
+        ...getEmptyGeometry(),
+        highPivotCount: highPivots.length,
+        lowPivotCount: lowPivots.length,
+        volatilityExpansionRatio,
+        volatilityExpansion,
+        pivots: pivots.map((pivot) => ({ ...pivot })),
+        historySize: candles.length,
+        pivotHistorySize: pivots.length
+      };
+      return geometry;
+    }
+    const oldestPivotIndex = Math.min(...pivots.map((pivot) => pivot.barIndex));
+    const firstCandle = options.lineStartMode === "history" ? candles[0] : candles.find((item) => item.barIndex >= oldestPivotIndex) ?? candles[0];
+    const startOffset = firstCandle.barIndex - barIndex;
+    const upperStartPrice = upper.currentValue + upper.slopePerBar * startOffset;
+    const lowerStartPrice = lower.currentValue + lower.slopePerBar * startOffset;
+    const centerPrice = (upper.currentValue + lower.currentValue) / 2;
+    const centerStartPrice = (upperStartPrice + lowerStartPrice) / 2;
+    const width = upper.currentValue - lower.currentValue;
+    const widthAtr = width / finiteAtr;
+    const centerSlopeAtrPerBar = (upper.slopePerBar + lower.slopePerBar) / 2 / finiteAtr;
+    const spanBars = Math.max(1, barIndex - firstCandle.barIndex);
+    const boundaryDivergenceAtr = Math.abs(upper.slopePerBar - lower.slopePerBar) * spanBars / finiteAtr;
+    const tolerance = finiteAtr * options.containmentToleranceAtr;
+    const containedCandles = candles.filter((item) => {
+      const offset = item.barIndex - barIndex;
+      const projectedUpper = upper.currentValue + upper.slopePerBar * offset + tolerance;
+      const projectedLower = lower.currentValue + lower.slopePerBar * offset - tolerance;
+      return item.close <= projectedUpper && item.close >= projectedLower;
+    }).length;
+    const containmentRatio = candles.length > 0 ? containedCandles / candles.length : 0;
+    const rangeAgeBars = spanBars + 1;
+    const enoughPivots = highPivots.length >= options.minPivotsPerSide && lowPivots.length >= options.minPivotsPerSide;
+    const ready = enoughPivots;
+    const detected = ready && rangeAgeBars >= options.minRangeAgeBars && widthAtr >= options.minWidthAtr && (options.maxWidthAtr === 0 || widthAtr <= options.maxWidthAtr) && Math.abs(centerSlopeAtrPerBar) <= options.maxCenterSlopeAtrPerBar && boundaryDivergenceAtr <= options.maxBoundaryDivergenceAtr && containmentRatio >= options.minContainmentRatio && !volatilityExpansion;
+    const breakoutBuffer = finiteAtr * options.breakoutToleranceAtr;
+    const breakoutDirection = candle.close > upper.currentValue + breakoutBuffer ? "UP" : candle.close < lower.currentValue - breakoutBuffer ? "DOWN" : null;
+    const endTimestamp = candle.timestamp;
+    geometry = {
+      ready,
+      detected,
+      upperPrice: upper.currentValue,
+      lowerPrice: lower.currentValue,
+      centerPrice,
+      position: width > 0 ? (candle.close - lower.currentValue) / width : null,
+      widthAtr,
+      centerSlopeAtrPerBar,
+      boundaryDivergenceAtr,
+      containmentRatio,
+      highPivotCount: highPivots.length,
+      lowPivotCount: lowPivots.length,
+      rangeAgeBars,
+      breakoutDirection,
+      volatilityExpansionRatio,
+      volatilityExpansion,
+      upperLine: {
+        startTimestamp: firstCandle.timestamp,
+        startPrice: upperStartPrice,
+        endTimestamp,
+        endPrice: upper.currentValue
+      },
+      lowerLine: {
+        startTimestamp: firstCandle.timestamp,
+        startPrice: lowerStartPrice,
+        endTimestamp,
+        endPrice: lower.currentValue
+      },
+      centerLine: {
+        startTimestamp: firstCandle.timestamp,
+        startPrice: centerStartPrice,
+        endTimestamp,
+        endPrice: centerPrice
+      },
+      pivots: pivots.map((pivot) => ({ ...pivot })),
+      historySize: candles.length,
+      pivotHistorySize: pivots.length
+    };
+    return geometry;
+  };
+  return {
+    next,
+    getState: () => ({
+      ...geometry,
+      pivots: geometry.pivots.map((pivot) => ({ ...pivot })),
+      upperLine: geometry.upperLine ? { ...geometry.upperLine } : null,
+      lowerLine: geometry.lowerLine ? { ...geometry.lowerLine } : null,
+      centerLine: geometry.centerLine ? { ...geometry.centerLine } : null
+    })
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createCausalRangeGeometryEngine
+});

package/dist/range-geometry.mjs

@@ -0,0 +1,249 @@
+// src/range-geometry.ts
+var getEmptyGeometry = () => ({
+  ready: false,
+  detected: false,
+  upperPrice: null,
+  lowerPrice: null,
+  centerPrice: null,
+  position: null,
+  widthAtr: null,
+  centerSlopeAtrPerBar: null,
+  boundaryDivergenceAtr: null,
+  containmentRatio: null,
+  highPivotCount: 0,
+  lowPivotCount: 0,
+  rangeAgeBars: 0,
+  breakoutDirection: null,
+  volatilityExpansionRatio: null,
+  volatilityExpansion: false,
+  upperLine: null,
+  lowerLine: null,
+  centerLine: null,
+  pivots: [],
+  historySize: 0,
+  pivotHistorySize: 0
+});
+var fitRegression = (pivots, currentBarIndex) => {
+  if (pivots.length < 2) return null;
+  const points = pivots.map((pivot) => ({
+    x: pivot.barIndex - currentBarIndex,
+    y: pivot.price
+  }));
+  const meanX = points.reduce((sum, point) => sum + point.x, 0) / points.length;
+  const meanY = points.reduce((sum, point) => sum + point.y, 0) / points.length;
+  let covariance = 0;
+  let variance = 0;
+  for (const point of points) {
+    const offsetX = point.x - meanX;
+    covariance += offsetX * (point.y - meanY);
+    variance += offsetX * offsetX;
+  }
+  if (variance <= Number.EPSILON) return null;
+  const slopePerBar = covariance / variance;
+  return {
+    currentValue: meanY - slopePerBar * meanX,
+    slopePerBar
+  };
+};
+var hasConfirmedPivotHigh = ({
+  candles,
+  candidateIndex,
+  leftBars,
+  rightBars
+}) => {
+  const candidate = candles[candidateIndex];
+  if (!candidate) return false;
+  for (let index = candidateIndex - leftBars; index <= candidateIndex + rightBars; index += 1) {
+    if (index === candidateIndex) continue;
+    if ((candles[index]?.high ?? Number.POSITIVE_INFINITY) >= candidate.high) {
+      return false;
+    }
+  }
+  return true;
+};
+var hasConfirmedPivotLow = ({
+  candles,
+  candidateIndex,
+  leftBars,
+  rightBars
+}) => {
+  const candidate = candles[candidateIndex];
+  if (!candidate) return false;
+  for (let index = candidateIndex - leftBars; index <= candidateIndex + rightBars; index += 1) {
+    if (index === candidateIndex) continue;
+    if ((candles[index]?.low ?? Number.NEGATIVE_INFINITY) <= candidate.low) {
+      return false;
+    }
+  }
+  return true;
+};
+var isFiniteCandle = (candle) => [candle.timestamp, candle.open, candle.high, candle.low, candle.close].every(
+  Number.isFinite
+);
+var createCausalRangeGeometryEngine = ({
+  options
+}) => {
+  const candleLimit = Math.max(
+    options.lookbackBars,
+    options.pivotLeftBars + options.pivotRightBars + 1
+  );
+  const candles = [];
+  const pivots = [];
+  const atrHistory = [];
+  let barIndex = -1;
+  let lastTimestamp = null;
+  let geometry = getEmptyGeometry();
+  const next = (candle, atr) => {
+    if (!isFiniteCandle(candle)) return geometry;
+    if (lastTimestamp != null && candle.timestamp <= lastTimestamp) {
+      return geometry;
+    }
+    lastTimestamp = candle.timestamp;
+    barIndex += 1;
+    candles.push({ ...candle, barIndex });
+    if (candles.length > candleLimit) {
+      candles.splice(0, candles.length - candleLimit);
+    }
+    const finiteAtr = Number.isFinite(atr) && atr > 0 ? atr : null;
+    if (finiteAtr != null) {
+      atrHistory.push(finiteAtr);
+      if (atrHistory.length > options.lookbackBars) {
+        atrHistory.splice(0, atrHistory.length - options.lookbackBars);
+      }
+    }
+    const candidateArrayIndex = candles.length - 1 - options.pivotRightBars;
+    if (candidateArrayIndex >= options.pivotLeftBars) {
+      const candidate = candles[candidateArrayIndex];
+      if (hasConfirmedPivotHigh({
+        candles,
+        candidateIndex: candidateArrayIndex,
+        leftBars: options.pivotLeftBars,
+        rightBars: options.pivotRightBars
+      })) {
+        pivots.push({
+          kind: "high",
+          barIndex: candidate.barIndex,
+          timestamp: candidate.timestamp,
+          price: candidate.high
+        });
+      }
+      if (hasConfirmedPivotLow({
+        candles,
+        candidateIndex: candidateArrayIndex,
+        leftBars: options.pivotLeftBars,
+        rightBars: options.pivotRightBars
+      })) {
+        pivots.push({
+          kind: "low",
+          barIndex: candidate.barIndex,
+          timestamp: candidate.timestamp,
+          price: candidate.low
+        });
+      }
+    }
+    const firstRetainedBarIndex = barIndex - options.lookbackBars + 1;
+    while (pivots.length > 0 && pivots[0].barIndex < firstRetainedBarIndex) {
+      pivots.shift();
+    }
+    const highPivots = pivots.filter((pivot) => pivot.kind === "high");
+    const lowPivots = pivots.filter((pivot) => pivot.kind === "low");
+    const upper = fitRegression(highPivots, barIndex);
+    const lower = fitRegression(lowPivots, barIndex);
+    const volatilityBaseline = atrHistory.length > 0 ? atrHistory.reduce((sum, value) => sum + value, 0) / atrHistory.length : null;
+    const volatilityExpansionRatio = finiteAtr != null && volatilityBaseline != null && volatilityBaseline > 0 ? finiteAtr / volatilityBaseline : null;
+    const volatilityExpansion = options.maxVolatilityExpansion > 0 && volatilityExpansionRatio != null && volatilityExpansionRatio > options.maxVolatilityExpansion;
+    if (upper == null || lower == null || finiteAtr == null || upper.currentValue <= lower.currentValue) {
+      geometry = {
+        ...getEmptyGeometry(),
+        highPivotCount: highPivots.length,
+        lowPivotCount: lowPivots.length,
+        volatilityExpansionRatio,
+        volatilityExpansion,
+        pivots: pivots.map((pivot) => ({ ...pivot })),
+        historySize: candles.length,
+        pivotHistorySize: pivots.length
+      };
+      return geometry;
+    }
+    const oldestPivotIndex = Math.min(...pivots.map((pivot) => pivot.barIndex));
+    const firstCandle = options.lineStartMode === "history" ? candles[0] : candles.find((item) => item.barIndex >= oldestPivotIndex) ?? candles[0];
+    const startOffset = firstCandle.barIndex - barIndex;
+    const upperStartPrice = upper.currentValue + upper.slopePerBar * startOffset;
+    const lowerStartPrice = lower.currentValue + lower.slopePerBar * startOffset;
+    const centerPrice = (upper.currentValue + lower.currentValue) / 2;
+    const centerStartPrice = (upperStartPrice + lowerStartPrice) / 2;
+    const width = upper.currentValue - lower.currentValue;
+    const widthAtr = width / finiteAtr;
+    const centerSlopeAtrPerBar = (upper.slopePerBar + lower.slopePerBar) / 2 / finiteAtr;
+    const spanBars = Math.max(1, barIndex - firstCandle.barIndex);
+    const boundaryDivergenceAtr = Math.abs(upper.slopePerBar - lower.slopePerBar) * spanBars / finiteAtr;
+    const tolerance = finiteAtr * options.containmentToleranceAtr;
+    const containedCandles = candles.filter((item) => {
+      const offset = item.barIndex - barIndex;
+      const projectedUpper = upper.currentValue + upper.slopePerBar * offset + tolerance;
+      const projectedLower = lower.currentValue + lower.slopePerBar * offset - tolerance;
+      return item.close <= projectedUpper && item.close >= projectedLower;
+    }).length;
+    const containmentRatio = candles.length > 0 ? containedCandles / candles.length : 0;
+    const rangeAgeBars = spanBars + 1;
+    const enoughPivots = highPivots.length >= options.minPivotsPerSide && lowPivots.length >= options.minPivotsPerSide;
+    const ready = enoughPivots;
+    const detected = ready && rangeAgeBars >= options.minRangeAgeBars && widthAtr >= options.minWidthAtr && (options.maxWidthAtr === 0 || widthAtr <= options.maxWidthAtr) && Math.abs(centerSlopeAtrPerBar) <= options.maxCenterSlopeAtrPerBar && boundaryDivergenceAtr <= options.maxBoundaryDivergenceAtr && containmentRatio >= options.minContainmentRatio && !volatilityExpansion;
+    const breakoutBuffer = finiteAtr * options.breakoutToleranceAtr;
+    const breakoutDirection = candle.close > upper.currentValue + breakoutBuffer ? "UP" : candle.close < lower.currentValue - breakoutBuffer ? "DOWN" : null;
+    const endTimestamp = candle.timestamp;
+    geometry = {
+      ready,
+      detected,
+      upperPrice: upper.currentValue,
+      lowerPrice: lower.currentValue,
+      centerPrice,
+      position: width > 0 ? (candle.close - lower.currentValue) / width : null,
+      widthAtr,
+      centerSlopeAtrPerBar,
+      boundaryDivergenceAtr,
+      containmentRatio,
+      highPivotCount: highPivots.length,
+      lowPivotCount: lowPivots.length,
+      rangeAgeBars,
+      breakoutDirection,
+      volatilityExpansionRatio,
+      volatilityExpansion,
+      upperLine: {
+        startTimestamp: firstCandle.timestamp,
+        startPrice: upperStartPrice,
+        endTimestamp,
+        endPrice: upper.currentValue
+      },
+      lowerLine: {
+        startTimestamp: firstCandle.timestamp,
+        startPrice: lowerStartPrice,
+        endTimestamp,
+        endPrice: lower.currentValue
+      },
+      centerLine: {
+        startTimestamp: firstCandle.timestamp,
+        startPrice: centerStartPrice,
+        endTimestamp,
+        endPrice: centerPrice
+      },
+      pivots: pivots.map((pivot) => ({ ...pivot })),
+      historySize: candles.length,
+      pivotHistorySize: pivots.length
+    };
+    return geometry;
+  };
+  return {
+    next,
+    getState: () => ({
+      ...geometry,
+      pivots: geometry.pivots.map((pivot) => ({ ...pivot })),
+      upperLine: geometry.upperLine ? { ...geometry.upperLine } : null,
+      lowerLine: geometry.lowerLine ? { ...geometry.lowerLine } : null,
+      centerLine: geometry.centerLine ? { ...geometry.centerLine } : null
+    })
+  };
+};
+export {
+  createCausalRangeGeometryEngine
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tradejs/indicators",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "MIT-licensed indicator plugin catalog for the TradeJS framework.",
   "keywords": [
     "tradejs",
@@ -29,11 +29,16 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./range-geometry": {
+      "types": "./dist/range-geometry.d.ts",
+      "import": "./dist/range-geometry.mjs",
+      "require": "./dist/range-geometry.js"
     }
   },
   "dependencies": {
-    "@tradejs/core": "^3.0.0",
-    "@tradejs/types": "^3.0.0",
+    "@tradejs/core": "^3.0.1",
+    "@tradejs/types": "^3.0.1",
     "fast-technical-indicators": "^1.1.4",
     "klinecharts": "10.0.0-alpha9",
     "technicalindicators": "^3.1.0"