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

package/src/engine/indicators/scheduler.ts

@@ -141,6 +141,9 @@ export class IndicatorScheduler {
     // 重绘回调
     private invalidateCallback: (() => void) | null = null
 
+    // Worker 异步结果应用完毕回调（用于串联其他管线，如 Alert）
+    private onResultsAppliedCallback: (() => void) | null = null
+
     /** 从 Chart 获取活跃副图 paneId 列表的回调 */
     private getActiveSubPaneIds: (() => string[]) | null = null
 
@@ -229,6 +232,14 @@ export class IndicatorScheduler {
         this.invalidateCallback = callback
     }
 
+    /**
+     * 设置 Worker 异步结果应用完毕回调
+     * 当 Worker 返回计算结果并写入 StateStore 后触发，用于串联 Alert 等管线
+     */
+    setOnResultsApplied(callback: () => void): void {
+        this.onResultsAppliedCallback = callback
+    }
+
     /**
      * 副图增删后通知 scheduler 刷新 active mask
      */
@@ -251,6 +262,7 @@ export class IndicatorScheduler {
         this.inlineRuntime = null
         this.latestResult = null
         this.invalidateCallback = null
+        this.onResultsAppliedCallback = null
     }
 
     // ============================================================================
@@ -402,6 +414,9 @@ export class IndicatorScheduler {
 
         // 触发重绘
         this.invalidateCallback?.()
+
+        // 通知外部（Alert 等管线）指标结果已就绪
+        this.onResultsAppliedCallback?.()
     }
 
     // ============================================================================

package/src/engine/indicators/soa.ts

@@ -1,3 +1,4 @@
+import { KLineChartError } from '../../errors'
 import type { KLineData } from '../../types/price'
 
 /**
@@ -249,7 +250,7 @@ export class SharedKLineBuffer {
     if (start < 0) start = 0
     if (end > layout.length) end = layout.length
     if (start >= end) {
-      throw new Error(`Invalid subview range: [${start}, ${end})`)
+      throw new KLineChartError('INDICATOR_INVALID_PARAM', `Invalid subview range: [${start}, ${end})`)
     }
 
     const length = end - start

package/src/engine/indicators/stateComposer.ts

@@ -3,6 +3,7 @@
  * 把 Worker/Runtime 返回的 series bundle 组装成与现有兼容的 render states
  */
 
+import { KLineChartError } from '../../errors'
 import type {
     MARenderState,
 } from './state/maState'
@@ -229,7 +230,7 @@ function composeRequiredMetadataVisibleState(
 
     const compose = meta.visibleState?.compose
     if (!compose) {
-        throw new Error(`[StateComposer] Missing visibleState.compose for ${indicatorId}`)
+        throw new KLineChartError('NOT_REGISTERED', `[StateComposer] Missing visibleState.compose for ${indicatorId}`)
     }
 
     return compose({

package/src/engine/subPaneManager.ts

@@ -1,3 +1,4 @@
+import { KLineChartError } from '../errors'
 import type { SubIndicatorType } from './renderers/Indicator'
 import { createSignal, type Signal } from '../reactivity/signal'
 import { createSubIndicatorRenderer } from './renderers/Indicator'
@@ -157,7 +158,7 @@ export class SubPaneManager {
     ): RendererPlugin {
         const definition = ctx.getIndicatorScheduler().getIndicatorMetadata(indicatorId)
         if (!definition) {
-            throw new Error(`[SubPaneManager] Unknown indicator: ${indicatorId}`)
+            throw new KLineChartError('NOT_REGISTERED', `[SubPaneManager] Unknown indicator: ${indicatorId}`)
         }
         return createSubIndicatorRenderer({ indicatorId, paneId, definition, params })
     }

package/src/engine/utils/chartZoomController.ts

@@ -10,6 +10,8 @@ export interface ZoomDependencies {
   getLogicalScrollLeft: () => number
   getCurrentDpr: () => number
   getLeftLoadBufferWidth: () => number
+  getContentWidth: () => number
+  getClientWidth: () => number
   setScrollLeft: (v: number) => void
   onZoomCommitted: (result: ZoomCommittedResult) => void
   getKWidth: () => number
@@ -93,8 +95,12 @@ export class ChartZoomController {
     if (!result) return
 
     const domScrollLeft = result.newScrollLeft + this.deps.getLeftLoadBufferWidth()
+    const contentWidth = this.deps.getContentWidth()
+    const clientWidth = this.deps.getClientWidth()
+    const maxScroll = Math.max(0, contentWidth - clientWidth)
+    const clampedScrollLeft = Math.round(Math.max(0, Math.min(domScrollLeft, maxScroll)) * dpr) / dpr
     this._currentZoomLevel = result.targetLevel
-    this.deps.setScrollLeft(domScrollLeft)
+    this.deps.setScrollLeft(clampedScrollLeft)
     this.deps.onZoomCommitted({
       kWidth: result.newKWidth,
       kGap: result.newKGap,

package/src/errors-help.ts

@@ -0,0 +1,218 @@
+/**
+ * Error recovery hints + diagnostic formatter.
+ *
+ * The companion to `errors.ts`: that file defines the contract
+ * ({@link KLineChartError} + {@link KLineChartErrorCode}); this file
+ * makes each thrown error *useful at the point of catch*.
+ *
+ * What hosts get:
+ *
+ *   - `getRecoveryHint(code)` — a 1–2 sentence "what to do next"
+ *     keyed by error code. Suitable for displaying inline in a dev
+ *     overlay, terminal log, or React error boundary.
+ *   - `formatKLineChartError(err)` — multi-line diagnostic that
+ *     combines the code, the original message, the recovery hint,
+ *     and the cause chain (ES2022 `Error.cause`). The output is
+ *     plain text — no ANSI, no Markdown — so it composes with
+ *     whatever rendering layer the host chooses.
+ *
+ * Why this isn't in `errors.ts`: the recovery hints are user-facing
+ * copy. Keeping them separate means the message taxonomy stays
+ * focused (it's the contract), while the help text can evolve
+ * without churning the contract file.
+ *
+ * Why hints are bundled (not lazy-loaded from a CDN, à la React):
+ * @klinechart-quant ships to environments without network
+ * (kiosk dashboards, isolated trading workstations, Electron apps).
+ * The hint text adds ~2 KB; that's the cheapest possible "useful
+ * error" we can ship.
+ */
+
+import type { KLineChartError, KLineChartErrorCode } from './errors'
+import { isKLineChartError } from './errors'
+
+// ---------------------------------------------------------------------------
+// Recovery hints — keyed by KLineChartErrorCode
+// ---------------------------------------------------------------------------
+
+/**
+ * Note for maintainers: every code in `KLineChartErrorCode` MUST have an
+ * entry here. The "every code has a hint" test enforces this — adding a
+ * code without a hint fails CI.
+ */
+const HINTS: Readonly<Record<KLineChartErrorCode, string>> = {
+    // Generic
+    INVALID_PARAM:
+        'Check the argument values against the documented contract. If a finite number is expected, NaN / Infinity are rejected; if a positive value is expected, zero and negatives are rejected.',
+    INVALID_STATE:
+        'The operation is incompatible with the current controller state. Read the relevant state signal (e.g. `position`, `mode`) before retrying.',
+    DISPOSED:
+        'This controller was disposed and silently no-ops on further mutations. Create a new instance — disposal is one-way.',
+    NOT_REGISTERED:
+        'The id was not registered with this controller. Call register() / setBaseBars() / equivalent before the operation that needs it.',
+
+    // Scale (TimeScale + PriceScale)
+    SCALE_RANGE_INVALID:
+        'visibleMax must be >= visibleMin and both must be finite. Verify any computed range (e.g. autoFit) is well-formed before passing it in.',
+    SCALE_HEIGHT_INVALID:
+        'height must be > 0. After a host resize, re-check the container has a non-zero rect before updating the scale.',
+    SCALE_LOG_REQUIRES_POSITIVE:
+        "Log-mode price scales require strictly positive bounds. Either clamp the range to (0, +∞) or switch the scale's mode to 'linear' before assigning a range that includes <= 0.",
+    SCALE_BAR_WIDTH_INVALID:
+        'barWidth must be > 0. Zoom helpers should clamp the result above a floor (e.g. 0.5 px) before calling setBarWidth.',
+
+    // Footprint controller
+    FOOTPRINT_TICKSIZE_INVALID:
+        'FootprintController tickSize must be > 0 (the quantization unit for the price ladder).',
+    FOOTPRINT_BAR_INTERVAL_INVALID:
+        'FootprintController barIntervalMs must be a positive finite number — the ms-per-bar bucket width.',
+    FOOTPRINT_RATIO_INVALID:
+        'FootprintController imbalanceRatio must be > 0 — the ask:bid ratio threshold for the diagonal imbalance flag.',
+
+    // Anchored VWAP
+    AVWAP_ANCHOR_OUT_OF_RANGE:
+        'anchorIndex must satisfy 0 <= idx < bars.length. Pass an empty bars[] to short-circuit if you have no data yet.',
+
+    // Indicators (shared)
+    INDICATOR_INVALID_PARAM:
+        'Indicator input validation failed. Common causes: period < 2, sigma <= 0, offset outside [0, 1]. See the indicator function header for its exact ranges.',
+
+    // Order Book Heatmap (shared across subsystems)
+    HEATMAP_CONFIG_INVALID:
+        'Order book heatmap config check failed. Most likely culprit: tickSize, snapshotIntervalMs, snapshotRingCapacity, or logColorRange bounds out of range. The error message names the failing field.',
+
+    // MTF Overlay
+    MTF_CONFIG_INVALID:
+        'Multi-timeframe overlay config check failed. Likely targetIntervalMs <= 0, base/target interval mismatch, or a duplicate series id. The error message names the failing field.',
+
+    // Alternative chart types
+    CHART_TYPE_CONFIG_INVALID:
+        'Alternative chart-type config check failed. Renko needs brickSize > 0 (or useATR.period >= 1); Range Bars needs range > 0; Point & Figure needs boxSize > 0 and reversal >= 1.',
+
+    // Replay
+    REPLAY_CONFIG_INVALID:
+        'Replay config check failed. Range needs finite start/end with end >= start; speed must be a positive finite number (reverse playback is rejected in v1).',
+
+    // Controller wiring
+    CONTROLLER_CONFIG_INVALID:
+        'Chart controller wiring is incomplete. Most often: container is null/undefined, opts is missing, or no ChartControllerFactory was registered via __setChartFactory before mount.',
+
+    // Data-fetcher
+    FETCH_FAILED:
+        'A remote data-fetch failed. Check network connectivity, API endpoint, and authentication tokens. If using baostock/tradingview provider, verify the symbol and period are valid.',
+
+    // Serialization
+    SCHEMA_VERSION_MISMATCH:
+        'The serialized state was produced by a different schema version. Migrate it via the schema-version converter, or re-export from the source session.',
+    INVALID_JSON:
+        'The state string was not valid JSON. If it came from a textarea, check for accidental BOM, smart quotes, or trailing commas.',
+    NOT_OBJECT:
+        'A SerializedChartState root must be a JSON object. Arrays and primitives are rejected.',
+    INVALID_TIMESTAMP:
+        'snapshotTakenAt must be an ISO 8601 string parseable by Date.parse. Format it via new Date().toISOString() on the producing side.',
+    MISSING_CONTROLLERS:
+        'A SerializedChartState requires a controllers object. If you intentionally have no controllers, pass an empty object {}.',
+}
+
+/**
+ * Returns the recovery hint for an error code. Always non-empty; if a new
+ * code lands without an entry, the bundled test fails at CI.
+ */
+export function getRecoveryHint(code: KLineChartErrorCode): string {
+    return HINTS[code]
+}
+
+// ---------------------------------------------------------------------------
+// formatKLineChartError — dev-overlay-ready diagnostic
+// ---------------------------------------------------------------------------
+
+export interface FormatErrorOptions {
+    /**
+     * Include the recovery hint line. Default true. Set false when the
+     * host renders the hint separately (e.g. a foldable section).
+     */
+    readonly includeHint?: boolean
+    /**
+     * Include the `.cause` chain (ES2022). Default true. When false the
+     * output is single-error.
+     */
+    readonly includeCause?: boolean
+    /**
+     * Include the stack trace. Default false — stacks are noisy and most
+     * dev overlays render them separately. Set true for log output.
+     */
+    readonly includeStack?: boolean
+    /**
+     * Indent prefix for cause-chain lines. Default `'  '` (two spaces).
+     */
+    readonly indent?: string
+}
+
+const DEFAULTS: Required<FormatErrorOptions> = {
+    includeHint: true,
+    includeCause: true,
+    includeStack: false,
+    indent: '  ',
+}
+
+/**
+ * Format a KLineChartError (or any value caught in a try / catch) into
+ * a plain-text multi-line diagnostic ready for a dev overlay, console,
+ * or test failure message.
+ *
+ * Example output:
+ *
+ *   KLineChartError [SCALE_BAR_WIDTH_INVALID]
+ *     createTimeScale: initialBarWidth must be > 0, got 0
+ *     Hint: barWidth must be > 0. Zoom helpers should clamp the result above a floor (e.g. 0.5 px) before calling setBarWidth.
+ *
+ * For non-KLineChartError input the output is one line — the value's
+ * own `toString()` or `String(value)`.
+ */
+export function formatKLineChartError(
+    err: unknown,
+    opts?: FormatErrorOptions,
+): string {
+    const cfg = { ...DEFAULTS, ...(opts ?? {}) }
+    if (!isKLineChartError(err)) {
+        // Pass-through for unknown errors so callers can use this
+        // unconditionally and still get readable output.
+        if (err instanceof Error) {
+            const head = `${err.name}: ${err.message}`
+            if (!cfg.includeStack || typeof err.stack !== 'string') return head
+            return `${head}\n${err.stack}`
+        }
+        return String(err)
+    }
+    const lines: string[] = []
+    lines.push(`KLineChartError [${err.code}]`)
+    lines.push(`${cfg.indent}${err.message}`)
+    if (cfg.includeHint) {
+        lines.push(`${cfg.indent}Hint: ${getRecoveryHint(err.code)}`)
+    }
+    if (cfg.includeCause && hasCause(err)) {
+        const cause = (err as KLineChartError & { cause?: unknown }).cause
+        lines.push(`${cfg.indent}Caused by:`)
+        const child = formatKLineChartError(cause, {
+            ...cfg,
+            indent: cfg.indent + cfg.indent,
+        })
+        // Indent every line of the child.
+        for (const ln of child.split('\n')) {
+            lines.push(`${cfg.indent}${ln}`)
+        }
+    }
+    if (cfg.includeStack && typeof err.stack === 'string') {
+        lines.push(`${cfg.indent}Stack:`)
+        for (const ln of err.stack.split('\n')) {
+            lines.push(`${cfg.indent}${cfg.indent}${ln}`)
+        }
+    }
+    return lines.join('\n')
+}
+
+function hasCause(err: unknown): boolean {
+    if (typeof err !== 'object' || err === null) return false
+    const cause = (err as { cause?: unknown }).cause
+    return cause !== undefined && cause !== null
+}

package/src/errors.ts

@@ -0,0 +1,128 @@
+/**
+ * KLineChartError — shared error taxonomy for `@klinechart-quant/*`.
+ *
+ * API audit BLOCKER-005 reported 53/54 throws were plain `Error`, 1
+ * `RangeError`, and 2 one-off custom classes with no shared base. This
+ * file is the harmonisation point: every recoverable failure across all
+ * five publishable packages should be a `KLineChartError` carrying a
+ * stable `code` from {@link KLineChartErrorCode}.
+ *
+ * Design:
+ *   - Extends `Error` directly (no abstract layer) so it Just Works under
+ *     V8 stack traces, async/await, and `Error.captureStackTrace`.
+ *   - `code` is a string enum (not a literal union) so end-user code can
+ *     branch on it without importing the enum object.
+ *   - `cause` mirrors the ES2022 `Error.cause` field so wrapping a lower-
+ *     level failure preserves the chain.
+ *   - `instanceof KLineChartError` works across the package boundary
+ *     because every publishable package imports this same module.
+ *
+ * Migration policy: each existing `throw new Error('msg')` becomes
+ * `throw new KLineChartError('CODE', 'msg', { cause? })`. We do NOT rename
+ * `RangeError` throws or browser/Node built-in errors raised by lower
+ * layers — those keep their native type but downstream catch blocks
+ * `instanceof KLineChartError` distinguish "expected/recoverable" from
+ * "platform/unexpected".
+ */
+
+/**
+ * Stable error code surface. New codes append-only — never remove or
+ * renumber. Downstream code branches on these strings.
+ *
+ * Naming convention: SCREAMING_SNAKE_CASE, domain-prefixed where useful
+ * (`SCALE_`, `FOOTPRINT_`, etc.) to disambiguate similar shapes across
+ * controllers.
+ */
+export type KLineChartErrorCode =
+    // generic
+    | 'INVALID_PARAM'
+    | 'INVALID_STATE'
+    | 'DISPOSED'
+    | 'NOT_REGISTERED'
+    // scale (TimeScale / PriceScale construction + setters)
+    | 'SCALE_RANGE_INVALID'
+    | 'SCALE_HEIGHT_INVALID'
+    | 'SCALE_LOG_REQUIRES_POSITIVE'
+    | 'SCALE_BAR_WIDTH_INVALID'
+    // footprint
+    | 'FOOTPRINT_TICKSIZE_INVALID'
+    | 'FOOTPRINT_BAR_INTERVAL_INVALID'
+    | 'FOOTPRINT_RATIO_INVALID'
+    // anchoredVwap
+    | 'AVWAP_ANCHOR_OUT_OF_RANGE'
+    // indicators (shared — every indicator validates inputs the same way)
+    | 'INDICATOR_INVALID_PARAM'
+    // orderBookHeatmap (controller + logColorScale + state + snapshotRing)
+    | 'HEATMAP_CONFIG_INVALID'
+    // mtfOverlay (alignToBaseIndex + resampleBars + createMtfController)
+    | 'MTF_CONFIG_INVALID'
+    // alternative chart types (renko / rangeBars / pointAndFigure)
+    | 'CHART_TYPE_CONFIG_INVALID'
+    // replay controller
+    | 'REPLAY_CONFIG_INVALID'
+    // scene / chart-controller / framework adapter wiring
+    | 'CONTROLLER_CONFIG_INVALID'
+    // data-fetcher (gotdx / baostock / tradingview)
+    | 'FETCH_FAILED'
+    // serialization
+    | 'SCHEMA_VERSION_MISMATCH'
+    | 'INVALID_JSON'
+    | 'NOT_OBJECT'
+    | 'INVALID_TIMESTAMP'
+    | 'MISSING_CONTROLLERS'
+
+export interface KLineChartErrorOptions {
+    /** Lower-level error this wraps (preserved as the standard `.cause`). */
+    cause?: unknown
+}
+
+/**
+ * Base error for everything thrown by `@klinechart-quant/*` that's
+ * expected as part of the API contract.
+ *
+ * Always pass a `code` from {@link KLineChartErrorCode}; the message is
+ * the human-readable explanation.
+ */
+export class KLineChartError extends Error {
+    readonly code: KLineChartErrorCode
+
+    constructor(code: KLineChartErrorCode, message: string, opts?: KLineChartErrorOptions) {
+        // Forward `cause` via the ES2022 Error options bag when available.
+        if (opts?.cause !== undefined) {
+            super(message, { cause: opts.cause })
+        } else {
+            super(message)
+        }
+        this.code = code
+        // `name` defaults to the constructor name in V8; pinning it makes
+        // serialized errors (e.g. via JSON.stringify) carry the type tag.
+        this.name = 'KLineChartError'
+        // Capture stack at the throw site, not inside the constructor.
+        // V8-specific but harmless elsewhere.
+        if (typeof (Error as unknown as { captureStackTrace?: unknown }).captureStackTrace === 'function') {
+            ; (Error as unknown as { captureStackTrace: (e: Error, c: unknown) => void }).captureStackTrace(
+                this,
+                KLineChartError,
+            )
+        }
+    }
+}
+
+/**
+ * Convenience type-guard that doubles as a `code`-narrower:
+ *
+ *   try { ... } catch (e) {
+ *     if (isKLineChartError(e, 'DISPOSED')) {
+ *       // e.code is narrowed to 'DISPOSED'
+ *     }
+ *   }
+ */
+export function isKLineChartError(value: unknown): value is KLineChartError
+export function isKLineChartError<C extends KLineChartErrorCode>(
+    value: unknown,
+    code: C,
+): value is KLineChartError & { code: C }
+export function isKLineChartError(value: unknown, code?: KLineChartErrorCode): boolean {
+    if (!(value instanceof KLineChartError)) return false
+    return code === undefined || value.code === code
+}

package/src/index.ts

@@ -5,3 +5,40 @@ export { VERSION } from './version'
 export * from './tokens'
 export { formatTimestamp } from './utils/dateFormat'
 export { generateUUID } from './utils/uuid'
+
+// ── Batch 1: Error taxonomy ───────────────────────────────────────────────
+export {
+    KLineChartError,
+    isKLineChartError,
+    type KLineChartErrorCode,
+    type KLineChartErrorOptions,
+} from './errors'
+export {
+    getRecoveryHint,
+    formatKLineChartError,
+    type FormatErrorOptions,
+} from './errors-help'
+
+// ── Batch 2: Framework-agnostic foundation ────────────────────────────────
+export * from './input'
+export * from './scale'
+export * from './scheduler'
+export type * from './render'
+export * from './renderer-tier'
+
+// ── Batch 3: Scene abstraction (depends on render) ────────────────────────
+export * from './scene'
+
+// ── Batch 4: Independent business features ────────────────────────────────
+export * from './alerts'
+export * from './replay'
+export * from './chartTypes'
+export * from './indicators'
+
+// ── Batch 5: Component data models ────────────────────────────────────────
+export * from './components/volumeProfile'
+export * from './components/orderBookHeatmap'
+export * from './components/footprint'
+export * from './components/anchoredVwap'
+export * from './components/mtfOverlay'
+export * from './components/crosshairSync'

package/src/indicators/__tests__/maFamily.test.ts

@@ -0,0 +1,159 @@
+/**
+ * MA family completion pack tests (B-9).
+ *
+ * Each indicator gets at least:
+ *   - length parity assertion (output length === input length)
+ *   - NaN-priming-window assertion (correct number of leading NaN)
+ *   - convergence-or-fixture assertion (constant input → constant output;
+ *     known-trending input → monotonic output where applicable)
+ *   - parameter-validation throw paths
+ */
+
+import { describe, it, expect } from 'vitest'
+import { computeALMA } from '../alma'
+import { computeT3 } from '../t3'
+import { computeZLEMA } from '../zlema'
+import { computeLSMA } from '../lsma'
+import { computeVIDYA } from '../vidya'
+import { computeFRAMA } from '../frama'
+
+function constant(n: number, v: number): number[] {
+    return Array.from({ length: n }, () => v)
+}
+
+function ramp(n: number, start = 1, step = 1): number[] {
+    return Array.from({ length: n }, (_, i) => start + step * i)
+}
+
+function countLeadingNaN(out: Float64Array): number {
+    let c = 0
+    for (let i = 0; i < out.length; i++) {
+        if (Number.isNaN(out[i])) c++
+        else break
+    }
+    return c
+}
+
+describe('computeALMA', () => {
+    it('output length === input length', () => {
+        const r = computeALMA(ramp(50), { period: 10 })
+        expect(r.length).toBe(50)
+    })
+
+    it('first period - 1 entries are NaN', () => {
+        const r = computeALMA(ramp(20), { period: 5 })
+        expect(countLeadingNaN(r)).toBe(4)
+    })
+
+    it('constant input → constant output (after priming)', () => {
+        const r = computeALMA(constant(20, 100), { period: 5 })
+        for (let i = 4; i < 20; i++) expect(r[i]!).toBeCloseTo(100, 9)
+    })
+
+    it('throws on invalid params', () => {
+        expect(() => computeALMA([1, 2], { period: 0 })).toThrow(/period/)
+        expect(() => computeALMA([1, 2], { period: 5, offset: -0.1 })).toThrow(/offset/)
+        expect(() => computeALMA([1, 2], { period: 5, sigma: 0 })).toThrow(/sigma/)
+    })
+})
+
+describe('computeT3', () => {
+    it('output length === input length', () => {
+        const r = computeT3(ramp(50), { period: 5 })
+        expect(r.length).toBe(50)
+    })
+
+    it('seeds on first sample and produces no NaN once primed', () => {
+        const r = computeT3(constant(30, 50), { period: 5 })
+        // T3 with constant input is a 6-deep EMA cascade of 50 → asymptotes to 50.
+        const last = r[r.length - 1]!
+        expect(last).toBeCloseTo(50, 6)
+    })
+
+    it('respects volumeFactor bounds', () => {
+        expect(() => computeT3(ramp(20), { period: 5, volumeFactor: -0.1 })).toThrow(/volumeFactor/)
+        expect(() => computeT3(ramp(20), { period: 5, volumeFactor: 1.1 })).toThrow(/volumeFactor/)
+    })
+})
+
+describe('computeZLEMA', () => {
+    it('output length === input length', () => {
+        const r = computeZLEMA(ramp(30), { period: 8 })
+        expect(r.length).toBe(30)
+    })
+
+    it('lag = floor((period-1)/2) leading NaN', () => {
+        // period 8 → lag = 3 → 3 leading NaN
+        const r = computeZLEMA(ramp(30), { period: 8 })
+        expect(countLeadingNaN(r)).toBe(3)
+    })
+
+    it('on a linear ramp, leads or matches the ramp value (zero-lag promise)', () => {
+        // For prices = i, the zero-lag-adjusted series is also linear and a
+        // unit-slope EMA over it tracks the line within numerical tolerance
+        // once primed. We check that the indicator value at i is within a
+        // small constant of i (no large lag).
+        const r = computeZLEMA(ramp(40, 0, 1), { period: 10 })
+        for (let i = 15; i < 40; i++) {
+            expect(Math.abs(r[i]! - i)).toBeLessThan(2)
+        }
+    })
+})
+
+describe('computeLSMA', () => {
+    it('output length === input length and period-1 leading NaN', () => {
+        const r = computeLSMA(ramp(30), { period: 7 })
+        expect(r.length).toBe(30)
+        expect(countLeadingNaN(r)).toBe(6)
+    })
+
+    it('on a perfect linear ramp, LSMA value equals the ramp value (LR endpoint = current bar)', () => {
+        const r = computeLSMA(ramp(40, 10, 0.5), { period: 5 })
+        // ramp(i) = 10 + 0.5 * i; LSMA fits over [i-4..i] and returns line at right endpoint = ramp(i)
+        for (let i = 4; i < 40; i++) {
+            expect(r[i]!).toBeCloseTo(10 + 0.5 * i, 9)
+        }
+    })
+
+    it('constant input → LSMA equals the constant', () => {
+        const r = computeLSMA(constant(20, 7), { period: 5 })
+        for (let i = 4; i < 20; i++) expect(r[i]!).toBeCloseTo(7, 9)
+    })
+})
+
+describe('computeVIDYA', () => {
+    it('output length === input length', () => {
+        const r = computeVIDYA(ramp(30), { period: 9 })
+        expect(r.length).toBe(30)
+    })
+
+    it('first cmoPeriod entries are NaN', () => {
+        const r = computeVIDYA(ramp(30), { period: 9, cmoPeriod: 5 })
+        expect(countLeadingNaN(r)).toBe(5)
+    })
+
+    it('constant input → CMO degenerate → alpha == 0 → stays at seed', () => {
+        // With constant input the CMO has no signal (sum gain = sum loss = 0),
+        // we treat it as 0 → alpha = 0 → VIDYA equals the first valid price.
+        const r = computeVIDYA(constant(20, 42), { period: 5, cmoPeriod: 3 })
+        for (let i = 3; i < 20; i++) expect(r[i]!).toBeCloseTo(42, 9)
+    })
+})
+
+describe('computeFRAMA', () => {
+    it('output length === input length and period-1 leading NaN', () => {
+        const r = computeFRAMA(ramp(40), { period: 16 })
+        expect(r.length).toBe(40)
+        expect(countLeadingNaN(r)).toBe(15)
+    })
+
+    it('rejects odd or too-small periods', () => {
+        expect(() => computeFRAMA(ramp(20), { period: 3 })).toThrow(/period/)
+        expect(() => computeFRAMA(ramp(20), { period: 5 })).toThrow(/period/)
+    })
+
+    it('constant input → flat output once primed', () => {
+        const r = computeFRAMA(constant(40, 9), { period: 8 })
+        for (let i = 7; i < 40; i++) expect(r[i]!).toBeCloseTo(9, 6)
+    })
+})