@forgecharts/sdk 1.1.23

package/src/tscript/runtime.ts

@@ -0,0 +1,525 @@
+/**
+ * TScript Runtime — tree-walking interpreter.
+ *
+ * Execution model
+ * ───────────────
+ * A TScript program is executed once per compiled bar in left-to-right,
+ * top-to-bottom statement order.  The runtime keeps a persistent `Scope`
+ * so that `Series` variables accumulate history across bars.
+ *
+ * Built-in series (available in every script):
+ *   open, high, low, close, volume, hl2, hlc3, ohlc4, bar_index
+ *
+ * Built-in TA functions:
+ *   sma(src, length)   — simple moving average
+ *   ema(src, length)   — exponential moving average
+ *   wma(src, length)   — weighted moving average
+ *   rma(src, length)   — Wilder's (RMA) moving average
+ *   stdev(src, length) — rolling standard deviation
+ *   highest(src, n)    — rolling max over n bars
+ *   lowest(src, n)     — rolling min over n bars
+ *   change(src, n?)    — src - src[n] (default n=1)
+ *   mom(src, length)   — momentum = change(src, length)
+ *   atr(length)        — Average True Range
+ *   crossover(a, b)    — a crosses above b
+ *   crossunder(a, b)   — a crosses below b
+ *   nz(x, y?)          — replace NaN with y (default 0)
+ *   na(x)              — true if x is NaN
+ *   abs(x)             — Math.abs
+ *   max(...)           — Math.max over args
+ *   min(...)           — Math.min over args
+ *   round(x)           — Math.round
+ *   floor(x)           — Math.floor
+ *   ceil(x)            — Math.ceil
+ *   sqrt(x)            — Math.sqrt
+ *   log(x)             — Math.log
+ *   pow(x, y)          — Math.pow
+ *   sign(x)            — Math.sign
+ *
+ * Built-in utility functions:
+ *   input(default, ...)  — returns the default value (params resolved externally)
+ *   plot(value, ...)     — records a value for the current bar
+ *   barssince(cond)      — bars since condition was true
+ */
+
+import type { OHLCV } from '@forgecharts/types';
+import { Series } from './series';
+import { Parser } from './parser';
+import type {
+  Program, Stmt, Expr,
+  AssignStmt, ExprStmt, IndicatorDecl,
+  NumberLit, StringLit, BoolLit, Identifier,
+  IndexExpr, CallExpr, BinaryExpr, UnaryExpr,
+  TernaryExpr, LogicalExpr,
+} from './ast';
+import type { IndicatorPoint } from '../core/IndicatorEngine';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** A TScript value is a number, boolean, string, or Series. */
+export type TValue = number | boolean | string | Series;
+
+/** Scope maps variable names to their TScript values. */
+export type Scope = Map<string, TValue>;
+
+/** Result produced by a single script execution run. */
+export type ScriptResult = {
+  /** Title from indicator("...") declaration. */
+  title:  string;
+  /** Collected plot() calls for this run, in declaration order. */
+  plots:  IndicatorPoint[][];
+};
+
+// ─── Scope helpers ────────────────────────────────────────────────────────────
+
+function _num(v: TValue, ctx: string): number {
+  if (v instanceof Series)   return v.value;
+  if (typeof v === 'number') return v;
+  if (typeof v === 'boolean') return v ? 1 : 0;
+  throw new TypeError(`[TScript] ${ctx}: expected number, got ${typeof v}`);
+}
+
+function _bool(v: TValue): boolean {
+  if (v instanceof Series)    return !isNaN(v.value) && v.value !== 0;
+  if (typeof v === 'number')  return !isNaN(v) && v !== 0;
+  if (typeof v === 'boolean') return v;
+  return Boolean(v);
+}
+
+// ─── TScriptRuntime ───────────────────────────────────────────────────────────
+
+export class TScriptRuntime {
+  private readonly _program:    Program;
+  private readonly _scope:      Scope     = new Map();
+  private readonly _plotSeries: Series[]  = [];  // one entry per plot() call order
+
+  // Public metadata set by indicator() declaration
+  title: string = 'Script';
+
+  constructor(src: string) {
+    this._program = new Parser(src).parse();
+
+    // Extract title from first IndicatorDecl if present
+    for (const stmt of this._program.stmts) {
+      if (stmt.kind === 'IndicatorDecl') {
+        this.title = stmt.title;
+        break;
+      }
+    }
+  }
+
+  /**
+   * Execute one bar.
+   *
+   * Call this in chronological order for every OHLCV bar.
+   * The runtime updates all built-in series with the bar's OHLCV values,
+   * then re-executes the full program body.
+   *
+   * @returns the current values of all `plot()` series after this bar.
+   */
+  execBar(bar: OHLCV, barIndex: number): void {
+    // ── Push OHLCV values into built-in series ────────────────────────────────
+    this._pushBuiltin('open',       bar.open);
+    this._pushBuiltin('high',       bar.high);
+    this._pushBuiltin('low',        bar.low);
+    this._pushBuiltin('close',      bar.close);
+    this._pushBuiltin('volume',     bar.volume);
+    this._pushBuiltin('hl2',        (bar.high + bar.low) / 2);
+    this._pushBuiltin('hlc3',       (bar.high + bar.low + bar.close) / 3);
+    this._pushBuiltin('ohlc4',      (bar.open + bar.high + bar.low + bar.close) / 4);
+    this._pushBuiltin('bar_index',  barIndex);
+
+    // ── Reset per-bar plot accumulators ───────────────────────────────────────
+    this._plotIdx = 0;
+
+    // ── Execute all statements (skipping IndicatorDecl) ──────────────────────
+    for (const stmt of this._program.stmts) {
+      this._execStmt(stmt);
+    }
+  }
+
+  /**
+   * Run the full bar history and return IndicatorPoint arrays indexed by
+   * plot() call order.
+   *
+   * @param bars   chronologically ordered OHLCV array
+   */
+  run(bars: readonly OHLCV[]): IndicatorPoint[][] {
+    this.reset();
+    for (let i = 0; i < bars.length; i++) {
+      this.execBar(bars[i]!, i);
+    }
+    return this.getPlots(bars);
+  }
+
+  /**
+   * Snapshot the current plot series as IndicatorPoint arrays.
+   * Must be called after `run()` or after the last `execBar()`.
+   * @param bars the same bar array passed to run() — used for timestamps.
+   */
+  getPlots(bars: readonly OHLCV[]): IndicatorPoint[][] {
+    return this._plotSeries.map((series) => {
+      const values = series.toArray(); // oldest→newest
+      const offset = bars.length - values.length;
+      return values
+        .map((value, i) => ({
+          time:  bars[offset + i]!.time,
+          value,
+        }))
+        .filter((p) => !isNaN(p.value));
+    });
+  }
+
+  /** Reset all persistent series state (call on symbol/timeframe change). */
+  reset(): void {
+    for (const v of this._scope.values()) {
+      if (v instanceof Series) v.reset();
+    }
+    for (const s of this._plotSeries) s.reset();
+    this._plotIdx = 0;
+  }
+
+  // ─── Private: statement execution ───────────────────────────────────────────
+
+  private _execStmt(stmt: Stmt): void {
+    switch (stmt.kind) {
+      case 'IndicatorDecl': break; // handled at construction
+      case 'AssignStmt':    this._execAssign(stmt); break;
+      case 'ExprStmt':      this._evalExpr(stmt.expr); break;
+    }
+  }
+
+  private _execAssign(stmt: AssignStmt): void {
+    const rhs = this._evalExpr(stmt.value);
+    const existing = this._scope.get(stmt.name);
+
+    if (existing instanceof Series) {
+      // Persist a series variable: push the new value each bar
+      existing.push(_num(rhs, `assignment to '${stmt.name}'`));
+    } else {
+      // First assignment: if RHS is a number, wrap in a Series for history
+      if (typeof rhs === 'number' || rhs instanceof Series) {
+        const series = new Series(1000);
+        series.push(rhs instanceof Series ? rhs.value : rhs);
+        this._scope.set(stmt.name, series);
+      } else {
+        this._scope.set(stmt.name, rhs);
+      }
+    }
+  }
+
+  // ─── Private: expression evaluation ─────────────────────────────────────────
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private _evalExpr(expr: Expr): TValue {
+    switch (expr.kind) {
+      case 'NumberLit':  return (expr as NumberLit).value;
+      case 'StringLit':  return (expr as StringLit).value;
+      case 'BoolLit':    return (expr as BoolLit).value;
+      case 'Identifier': return this._evalIdent(expr as Identifier);
+      case 'IndexExpr':  return this._evalIndex(expr as IndexExpr);
+      case 'CallExpr':   return this._evalCall(expr as CallExpr);
+      case 'BinaryExpr': return this._evalBinary(expr as BinaryExpr);
+      case 'UnaryExpr':  return this._evalUnary(expr as UnaryExpr);
+      case 'TernaryExpr':return this._evalTernary(expr as TernaryExpr);
+      case 'LogicalExpr':return this._evalLogical(expr as LogicalExpr);
+    }
+  }
+
+  private _evalIdent(expr: Identifier): TValue {
+    const v = this._scope.get(expr.name);
+    if (v === undefined) {
+      throw new ReferenceError(`[TScript] Undefined variable '${expr.name}'`);
+    }
+    // Return the Series itself; callers use _num() to coerce if needed.
+    return v;
+  }
+
+  private _evalIndex(expr: IndexExpr): number {
+    const series = this._evalExpr(expr.series);
+    const idx    = _num(this._evalExpr(expr.index), 'series index');
+    if (!(series instanceof Series)) {
+      throw new TypeError('[TScript] Index operator [] can only be applied to a series');
+    }
+    return series.get(Math.round(idx));
+  }
+
+  private _evalBinary(expr: BinaryExpr): TValue {
+    const l = _num(this._evalExpr(expr.left),  `left of '${expr.op}'`);
+    const r = _num(this._evalExpr(expr.right), `right of '${expr.op}'`);
+    switch (expr.op) {
+      case '+': return l + r;
+      case '-': return l - r;
+      case '*': return l * r;
+      case '/': return r === 0 ? NaN : l / r;
+      case '%': return l % r;
+      case '<': return l < r;
+      case '>': return l > r;
+      case '<=': return l <= r;
+      case '>=': return l >= r;
+      case '==': return l === r;
+      case '!=': return l !== r;
+    }
+  }
+
+  private _evalUnary(expr: UnaryExpr): TValue {
+    if (expr.op === 'not') return !_bool(this._evalExpr(expr.operand));
+    return -_num(this._evalExpr(expr.operand), 'unary -');
+  }
+
+  private _evalTernary(expr: TernaryExpr): TValue {
+    return _bool(this._evalExpr(expr.condition))
+      ? this._evalExpr(expr.consequent)
+      : this._evalExpr(expr.alternate);
+  }
+
+  private _evalLogical(expr: LogicalExpr): TValue {
+    const l = _bool(this._evalExpr(expr.left));
+    if (expr.op === 'and') return l ? _bool(this._evalExpr(expr.right)) : false;
+    return l ? true : _bool(this._evalExpr(expr.right));
+  }
+
+  // ─── Built-in function dispatch ──────────────────────────────────────────────
+
+  private _plotIdx = 0;
+
+  private _evalCall(expr: CallExpr): TValue {
+    const fn = expr.callee;
+    const args = expr.args;
+
+    switch (fn) {
+      // ── Utility ────────────────────────────────────────────────────────────
+      case 'input': {
+        // input(default) — return default value; full param resolution is external
+        if (args.length === 0) return 0;
+        const def = this._evalExpr(args[0]!);
+        return typeof def === 'string' ? parseFloat(def) || 0 : _num(def, 'input()');
+      }
+
+      case 'plot': {
+        const value = _num(this._evalExpr(args[0]!), 'plot()');
+        const idx = this._plotIdx++;
+        if (idx >= this._plotSeries.length) {
+          this._plotSeries.push(new Series(1000));
+        }
+        this._plotSeries[idx]!.push(value);
+        return value;
+      }
+
+      case 'na': {
+        if (args.length > 0) {
+          const v = this._evalExpr(args[0]!);
+          return typeof v === 'number' ? isNaN(v) : v instanceof Series ? isNaN(v.value) : false;
+        }
+        return NaN;
+      }
+
+      case 'nz': {
+        const v = _num(this._evalExpr(args[0]!), 'nz()');
+        const fallback = args.length > 1 ? _num(this._evalExpr(args[1]!), 'nz() fallback') : 0;
+        return isNaN(v) ? fallback : v;
+      }
+
+      case 'abs':   return Math.abs(_num(this._evalExpr(args[0]!), 'abs()'));
+      case 'round': return Math.round(_num(this._evalExpr(args[0]!), 'round()'));
+      case 'floor': return Math.floor(_num(this._evalExpr(args[0]!), 'floor()'));
+      case 'ceil':  return Math.ceil(_num(this._evalExpr(args[0]!), 'ceil()'));
+      case 'sqrt':  return Math.sqrt(_num(this._evalExpr(args[0]!), 'sqrt()'));
+      case 'log':   return Math.log(_num(this._evalExpr(args[0]!), 'log()'));
+      case 'sign':  return Math.sign(_num(this._evalExpr(args[0]!), 'sign()'));
+      case 'pow': {
+        const base = _num(this._evalExpr(args[0]!), 'pow() base');
+        const exp  = _num(this._evalExpr(args[1]!), 'pow() exponent');
+        return Math.pow(base, exp);
+      }
+      case 'max': return Math.max(...args.map((a) => _num(this._evalExpr(a), 'max()')));
+      case 'min': return Math.min(...args.map((a) => _num(this._evalExpr(a), 'min()')));
+
+      // ── TA functions ────────────────────────────────────────────────────────
+      case 'sma':    return this._ta_sma(args);
+      case 'ema':    return this._ta_ema(args);
+      case 'wma':    return this._ta_wma(args);
+      case 'rma':    return this._ta_rma(args);
+      case 'stdev':  return this._ta_stdev(args);
+      case 'highest':return this._ta_rolling(args, Math.max);
+      case 'lowest': return this._ta_rolling(args, Math.min);
+      case 'change': return this._ta_change(args);
+      case 'mom':    return this._ta_change(args);
+      case 'atr':    return this._ta_atr(args);
+      case 'crossover':  return this._ta_crossover(args);
+      case 'crossunder': return this._ta_crossunder(args);
+      case 'barssince':  return this._ta_barssince(args);
+
+      default:
+        throw new ReferenceError(`[TScript] Unknown function '${fn}'`);
+    }
+  }
+
+  // ─── TA helpers ──────────────────────────────────────────────────────────────
+
+  /** Resolve a call argument as a Series (wrapping scalar if needed). */
+  private _argSeries(arg: Expr, ctx: string): Series {
+    const v = this._evalExpr(arg);
+    if (v instanceof Series) return v;
+    if (typeof v === 'number') {
+      // Inline scalar: treat as a constant series with only the current value
+      const s = new Series(2);
+      s.push(v);
+      return s;
+    }
+    throw new TypeError(`[TScript] ${ctx}: expected a series`);
+  }
+
+  private _argInt(arg: Expr, ctx: string): number {
+    return Math.round(_num(this._evalExpr(arg), ctx));
+  }
+
+  private _ta_sma(args: Expr[]): number {
+    const src    = this._argSeries(args[0]!, 'sma(src)');
+    const period = this._argInt(args[1]!, 'sma(length)');
+    if (src.length < period) return NaN;
+    let sum = 0;
+    for (let i = 0; i < period; i++) sum += src.get(i);
+    return sum / period;
+  }
+
+  private _ta_ema(args: Expr[]): number {
+    const src    = this._argSeries(args[0]!, 'ema(src)');
+    const period = this._argInt(args[1]!, 'ema(length)');
+    if (src.length < period) return NaN;
+    // Persistent EMA state: store the last EMA value in a named internal Series
+    const stateKey = `__ema_${args[0]!.kind}_${period}`;
+    let prevEMA = this._getInternalNum(stateKey);
+    const k = 2 / (period + 1);
+    const cur = src.get(0);
+    const newEMA = isNaN(prevEMA)
+      ? this._smaOfSeries(src, period)    // seed with SMA on first valid bar
+      : cur * k + prevEMA * (1 - k);
+    this._setInternal(stateKey, newEMA);
+    return newEMA;
+  }
+
+  private _ta_wma(args: Expr[]): number {
+    const src    = this._argSeries(args[0]!, 'wma(src)');
+    const period = this._argInt(args[1]!, 'wma(length)');
+    if (src.length < period) return NaN;
+    const denom = (period * (period + 1)) / 2;
+    let sum = 0;
+    for (let i = 0; i < period; i++) sum += src.get(i) * (period - i);
+    return sum / denom;
+  }
+
+  private _ta_rma(args: Expr[]): number {
+    // Wilder's RMA: alpha = 1/period
+    const src    = this._argSeries(args[0]!, 'rma(src)');
+    const period = this._argInt(args[1]!, 'rma(length)');
+    if (src.length < period) return NaN;
+    const stateKey = `__rma_${args[0]!.kind}_${period}`;
+    let prev = this._getInternalNum(stateKey);
+    const alpha = 1 / period;
+    const cur = src.get(0);
+    const result = isNaN(prev) ? this._smaOfSeries(src, period) : alpha * cur + (1 - alpha) * prev;
+    this._setInternal(stateKey, result);
+    return result;
+  }
+
+  private _ta_stdev(args: Expr[]): number {
+    const src    = this._argSeries(args[0]!, 'stdev(src)');
+    const period = this._argInt(args[1]!, 'stdev(length)');
+    if (src.length < period) return NaN;
+    const mean = this._smaOfSeries(src, period);
+    let variance = 0;
+    for (let i = 0; i < period; i++) {
+      const diff = src.get(i) - mean;
+      variance += diff * diff;
+    }
+    return Math.sqrt(variance / period);
+  }
+
+  private _ta_rolling(args: Expr[], fn: (...v: number[]) => number): number {
+    const src    = this._argSeries(args[0]!, 'highest/lowest(src)');
+    const period = this._argInt(args[1]!, 'highest/lowest(length)');
+    if (src.length < period) return NaN;
+    let result = src.get(0);
+    for (let i = 1; i < period; i++) result = fn(result, src.get(i));
+    return result;
+  }
+
+  private _ta_change(args: Expr[]): number {
+    const src    = this._argSeries(args[0]!, 'change(src)');
+    const period = args.length > 1 ? this._argInt(args[1]!, 'change(length)') : 1;
+    if (src.length <= period) return NaN;
+    return src.get(0) - src.get(period);
+  }
+
+  private _ta_atr(args: Expr[]): number {
+    const period = this._argInt(args[0]!, 'atr(length)');
+    const high   = this._scope.get('high');
+    const low    = this._scope.get('low');
+    const close  = this._scope.get('close');
+    if (!(high instanceof Series) || !(low instanceof Series) || !(close instanceof Series)) {
+      return NaN;
+    }
+    if (high.length < 2) return NaN;
+    const h  = high.get(0);
+    const l  = low.get(0);
+    const pc = close.get(1); // previous close
+    const tr = Math.max(h - l, Math.abs(h - pc), Math.abs(l - pc));
+    const stateKey = `__atr_${period}`;
+    let prev = this._getInternalNum(stateKey);
+    const alpha = 1 / period;
+    const result = isNaN(prev) ? tr : alpha * tr + (1 - alpha) * prev;
+    this._setInternal(stateKey, result);
+    return result;
+  }
+
+  private _ta_crossover(args: Expr[]): boolean {
+    const a = this._argSeries(args[0]!, 'crossover(a)');
+    const b = this._argSeries(args[1]!, 'crossover(b)');
+    return a.get(0) > b.get(0) && a.get(1) <= b.get(1);
+  }
+
+  private _ta_crossunder(args: Expr[]): boolean {
+    const a = this._argSeries(args[0]!, 'crossunder(a)');
+    const b = this._argSeries(args[1]!, 'crossunder(b)');
+    return a.get(0) < b.get(0) && a.get(1) >= b.get(1);
+  }
+
+  private _ta_barssince(args: Expr[]): number {
+    const cond = this._argSeries(args[0]!, 'barssince(cond)');
+    for (let i = 0; i < cond.length; i++) {
+      if (_bool(cond.get(i))) return i;
+    }
+    return NaN;
+  }
+
+  // ─── Internal state helpers ──────────────────────────────────────────────────
+
+  /** Persistent scalar state for stateful TA functions (EMA, RMA, ATR). */
+  private readonly _internalState = new Map<string, number>();
+
+  private _getInternalNum(key: string): number {
+    return this._internalState.get(key) ?? NaN;
+  }
+
+  private _setInternal(key: string, value: number): void {
+    this._internalState.set(key, value);
+  }
+
+  /** Push a value into a named built-in Series, creating it if needed. */
+  private _pushBuiltin(name: string, value: number): void {
+    let series = this._scope.get(name);
+    if (!(series instanceof Series)) {
+      series = new Series(1000);
+      this._scope.set(name, series);
+    }
+    series.push(value);
+  }
+
+  /** Compute a simple rolling average directly from a Series (no state). */
+  private _smaOfSeries(src: Series, period: number): number {
+    let sum = 0;
+    for (let i = 0; i < period; i++) sum += src.get(i);
+    return sum / period;
+  }
+}

package/src/tscript/series.ts

@@ -0,0 +1,84 @@
+/**
+ * TScript Series — fixed-capacity ring buffer for historical bar data.
+ *
+ * Access pattern mirrors Pine Script:
+ *   series.value       — current (bar 0) value
+ *   series.get(0)      — same as .value
+ *   series.get(1)      — 1 bar ago
+ *   series.get(n)      — n bars ago (returns NaN if out of range)
+ *
+ * Internally the ring buffer stores the `capacity` most recent values in a
+ * circular array, so `.push()` is O(1) with no allocation after warm-up.
+ *
+ * @example
+ * ```ts
+ * const s = new Series(500);
+ * s.push(1); s.push(2); s.push(3);
+ * s.get(0); // 3 (current)
+ * s.get(1); // 2 (one bar ago)
+ * s.get(2); // 1 (two bars ago)
+ * ```
+ */
+export class Series {
+  private readonly _buf: Float64Array;
+  private readonly _cap: number;
+  private _head: number = 0;   // index of the NEXT write slot
+  private _len:  number = 0;   // number of values stored so far
+
+  constructor(capacity = 1000) {
+    this._cap = capacity;
+    this._buf = new Float64Array(capacity).fill(NaN);
+  }
+
+  /** Append a new value at the current bar position. */
+  push(value: number): void {
+    this._buf[this._head] = value;
+    this._head = (this._head + 1) % this._cap;
+    if (this._len < this._cap) this._len++;
+  }
+
+  /**
+   * Retrieve a historical value.
+   * @param lookback  0 = current bar, 1 = previous bar, etc.
+   */
+  get(lookback: number): number {
+    if (lookback < 0 || lookback >= this._len) return NaN;
+    // Head points to NEXT slot, so current value is at head-1
+    const idx = (this._head - 1 - lookback + this._cap * 2) % this._cap;
+    return this._buf[idx]!;
+  }
+
+  /** Alias for get(0). */
+  get value(): number {
+    return this.get(0);
+  }
+
+  /** Number of values stored (up to capacity). */
+  get length(): number {
+    return this._len;
+  }
+
+  /** Ring-buffer capacity. */
+  get capacity(): number {
+    return this._cap;
+  }
+
+  /**
+   * Snapshot: returns all stored values in chronological order
+   * (oldest first, newest last).
+   */
+  toArray(): number[] {
+    const out: number[] = new Array(this._len);
+    for (let i = 0; i < this._len; i++) {
+      out[i] = this.get(this._len - 1 - i);
+    }
+    return out;
+  }
+
+  /** Reset the buffer (e.g. on symbol change). */
+  reset(): void {
+    this._buf.fill(NaN);
+    this._head = 0;
+    this._len  = 0;
+  }
+}

package/src/types/IChart.ts

@@ -0,0 +1,56 @@
+import type { SeriesOptions, Viewport } from '@forgecharts/types';
+import type { ISeries } from './ISeries';
+import type { CoordTransform } from '../core/CoordTransform';
+
+export interface IChart {
+  /**
+   * Adds a new series to the chart and returns a handle for data management.
+   */
+  addSeries(options: SeriesOptions): ISeries;
+
+  /**
+   * Removes a previously added series.
+   */
+  removeSeries(series: ISeries): void;
+
+  /**
+   * Registers a plugin that participates in the render loop.
+   */
+  addPlugin(plugin: IChartPlugin): void;
+
+  /**
+   * Deregisters a plugin.
+   */
+  removePlugin(plugin: IChartPlugin): void;
+
+  /**
+   * Applies partial chart options at runtime (theme, scale options, etc.).
+   */
+  applyOptions(options: import('@forgecharts/types').ChartOptions): void;
+
+  /**
+   * Manually sets the canvas dimensions. Usually called from ResizeObserver.
+   */
+  resize(width: number, height: number): void;
+
+  /**
+   * Tears down all resources and removes canvas elements from the DOM.
+   */
+  destroy(): void;
+
+  /**
+   * Returns the coordinate transform for pixel ↔ data conversions.
+   * The returned instance is kept up-to-date across resizes; callers may
+   * hold a stable reference.
+   */
+  transform(): CoordTransform;
+}
+
+export interface IChartPlugin {
+  /** Called once when the plugin is added to a chart. */
+  onAttach(chart: IChart): void;
+  /** Called once when the plugin is removed from a chart. */
+  onDetach(): void;
+  /** Called every animation frame after series are rendered. */
+  onRender(): void;
+}

package/src/types/IRenderer.ts

@@ -0,0 +1,16 @@
+import type { OHLCV, SeriesOptions, Viewport, Rect } from '@forgecharts/types';
+
+/**
+ * IRenderer — contract for all series drawing strategies.
+ * Each renderer receives only what it needs: bars, viewport, and target rect.
+ * No DOM or Chart references — pure canvas drawing.
+ */
+export interface IRenderer {
+  draw(
+    ctx: CanvasRenderingContext2D,
+    bars: readonly OHLCV[],
+    viewport: Viewport,
+    rect: Rect,
+    options: SeriesOptions,
+  ): void;
+}