@363045841yyt/klinechart-core 0.7.3

package/src/engine/drawing/plugin.ts

@@ -0,0 +1,343 @@
+import type { RendererPlugin, RenderContext, DrawingStyle, DrawingPrimitive, YAxisLabel, XAxisLabel, YAxisRange, XAxisRange } from '../../plugin'
+import { RENDERER_PRIORITY } from '../../plugin'
+import {
+  DrawingStore,
+  DrawingDefinitionRegistry,
+  createDefaultPrimitiveRendererSet,
+  registerDefaultDrawingDefinitions,
+} from './index'
+import type { PrimitiveRendererSet } from './index'
+import type { KLineData } from '../../types/price'
+import { getPhysicalKLineConfig } from '../utils/klineConfig'
+
+/**
+ * 为选中的绘图推送锚点轴标签
+ * 提取为独立函数供主插件和 overlay 插件共用
+ */
+function pushSelectedDrawingLabels(
+  store: DrawingStore,
+  definitions: DrawingDefinitionRegistry,
+  context: RenderContext,
+  pane: RenderContext['pane'],
+  seriesData: KLineData[],
+  range: RenderContext['range'],
+  kWidth: number,
+  kGap: number,
+  dpr: number,
+  viewport: NonNullable<RenderContext['viewport']>,
+  startXPx: number,
+  unitPx: number
+): void {
+  const selectedId = store.getSelectedId()
+  if (!selectedId) return
+
+  const selectedDrawing = store.getAll().find(d => d.id === selectedId)
+  if (!selectedDrawing || !selectedDrawing.visible || selectedDrawing.paneId !== pane.id) return
+
+  const geometry = definitions.compute(selectedDrawing, {
+    pane,
+    visibleData: seriesData.slice(range.start, range.end),
+    seriesData,
+    range,
+    kLinePositions: context.kLinePositions,
+    kLineCenters: context.kLineCenters,
+    kBarRects: context.kBarRects,
+    kWidth,
+    kGap,
+    dpr,
+    paneWidth: context.paneWidth,
+    viewport,
+    toScreen(anchor) {
+      if (!Number.isFinite(anchor.index) || anchor.index < 0) {
+        return { x: -kWidth, y: pane.yAxis.priceToY(anchor.price) }
+      }
+      const x = (startXPx + anchor.index * unitPx + (unitPx - 1) / 2) / dpr - viewport.scrollLeft
+      return { x, y: pane.yAxis.priceToY(anchor.price) }
+    },
+  })
+
+  if (!geometry) return
+
+  // 只在价格 pane 时添加标签
+  if (pane.role !== 'price') return
+
+  // 合并用户锚点和计算锚点
+  const allAnchors = [...selectedDrawing.anchors, ...(geometry.computedAnchors ?? [])]
+  if (allAnchors.length === 0) return
+
+  // 计算锚点价格范围，用于Y轴价格范围带
+  if (allAnchors.length >= 2) {
+    let minP = Infinity, maxP = -Infinity
+    for (const a of allAnchors) {
+      if (!Number.isFinite(a.price)) continue
+      if (a.price < minP) minP = a.price
+      if (a.price > maxP) maxP = a.price
+    }
+    if (Number.isFinite(minP) && Number.isFinite(maxP) && minP !== maxP) {
+      if (!context.yAxisRanges) context.yAxisRanges = []
+      context.yAxisRanges.push({
+        topY: pane.yAxis.priceToY(maxP),
+        bottomY: pane.yAxis.priceToY(minP),
+        color: selectedDrawing.style?.stroke ?? '#2962ff',
+        opacity: 0.15,
+      })
+    }
+  }
+
+  // 计算锚点X坐标范围，用于X轴时间范围带
+  if (allAnchors.length >= 2) {
+    let minIdx = Infinity, maxIdx = -Infinity
+    for (const a of allAnchors) {
+      if (!Number.isFinite(a.index) || a.index < 0) continue
+      if (a.index < minIdx) minIdx = a.index
+      if (a.index > maxIdx) maxIdx = a.index
+    }
+    if (Number.isFinite(minIdx) && Number.isFinite(maxIdx) && minIdx !== maxIdx) {
+      if (!context.xAxisRanges) context.xAxisRanges = []
+      const leftX = (startXPx + minIdx * unitPx + (unitPx - 1) / 2) / dpr
+      const rightX = (startXPx + maxIdx * unitPx + (unitPx - 1) / 2) / dpr
+      context.xAxisRanges.push({
+        leftX,
+        rightX,
+        color: selectedDrawing.style?.stroke ?? '#2962ff',
+        opacity: 0.15,
+      })
+    }
+  }
+
+  // 辅助函数：根据index获取时间戳
+  const getTimestampForIndex = (idx: number): number | null => {
+    if (idx >= 0 && idx < seriesData.length) {
+      return seriesData[idx]?.timestamp ?? null
+    }
+    if (seriesData.length >= 2 && idx >= seriesData.length) {
+      const lastIdx = seriesData.length - 1
+      const secondLastIdx = seriesData.length - 2
+      const lastTs = seriesData[lastIdx]!.timestamp
+      const secondLastTs = seriesData[secondLastIdx]!.timestamp
+      const timeStep = lastTs - secondLastTs
+      return lastTs + (idx - lastIdx) * timeStep
+    }
+    return null
+  }
+
+  // 推送每个锚点的标签
+  for (const anchor of allAnchors) {
+    if (!Number.isFinite(anchor.index) || !Number.isFinite(anchor.price)) continue
+
+    const screenPoint = (() => {
+      if (anchor.index < 0) {
+        return { x: -kWidth, y: pane.yAxis.priceToY(anchor.price) }
+      }
+      const x = (startXPx + anchor.index * unitPx + (unitPx - 1) / 2) / dpr - viewport.scrollLeft
+      return { x, y: pane.yAxis.priceToY(anchor.price) }
+    })()
+
+    // Y轴标签
+    if (screenPoint.y >= 0 && screenPoint.y <= pane.height) {
+      if (!context.yAxisLabels) context.yAxisLabels = []
+      context.yAxisLabels.push({
+        dataIndex: Math.round(anchor.index),
+        price: anchor.price,
+        y: screenPoint.y,
+        style: {
+          bgColor: selectedDrawing.style?.stroke ?? '#2962ff',
+          borderColor: selectedDrawing.style?.stroke ?? '#2962ff',
+          textColor: '#ffffff',
+        }
+      })
+    }
+
+    // X轴标签
+    if (screenPoint.x >= -kWidth && screenPoint.x <= viewport.plotWidth + kWidth) {
+      const timestamp = anchor.time
+        ? (typeof anchor.time === 'string' ? new Date(anchor.time).getTime() : anchor.time)
+        : getTimestampForIndex(Math.round(anchor.index))
+      if (!timestamp) continue
+
+      if (!context.xAxisLabels) context.xAxisLabels = []
+      context.xAxisLabels.push({
+        dataIndex: Math.round(anchor.index),
+        timestamp,
+        x: screenPoint.x + viewport.scrollLeft,
+        style: {
+          bgColor: selectedDrawing.style?.stroke ?? '#2962ff',
+          textColor: '#ffffff',
+        }
+      })
+    }
+  }
+}
+
+/**
+ * 创建绘图渲染器插件（主层，负责绘制 shape）
+ * 注意：此插件不再推送轴标签，标签由 createDrawingLabelOverlayPlugin 负责
+ */
+export function createDrawingRendererPlugin(options: {
+  store: DrawingStore
+  paneId?: string
+  definitions?: DrawingDefinitionRegistry
+  renderers?: PrimitiveRendererSet
+}): RendererPlugin {
+  const store = options.store
+  const definitions = options.definitions ?? new DrawingDefinitionRegistry()
+  const renderers = options.renderers ?? createDefaultPrimitiveRendererSet()
+  registerDefaultDrawingDefinitions(definitions)
+
+  return {
+    name: 'drawingRenderer',
+    version: '0.1.0',
+    description: '绘图渲染器（仅负责绘制形状）',
+    debugName: '绘图层',
+    paneId: options.paneId ?? 'main',
+    priority: -25,
+    draw(context: RenderContext) {
+      const { ctx, pane, data, range, dpr, paneWidth, kLinePositions, kLineCenters, kBarRects, kWidth, kGap } = context
+      const viewport = context.viewport ?? {
+        scrollLeft: context.scrollLeft,
+        plotWidth: paneWidth,
+        plotHeight: pane.height,
+      }
+      const seriesData = data as KLineData[]
+      const visibleData = seriesData.slice(range.start, range.end)
+      const drawings = store.getVisibleByPane(pane.id)
+      if (drawings.length === 0) return
+
+      const viewportClip = {
+        left: 0,
+        top: 0,
+        right: viewport.plotWidth,
+        bottom: pane.height,
+      }
+
+      ctx.save()
+      ctx.beginPath()
+      ctx.rect(0, 0, viewport.plotWidth, pane.height)
+      ctx.clip()
+
+      for (const drawing of drawings) {
+        const geometry = definitions.compute(drawing, {
+          pane,
+          visibleData,
+          seriesData,
+          range,
+          kLinePositions,
+          kLineCenters,
+          kBarRects,
+          kWidth,
+          kGap,
+          dpr,
+          paneWidth,
+          viewport,
+          toScreen(anchor) {
+            const { startXPx, unitPx } = getPhysicalKLineConfig(kWidth, kGap, dpr)
+            if (!Number.isFinite(anchor.index) || anchor.index < 0) {
+              return { x: -kWidth, y: pane.yAxis.priceToY(anchor.price) }
+            }
+            const x = (startXPx + anchor.index * unitPx + (unitPx - 1) / 2) / dpr - viewport.scrollLeft
+            return { x, y: pane.yAxis.priceToY(anchor.price) }
+          },
+        })
+        if (!geometry) continue
+
+        const isSelected = store.getSelectedId() === drawing.id
+        const primitives = isSelected
+          ? geometry.primitives.map((p) => applySelectedStyle(p, drawing.style))
+          : geometry.primitives
+
+        // 绘制形状（不再推送轴标签，标签由 overlay 插件负责）
+        for (const primitive of primitives) {
+          if (primitive.kind === 'point') {
+            renderers.point(ctx, primitive, dpr)
+            continue
+          }
+          if (primitive.kind === 'line') {
+            renderers.line(ctx, primitive, viewportClip, dpr)
+            continue
+          }
+          if (primitive.kind === 'area') {
+            renderers.area(ctx, primitive, dpr)
+            continue
+          }
+          renderers.text(ctx, primitive, dpr)
+        }
+      }
+
+      ctx.restore()
+    },
+  }
+}
+
+/**
+ * 创建绘图标签 Overlay 插件
+ * 
+ * ⚠️ 警告：此插件必须在 All 和 Overlay 更新级别运行
+ * 当前代码库中没有 UpdateLevel.Main 的触发点，因此此插件设置为 layer: 'overlay' 是安全的
+ * 如果将来添加 Main 级别的更新，此插件会被跳过，导致选中绘图的轴标签消失
+ * 
+ * 解决方案：如果将来需要使用 Main 级别，请将此插件改为同时在 main 和 overlay 层注册，
+ * 或移除分层过滤让此插件在所有级别运行
+ */
+export function createDrawingLabelOverlayPlugin(options: {
+  store: DrawingStore
+  paneId?: string
+  definitions?: DrawingDefinitionRegistry
+}): RendererPlugin {
+  const store = options.store
+  const definitions = options.definitions ?? new DrawingDefinitionRegistry()
+  registerDefaultDrawingDefinitions(definitions)
+
+  return {
+    name: 'drawingLabelOverlay',
+    version: '0.1.0',
+    description: '绘图轴标签渲染器（overlay 层，负责推送选中绘图的轴标签）',
+    debugName: '绘图标签层',
+    paneId: options.paneId ?? 'main',
+    layer: 'overlay',
+    priority: -24, // 比主绘图层稍晚，确保在其他 overlay 插件之后
+    draw(context: RenderContext) {
+      const { pane, data, range, dpr, paneWidth, kWidth, kGap } = context
+      const viewport = context.viewport ?? {
+        scrollLeft: context.scrollLeft,
+        plotWidth: paneWidth,
+        plotHeight: pane.height,
+      }
+      const seriesData = data as KLineData[]
+      const { startXPx, unitPx } = getPhysicalKLineConfig(kWidth, kGap, dpr)
+
+      // 推送选中绘图的锚点标签
+      pushSelectedDrawingLabels(
+        store,
+        definitions,
+        context,
+        pane,
+        seriesData,
+        range,
+        kWidth,
+        kGap,
+        dpr,
+        viewport,
+        startXPx,
+        unitPx
+      )
+    },
+  }
+}
+
+function applySelectedStyle(primitive: DrawingPrimitive, baseStyle: DrawingStyle): DrawingPrimitive {
+  const selectedStroke = baseStyle.stroke ?? '#2962ff'
+  const selectedWidth = (baseStyle.strokeWidth ?? 1) + 1
+  const selectedPointRadius = (baseStyle.pointRadius ?? 4) + 2
+
+  if (primitive.kind === 'point') {
+    return { ...primitive, style: { ...primitive.style, stroke: selectedStroke, pointRadius: selectedPointRadius } }
+  }
+  if (primitive.kind === 'line') {
+    return { ...primitive, style: { ...primitive.style, stroke: selectedStroke, strokeWidth: selectedWidth } }
+  }
+  if (primitive.kind === 'area') {
+    return { ...primitive, style: { ...primitive.style, stroke: selectedStroke } }
+  }
+  // text
+  return { ...primitive, style: { ...primitive.style, textColor: selectedStroke, fontSize: (primitive.style?.fontSize ?? 12) + 1 } }
+}

package/src/engine/indicators/__tests__/__fixtures__/golden/atr.json

@@ -0,0 +1,38 @@
+{
+    "$schema": "Wilder ATR golden values. Period=14. null = warm-up (undefined).",
+    "$source": "Hand-derived from Wilder definition: TR(t)=max(H-L, |H-PrevC|, |L-PrevC|); TR(0)=H-L; ATR(period-1)=mean(TR[0..period-1]); ATR(t)=((period-1)*ATR(t-1)+TR(t))/period for t>=period. Cross-verified by manual computation through index 19; subsequent values are the deterministic float64 continuation of the same recurrence.",
+    "$tolerance": 1e-9,
+    "$note": "Follow-up: replace with pandas-ta / TA-Lib generated fixtures once `scripts/gen-golden.py` lands.",
+    "constantPrice": {
+        "period": 14,
+        "series": [
+            null, null, null, null, null, null, null, null, null, null, null, null, null,
+            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
+        ]
+    },
+    "pureUptrend": {
+        "period": 14,
+        "series": [
+            null, null, null, null, null, null, null, null, null, null, null, null, null,
+            2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2
+        ]
+    },
+    "spikeAtBar19": {
+        "period": 14,
+        "series": [
+            null, null, null, null, null, null, null, null, null, null, null, null, null,
+            2,
+            2,
+            2,
+            2,
+            2,
+            2,
+            2.9285714285714284,
+            2.862244897959184,
+            2.800655976676385,
+            2.7434662640566362,
+            2.690361530909734,
+            2.6410499929876154
+        ]
+    }
+}

package/src/engine/indicators/__tests__/__fixtures__/golden/dema.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "DEMA (Double Exponential MA) golden values. period=20.",
+    "$source": "Hand-derived for constantPrice only — EMA seeded with first close, so EMA = constant immediately; DEMA = 2*c - c = c throughout.",
+    "$note": "pureUptrend/spike golden deferred to pandas-ta gen-golden.py; property/edge tests cover the rest.",
+    "$tolerance": 1e-9,
+    "constantPrice": {
+        "period": 20,
+        "series": [
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100,
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100,
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100
+        ]
+    }
+}

package/src/engine/indicators/__tests__/__fixtures__/golden/hma.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "HMA (Hull Moving Average) golden values. period=9.",
+    "$source": "Hand-derived for constantPrice — WMA on constant input yields constant at every stage; 2*WMA(c, n/2) - WMA(c, n) = 2c - c = c; final WMA(c, sqrt(n)) = c.",
+    "$note": "pureUptrend/spike golden deferred to pandas-ta gen-golden.py; property/edge tests cover the rest. Warm-up = period-1 + round(sqrt(period))-1 = 8+2 = 10 for period=9.",
+    "$tolerance": 1e-9,
+    "constantPrice": {
+        "period": 9,
+        "series": [
+            null, null, null, null, null, null, null, null, null, null,
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100,
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100
+        ]
+    }
+}

package/src/engine/indicators/__tests__/__fixtures__/golden/index.ts

@@ -0,0 +1,55 @@
+import atrGolden from './atr.json'
+import wmaGolden from './wma.json'
+import demaGolden from './dema.json'
+import temaGolden from './tema.json'
+import hmaGolden from './hma.json'
+import kamaGolden from './kama.json'
+
+export interface GoldenSeries {
+    period: number
+    series: (number | null)[]
+}
+
+export type GoldenFixture = Record<string, GoldenSeries>
+
+export const ATR_GOLDEN: GoldenFixture = filterMeta(atrGolden as Record<string, unknown>)
+export const WMA_GOLDEN: GoldenFixture = filterMeta(wmaGolden as Record<string, unknown>)
+export const DEMA_GOLDEN: GoldenFixture = filterMeta(demaGolden as Record<string, unknown>)
+export const TEMA_GOLDEN: GoldenFixture = filterMeta(temaGolden as Record<string, unknown>)
+export const HMA_GOLDEN: GoldenFixture = filterMeta(hmaGolden as Record<string, unknown>)
+export const KAMA_GOLDEN: GoldenFixture = filterMeta(kamaGolden as Record<string, unknown>)
+
+function filterMeta(raw: Record<string, unknown>): GoldenFixture {
+    const out: GoldenFixture = {}
+    for (const [key, value] of Object.entries(raw)) {
+        if (key.startsWith('$')) continue
+        out[key] = value as GoldenSeries
+    }
+    return out
+}
+
+export function assertSeriesClose(
+    actual: readonly (number | undefined)[],
+    expected: readonly (number | null)[],
+    tolerance = 1e-9,
+): void {
+    if (actual.length !== expected.length) {
+        throw new Error(`series length mismatch: actual=${actual.length} expected=${expected.length}`)
+    }
+    for (let i = 0; i < expected.length; i++) {
+        const a = actual[i]
+        const e = expected[i]
+        if (e === null) {
+            if (a !== undefined) {
+                throw new Error(`at index ${i}: expected undefined (warm-up), got ${a}`)
+            }
+            continue
+        }
+        if (a === undefined) {
+            throw new Error(`at index ${i}: expected ${e}, got undefined`)
+        }
+        if (Math.abs(a - e) > tolerance) {
+            throw new Error(`at index ${i}: expected ${e}, got ${a} (Δ=${Math.abs(a - e)})`)
+        }
+    }
+}

package/src/engine/indicators/__tests__/__fixtures__/golden/kama.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "KAMA (Kaufman Adaptive MA) golden values. period=10, fast=2, slow=30.",
+    "$source": "Hand-derived for constantPrice — ER = 0/0 → 0 → SC = slowSC^2; but seed is close[period-1]=100, then KAMA(t) = 100 + SC*(100-100) = 100 ∀ t≥period-1.",
+    "$note": "pureUptrend/spike golden deferred to pandas-ta gen-golden.py; property tests cover the rest.",
+    "$tolerance": 1e-9,
+    "constantPrice": {
+        "period": 10,
+        "series": [
+            null, null, null, null, null, null, null, null, null,
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100,
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100
+        ]
+    }
+}

package/src/engine/indicators/__tests__/__fixtures__/golden/tema.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "TEMA (Triple Exponential MA) golden values. period=20.",
+    "$source": "Hand-derived for constantPrice — EMA chain on a constant input yields constant output at every stage; TEMA = 3*c - 3*c + c = c.",
+    "$note": "pureUptrend/spike golden deferred to pandas-ta gen-golden.py; property/edge tests cover the rest.",
+    "$tolerance": 1e-9,
+    "constantPrice": {
+        "period": 20,
+        "series": [
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100,
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100,
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100
+        ]
+    }
+}

package/src/engine/indicators/__tests__/__fixtures__/golden/wma.json

@@ -0,0 +1,40 @@
+{
+    "$schema": "WMA (Weighted Moving Average) golden values. period=9. null = warm-up.",
+    "$source": "Hand-derived: WMA(t) = sum_{k=0..n-1} (k+1)*values[t-n+1+k] / (n*(n+1)/2). For pureUptrend with close=100+i, sum increments by exactly denom=45 per step → series goes 4740/45, 4785/45, ... = 105.333, 106.333, ...",
+    "$tolerance": 1e-9,
+    "constantPrice": {
+        "period": 9,
+        "series": [
+            null, null, null, null, null, null, null, null,
+            100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100
+        ]
+    },
+    "pureUptrend": {
+        "period": 9,
+        "series": [
+            null, null, null, null, null, null, null, null,
+            105.33333333333333,
+            106.33333333333333,
+            107.33333333333333,
+            108.33333333333333,
+            109.33333333333333,
+            110.33333333333333,
+            111.33333333333333,
+            112.33333333333333,
+            113.33333333333333,
+            114.33333333333333,
+            115.33333333333333,
+            116.33333333333333,
+            117.33333333333333,
+            118.33333333333333,
+            119.33333333333333,
+            120.33333333333333,
+            121.33333333333333,
+            122.33333333333333,
+            123.33333333333333,
+            124.33333333333333,
+            125.33333333333333,
+            126.33333333333333
+        ]
+    }
+}

package/src/engine/indicators/__tests__/__fixtures__/synthetic.ts

@@ -0,0 +1,65 @@
+import type { KLineData } from '@/types/price'
+
+const T0 = 1_700_000_000_000
+const MINUTE = 60_000
+
+function bar(i: number, open: number, high: number, low: number, close: number, volume = 1000): KLineData {
+    return { timestamp: T0 + i * MINUTE, open, high, low, close, volume }
+}
+
+export const empty: KLineData[] = []
+
+export const singleBar: KLineData[] = [bar(0, 100, 101, 99, 100)]
+
+export const shortSequence: KLineData[] = [
+    bar(0, 100, 101, 99, 100),
+    bar(1, 100, 102, 99, 101),
+    bar(2, 101, 103, 100, 102),
+]
+
+export const constantPrice: KLineData[] = Array.from({ length: 30 }, (_, i) =>
+    bar(i, 100, 100, 100, 100),
+)
+
+export const pureUptrend: KLineData[] = Array.from({ length: 30 }, (_, i) =>
+    bar(i, 100 + i, 101 + i, 99 + i, 100 + i),
+)
+
+export const pureDowntrend: KLineData[] = Array.from({ length: 30 }, (_, i) =>
+    bar(i, 200 - i, 201 - i, 199 - i, 200 - i),
+)
+
+export const sideways: KLineData[] = Array.from({ length: 30 }, (_, i) => {
+    const phase = (i % 4) - 1.5
+    const close = 100 + phase
+    return bar(i, 100, 100 + Math.abs(phase) + 0.5, 100 - Math.abs(phase) - 0.5, close)
+})
+
+export const spikeAtBar19: KLineData[] = (() => {
+    const out: KLineData[] = []
+    for (let i = 0; i < 19; i++) out.push(bar(i, 100, 101, 99, 100))
+    out.push(bar(19, 100, 110, 95, 105))
+    for (let i = 20; i < 25; i++) out.push(bar(i, 105, 106, 104, 105))
+    return out
+})()
+
+export const gapUp: KLineData[] = (() => {
+    const out: KLineData[] = []
+    for (let i = 0; i < 10; i++) out.push(bar(i, 100, 101, 99, 100))
+    for (let i = 10; i < 20; i++) out.push(bar(i, 110, 111, 109, 110))
+    return out
+})()
+
+export const FIXTURES = {
+    empty,
+    singleBar,
+    shortSequence,
+    constantPrice,
+    pureUptrend,
+    pureDowntrend,
+    sideways,
+    spikeAtBar19,
+    gapUp,
+} as const
+
+export type FixtureName = keyof typeof FIXTURES

package/src/engine/indicators/__tests__/_propertyAssertions.ts

@@ -0,0 +1,76 @@
+type SparseSeries = readonly (number | undefined)[]
+
+export function assertWarmupThenDefined(series: SparseSeries, expectedWarmup: number, label: string): void {
+    for (let i = 0; i < expectedWarmup; i++) {
+        if (series[i] !== undefined) {
+            throw new Error(`${label}: index ${i} should be warm-up (undefined), got ${series[i]}`)
+        }
+    }
+    for (let i = expectedWarmup; i < series.length; i++) {
+        if (series[i] === undefined) {
+            throw new Error(`${label}: index ${i} should be defined after warm-up, got undefined`)
+        }
+    }
+}
+
+export function assertNonNegative(series: SparseSeries, label: string): void {
+    for (let i = 0; i < series.length; i++) {
+        const v = series[i]
+        if (v !== undefined && v < 0) {
+            throw new Error(`${label}: index ${i} should be ≥ 0, got ${v}`)
+        }
+    }
+}
+
+export function assertBounded(
+    series: SparseSeries,
+    min: number,
+    max: number,
+    label: string,
+): void {
+    for (let i = 0; i < series.length; i++) {
+        const v = series[i]
+        if (v === undefined) continue
+        if (v < min || v > max) {
+            throw new Error(`${label}: index ${i} value ${v} outside [${min}, ${max}]`)
+        }
+    }
+}
+
+export function assertMonotonicByDirection(
+    series: SparseSeries,
+    directions: readonly number[],
+    label: string,
+): void {
+    if (series.length !== directions.length) {
+        throw new Error(`${label}: series and directions length mismatch (${series.length} vs ${directions.length})`)
+    }
+    let prev: number | undefined
+    for (let i = 0; i < series.length; i++) {
+        const v = series[i]
+        if (v === undefined) {
+            prev = undefined
+            continue
+        }
+        if (prev !== undefined) {
+            const expectedDir = directions[i]!
+            const actualDir = Math.sign(v - prev)
+            if (expectedDir !== 0 && actualDir !== expectedDir && actualDir !== 0) {
+                throw new Error(
+                    `${label}: at index ${i} expected direction ${expectedDir}, value moved from ${prev} to ${v} (dir=${actualDir})`,
+                )
+            }
+        }
+        prev = v
+    }
+}
+
+export function assertFiniteOrUndefined(series: SparseSeries, label: string): void {
+    for (let i = 0; i < series.length; i++) {
+        const v = series[i]
+        if (v === undefined) continue
+        if (!Number.isFinite(v)) {
+            throw new Error(`${label}: index ${i} non-finite value ${v}`)
+        }
+    }
+}