@forgecharts/sdk 1.1.23

package/src/api/TChart.ts

@@ -0,0 +1,881 @@
+import type {
+  ChartConfig,
+  ChartInterval,
+  ChartTheme,
+  ChartEventMap,
+  ChartLayout,
+  Drawing,
+  IDatafeed,
+  IndicatorConfig,
+  IndicatorInstance,
+  IPlugin,
+  IPublicChart,
+  OHLCV,
+  PaneDescriptor,
+} from '@forgecharts/types';
+import { Chart } from '../core/Chart';
+import { EventBus } from './EventBus';
+import { IndicatorRegistry } from './IndicatorRegistry';
+import { DrawingManager } from './DrawingManager';
+import { LayoutManager } from './LayoutManager';
+import { PaneManager } from './PaneManager';
+import { DatafeedConnector } from '../datafeed/DatafeedConnector';
+import type { ISeries } from '../types/ISeries';
+import type { CoordTransform } from '../core/CoordTransform';
+import { TradingOverlayStore } from '../trading/TradingOverlayStore';
+import { UnmanagedIngestion } from '../trading/UnmanagedIngestion';
+import { isUnmanagedMode } from '../licensing/ChartRuntimeResolver';
+import type { CandleInput, ChartOrder, ChartPosition, ExecutionFill } from '../trading/tradingTypes';
+import { ManagedTradingController } from '../trading/managed/ManagedTradingController';
+
+/** Candle duration in seconds per timeframe — used for the history-prefetch threshold. */
+const _TF_SECS: Partial<Record<string, number>> = {
+  '1s': 1, '5s': 5, '10s': 10, '30s': 30,
+  '1m': 60, '3m': 180, '5m': 300, '15m': 900, '30m': 1800,
+  '1h': 3600, '2h': 7200, '4h': 14400, '6h': 21600, '12h': 43200,
+  '1d': 86400, '3d': 259200, '1w': 604800, '1M': 2592000,
+};
+
+/**
+ * TChart — the stable public chart instance returned by `createChart()`.
+ *
+ * Wraps the internal canvas `Chart` engine and exposes the documented
+ * public API. Application code and plugins should only interact with
+ * `TChart`/`IPublicChart`; never with the internal `Chart` class directly.
+ *
+ * @example
+ * ```ts
+ * import { createChart } from '@forgecharts/sdk';
+ *
+ * const chart = createChart({
+ *   container: document.getElementById('chart')!,
+ *   symbol: 'BTCUSDT',
+ *   interval: '5m',
+ * });
+ *
+ * chart.on('symbolChanged', ({ symbol }) => console.log('Symbol:', symbol));
+ *
+ * chart.setTheme('light');
+ * const id = chart.addIndicator({ type: 'ema', params: { period: 20 } });
+ * chart.removeIndicator(id);
+ *
+ * const layout = chart.saveLayout();         // portable JSON-ready object
+ * chart.loadLayout(layout);                  // restore
+ *
+ * chart.destroy();
+ * ```
+ */
+export class TChart implements IPublicChart {
+  private readonly _core: Chart;
+  private readonly _bus: EventBus;
+  private readonly _indicators: IndicatorRegistry;
+  private readonly _drawings: DrawingManager;
+  private readonly _panes: PaneManager;
+  private readonly _plugins: IPlugin[] = [];
+
+  /** Primary price series — created once; fed by the datafeed or directly. */
+  private readonly _series: ISeries;
+  /** Datafeed connector — null when no datafeed was provided. */
+  private _connector: DatafeedConnector | null = null;
+
+  private _symbol: string;
+  private _interval: ChartInterval;
+  private _theme: ChartTheme;
+  private _destroyed = false;
+
+  /**
+   * In-memory auth token.  Set via constructor `getAuthToken` callback or
+   * directly via `setAuthToken()`.  Takes precedence over localStorage.
+   */
+  private _authToken: string | null = null;
+  private readonly _getAuthToken: (() => string | Promise<string>) | null = null;
+  private readonly _apiUrl: string;
+
+  // ─ Shared trading overlay store (used by both unmanaged and managed modes) ──
+  private readonly _overlayStore: TradingOverlayStore = new TradingOverlayStore();
+  /** Lazy-initialised; only created when first unmanaged ingestion method is called. */
+  private _unmanagedIngestion: UnmanagedIngestion | null = null;
+  /** Lazy-initialised; only created when getManagedTrading() is first called. */
+  private _managedTrading: ManagedTradingController | null = null;
+
+  /**
+   * Returns a Bearer token for API calls.  Resolution order:
+   * 1. In-memory `_authToken` (set via `setAuthToken()`).
+   * 2. `getAuthToken` callback from config (embedder-managed).
+   * 3. `localStorage["forgecharts-token"]` (built-in frontend fallback).
+   *
+   * Returns `null` when no token is available — API calls will be unauthenticated.
+   */
+  async resolveAuthToken(): Promise<string | null> {
+    if (this._authToken) return this._authToken;
+    if (this._getAuthToken) {
+      try { return await this._getAuthToken(); } catch { return null; }
+    }
+    if (typeof localStorage !== 'undefined') {
+      return localStorage.getItem('forgecharts-token');
+    }
+    return null;
+  }
+
+  constructor(config: ChartConfig) {
+    this._symbol = config.symbol;
+    this._apiUrl = config.apiUrl ?? '';
+    if (config.getAuthToken) this._getAuthToken = config.getAuthToken;
+    this._interval = config.interval ?? '1h';
+    this._theme = config.theme ?? 'dark';
+
+    this._bus = new EventBus();
+    this._indicators = new IndicatorRegistry();
+    this._panes = new PaneManager();
+
+    this._core = new Chart(config.container, {
+      theme: this._theme,
+      handleScroll: !(config.disableScroll ?? false),
+      handleScale: !(config.disableZoom ?? false),
+      ...(config.crosshair !== undefined ? { crosshair: config.crosshair } : {}),
+    });
+
+    // Use the Chart's own DrawingManager so drawings are rendered automatically
+    this._drawings = this._core.drawingManager();
+
+    // Wire drawing callbacks
+    this._core.onDrawingCommitted = (drawing) => {
+      this._bus.emit('drawingCreated', drawing);
+    };
+    this._core.onDrawingDeleted = (id) => {
+      this._bus.emit('drawingRemoved', { id });
+    };
+    this._core.onDrawingContextMenu = (id, x, y) => {
+      this._bus.emit('drawingContextMenu', { id, x, y });
+    };
+
+    // Prime the chart with a default candlestick series and retain the reference
+    this._series = this._core.addSeries({ type: 'candlestick' });
+
+    // Tell the core chart which timeframe is active (for last-price countdown)
+    this._core.setInterval(this._interval);
+
+    // Wire datafeed if provided
+    if (config.datafeed !== undefined) {
+      this._connector = this._buildConnector(config.datafeed);
+      this._connector.connect(this._symbol, this._interval);
+    }
+
+    // Lazy-load older history when the user pans/zooms the left edge into view.
+    // Fires on every pan/zoom; debounced internally by DatafeedConnector._isLoadingMore.
+    this._core.onViewportChanged = () => {
+      const connector = this._connector;
+      if (!connector) return;
+      const bars = this._series.data();
+      if (bars.length === 0) return;
+      const oldestBarTime = bars[0]!.time;
+      const { from } = this._core.getViewport().timeRange;
+      // Trigger when the viewport left edge is within 30 candles of the oldest loaded bar
+      const tfSec = _TF_SECS[this._interval] ?? 3600;
+      if (from < oldestBarTime + tfSec * 30) {
+        connector.loadMoreHistory(this._symbol, this._interval);
+      }
+    };
+
+    // Attach plugins provided at construction time
+    for (const plugin of config.plugins ?? []) {
+      this._attachPlugin(plugin);
+    }
+  }
+
+  // ─── Getters ─────────────────────────────────────────────────────────────────
+
+  /** Currently displayed symbol. */
+  get symbol(): string {
+    return this._symbol;
+  }
+
+  /** Currently active interval. */
+  get interval(): ChartInterval {
+    return this._interval;
+  }
+
+  /** Currently active theme. */
+  get theme(): ChartTheme {
+    return this._theme;
+  }
+
+  // ─── Data access ─────────────────────────────────────────────────────────────
+
+  /** Returns the current bar dataset (sorted ascending by time). */
+  getBars(): readonly OHLCV[] {
+    return this._series.data();
+  }
+
+  /** Returns the coordinate transform used for pixel ⇔ data conversions. */
+  getTransform(): CoordTransform {
+    return this._core.transform();
+  }
+
+  /** Returns the current sub-pane descriptors. */
+  getPanes(): readonly PaneDescriptor[] {
+    return this._panes.getPanes();
+  }
+
+  /** Returns all active indicator instances. */
+  getIndicators(): readonly IndicatorInstance[] {
+    return this._indicators.all();
+  }
+
+  /**
+   * Resizes a sub-pane by setting its height fraction.
+   * Remaining panes absorb the difference proportionally.
+   */
+  resizePane(id: string, newFraction: number): void {
+    this._assertAlive();
+    this._panes.resizePane(id, newFraction);
+  }
+
+  // ─── Auth ─────────────────────────────────────────────────────────────────────
+
+  /**
+   * Sets a static Bearer token for API calls (layouts, etc.).
+   *
+   * Call this after your user authenticates.  If you prefer token refresh,
+   * supply `getAuthToken` in `ChartConfig` instead — that callback is invoked
+   * on every API request so you can return a fresh token each time.
+   *
+   * @example
+   * ```ts
+   * // After your own login succeeds:
+   * const { forgechartsToken } = await myBackend.login(email, password);
+   * chart.setAuthToken(forgechartsToken);
+   * ```
+   */
+  setAuthToken(token: string): void {
+    this._authToken = token;
+  }
+
+  /**
+   * Clears the in-memory auth token (e.g. on logout).
+   * After calling this the SDK falls back to `getAuthToken` or localStorage.
+   */
+  clearAuthToken(): void {
+    this._authToken = null;
+  }
+
+  // ─── Setters ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Changes the displayed symbol.
+   * No-ops if the symbol is unchanged.
+   * Emits `symbolChanged`.
+   */
+  setSymbol(symbol: string): void {
+    this._assertAlive();
+    if (symbol === this._symbol) return;
+    this._symbol = symbol;
+    this._bus.emit('symbolChanged', { symbol });
+    this._connector?.reconnect(symbol, this._interval);
+  }
+
+  /**
+   * Changes the active interval.
+   * No-ops if the interval is unchanged.
+   * Emits `intervalChanged`.
+   */
+  setInterval(interval: ChartInterval): void {
+    this._assertAlive();
+    if (interval === this._interval) return;
+    this._interval = interval;
+    this._core.setInterval(interval);
+    this._bus.emit('intervalChanged', { interval });
+    this._connector?.reconnect(this._symbol, interval);
+  }
+
+  /**
+   * Switches the colour theme.
+   * No-ops if the theme is unchanged.
+   * Emits `themeChanged`.
+   */
+  setTheme(theme: ChartTheme): void {
+    this._assertAlive();
+    if (theme === this._theme) return;
+    this._theme = theme;
+    this._core.applyOptions({ theme });
+    this._bus.emit('themeChanged', { theme });
+  }
+
+  /** Updates the timezone used for all time-axis labels. */
+  setTimezone(timezone: string): void {
+    this._assertAlive();
+    this._core.applyOptions({ timezone });
+  }
+
+  /**
+   * Applies low-level chart options (colors, theme, scales, etc.).
+   * Pass `{ colors: { background: '#fff' } }` to change individual canvas colors.
+   */
+  applyOptions(options: Partial<import('@forgecharts/types').ChartOptions>): void {
+    this._assertAlive();
+    this._core.applyOptions(options);
+  }
+
+  /** Scrolls the viewport so the latest bar is visible at the right edge. */
+  scrollToEnd(): void {
+    this._assertAlive();
+    this._core.scrollToEnd();
+  }
+
+  /**
+   * Sets the default viewport: 10 days visible with the latest bar near the
+   * right edge (5% empty space on the right for future price action).
+   */
+  fitDefaultView(): void {
+    this._assertAlive();
+    this._core.fitDefaultView();
+  }
+
+  /**
+   * Resets the price axis to auto-fit mode without changing the time range.
+   * Use this after restoring a saved viewport to prevent a stale priceRange
+   * from locking the scale at a wrong value (e.g. the default 0–100).
+   */
+  resetPriceScale(): void {
+    this._assertAlive();
+    this._core.resetPriceScale();
+  }
+
+  /** Returns the current visible time and price ranges. */
+  getViewport(): import('@forgecharts/types').Viewport {
+    this._assertAlive();
+    return this._core.getViewport();
+  }
+
+  /** Restores a previously saved viewport (time + price ranges). */
+  restoreViewport(v: import('@forgecharts/types').Viewport): void {
+    this._assertAlive();
+    this._core.restoreViewport(v);
+  }
+
+  // ─── Indicators ──────────────────────────────────────────────────────────────
+
+  /**
+   * Registers an indicator and returns its opaque id.
+   * Emits `indicatorAdded`.
+   *
+   * @example
+   * ```ts
+   * const rsiId = chart.addIndicator({ type: 'rsi', params: { period: 14 } });
+   * ```
+   */
+  addIndicator(config: IndicatorConfig): string {
+    this._assertAlive();
+    const id = this._indicators.add(config);
+    // Non-overlay indicators get their own dedicated sub-pane
+    if (config.overlay !== true) {
+      const label = _indicatorTypeLabel(config.type);
+      const paneId = this._panes.createPane(label);
+      this._panes.assignIndicator(id, paneId);
+    }
+    this._bus.emit('indicatorAdded', { id, config });
+    return id;
+  }
+
+  /**
+   * Removes a previously added indicator.
+   * Silently no-ops if the id is unknown.
+   * Emits `indicatorRemoved`.
+   */
+  removeIndicator(id: string): void {
+    this._assertAlive();
+    // Find which pane holds this indicator before removal
+    const paneId = this._panes.getPanes().find((p) => p.indicatorIds.includes(id))?.id;
+    const removed = this._indicators.remove(id);
+    if (removed) {
+      this._panes.unassignIndicator(id);
+      // Remove the pane if it is now empty
+      if (paneId !== undefined) {
+        const pane = this._panes.getPanes().find((p) => p.id === paneId);
+        if (pane !== undefined && pane.indicatorIds.length === 0) {
+          this._panes.removePane(paneId);
+        }
+      }
+      this._bus.emit('indicatorRemoved', { id });
+    }
+  }
+
+  // ─── Drawings ────────────────────────────────────────────────────────────────
+
+  /**
+   * Adds a drawing to the chart and returns its generated id.
+   * Emits `drawingCreated`.
+   *
+   * @example
+   * ```ts
+   * const id = chart.addDrawing({
+   *   type: 'trendline',
+   *   points: [
+   *     { time: 1700000000, price: 45000 },
+   *     { time: 1700003600, price: 46000 },
+   *   ],
+   * });
+   * ```
+   */
+  addDrawing(drawing: Omit<Drawing, 'id'>): string {
+    this._assertAlive();
+    const id = this._drawings.add(drawing);
+    const full = this._drawings.get(id);
+    if (!full) throw new Error('[ForgeCharts] DrawingManager failed to store drawing');
+    this._bus.emit('drawingCreated', full);
+    this._core.markDirty();
+    return id;
+  }
+
+  /**
+   * Removes a single drawing by id.
+   * Emits `drawingRemoved`.
+   */
+  removeDrawing(id: string): void {
+    this._assertAlive();
+    if (!this._drawings.has(id)) return;
+    this._drawings.remove(id);
+    this._bus.emit('drawingRemoved', { id });
+    this._core.markDirty();
+  }
+
+  /**
+   * Activates a drawing tool. Clicks will place anchors on the chart.
+   * The tool remains active after each commit (auto-repeat). Press Escape to cancel.
+   */
+  startDrawingTool(type: import('@forgecharts/types').DrawingType): void {
+    this._assertAlive();
+    this._core.startDrawingTool(type);
+  }
+
+  /** Cancels an active drawing tool and returns to cursor mode. */
+  cancelDrawingTool(): void {
+    this._assertAlive();
+    this._core.cancelDrawingTool();
+  }
+
+  /**
+   * Show or hide the SDK crosshair lines.
+   * Call with `false` for Arrow mode; `true` for crosshair / dot / demonstration.
+   */
+  setCrosshairEnabled(enabled: boolean): void {
+    this._assertAlive();
+    this._core.setCrosshairEnabled(enabled);
+  }
+
+  /** Hides (`true`) or restores (`false`) the native OS cursor for dot / demonstration pointer modes. */
+  setNativeCursorHidden(hidden: boolean): void {
+    this._assertAlive();
+    this._core.setNativeCursorHidden(hidden);
+  }
+
+  /** Deletes the currently selected drawing (if any). */
+  deleteSelectedDrawing(): void {
+    this._assertAlive();
+    this._core.deleteSelectedDrawing();
+  }
+
+  /** Shows or hides all drawings on the chart. */
+  setAllDrawingsVisible(v: boolean): void {
+    this._assertAlive();
+    this._core.setAllDrawingsVisible(v);
+  }
+
+  /** Shows or hides all indicators/series on the chart. */
+  setIndicatorsVisible(v: boolean): void {
+    this._assertAlive();
+    this._core.setIndicatorsVisible(v);
+  }
+
+  /**
+   * Removes all drawings from the chart.
+   * Emits `drawingsCleared`.
+   */
+  clearDrawings(): void {
+    this._assertAlive();
+    this._drawings.clear();
+    this._bus.emit('drawingsCleared', {});
+  }
+
+  // ─── Layout ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Restores a previously saved layout.
+   * Replaces current symbol, interval, theme, indicators, and drawings.
+   * Emits `layoutLoaded`.
+   */
+  loadLayout(layout: ChartLayout): void {
+    this._assertAlive();
+
+    this._symbol = layout.symbol;
+    this._interval = layout.interval;
+
+    // Theme (use internal setter to propagate to canvas)
+    if (layout.theme !== this._theme) {
+      this._theme = layout.theme;
+      this._core.applyOptions({ theme: layout.theme });
+    }
+
+    // Indicators
+    this._indicators.clear();
+    for (const inst of layout.indicators) {
+      this._indicators.add(inst.config);
+    }
+
+    // Drawings — strip old ids and re-add (DrawingManager assigns new ids)
+    this._drawings.clear();
+    for (const { id: _discarded, ...rest } of layout.drawings) {
+      this._drawings.add(rest as Omit<Drawing, 'id'>);
+    }
+    this._core.markDirty();
+
+    // Panes
+    this._panes.clear();
+    if (layout.panes !== undefined) {
+      this._panes.restore(layout.panes);
+    }
+
+    // Viewport — restore time range so the chart opens at the same position.
+    // Price is also restored so custom scales are preserved.
+    if (layout.viewport) {
+      this._core.restoreViewport(layout.viewport);
+    }
+
+    this._bus.emit('layoutLoaded', layout);
+  }
+
+  /**
+   * Serialises the current chart state to a portable layout object.
+   * Safe to `JSON.stringify()` for persistence.
+   * Emits `layoutSaved`.
+   */
+  saveLayout(): ChartLayout {
+    this._assertAlive();
+    const panes = this._panes.serialize();
+    const layout = LayoutManager.save({
+      symbol: this._symbol,
+      interval: this._interval,
+      theme: this._theme,
+      indicators: this._indicators.all(),
+      drawings: this._drawings.all(),
+      viewport: this._core.getViewport(),
+      ...(panes.length > 0 ? { panes } : {}),
+    });
+    this._bus.emit('layoutSaved', layout);
+    return layout;
+  }
+
+  // ─── Plugin API ───────────────────────────────────────────────────────────────
+
+  /**
+   * Attaches a plugin at runtime.
+   *
+   * @example
+   * ```ts
+   * chart.use(new WatermarkPlugin({ text: 'ForgeCharts' }));
+   * ```
+   */
+  use(plugin: IPlugin): this {
+    this._assertAlive();
+    this._attachPlugin(plugin);
+    return this;
+  }
+
+  /**
+   * Detaches a plugin by its `id` property.
+   * Silently no-ops if the plugin is not attached.
+   */
+  eject(pluginId: string): this {
+    const idx = this._plugins.findIndex((p) => p.id === pluginId);
+    if (idx === -1) return this;
+    const [removed] = this._plugins.splice(idx, 1) as [IPlugin];
+    removed.onDetach();
+    return this;
+  }
+
+  // ─── Event bus ────────────────────────────────────────────────────────────────
+
+  /**
+   * Subscribes to a chart event.
+   *
+   * @example
+   * ```ts
+   * chart.on('symbolChanged', ({ symbol }) => {
+   *   document.title = symbol;
+   * });
+   * ```
+   */
+  on<K extends keyof ChartEventMap>(
+    event: K,
+    handler: (payload: ChartEventMap[K]) => void,
+  ): this {
+    this._bus.on(event, handler);
+    return this;
+  }
+
+  /**
+   * Unsubscribes a previously registered handler.
+   * The handler reference must be the same function passed to `on()`.
+   */
+  off<K extends keyof ChartEventMap>(
+    event: K,
+    handler: (payload: ChartEventMap[K]) => void,
+  ): this {
+    this._bus.off(event, handler);
+    return this;
+  }
+
+  /**
+   * Subscribes to an event for a single invocation.
+   * The handler is automatically removed after it fires once.
+   */
+  once<K extends keyof ChartEventMap>(
+    event: K,
+    handler: (payload: ChartEventMap[K]) => void,
+  ): this {
+    this._bus.once(event, handler);
+    return this;
+  }
+
+  // ─── Lifecycle ────────────────────────────────────────────────────────────────
+
+  /**
+   * Tears down the chart instance:
+   * 1. Detaches all plugins
+   * 2. Destroys the canvas engine (removes DOM elements)
+   * 3. Emits `destroyed`
+   * 4. Clears all event listeners
+   *
+   * After `destroy()` every further method call throws `[ForgeCharts] destroyed`.
+   */
+  destroy(): void {
+    if (this._destroyed) return;
+    this._destroyed = true;
+
+    // Tear down datafeed before destroying the canvas so no tick can arrive
+    // after series / canvas are gone
+    this._connector?.destroy();
+    this._connector = null;
+
+    for (const plugin of [...this._plugins]) {
+      plugin.onDetach();
+    }
+    this._plugins.length = 0;
+
+    this._core.destroy();
+    this._bus.emit('destroyed', {});
+    this._bus.clear();
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  // ─── Unmanaged ingestion ───────────────────────────────────────────────────
+
+  /**
+   * Load a full historical bar snapshot in unmanaged mode.
+   * Replaces the ingestion engine’s bar array and triggers a chart resync.
+   *
+   * **Only available in unmanaged mode.** Throws if the active license is managed.
+   *
+   * Call this once at startup (or after a symbol/interval change) before
+   * streaming live candles via `pushCandle()`.
+   *
+   * @param bars  Chronologically ordered (oldest → newest) candle array.
+   */
+  setHistory(bars: CandleInput[]): void {
+    this._assertAlive();
+    this._getIngestion().setHistory(bars);
+  }
+
+  /**
+   * Push a single live candle in unmanaged mode.
+   * Follows standard OHLCV merge rules:
+   * - same timestamp → update existing bar
+   * - newer timestamp → append new bar
+   * - older timestamp → silently ignored
+   *
+   * **Only available in unmanaged mode.** Throws if the active license is managed.
+   */
+  pushCandle(bar: CandleInput): void {
+    this._assertAlive();
+    this._getIngestion().pushCandle(bar);
+  }
+
+  // ─── Trading overlay ─────────────────────────────────────────────────────
+  // Shared between unmanaged and managed modes. In unmanaged mode the client
+  // provides state externally; in managed mode the managed trading service
+  // will drive these via the same store.
+
+  /** Returns the shared trading overlay store (read access for renderers). */
+  getOverlayStore(): TradingOverlayStore {
+    return this._overlayStore;
+  }
+
+  /**
+   * Alias for {@link getOverlayStore} — canonical name used in documentation
+   * and the public SDK contract.
+   */
+  getTradingOverlayStore(): TradingOverlayStore {
+    return this._overlayStore;
+  }
+
+  // ─ Orders ──
+
+  /** Replace the entire order set on the chart overlay. */
+  setOrders(orders: ChartOrder[]): void {
+    this._assertAlive();
+    this._overlayStore.setOrders(orders);
+    this._core.markDirty();
+  }
+
+  /** Insert or update a single order (matched by `order.id`). */
+  upsertOrder(order: ChartOrder): void {
+    this._assertAlive();
+    this._overlayStore.upsertOrder(order);
+    this._core.markDirty();
+  }
+
+  /** Remove an order line by id. Silent no-op if not found. */
+  removeOrder(orderId: string): void {
+    this._assertAlive();
+    this._overlayStore.removeOrder(orderId);
+    this._core.markDirty();
+  }
+
+  // ─ Positions ──
+
+  /** Replace the entire position set on the chart overlay. */
+  setPositions(positions: ChartPosition[]): void {
+    this._assertAlive();
+    this._overlayStore.setPositions(positions);
+    this._core.markDirty();
+  }
+
+  /** Insert or update a single position (matched by `position.id`). */
+  upsertPosition(position: ChartPosition): void {
+    this._assertAlive();
+    this._overlayStore.upsertPosition(position);
+    this._core.markDirty();
+  }
+
+  /** Remove a position marker by id. Silent no-op if not found. */
+  removePosition(positionId: string): void {
+    this._assertAlive();
+    this._overlayStore.removePosition(positionId);
+    this._core.markDirty();
+  }
+
+  // ─ Fills ──
+
+  /** Append an execution fill marker to the chart. Fills are append-only. */
+  pushExecution(fill: ExecutionFill): void {
+    this._assertAlive();
+    this._overlayStore.pushExecution(fill);
+    this._core.markDirty();
+  }
+
+  // ─── Managed trading ────────────────────────────────────────────────────
+
+  /**
+   * Returns the managed trading controller for this chart instance.
+   *
+   * The controller is lazily created the first time this is called.
+   * It is bound to this chart’s shared overlay store so all managed trades
+   * flow into the same visual layer as unmanaged overlays.
+   *
+   * Call `chart.getManagedTrading().registerProvider(myProvider)` to wire
+   * up an execution backend.
+   *
+   * **Requires a managed-mode license.** The controller’s methods will throw
+   * if called without appropriate capability.
+   *
+   * @example
+   * ```ts
+   * const mgd = chart.getManagedTrading();
+   * mgd.registerProvider(new RithmicProvider(credentials));
+   * await mgd.placeOrder({ symbol: 'ES', side: 'buy', type: 'limit', limitPrice: 5200, qty: 1 });
+   * ```
+   */
+  getManagedTrading(): ManagedTradingController {
+    this._assertAlive();
+    if (!this._managedTrading) {
+      this._managedTrading = new ManagedTradingController(this._overlayStore);
+    }
+    return this._managedTrading;
+  }
+
+  private _attachPlugin(plugin: IPlugin): void {
+    this._plugins.push(plugin);
+    plugin.onAttach(this);
+  }
+
+  private _assertAlive(): void {
+    if (this._destroyed) {
+      throw new Error('[ForgeCharts] Method called on a destroyed chart instance.');
+    }
+  }
+
+  /**
+   * Returns the UnmanagedIngestion instance, lazily creating it on first call.
+   * Wires the ingestion callbacks so live candle updates flow into the chart series.
+   */
+  private _getIngestion(): UnmanagedIngestion {
+    if (!this._unmanagedIngestion) {
+      if (!isUnmanagedMode()) {
+        throw new Error(
+          '[ForgeCharts] External data ingestion is only available in unmanaged mode.',
+        );
+      }
+      this._unmanagedIngestion = new UnmanagedIngestion(this._interval, {
+        onBarUpdated: (bar) => {
+          this._series.update(bar);
+          this._bus.emit('barsUpdated', { count: this._series.data().length });
+        },
+        onResync: (bars) => {
+          this._series.setData(bars as unknown as OHLCV[]);
+          this._bus.emit('barsUpdated', { count: bars.length });
+        },
+      });
+    }
+    return this._unmanagedIngestion;
+  }
+
+  // ─── Datafeed ─────────────────────────────────────────────────────────────────
+
+  private _buildConnector(datafeed: IDatafeed): DatafeedConnector {
+    return new DatafeedConnector(datafeed, this._series, {
+      onLoading: (symbol, interval) => {
+        this._bus.emit('dataLoading', { symbol, interval });
+      },
+      onLoaded: (symbol, interval, count) => {
+        this._bus.emit('dataLoaded', { symbol, interval, count });
+        this._bus.emit('barsUpdated', { count });
+      },
+      onError: (symbol, interval, error) => {
+        this._bus.emit('dataError', { symbol, interval, error });
+      },
+      onUpdate: (_bar) => {
+        this._bus.emit('barsUpdated', { count: this._series.data().length });
+      },
+    });
+  }
+}
+
+// ─── Module helpers ───────────────────────────────────────────────────────────
+
+function _indicatorTypeLabel(type: IndicatorConfig['type']): string {
+  switch (type) {
+    case 'rsi':        return 'RSI';
+    case 'macd':       return 'MACD';
+    case 'volume':     return 'Volume';
+    case 'sma':        return 'SMA';
+    case 'ema':        return 'EMA';
+    case 'wma':        return 'WMA';
+    case 'bbands':     return 'BB';
+    case 'stochastic': return 'Stoch';
+    case 'atr':        return 'ATR';
+    case 'obv':        return 'OBV';
+    case 'script':     return 'Script';
+    default:           return type;
+  }
+}