@forgecharts/sdk 1.1.23

package/src/core/CoordTransform.ts

@@ -0,0 +1,282 @@
+import type { TimeRange, PriceRange, Point, DrawingPoint } from '@forgecharts/types';
+import type { TimeScale } from './TimeScale';
+import type { PriceScale } from './PriceScale';
+
+/**
+ * Immutable snapshot of the plot area geometry (excluding axes).
+ * All coordinates are in logical canvas pixels (pre-DPR).
+ */
+export type PlotArea = {
+  /** Left edge — always 0. */
+  readonly left: number;
+  /** Top edge — always 0. */
+  readonly top: number;
+  /** Right edge = canvasWidth − priceScaleWidth. */
+  readonly right: number;
+  /** Bottom edge = canvasHeight − timeScaleHeight. */
+  readonly bottom: number;
+  /** Drawable width (canvasWidth − priceScaleWidth). */
+  readonly width: number;
+  /** Drawable height (canvasHeight − timeScaleHeight). */
+  readonly height: number;
+};
+
+/**
+ * CoordTransform — the single source of truth for all coordinate conversions.
+ *
+ * Converts between chart data-space coordinates (Unix timestamp in seconds,
+ * price) and canvas pixel coordinates (x, y).  Every chart subsystem that
+ * needs coordinate maths — the Crosshair, series renderers, drawing tools,
+ * plugins — should use this class rather than reading scale internals directly.
+ *
+ * A `CoordTransform` instance is owned by `Chart` and can be retrieved via
+ * `chart.transform()`.  It is kept up-to-date with every resize; callers
+ * hold a stable reference and always see current values.
+ *
+ * @example
+ * ```ts
+ * const t = chart.transform();
+ *
+ * // Data → pixel
+ * const x = t.timeToX(bar.time);
+ * const y = t.priceToY(bar.close);
+ * const { x, y } = t.toPixel(bar.time, bar.close);
+ *
+ * // Pixel → data (e.g. read pointer position)
+ * const { time, price } = t.fromPixel(event.offsetX, event.offsetY);
+ *
+ * // Zoom on wheel
+ * t.zoomTime(0.9, event.offsetX);   // zoom in
+ *
+ * // Pan on drag
+ * t.pan(dx, dy);
+ * ```
+ */
+export class CoordTransform {
+  private _canvasWidth = 0;
+  private _canvasHeight = 0;
+
+  private readonly _timeScale: TimeScale;
+  private readonly _priceScale: PriceScale;
+
+  /** Width of the right-side price axis in logical pixels. */
+  readonly priceScaleWidth: number;
+
+  /** Height of the bottom time axis in logical pixels. */
+  readonly timeScaleHeight: number;
+
+  constructor(
+    timeScale: TimeScale,
+    priceScale: PriceScale,
+    priceScaleWidth: number,
+    timeScaleHeight: number,
+  ) {
+    this._timeScale = timeScale;
+    this._priceScale = priceScale;
+    this.priceScaleWidth = priceScaleWidth;
+    this.timeScaleHeight = timeScaleHeight;
+  }
+
+  // ─── Canvas update ────────────────────────────────────────────────────────
+
+  /**
+   * Stores the current canvas size.
+   * **Must be called** by `Chart` once at construction and after every resize.
+   */
+  update(canvasWidth: number, canvasHeight: number): void {
+    this._canvasWidth = canvasWidth;
+    this._canvasHeight = canvasHeight;
+  }
+
+  // ─── Plot area geometry ───────────────────────────────────────────────────
+
+  /**
+   * The drawable region excluding both axes.
+   * Use this to clip drawing operations or check mouse bounds.
+   */
+  get plotArea(): PlotArea {
+    const w = this._canvasWidth - this.priceScaleWidth;
+    const h = this._canvasHeight - this.timeScaleHeight;
+    return { left: 0, top: 0, right: w, bottom: h, width: w, height: h };
+  }
+
+  /** Full logical canvas width (plot area + price axis). */
+  get canvasWidth(): number {
+    return this._canvasWidth;
+  }
+
+  /** Full logical canvas height (plot area + time axis). */
+  get canvasHeight(): number {
+    return this._canvasHeight;
+  }
+
+  /** Drawable width (canvas width minus the price axis). */
+  get plotWidth(): number {
+    return this._canvasWidth - this.priceScaleWidth;
+  }
+
+  /** Drawable height (canvas height minus the time axis). */
+  get plotHeight(): number {
+    return this._canvasHeight - this.timeScaleHeight;
+  }
+
+  // ─── Time axis ────────────────────────────────────────────────────────────
+
+  /**
+   * Maps a Unix timestamp (seconds) to a canvas X pixel.
+   *
+   * Returns a value in `[0, plotWidth]` for visible times; may be negative
+   * or exceed `plotWidth` for off-screen bars — useful for clipping checks.
+   */
+  timeToX(time: number): number {
+    return this._timeScale.timeToX(time, this._canvasWidth);
+  }
+
+  /**
+   * Maps a canvas X pixel coordinate back to a Unix timestamp (seconds).
+   */
+  xToTime(x: number): number {
+    return this._timeScale.xToTime(x, this._canvasWidth);
+  }
+
+  // ─── Price axis ───────────────────────────────────────────────────────────
+
+  /**
+   * Maps a price value to a canvas Y pixel.
+   *
+   * Y = 0 is the top of the canvas.  Higher prices map to smaller Y values
+   * in normal (non-inverted) scale mode.
+   */
+  priceToY(price: number): number {
+    return this._priceScale.priceToY(price, this._canvasHeight);
+  }
+
+  /**
+   * Maps a canvas Y pixel coordinate back to a price value.
+   */
+  yToPrice(y: number): number {
+    return this._priceScale.yToPrice(y, this._canvasHeight);
+  }
+
+  // ─── Combined helpers ─────────────────────────────────────────────────────
+
+  /**
+   * Converts a data-space point to a canvas pixel.
+   *
+   * @example
+   * ```ts
+   * const { x, y } = transform.toPixel(bar.time, bar.high);
+   * ctx.arc(x, y, 3, 0, Math.PI * 2);
+   * ```
+   */
+  toPixel(time: number, price: number): Point {
+    return { x: this.timeToX(time), y: this.priceToY(price) };
+  }
+
+  /**
+   * Converts a canvas pixel to a data-space point (time, price).
+   *
+   * Returned `time` is in Unix seconds; `price` is in the same units as the
+   * price scale (e.g. USD for BTCUSDT charts).
+   *
+   * @example
+   * ```ts
+   * canvas.addEventListener('click', e => {
+   *   const { time, price } = transform.fromPixel(e.offsetX, e.offsetY);
+   * });
+   * ```
+   */
+  fromPixel(x: number, y: number): DrawingPoint {
+    return { time: this.xToTime(x), price: this.yToPrice(y) };
+  }
+
+  /**
+   * Returns `true` when pixel `(x, y)` falls inside the plot area —
+   * i.e. not over the axis gutter regions.
+   */
+  inPlotArea(x: number, y: number): boolean {
+    return x >= 0 && x <= this.plotWidth && y >= 0 && y <= this.plotHeight;
+  }
+
+  // ─── Zoom ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Zooms the time axis around a canvas-space pivot X pixel.
+   *
+   * @param factor  Multiplier applied to the visible time span.
+   *                `< 1` = zoom in (fewer bars visible),
+   *                `> 1` = zoom out (more bars visible).
+   * @param pivotX  Canvas X pixel that remains fixed during the zoom.
+   *                Pass `event.offsetX` from a wheel event.
+   */
+  zoomTime(factor: number, pivotX: number): void {
+    this._timeScale.zoom(factor, pivotX, this._canvasWidth);
+  }
+
+  /**
+   * Zooms the price axis around a canvas-space pivot Y pixel.
+   *
+   * @param factor  Multiplier for the visible price span.
+   *                `> 1` = zoom out (wider range), `< 1` = zoom in (narrower range).
+   * @param pivotY  Canvas Y pixel that stays fixed during the zoom.
+   */
+  zoomPrice(factor: number, pivotY: number): void {
+    const pivotPrice = this.yToPrice(pivotY);
+    const { min, max } = this._priceScale.visibleRange;
+    const span = max - min;
+    const newSpan = span * factor;
+    // Keep the pivot price anchored at the same Y position
+    const ratio = (pivotPrice - min) / span;
+    const newMin = pivotPrice - ratio * newSpan;
+    this._priceScale.setVisibleRange({ min: newMin, max: newMin + newSpan });
+  }
+
+  // ─── Pan ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Pans the chart by a pixel delta — typically called from a drag handler.
+   *
+   * - `deltaX > 0` (right drag) shifts the visible time range backward
+   *   (revealing older bars).
+   * - `deltaX < 0` (left drag) shifts forward (revealing newer bars).
+   * - `deltaY > 0` (down drag) shifts the visible price range downward.
+   * - `deltaY < 0` (up drag) shifts the price range upward.
+   *
+   * @param deltaX  Horizontal pixel displacement since last event.
+   * @param deltaY  Vertical pixel displacement since last event.
+   */
+  pan(deltaX: number, deltaY: number): void {
+    // ── Time axis ────────────────────────────────────────────────────────────
+    if (deltaX !== 0 && this._canvasWidth > 0) {
+      const { from, to } = this._timeScale.visibleRange;
+      const timeSpan = to - from;
+      // Right drag (deltaX > 0) → move range backward → negate
+      const deltaSeconds = (deltaX / this.plotWidth) * timeSpan;
+      this._timeScale.scroll(-deltaSeconds);
+    }
+
+    // ── Price axis ────────────────────────────────────────────────────────────
+    if (deltaY !== 0 && this._canvasHeight > 0) {
+      const { min, max } = this._priceScale.visibleRange;
+      const priceSpan = max - min;
+      // Down drag (deltaY > 0) → chart content moves down → reveal higher prices → add
+      const deltaPrice = (deltaY / this.plotHeight) * priceSpan;
+      this._priceScale.setVisibleRange({
+        min: min + deltaPrice,
+        max: max + deltaPrice,
+      });
+    }
+  }
+
+  // ─── Range accessors ──────────────────────────────────────────────────────
+
+  /** The currently visible time range (Unix seconds). */
+  get timeRange(): TimeRange {
+    return this._timeScale.visibleRange;
+  }
+
+  /** The currently visible price range. */
+  get priceRange(): PriceRange {
+    return this._priceScale.visibleRange;
+  }
+}

package/src/core/Crosshair.ts

@@ -0,0 +1,207 @@
+import type { ChartColors, ChartOptions, CrosshairOptions } from '@forgecharts/types';
+import type { CanvasLayer } from './CanvasLayer';
+import type { CoordTransform } from './CoordTransform';
+import { hexToRgba } from '@forgecharts/utils';
+
+/**
+ * Crosshair — renders the interactive cross-line overlay and price/time labels.
+ */
+export class Crosshair {
+  private _x: number | null = null;
+  private _snapTime: number | null = null;
+  private _y: number | null = null;
+  private readonly _layer: CanvasLayer;
+  private readonly _colors: ChartColors;
+  private readonly _options: Required<CrosshairOptions>;
+  private readonly _transform: CoordTransform;
+  /** IANA timezone for the time label on the crosshair. Falls back to UTC. */
+  timezone: string | undefined = undefined;
+  /** Active timeframe — controls whether time is shown alongside the date. */
+  interval: string = '1h';
+
+  constructor(
+    layer: CanvasLayer,
+    colors: ChartColors,
+    chartOptions: ChartOptions,
+    transform: CoordTransform,
+  ) {
+    this._layer = layer;
+    this._colors = colors;
+    this._transform = transform;
+    const co = chartOptions.crosshair as CrosshairOptions | undefined;
+    this._options = {
+      mode: co?.mode ?? 'normal',
+      vertLine: {
+        ...(co?.vertLine?.color !== undefined ? { color: co.vertLine.color } : {}),
+        width: co?.vertLine?.width ?? 1,
+        style: co?.vertLine?.style ?? 'dashed',
+        visible: co?.vertLine?.visible ?? true,
+        labelVisible: co?.vertLine?.labelVisible ?? true,
+      },
+      horzLine: {
+        ...(co?.horzLine?.color !== undefined ? { color: co.horzLine.color } : {}),
+        width: co?.horzLine?.width ?? 1,
+        style: co?.horzLine?.style ?? 'dashed',
+        visible: co?.horzLine?.visible ?? true,
+        labelVisible: co?.horzLine?.labelVisible ?? true,
+      },
+    };
+  }
+
+  update(x: number, y: number, snapTime?: number): void {
+    this._x = x;
+    this._y = y;
+    this._snapTime = snapTime ?? null;
+  }
+
+  hide(): void {
+    this._x = null;
+    this._y = null;
+    this._snapTime = null;
+  }
+
+  destroy(): void {
+    this.hide();
+  }
+
+  render(ctx: CanvasRenderingContext2D, width: number, height: number): void {
+    if (this._x === null || this._y === null) return;
+    if (this._options.mode === 'hidden') return;
+
+    const { x, y } = { x: this._x, y: this._y };
+    const priceScaleWidth = this._transform.priceScaleWidth;
+    const timeScaleHeight = this._transform.timeScaleHeight;
+    const plotWidth = this._transform.plotWidth;
+    const plotHeight = this._transform.plotHeight;
+
+    // Suppress unused-variable warnings — width/height kept for API compatibility
+    void width;
+    void height;
+
+    ctx.save();
+
+    // Vertical line
+    if (this._options.vertLine.visible === true && x >= 0 && x <= plotWidth) {
+      const vl = this._options.vertLine;
+      ctx.beginPath();
+      ctx.strokeStyle = vl.color ?? this._colors.crosshair;
+      ctx.lineWidth = vl.width ?? 1;
+      this._applyLineStyle(ctx, vl.style ?? 'dashed');
+      ctx.moveTo(x, 0);
+      ctx.lineTo(x, plotHeight);
+      ctx.stroke();
+      ctx.setLineDash([]);
+    }
+
+    // Horizontal line
+    if (this._options.horzLine.visible === true && y >= 0 && y <= plotHeight) {
+      const hl = this._options.horzLine;
+      ctx.beginPath();
+      ctx.strokeStyle = hl.color ?? this._colors.crosshair;
+      ctx.lineWidth = hl.width ?? 1;
+      this._applyLineStyle(ctx, hl.style ?? 'dashed');
+      ctx.moveTo(0, y);
+      ctx.lineTo(plotWidth, y);
+      ctx.stroke();
+      ctx.setLineDash([]);
+
+      // Price label on right axis
+      if (this._options.horzLine.labelVisible === true) {
+        const price = this._transform.yToPrice(y);
+        const label = this._formatPrice(price);
+        const labelBg = hexToRgba(this._colors.crosshair, 0.9);
+        ctx.fillStyle = labelBg;
+        const labelW = priceScaleWidth;
+        const labelH = 18;
+        const labelY = y - labelH / 2;
+        ctx.fillRect(plotWidth, labelY, labelW, labelH);
+        ctx.fillStyle = this._colors.background;
+        ctx.font = '11px system-ui, sans-serif';
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'middle';
+        ctx.fillText(label, plotWidth + 6, y);
+      }
+    }
+
+    // Center crosshair indicator — 4 short arms with a gap, matching the toolbar icon
+    if (
+      this._options.vertLine.visible === true &&
+      this._options.horzLine.visible === true &&
+      x >= 0 && x <= plotWidth &&
+      y >= 0 && y <= plotHeight
+    ) {
+      const GAP = 4;   // half-gap from center
+      const ARM = 8;   // arm length (tip to gap)
+      ctx.beginPath();
+      ctx.strokeStyle = this._colors.crosshair;
+      ctx.lineWidth = 1.5;
+      ctx.setLineDash([]);
+      // top arm
+      ctx.moveTo(x, y - GAP); ctx.lineTo(x, y - GAP - ARM);
+      // bottom arm
+      ctx.moveTo(x, y + GAP); ctx.lineTo(x, y + GAP + ARM);
+      // left arm
+      ctx.moveTo(x - GAP, y); ctx.lineTo(x - GAP - ARM, y);
+      // right arm
+      ctx.moveTo(x + GAP, y); ctx.lineTo(x + GAP + ARM, y);
+      ctx.stroke();
+      ctx.setLineDash([]);
+    }
+
+    // Time label on bottom axis (below vertical line)
+    if (
+      this._options.vertLine.visible === true &&
+      this._options.vertLine.labelVisible === true &&
+      x >= 0 && x <= plotWidth
+    ) {
+      const time = this._snapTime ?? this._transform.xToTime(x);
+      const label = this._formatTime(time);
+      const dailyIntervals = new Set(['1d', '2d', '3d', '1w', '2w', '1M', '3M', '6M', '12M']);
+      const labelW = dailyIntervals.has(this.interval) ? 110 : 160;
+      const labelH = timeScaleHeight - 4;
+      const labelX = Math.max(labelW / 2, Math.min(x, plotWidth - labelW / 2));
+      const labelBg = hexToRgba(this._colors.crosshair, 0.9);
+      ctx.fillStyle = labelBg;
+      ctx.fillRect(labelX - labelW / 2, plotHeight + 2, labelW, labelH);
+      ctx.fillStyle = this._colors.background;
+      ctx.font = '11px system-ui, sans-serif';
+      ctx.textAlign = 'center';
+      ctx.textBaseline = 'middle';
+      ctx.fillText(label, labelX, plotHeight + 2 + labelH / 2);
+    }
+
+    ctx.restore();
+  }
+
+  private _applyLineStyle(ctx: CanvasRenderingContext2D, style: string): void {
+    if (style === 'dashed') ctx.setLineDash([4, 4]);
+    else if (style === 'dotted') ctx.setLineDash([1, 3]);
+    else ctx.setLineDash([]);
+  }
+
+  /** Formats a price as a fixed-decimal string. */
+  private _formatPrice(price: number): string {
+    // Show more decimals for low-value instruments (e.g. forex, small-cap)
+    const decimals = price < 1 ? 6 : price < 1000 ? 4 : 2;
+    return price.toFixed(decimals);
+  }
+
+  /** Formats a Unix timestamp (seconds) as a human-readable date/time string. */
+  private _formatTime(time: number): string {
+    const timeZone: string = (!this.timezone || this.timezone === 'exchange') ? 'UTC' : this.timezone;
+    const d = new Date(time * 1000);
+    const weekday = d.toLocaleDateString('en-US', { weekday: 'short', timeZone });
+    const day     = d.toLocaleDateString('en-US', { day: '2-digit',   timeZone });
+    const month   = d.toLocaleDateString('en-US', { month: 'short',   timeZone });
+    const year    = d.toLocaleDateString('en-US', { year: '2-digit',  timeZone });
+    const datePart = `${weekday} ${day} ${month} '${year}`;
+
+    // Show time only for sub-day intervals
+    const dailyIntervals = new Set(['1d', '2d', '3d', '1w', '2w', '1M', '3M', '6M', '12M']);
+    if (dailyIntervals.has(this.interval)) return datePart;
+
+    const hh = d.toLocaleString('en-US', { hour: '2-digit', hour12: false, timeZone });
+    const mm = d.toLocaleString('en-US', { minute: '2-digit', timeZone }).padStart(2, '0');
+    return `${datePart}  ${hh}:${mm}`;
+  }
+}

package/src/core/IndicatorEngine.ts

@@ -0,0 +1,216 @@
+/**
+ * IndicatorEngine — pure, stateless computation functions.
+ *
+ * All functions accept a readonly OHLCV array and operation-specific
+ * parameters, and return plain value arrays.  No side effects, no
+ * class instances.  Safe to call from any renderer or React component.
+ */
+
+import type { OHLCV, PriceField } from '@forgecharts/types';
+
+// ─── Output point types ───────────────────────────────────────────────────────
+
+export type IndicatorPoint = {
+  readonly time: number;
+  readonly value: number;
+};
+
+export type MACDPoint = {
+  readonly time: number;
+  readonly macd: number;
+  readonly signal: number;
+  readonly histogram: number;
+};
+
+// ─── Internals ────────────────────────────────────────────────────────────────
+
+/**
+ * Exponential moving average over an arbitrary number array.
+ * Uses the standard multiplier k = 2 / (period + 1).
+ * The very first value seeds the EMA (warm-start).
+ */
+function _ema(values: readonly number[], period: number): number[] {
+  if (values.length === 0) return [];
+  const k = 2 / (period + 1);
+  const result: number[] = [values[0]!];
+  for (let i = 1; i < values.length; i++) {
+    result.push(values[i]! * k + result[i - 1]! * (1 - k));
+  }
+  return result;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/** Simple Moving Average over bar close prices. */
+export function computeSMA(bars: readonly OHLCV[], period: number): IndicatorPoint[] {
+  if (period < 1 || bars.length < period) return [];
+  const result: IndicatorPoint[] = [];
+  let windowSum = 0;
+  for (let i = 0; i < period; i++) windowSum += bars[i]!.close;
+  result.push({ time: bars[period - 1]!.time, value: windowSum / period });
+  for (let i = period; i < bars.length; i++) {
+    windowSum += bars[i]!.close - bars[i - period]!.close;
+    result.push({ time: bars[i]!.time, value: windowSum / period });
+  }
+  return result;
+}
+
+/** Exponential Moving Average over bar close prices. */
+export function computeEMA(bars: readonly OHLCV[], period: number): IndicatorPoint[] {
+  if (period < 1 || bars.length < period) return [];
+  const closes = bars.map((b) => b.close);
+  return _ema(closes, period).map((value, i) => ({ time: bars[i]!.time, value }));
+}
+
+/**
+ * Relative Strength Index using Wilder's smoothing.
+ * Returns values in [0, 100].
+ * Requires at least `period + 1` bars; returns [] otherwise.
+ */
+export function computeRSI(bars: readonly OHLCV[], period = 14): IndicatorPoint[] {
+  if (bars.length < period + 1) return [];
+
+  // Seed: simple average of first `period` up/down moves
+  let avgGain = 0;
+  let avgLoss = 0;
+  for (let i = 1; i <= period; i++) {
+    const d = bars[i]!.close - bars[i - 1]!.close;
+    if (d > 0) avgGain += d;
+    else avgLoss -= d;
+  }
+  avgGain /= period;
+  avgLoss /= period;
+
+  const result: IndicatorPoint[] = [];
+  result.push({
+    time: bars[period]!.time,
+    value: avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss),
+  });
+
+  // Wilder's smoothing for remaining bars
+  for (let i = period + 1; i < bars.length; i++) {
+    const d = bars[i]!.close - bars[i - 1]!.close;
+    const gain = d > 0 ? d : 0;
+    const loss = d < 0 ? -d : 0;
+    avgGain = (avgGain * (period - 1) + gain) / period;
+    avgLoss = (avgLoss * (period - 1) + loss) / period;
+    result.push({
+      time: bars[i]!.time,
+      value: avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss),
+    });
+  }
+  return result;
+}
+
+/**
+ * MACD — Moving Average Convergence/Divergence.
+ * Returns MACD line, Signal line, and Histogram.
+ * Standard defaults: fast=12, slow=26, signal=9.
+ */
+export function computeMACD(
+  bars: readonly OHLCV[],
+  fastPeriod = 12,
+  slowPeriod = 26,
+  signalPeriod = 9,
+): MACDPoint[] {
+  if (bars.length < slowPeriod) return [];
+
+  const closes = bars.map((b) => b.close);
+  const fastEMAs = _ema(closes, fastPeriod);
+  const slowEMAs = _ema(closes, slowPeriod);
+
+  // MACD line starts at index slowPeriod - 1 (first bar where slow EMA is meaningful)
+  const macdLine: number[] = [];
+  const macdTimes: number[] = [];
+  for (let i = slowPeriod - 1; i < bars.length; i++) {
+    macdLine.push(fastEMAs[i]! - slowEMAs[i]!);
+    macdTimes.push(bars[i]!.time);
+  }
+
+  if (macdLine.length < signalPeriod) return [];
+
+  const signalLine = _ema(macdLine, signalPeriod);
+  return signalLine.map((sig, i) => ({
+    time: macdTimes[i]!,
+    macd: macdLine[i]!,
+    signal: sig,
+    histogram: macdLine[i]! - sig,
+  }));
+}
+
+/** Volume bars — raw volume values keyed by bar time. */
+export function computeVolume(bars: readonly OHLCV[]): IndicatorPoint[] {
+  return bars.map((b) => ({ time: b.time, value: b.volume }));
+}
+
+// ─── Field extraction & series-based variants (for DAG chaining) ─────────────
+
+/** Extracts a single numeric value from an OHLCV bar by named price field. */
+export function extractField(bar: OHLCV, field: PriceField): number {
+  switch (field) {
+    case 'open':   return bar.open;
+    case 'high':   return bar.high;
+    case 'low':    return bar.low;
+    case 'close':  return bar.close;
+    case 'volume': return bar.volume;
+    case 'hl2':    return (bar.high + bar.low) / 2;
+    case 'hlc3':   return (bar.high + bar.low + bar.close) / 3;
+    case 'ohlc4':  return (bar.open + bar.high + bar.low + bar.close) / 4;
+  }
+}
+
+/**
+ * SMA over an arbitrary `IndicatorPoint[]` series (not just OHLCV close).
+ * Enables chains such as EMA(SMA(close, 20), 10).
+ */
+export function computeSMAFromSeries(
+  input: readonly IndicatorPoint[],
+  period: number,
+): IndicatorPoint[] {
+  if (period < 1 || input.length < period) return [];
+  const result: IndicatorPoint[] = [];
+  let sum = 0;
+  for (let i = 0; i < period; i++) sum += input[i]!.value;
+  result.push({ time: input[period - 1]!.time, value: sum / period });
+  for (let i = period; i < input.length; i++) {
+    sum += input[i]!.value - input[i - period]!.value;
+    result.push({ time: input[i]!.time, value: sum / period });
+  }
+  return result;
+}
+
+/**
+ * EMA over an arbitrary `IndicatorPoint[]` series.
+ * Seeds the EMA from the first input value.
+ */
+export function computeEMAFromSeries(
+  input: readonly IndicatorPoint[],
+  period: number,
+): IndicatorPoint[] {
+  if (period < 1 || input.length === 0) return [];
+  const k = 2 / (period + 1);
+  const result: IndicatorPoint[] = [{ time: input[0]!.time, value: input[0]!.value }];
+  for (let i = 1; i < input.length; i++) {
+    result.push({
+      time:  input[i]!.time,
+      value: input[i]!.value * k + result[i - 1]!.value * (1 - k),
+    });
+  }
+  return result;
+}
+
+/** WMA (Weighted Moving Average) over an arbitrary `IndicatorPoint[]` series. */
+export function computeWMAFromSeries(
+  input: readonly IndicatorPoint[],
+  period: number,
+): IndicatorPoint[] {
+  if (period < 1 || input.length < period) return [];
+  const denom = (period * (period + 1)) / 2;
+  const result: IndicatorPoint[] = [];
+  for (let i = period - 1; i < input.length; i++) {
+    let sum = 0;
+    for (let j = 0; j < period; j++) sum += input[i - j]!.value * (period - j);
+    result.push({ time: input[i]!.time, value: sum / denom });
+  }
+  return result;
+}