@forgecharts/sdk 1.1.23

package/src/licensing/__tests__/ChartRuntimeResolver.test.ts

@@ -0,0 +1,207 @@
+/**
+ * ChartRuntimeResolver — unit tests
+ *
+ * Covers:
+ *   - No license → unmanaged, all managed UI hidden, overlays/indicators/drawings visible
+ *   - Unmanaged license → same as no license for UI gating
+ *   - Managed license → all managed UI visible, external ingestion blocked
+ *   - Feature flags override defaults within a mode
+ *   - getCapabilities() snapshot is consistent with individual methods
+ *   - Module-level convenience functions alias correctly
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { LicenseManager } from '../LicenseManager';
+import { ChartRuntimeResolver } from '../ChartRuntimeResolver';
+import type { LicensePayload } from '../licenseTypes';
+
+function setLicense(payload: LicensePayload | null) {
+  const lm = LicenseManager.getInstance();
+  if (payload === null) { lm.clear(); } else { lm.loadLicense(payload); }
+}
+
+const UNMANAGED_PAYLOAD: LicensePayload = { licenseKey: 'u1', mode: 'unmanaged' };
+const MANAGED_PAYLOAD:   LicensePayload = { licenseKey: 'm1', mode: 'managed'   };
+
+describe('ChartRuntimeResolver — no license (safe defaults)', () => {
+  beforeEach(() => setLicense(null));
+
+  it('isUnmanagedMode() is true', () => {
+    expect(ChartRuntimeResolver.getInstance().isUnmanagedMode()).toBe(true);
+  });
+
+  it('isManagedMode() is false', () => {
+    expect(ChartRuntimeResolver.getInstance().isManagedMode()).toBe(false);
+  });
+
+  it('managed UI render flags are all false', () => {
+    const r = ChartRuntimeResolver.getInstance();
+    expect(r.canRenderOrderEntry()).toBe(false);
+    expect(r.canRenderBuySellButtons()).toBe(false);
+    expect(r.canRenderOrderTicket()).toBe(false);
+    expect(r.canRenderBracketControls()).toBe(false);
+    expect(r.canRenderOrderModificationControls()).toBe(false);
+    expect(r.canRenderManagedTradingControls()).toBe(false);
+  });
+
+  it('canRenderExternalOverlayOnlyMode() is true', () => {
+    expect(ChartRuntimeResolver.getInstance().canRenderExternalOverlayOnlyMode()).toBe(true);
+  });
+
+  it('always-on render flags remain true', () => {
+    const r = ChartRuntimeResolver.getInstance();
+    expect(r.canRenderCandles()).toBe(true);
+    expect(r.canRenderIndicators()).toBe(true);
+    expect(r.canRenderDrawings()).toBe(true);
+    expect(r.canRenderPositions()).toBe(true);
+    expect(r.canRenderFills()).toBe(true);
+    expect(r.canRenderOverlays()).toBe(true);
+  });
+
+  it('external ingestion is allowed in unmanaged mode', () => {
+    expect(ChartRuntimeResolver.getInstance().canUseExternalIngestion()).toBe(true);
+  });
+});
+
+describe('ChartRuntimeResolver — explicit unmanaged license', () => {
+  beforeEach(() => setLicense(UNMANAGED_PAYLOAD));
+
+  it('matches the no-license behaviour for all managed flags', () => {
+    const r = ChartRuntimeResolver.getInstance();
+    expect(r.canRenderOrderEntry()).toBe(false);
+    expect(r.canRenderManagedTradingControls()).toBe(false);
+    expect(r.canRenderExternalOverlayOnlyMode()).toBe(true);
+    expect(r.canRenderCandles()).toBe(true);
+  });
+});
+
+describe('ChartRuntimeResolver — managed license (full features)', () => {
+  beforeEach(() => setLicense(MANAGED_PAYLOAD));
+
+  it('isManagedMode() is true', () => {
+    expect(ChartRuntimeResolver.getInstance().isManagedMode()).toBe(true);
+  });
+
+  it('external ingestion is blocked in managed mode', () => {
+    expect(ChartRuntimeResolver.getInstance().canUseExternalIngestion()).toBe(false);
+  });
+
+  it('managed UI render flags are all true (no feature restrictions)', () => {
+    const r = ChartRuntimeResolver.getInstance();
+    expect(r.canRenderOrderEntry()).toBe(true);
+    expect(r.canRenderBuySellButtons()).toBe(true);
+    expect(r.canRenderOrderTicket()).toBe(true);
+    expect(r.canRenderBracketControls()).toBe(true);
+    expect(r.canRenderOrderModificationControls()).toBe(true);
+    expect(r.canRenderManagedTradingControls()).toBe(true);
+  });
+
+  it('canRenderExternalOverlayOnlyMode() is false', () => {
+    expect(ChartRuntimeResolver.getInstance().canRenderExternalOverlayOnlyMode()).toBe(false);
+  });
+
+  it('always-on flags still true in managed mode', () => {
+    const r = ChartRuntimeResolver.getInstance();
+    expect(r.canRenderCandles()).toBe(true);
+    expect(r.canRenderPositions()).toBe(true);
+    expect(r.canRenderFills()).toBe(true);
+    expect(r.canRenderDrawings()).toBe(true);
+  });
+});
+
+describe('ChartRuntimeResolver — feature flags restrict managed capabilities', () => {
+  it('orderEntry: false disables order entry render flags', () => {
+    setLicense({ licenseKey: 'mf', mode: 'managed', features: { orderEntry: false } });
+    const r = ChartRuntimeResolver.getInstance();
+    expect(r.canRenderOrderEntry()).toBe(false);
+    expect(r.canRenderBuySellButtons()).toBe(false);
+    expect(r.canRenderOrderTicket()).toBe(false);
+    // bracket/drag also depend on order entry
+    expect(r.canRenderBracketControls()).toBe(false);
+    expect(r.canRenderOrderModificationControls()).toBe(false);
+  });
+
+  it('bracketOrders: false hides bracket controls but not basic order entry', () => {
+    setLicense({
+      licenseKey: 'mb',
+      mode: 'managed',
+      features: { orderEntry: true, bracketOrders: false },
+    });
+    const r = ChartRuntimeResolver.getInstance();
+    expect(r.canRenderOrderEntry()).toBe(true);
+    expect(r.canRenderBracketControls()).toBe(false);
+  });
+
+  it('draggableOrders: false hides modification controls', () => {
+    setLicense({
+      licenseKey: 'md',
+      mode: 'managed',
+      features: { orderEntry: true, draggableOrders: false },
+    });
+    const r = ChartRuntimeResolver.getInstance();
+    expect(r.canRenderOrderEntry()).toBe(true);
+    expect(r.canRenderOrderModificationControls()).toBe(false);
+  });
+
+  it('indicators: false disables indicator rendering in both modes', () => {
+    setLicense({ licenseKey: 'ui', mode: 'unmanaged', features: { indicators: false } });
+    expect(ChartRuntimeResolver.getInstance().canRenderIndicators()).toBe(false);
+
+    setLicense({ licenseKey: 'mi', mode: 'managed', features: { indicators: false } });
+    expect(ChartRuntimeResolver.getInstance().canRenderIndicators()).toBe(false);
+  });
+});
+
+describe('ChartRuntimeResolver — getCapabilities() snapshot', () => {
+  it('snapshot is consistent with individual method values (unmanaged)', () => {
+    setLicense(UNMANAGED_PAYLOAD);
+    const r = ChartRuntimeResolver.getInstance();
+    const caps = r.getCapabilities();
+
+    expect(caps.mode).toBe('unmanaged');
+    expect(caps.renderOrderEntry).toBe(r.canRenderOrderEntry());
+    expect(caps.renderBuySellButtons).toBe(r.canRenderBuySellButtons());
+    expect(caps.renderBracketControls).toBe(r.canRenderBracketControls());
+    expect(caps.renderManagedTradingControls).toBe(r.canRenderManagedTradingControls());
+    expect(caps.renderExternalOverlayOnly).toBe(r.canRenderExternalOverlayOnlyMode());
+    expect(caps.renderCandles).toBe(true);
+  });
+
+  it('snapshot is consistent with individual method values (managed)', () => {
+    setLicense(MANAGED_PAYLOAD);
+    const r = ChartRuntimeResolver.getInstance();
+    const caps = r.getCapabilities();
+
+    expect(caps.mode).toBe('managed');
+    expect(caps.renderOrderEntry).toBe(r.canRenderOrderEntry());
+    expect(caps.renderBracketControls).toBe(r.canRenderBracketControls());
+    expect(caps.renderExternalOverlayOnly).toBe(false);
+    expect(caps.renderCandles).toBe(true);
+  });
+});
+
+describe('ChartRuntimeResolver — module-level convenience exports', () => {
+  it('module-level functions reflect the singleton state', async () => {
+    const {
+      isManagedMode, isUnmanagedMode,
+      canRenderOrderEntry, canRenderManagedTradingControls,
+      canRenderExternalOverlayOnlyMode, canRenderCandles,
+      getCapabilities,
+    } = await import('../ChartRuntimeResolver');
+
+    setLicense(null);
+    expect(isUnmanagedMode()).toBe(true);
+    expect(isManagedMode()).toBe(false);
+    expect(canRenderOrderEntry()).toBe(false);
+    expect(canRenderManagedTradingControls()).toBe(false);
+    expect(canRenderExternalOverlayOnlyMode()).toBe(true);
+    expect(canRenderCandles()).toBe(true);
+    expect(getCapabilities().mode).toBe('unmanaged');
+
+    setLicense(MANAGED_PAYLOAD);
+    expect(isManagedMode()).toBe(true);
+    expect(canRenderOrderEntry()).toBe(true);
+    expect(canRenderManagedTradingControls()).toBe(true);
+    expect(canRenderExternalOverlayOnlyMode()).toBe(false);
+  });
+});

package/src/licensing/__tests__/LicenseManager.test.ts

@@ -0,0 +1,180 @@
+/**
+ * LicenseManager — unit tests
+ *
+ * Covers:
+ *   - Default mode is 'unmanaged' with no license installed
+ *   - loadLicense drives mode and features correctly
+ *   - validateLicense resolves a payload (placeholder logic)
+ *   - clear() resets to safe unmanaged defaults
+ *   - subscribe/unsubscribe fires on every mutation
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { LicenseManager } from '../LicenseManager';
+import type { LicensePayload } from '../licenseTypes';
+
+const FAKE_URL = 'http://localhost:4100/api/public/license/verify';
+
+// Stub fetch so validateLicense tests don't need a real server
+function stubFetch(response: object): void {
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+    ok: true,
+    json: async () => response,
+  }));
+}
+
+// Always work with a fresh singleton state between tests
+function reset() {
+  LicenseManager.getInstance().clear();
+  vi.unstubAllGlobals();
+}
+
+describe('LicenseManager — defaults', () => {
+  beforeEach(reset);
+
+  it('default mode is unmanaged when no license installed', () => {
+    expect(LicenseManager.getInstance().getMode()).toBe('unmanaged');
+  });
+
+  it('getLicense() returns null before any license is loaded', () => {
+    expect(LicenseManager.getInstance().getLicense()).toBeNull();
+  });
+
+  it('getFeatures() returns an empty object by default', () => {
+    expect(LicenseManager.getInstance().getFeatures()).toEqual({});
+  });
+
+  it('hasFeature() returns false for any key when no license', () => {
+    const lm = LicenseManager.getInstance();
+    expect(lm.hasFeature('orderEntry')).toBe(false);
+    expect(lm.hasFeature('bracketOrders')).toBe(false);
+  });
+});
+
+describe('LicenseManager — loadLicense', () => {
+  beforeEach(reset);
+
+  it('sets mode to managed when payload.mode is managed', () => {
+    const lm = LicenseManager.getInstance();
+    const payload: LicensePayload = { licenseKey: 'k1', mode: 'managed' };
+    lm.loadLicense(payload);
+    expect(lm.getMode()).toBe('managed');
+  });
+
+  it('sets mode to unmanaged when payload.mode is unmanaged', () => {
+    const lm = LicenseManager.getInstance();
+    const payload: LicensePayload = { licenseKey: 'k2', mode: 'unmanaged' };
+    lm.loadLicense(payload);
+    expect(lm.getMode()).toBe('unmanaged');
+  });
+
+  it('exposes feature flags from the payload', () => {
+    const lm = LicenseManager.getInstance();
+    lm.loadLicense({
+      licenseKey: 'k3',
+      mode: 'managed',
+      features: { orderEntry: true, bracketOrders: true, draggableOrders: false },
+    });
+    expect(lm.hasFeature('orderEntry')).toBe(true);
+    expect(lm.hasFeature('bracketOrders')).toBe(true);
+    expect(lm.hasFeature('draggableOrders')).toBe(false);
+  });
+
+  it('getLicense() returns the loaded payload', () => {
+    const lm = LicenseManager.getInstance();
+    const payload: LicensePayload = { licenseKey: 'k4', mode: 'managed' };
+    lm.loadLicense(payload);
+    expect(lm.getLicense()).toEqual(payload);
+  });
+});
+
+describe('LicenseManager — validateLicense', () => {
+  beforeEach(reset);
+
+  it('resolves a LicensePayload for a non-empty key', async () => {
+    stubFetch({ valid: true, licenseKey: 'TEST-KEY-XYZ', mode: 'unmanaged', plan: 'default', expiresAt: null, features: {} });
+    const lm = LicenseManager.getInstance();
+    const payload = await lm.validateLicense('test-key-xyz', FAKE_URL);
+    expect(payload).toHaveProperty('licenseKey');
+    expect(payload).toHaveProperty('mode');
+    expect(lm.getLicense()).not.toBeNull();
+  });
+
+  it('rejects when the key is empty', async () => {
+    const lm = LicenseManager.getInstance();
+    await expect(lm.validateLicense('', FAKE_URL)).rejects.toThrow();
+  });
+
+  it('rejects when the key is whitespace-only', async () => {
+    const lm = LicenseManager.getInstance();
+    await expect(lm.validateLicense('   ', FAKE_URL)).rejects.toThrow();
+  });
+});
+
+describe('LicenseManager — clear', () => {
+  beforeEach(reset);
+
+  it('resets mode to unmanaged after a managed license', () => {
+    const lm = LicenseManager.getInstance();
+    lm.loadLicense({ licenseKey: 'k', mode: 'managed' });
+    expect(lm.getMode()).toBe('managed');
+    lm.clear();
+    expect(lm.getMode()).toBe('unmanaged');
+  });
+
+  it('nulls out getLicense() after clear', () => {
+    const lm = LicenseManager.getInstance();
+    lm.loadLicense({ licenseKey: 'k', mode: 'managed' });
+    lm.clear();
+    expect(lm.getLicense()).toBeNull();
+  });
+});
+
+describe('LicenseManager — subscribe / notify', () => {
+  beforeEach(reset);
+
+  it('subscriber is called when loadLicense is invoked', () => {
+    const lm = LicenseManager.getInstance();
+    const spy = vi.fn();
+    lm.subscribe(spy);
+    lm.loadLicense({ licenseKey: 'k', mode: 'unmanaged' });
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('subscriber is called when clear() is invoked', () => {
+    const lm = LicenseManager.getInstance();
+    const spy = vi.fn();
+    lm.subscribe(spy);
+    lm.clear();
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('subscriber is called when validateLicense resolves', async () => {
+    stubFetch({ valid: true, licenseKey: 'KEY', mode: 'unmanaged', plan: 'default', expiresAt: null, features: {} });
+    const lm = LicenseManager.getInstance();
+    const spy = vi.fn();
+    lm.subscribe(spy);
+    await lm.validateLicense('key', FAKE_URL);
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('unsubscribe stops future notifications', () => {
+    const lm = LicenseManager.getInstance();
+    const spy = vi.fn();
+    const unsub = lm.subscribe(spy);
+    unsub();
+    lm.loadLicense({ licenseKey: 'k', mode: 'unmanaged' });
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('multiple subscribers each fire independently', () => {
+    const lm = LicenseManager.getInstance();
+    const spyA = vi.fn();
+    const spyB = vi.fn();
+    lm.subscribe(spyA);
+    lm.subscribe(spyB);
+    lm.loadLicense({ licenseKey: 'k', mode: 'unmanaged' });
+    expect(spyA).toHaveBeenCalledTimes(1);
+    expect(spyB).toHaveBeenCalledTimes(1);
+  });
+});

package/src/licensing/licenseTypes.ts

@@ -0,0 +1,19 @@
+export type LicenseMode = 'managed' | 'unmanaged';
+
+export interface LicenseFeatures {
+  orderEntry?: boolean;
+  overlays?: boolean;
+  indicators?: boolean;
+  managedTrading?: boolean;
+  unmanagedIngestion?: boolean;
+  draggableOrders?: boolean;
+  bracketOrders?: boolean;
+}
+
+export interface LicensePayload {
+  licenseKey: string;
+  mode: LicenseMode;
+  plan?: string;
+  expires?: string;
+  features?: LicenseFeatures;
+}

package/src/pine/PineCompiler.ts

@@ -0,0 +1,68 @@
+/**
+ * PineCompiler — public entry point for the Pine Script compatibility layer.
+ *
+ * Pipeline:
+ *   Pine source → PineLexer → PineToken[] → PineParser → PineProgram
+ *               → PineTranspiler → TScript source → TScriptIndicator runtime
+ */
+
+import { PineParser }      from './pine-parser';
+import { PineTranspiler }  from './pine-transpiler';
+import { DiagnosticBag }   from './diagnostics';
+import type { Diagnostic } from './diagnostics';
+import { TScriptIndicator } from '../tscript/TScriptIndicator';
+import type { OHLCV }       from '@forgecharts/types';
+import type { IndicatorPoint } from '../core/IndicatorEngine';
+
+export type { Diagnostic };
+export type { DiagnosticSeverity } from './diagnostics';
+
+export interface PineCompileResult {
+  /** The transpiled TScript source string. */
+  readonly tscript:     string;
+  readonly diagnostics: readonly Diagnostic[];
+  /** `true` when there are no error-severity diagnostics. */
+  readonly ok:          boolean;
+}
+
+export class PineCompiler {
+  /**
+   * Compile Pine Script source to TScript.
+   * Parse errors throw a `SyntaxError`; semantic problems populate diagnostics.
+   */
+  compile(pineSource: string): PineCompileResult {
+    const diag = new DiagnosticBag();
+
+    const parser = new PineParser(pineSource);
+    const program = parser.parse();
+
+    const transpiler = new PineTranspiler(diag);
+    const tscript = transpiler.transpile(program);
+
+    return {
+      tscript,
+      diagnostics: diag.diagnostics,
+      ok:          !diag.hasErrors(),
+    };
+  }
+
+  /**
+   * Convenience: compile + run against a bar series.
+   * Returns the plot outputs and any diagnostics.
+   */
+  static run(
+    pineSource: string,
+    bars:       readonly OHLCV[],
+  ): { plots: IndicatorPoint[][]; diagnostics: readonly Diagnostic[] } {
+    const compiler = new PineCompiler();
+    const result   = compiler.compile(pineSource);
+
+    if (!result.ok) {
+      return { plots: [], diagnostics: result.diagnostics };
+    }
+
+    const indicator = new TScriptIndicator(result.tscript);
+    const plots     = indicator.run(bars);
+    return { plots, diagnostics: result.diagnostics };
+  }
+}

package/src/pine/diagnostics.ts

@@ -0,0 +1,30 @@
+/** Diagnostic emitted by the Pine compiler pipeline. */
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+
+export interface Diagnostic {
+  readonly severity: DiagnosticSeverity;
+  readonly message:  string;
+  readonly line:     number;
+  readonly col:      number;
+  /** Machine-readable code, e.g. 'PINE_UNSUPPORTED_FN' */
+  readonly code:     string;
+}
+
+export class DiagnosticBag {
+  private readonly _diags: Diagnostic[] = [];
+
+  add(
+    severity: DiagnosticSeverity,
+    message:  string,
+    loc:      { line: number; col: number },
+    code:     string,
+  ): void {
+    this._diags.push({ severity, message, line: loc.line, col: loc.col, code });
+  }
+
+  get diagnostics(): readonly Diagnostic[] { return this._diags; }
+
+  hasErrors(): boolean {
+    return this._diags.some(d => d.severity === 'error');
+  }
+}

package/src/pine/index.ts

@@ -0,0 +1,7 @@
+export { PineParser }     from './pine-parser';
+export { PineTranspiler } from './pine-transpiler';
+export { DiagnosticBag }  from './diagnostics';
+export { PineCompiler }   from './PineCompiler';
+export type { Diagnostic, DiagnosticSeverity } from './diagnostics';
+export type { PineCompileResult } from './PineCompiler';
+export type { PineProgram, PineStmt, PineExpr } from './pine-ast';

package/src/pine/pine-ast.ts

@@ -0,0 +1,163 @@
+/**
+ * Pine Script AST types — subset understood by the ForgeCharts Pine compat layer.
+ *
+ * Supported Pine v5 constructs:
+ *   indicator(title, overlay?, ...)
+ *   input(defval, title?, ...)  /  input.int()  /  input.float()  /  input.bool()  /  input.source()
+ *   ta.sma()  ta.ema()  ta.wma()  ta.rma()  ta.rsi()  ta.macd()
+ *   ta.stdev()  ta.highest()  ta.lowest()  ta.change()  ta.mom()  ta.atr()
+ *   ta.crossover()  ta.crossunder()  ta.barssince()
+ *   math.abs()  math.max()  math.min()  math.round()  math.floor()  math.ceil()
+ *   math.sqrt()  math.log()  math.pow()  math.sign()
+ *   plot()  plotshape()
+ *   nz()  na()
+ *   if / else blocks
+ *   var declarations
+ *   ternary  a ? b : c
+ */
+
+// ─── Locations ────────────────────────────────────────────────────────────────
+
+export type Loc = { line: number; col: number };
+
+// ─── Literals ─────────────────────────────────────────────────────────────────
+
+export type PineNumberLit = { kind: 'PineNumberLit'; value: number; loc: Loc };
+export type PineStringLit = { kind: 'PineStringLit'; value: string; loc: Loc };
+export type PineBoolLit   = { kind: 'PineBoolLit';   value: boolean; loc: Loc };
+export type PineColorLit  = { kind: 'PineColorLit';  value: string; loc: Loc };  // e.g. color.red
+export type PineNa        = { kind: 'PineNa'; loc: Loc };
+
+// ─── Expressions ──────────────────────────────────────────────────────────────
+
+export type PineIdent = {
+  kind: 'PineIdent';
+  name: string;
+  loc:  Loc;
+};
+
+/** Namespaced call: ta.sma(src, len) or math.abs(x) */
+export type PineNsCall = {
+  kind:      'PineNsCall';
+  namespace: string;   // 'ta' | 'math' | 'input' | 'color' | etc.
+  fn:        string;
+  args:      PineExpr[];
+  namedArgs: Map<string, PineExpr>;
+  loc:       Loc;
+};
+
+/** Plain function call: sma(src, len), indicator(...), plot(...) */
+export type PineCall = {
+  kind:      'PineCall';
+  fn:        string;
+  args:      PineExpr[];
+  namedArgs: Map<string, PineExpr>;
+  loc:       Loc;
+};
+
+export type PineIndex = {
+  kind:   'PineIndex';
+  series: PineExpr;
+  index:  PineExpr;
+  loc:    Loc;
+};
+
+export type PineBinary = {
+  kind:  'PineBinary';
+  op:    '+' | '-' | '*' | '/' | '%' | '<' | '>' | '<=' | '>=' | '==' | '!=' | 'and' | 'or';
+  left:  PineExpr;
+  right: PineExpr;
+  loc:   Loc;
+};
+
+export type PineUnary = {
+  kind:    'PineUnary';
+  op:      '-' | 'not';
+  operand: PineExpr;
+  loc:     Loc;
+};
+
+export type PineTernary = {
+  kind:       'PineTernary';
+  condition:  PineExpr;
+  consequent: PineExpr;
+  alternate:  PineExpr;
+  loc:        Loc;
+};
+
+/** Member access: color.red, bar_index, etc. — resolved at transpile time */
+export type PineMember = {
+  kind:   'PineMember';
+  object: string;
+  prop:   string;
+  loc:    Loc;
+};
+
+export type PineExpr =
+  | PineNumberLit
+  | PineStringLit
+  | PineBoolLit
+  | PineColorLit
+  | PineNa
+  | PineIdent
+  | PineNsCall
+  | PineCall
+  | PineIndex
+  | PineBinary
+  | PineUnary
+  | PineTernary
+  | PineMember;
+
+// ─── Statements ───────────────────────────────────────────────────────────────
+
+export type PineIndicatorDecl = {
+  kind:    'PineIndicatorDecl';
+  args:    PineExpr[];
+  namedArgs: Map<string, PineExpr>;
+  loc:     Loc;
+};
+
+/** var / varip declaration */
+export type PineVarDecl = {
+  kind:      'PineVarDecl';
+  modifier:  'var' | 'varip';
+  name:      string;
+  typeHint?: string;
+  value:     PineExpr;
+  loc:       Loc;
+};
+
+export type PineAssign = {
+  kind:  'PineAssign';
+  name:  string;
+  op:    '=' | ':=';
+  value: PineExpr;
+  loc:   Loc;
+};
+
+export type PineExprStmt = {
+  kind: 'PineExprStmt';
+  expr: PineExpr;
+  loc:  Loc;
+};
+
+export type PineIf = {
+  kind:       'PineIf';
+  condition:  PineExpr;
+  then:       PineStmt[];
+  else_:      PineStmt[];
+  loc:        Loc;
+};
+
+export type PineStmt =
+  | PineIndicatorDecl
+  | PineVarDecl
+  | PineAssign
+  | PineExprStmt
+  | PineIf;
+
+export type PineProgram = {
+  kind:    'PineProgram';
+  version: number;   // extracted from //@version=5
+  stmts:   PineStmt[];
+};