@forgecharts/sdk 1.1.23

package/src/core/Chart.ts

@@ -0,0 +1,917 @@
+import type { ChartOptions, ChartColors, ChartTheme, ChartKeyAction, Drawing, DrawingType, DrawingPoint, OHLCV, Timeframe } from '@forgecharts/types';
+import type { IChart, IChartPlugin } from '../types/IChart';
+import type { ISeries } from '../types/ISeries';
+import { CanvasLayer } from './CanvasLayer';
+import { TimeScale } from './TimeScale';
+import { PriceScale } from './PriceScale';
+import { CoordTransform } from './CoordTransform';
+import { Crosshair } from './Crosshair';
+import { Series } from './Series';
+import { InteractionManager } from './InteractionManager';
+import { DrawingManager } from '../api/DrawingManager';
+import { DARK_COLORS, LIGHT_COLORS } from '../theme/colors';
+
+// ─── Last-price helpers (module-level) ────────────────────────────────────────
+
+const _TF_SECONDS: 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,
+};
+
+function _tfToSeconds(tf: Timeframe): number {
+  return _TF_SECONDS[tf] ?? 3600;
+}
+
+function _formatLastPrice(price: number): string {
+  const decimals = price < 1 ? 6 : price < 1000 ? 4 : 2;
+  return price.toFixed(decimals);
+}
+
+function _formatCountdown(secs: number): string {
+  const h = Math.floor(secs / 3600);
+  const m = Math.floor((secs % 3600) / 60);
+  const s = secs % 60;
+  if (h > 0) return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
+  return `${m}:${String(s).padStart(2, '0')}`;  
+}
+
+/**
+ * Chart — entry point for the ForgeCharts SDK.
+ *
+ * Manages the canvas layer stack, time/price scales, all series,
+ * and the interaction model. Uses the browser Canvas 2D API directly;
+ * no third-party chart library dependencies.
+ *
+ * @example
+ * ```ts
+ * const chart = new Chart(containerEl, { theme: 'dark' });
+ * const series = chart.addSeries({ type: 'candlestick' });
+ * series.setData(ohlcvArray);
+ * ```
+ */
+export class Chart implements IChart {
+  private readonly _container: HTMLElement;
+  private readonly _options: Required<ChartOptions>;
+  private readonly _colors: ChartColors;
+
+  // Canvas layers (back → front): grid, series, overlay
+  private readonly _gridLayer: CanvasLayer;
+  private readonly _seriesLayer: CanvasLayer;
+  private readonly _overlayLayer: CanvasLayer;
+
+  private readonly _timeScale: TimeScale;
+  private readonly _priceScale: PriceScale;
+  private readonly _transform: CoordTransform;
+  private readonly _crosshair: Crosshair;
+
+  private _series: Series[] = [];
+  private _plugins: IChartPlugin[] = [];
+  private _animationFrame: number | null = null;
+  private _dirty = true;
+  private _indicatorsVisible = true;
+  /** When true the user has manually adjusted the price scale; auto-fit is suspended. */
+  private _priceScaleManual = false;
+  /** Active timeframe — used for last-price countdown. */
+  private _interval: Timeframe = '1h';
+  /** Last second at which we ticked the countdown to force a re-render. */
+  private _lastCountdownSec = 0;
+
+  private readonly _resizeObserver: ResizeObserver;
+  private readonly _interaction: InteractionManager;
+
+  // ── Drawing system ───────────────────────────────────────────────────────────────
+  private readonly _drawingMgr: DrawingManager;
+  private _drawingTool: DrawingType | null = null;
+  private _drawingState: 'idle' | 'placing_second' | 'placing_third' = 'idle';
+  private _drawingP0: DrawingPoint | null = null;
+  private _drawingP1: DrawingPoint | null = null;
+  private _drawingCursorPt: DrawingPoint | null = null;
+  /** When false the crosshair is suppressed (e.g. Arrow/cursor mode). */
+  private _crosshairEnabled = true;
+
+  /** Called whenever a drawing is committed (created or updated). */
+  onDrawingCommitted: ((drawing: Drawing) => void) | undefined;
+  /** Called whenever a drawing is deleted. */
+  onDrawingDeleted: ((id: string) => void) | undefined;
+  /** Called when the user right-clicks a drawing.  x/y are canvas-relative pixels. */
+  onDrawingContextMenu: ((id: string, x: number, y: number) => void) | undefined;
+  /**
+   * Called after every pan or zoom interaction so external code (e.g. TChart)
+   * can check whether the visible time range now extends past the oldest
+   * loaded bar and trigger a lazy history fetch.
+   */
+  onViewportChanged: (() => void) | undefined;
+
+  constructor(container: HTMLElement, options: ChartOptions = {}) {
+    this._container = container;
+    this._container.style.position = 'relative';
+    this._container.style.overflow = 'hidden';
+
+    this._options = this._resolveOptions(options);
+    this._colors = this._resolveColors(this._options.theme, this._options.colors);
+
+    const { width, height } = container.getBoundingClientRect();
+    const dpr = window.devicePixelRatio ?? 1;
+
+    this._gridLayer = new CanvasLayer(container, { width, height, dpr, zIndex: 1 });
+    this._seriesLayer = new CanvasLayer(container, { width, height, dpr, zIndex: 2 });
+    this._overlayLayer = new CanvasLayer(container, { width, height, dpr, zIndex: 3 });
+
+    this._timeScale = new TimeScale(this._gridLayer, this._colors, this._options.timeScale);
+    this._priceScale = new PriceScale(this._gridLayer, this._colors, this._options.priceScale);
+
+    // CoordTransform is the single source of truth for all pixel ↔ data conversions.
+    // Created after the scales so it can hold live references to them.
+    this._transform = new CoordTransform(
+      this._timeScale,
+      this._priceScale,
+      this._priceScale.width,
+      this._timeScale.height,
+    );
+    this._transform.update(width, height);
+
+    this._crosshair = new Crosshair(this._overlayLayer, this._colors, this._options, this._transform);
+
+    // Propagate initial timezone to time axis and crosshair
+    if (this._options.timezone) {
+      this._timeScale.timezone = this._options.timezone;
+      this._crosshair.timezone = this._options.timezone;
+    }
+    this._drawingMgr = new DrawingManager();
+
+    this._interaction = new InteractionManager(
+      this._overlayLayer.canvas,
+      this._transform,
+      {
+        onPan: (dx, dy) => {
+          this._transform.pan(dx, dy);
+          this._dirty = true;
+          this.onViewportChanged?.();
+        },
+        onZoom: (factor, originX) => {
+          this._transform.zoomTime(factor, originX);
+          this._dirty = true;
+          this.onViewportChanged?.();
+        },
+        onCrosshairMove: (x, y) => {
+          if (!this._crosshairEnabled) return;
+          // Snap the vertical line to the nearest bar's timestamp so it always
+          // sits centred on a candle rather than floating between candles.
+          const { x: snappedX, time: snappedTime } = this._snapXToBar(x);
+          this._crosshair.update(snappedX, y, snappedTime);
+          this._dirty = true;
+        },
+        onCrosshairHide: () => {
+          this._crosshair.hide();
+          this._dirty = true;
+        },
+        onKeyAction: (action) => {
+          this._handleKeyAction(action);
+        },
+        onFitContent: () => {
+          this.scrollToEnd();
+        },
+        onPriceScaleZoom: (factor, originY) => {
+          this._priceScaleManual = true;
+          this._transform.zoomPrice(factor, originY);
+          this._dirty = true;
+        },
+        onPriceAxisDrag: (dy) => {
+          this._priceScaleManual = true;
+          // Exponential factor: drag down (dy > 0) = expand range, up = compress
+          this._transform.zoomPrice(Math.pow(1.005, dy), this._transform.plotHeight / 2);
+          this._dirty = true;
+        },
+        // Drawing tool callbacks
+        onDrawClick: (x, y) => {
+          this._handleDrawClick(x, y);
+        },
+        onDrawPointerMove: (x, y) => {
+          this._drawingCursorPt = {
+            time: this._transform.xToTime(x),
+            price: this._transform.yToPrice(y),
+          };
+          this._dirty = true;
+        },
+        onHandleDragStart: (_id, _hi) => {
+          this._dirty = true;
+        },
+        onHandleDragMove: (id, handleIndex, x, y) => {
+          const drawing = this._drawingMgr.get(id);
+          if (!drawing) return;
+          const snapped = this._snapToBar(x, y);
+          const newPoints = [...drawing.points] as DrawingPoint[];
+          newPoints[handleIndex] = snapped;
+          this._drawingMgr.update(id, { points: newPoints });
+          this._dirty = true;
+        },
+        onHandleDragEnd: (id, _hi) => {
+          const drawing = this._drawingMgr.get(id);
+          if (drawing) this.onDrawingCommitted?.(drawing);
+          this._dirty = true;
+        },
+        onBodyMoveStart: (_id) => {
+          this._dirty = true;
+        },
+        onBodyMoveMove: (id, dx, dy) => {
+          const drawing = this._drawingMgr.get(id);
+          if (!drawing) return;
+          const t = this._transform;
+          const newPoints = drawing.points.map((p): DrawingPoint => ({
+            time:  t.xToTime(t.timeToX(p.time) + dx),
+            price: t.yToPrice(t.priceToY(p.price) + dy),
+          }));
+          this._drawingMgr.update(id, { points: newPoints });
+          this._dirty = true;
+        },
+        onBodyMoveEnd: (id) => {
+          const drawing = this._drawingMgr.get(id);
+          if (drawing) this.onDrawingCommitted?.(drawing);
+          this._dirty = true;
+        },
+        onContextMenu: (x, y, hit) => {
+          // Right-click while a drawing tool is active cancels placement.
+          if (this._drawingTool !== null) {
+            this.cancelDrawingTool();
+            return;
+          }
+          if (hit.kind === 'drawing') {
+            this.onDrawingContextMenu?.(hit.id, x, y);
+          }
+        },
+      },
+      {
+        enablePan:  this._options.handleScroll,
+        enableZoom: this._options.handleScale,
+      },
+    );
+
+    this._resizeObserver = new ResizeObserver(() => this._onResize());
+    this._resizeObserver.observe(container);
+
+    this._scheduleRender();
+  }
+
+  // ─── Public API ──────────────────────────────────────────────────────────────
+
+  addSeries(options: Parameters<IChart['addSeries']>[0]): ISeries {
+    const series = new Series(options, this._colors);
+    // Wire live-tick repaints: whenever series data changes (WS tick calls
+    // series.update()), immediately mark the canvas dirty so the forming bar
+    // and last-price label repaint on the very next RAF frame — not once/second.
+    series.onDataChanged = () => { this._dirty = true; };
+    this._series.push(series);
+    this._dirty = true;
+    return series;
+  }
+
+  removeSeries(series: ISeries): void {
+    this._series = this._series.filter((s) => s !== series);
+    this._dirty = true;
+  }
+
+  addPlugin(plugin: IChartPlugin): void {
+    this._plugins.push(plugin);
+    plugin.onAttach(this);
+  }
+
+  removePlugin(plugin: IChartPlugin): void {
+    this._plugins = this._plugins.filter((p) => p !== plugin);
+    plugin.onDetach();
+  }
+
+  /** Set the active timeframe so the last-price countdown is accurate. */
+  setInterval(tf: Timeframe): void {
+    this._interval = tf;
+    this._crosshair.interval = tf;
+    this._timeScale.setTimeframe(tf);
+    this._dirty = true;
+  }
+
+  timeScale(): TimeScale {
+    return this._timeScale;
+  }
+
+  priceScale(): PriceScale {
+    return this._priceScale;
+  }
+
+  applyOptions(options: Partial<ChartOptions>): void {
+    Object.assign(this._options as Record<string, unknown>, options);
+    if (options.timezone !== undefined) {
+      this._timeScale.timezone = options.timezone;
+      this._crosshair.timezone = options.timezone;
+    }
+    if (options.colors !== undefined || options.theme !== undefined) {
+      const fresh = this._resolveColors(this._options.theme, this._options.colors);
+      Object.assign(this._colors as Record<string, unknown>, fresh);
+    }
+    this._dirty = true;
+  }
+
+  /** Pans the viewport so the latest bar is visible at the right edge. */
+  scrollToEnd(): void {
+    this._scrollToLatestBar();
+    this._dirty = true;
+  }
+
+  /** Returns the coordinate transform for this chart. */
+  transform(): CoordTransform {
+    return this._transform;
+  }
+
+  resize(width: number, height: number): void {
+    const dpr = window.devicePixelRatio ?? 1;
+    this._gridLayer.resize(width, height, dpr);
+    this._seriesLayer.resize(width, height, dpr);
+    this._overlayLayer.resize(width, height, dpr);
+    this._transform.update(width, height);
+    // Repaint synchronously so the canvas is never left blank between the
+    // clear (caused by assigning canvas.width/height) and the next RAF tick.
+    this._dirty = true;
+    this._render();
+  }
+
+  destroy(): void {
+    if (this._animationFrame !== null) cancelAnimationFrame(this._animationFrame);
+    this._resizeObserver.disconnect();
+    this._interaction.destroy();
+    this._gridLayer.destroy();
+    this._seriesLayer.destroy();
+    this._overlayLayer.destroy();
+    this._crosshair.destroy();
+    this._plugins.forEach((p) => p.onDetach());
+    this._series = [];
+    this._plugins = [];
+  }
+
+  // ─── Rendering ───────────────────────────────────────────────────────────────
+
+  private _scheduleRender(): void {
+    this._animationFrame = requestAnimationFrame(() => {
+      // Tick the countdown once per second so the label stays current.
+      const nowSec = Math.floor(Date.now() / 1000);
+      if (this._series.length > 0 && nowSec !== this._lastCountdownSec) {
+        this._lastCountdownSec = nowSec;
+        this._dirty = true;
+      }
+      this._render();
+      this._scheduleRender();
+    });
+  }
+
+  private _render(): void {
+    if (!this._dirty) return;
+    this._dirty = false;
+
+    // Auto-fit the price scale to the currently visible bars every frame.
+    // This keeps the candles in view after panning/zooming the time axis.
+    this._autoFitPriceToData();
+
+    this._renderGrid();
+    this._renderSeries();
+    this._renderOverlay();
+
+    this._plugins.forEach((p) => p.onRender());
+  }
+
+  private _renderGrid(): void {
+    const ctx = this._gridLayer.context;
+    const { width, height } = this._gridLayer;
+    ctx.clearRect(0, 0, width, height);
+
+    // Background
+    ctx.fillStyle = this._colors.background;
+    ctx.fillRect(0, 0, width, height);
+
+    this._timeScale.render(ctx, width, height);
+    this._priceScale.render(ctx, width, height);
+  }
+
+  setAllDrawingsVisible(v: boolean): void {
+    for (const d of this._drawingMgr.all()) {
+      this._drawingMgr.update(d.id, { visible: v });
+    }
+    this._dirty = true;
+  }
+
+  setIndicatorsVisible(v: boolean): void {
+    this._indicatorsVisible = v;
+    this._dirty = true;
+  }
+
+  private _renderSeries(): void {
+    const ctx = this._seriesLayer.context;
+    const { width, height } = this._seriesLayer;
+    ctx.clearRect(0, 0, width, height);
+
+    if (!this._indicatorsVisible) return;
+
+    const viewport = this._computeViewport();
+    for (const series of this._series) {
+      series.render(ctx, viewport, { x: 0, y: 0, width, height });
+    }
+  }
+
+  private _renderOverlay(): void {
+    const ctx = this._overlayLayer.context;
+    const { width, height } = this._overlayLayer;
+    ctx.clearRect(0, 0, width, height);
+
+    // Committed drawings
+    const selectedId = this._interaction.selectedDrawingId;
+    const candles = this._series[0]?.data() ?? [];
+    this._drawingMgr.render(ctx, this._transform, selectedId, this._interval, candles);
+    this._interaction.setDrawings(this._drawingMgr.all());
+
+    // In-progress placement preview
+    if (this._drawingTool !== null && this._drawingCursorPt !== null) {
+      const draft = this._buildDraftPreview();
+      if (draft) this._drawingMgr.renderPreview(ctx, this._transform, draft, this._interval, candles);
+    }
+
+    // Last-price dotted line + countdown
+    this._renderLastPriceLine(ctx);
+
+    this._crosshair.render(ctx, width, height);
+  }
+
+  // ─── Private helpers ─────────────────────────────────────────────────────────
+
+  /**
+   * Snaps a pixel X coordinate to the nearest bar's centre pixel.
+   * If no bars are loaded, or the nearest bar is more than SNAP_PX pixels away,
+   * returns the original x so the crosshair always renders at the cursor position.
+   */
+  private _snapXToBar(x: number): { x: number; time: number } {
+    const SNAP_PX = 20; // only snap when within this many pixels of a bar
+
+    // Collect all bar timestamps from the first series that has data.
+    let times: number[] | null = null;
+    for (const s of this._series) {
+      const data = s.data();
+      if (data.length > 0) {
+        times = data.map((b) => b.time);
+        break;
+      }
+    }
+    if (!times || times.length === 0) return { x, time: this._transform.xToTime(x) };
+
+    // Find the nearest bar in pixel space (not time space) so the snap radius is
+    // consistent regardless of timeframe or zoom level.
+    let nearestTime = times[0]!;
+    let minPixDist = Math.abs(this._transform.timeToX(nearestTime) - x);
+    for (let i = 1; i < times.length; i++) {
+      const px = this._transform.timeToX(times[i]!);
+      const d  = Math.abs(px - x);
+      if (d < minPixDist) { minPixDist = d; nearestTime = times[i]!; }
+    }
+
+    // If the nearest bar is within SNAP_PX, snap to it; otherwise keep raw cursor x.
+    if (minPixDist <= SNAP_PX) {
+      return { x: this._transform.timeToX(nearestTime), time: nearestTime };
+    }
+    return { x, time: this._transform.xToTime(x) };
+  }
+
+  private _computeViewport() {
+    return {
+      timeRange: this._timeScale.visibleRange,
+      priceRange: this._priceScale.visibleRange,
+    };
+  }
+
+  private _onResize(): void {
+    const { width, height } = this._container.getBoundingClientRect();
+    this.resize(width, height);
+  }
+
+  private _handleKeyAction(action: ChartKeyAction): void {
+    const step = 40;
+    const zf   = 1.1;
+    const cx   = this._transform.plotWidth / 2;
+
+    switch (action) {
+      case 'panLeft':  this._transform.pan( step, 0); break;
+      case 'panRight': this._transform.pan(-step, 0); break;
+      case 'panUp':    this._transform.pan(0,  step); break;
+      case 'panDown':  this._transform.pan(0, -step); break;
+      case 'zoomIn':   this._transform.zoomTime(1 / zf, cx); break;
+      case 'zoomOut':  this._transform.zoomTime(zf,     cx); break;
+      case 'scrollToEnd':   this._scrollToLatestBar(); break;
+      case 'scrollToStart': break;
+      case 'deselect':
+        if (this._drawingTool !== null) {
+          this.cancelDrawingTool();
+        } else {
+          this._interaction.clearSelection();
+        }
+        break;
+      case 'deleteSelection':
+        this.deleteSelectedDrawing();
+        break;
+    }
+    this._dirty = true;
+  }
+
+  /**
+   * Fits the price scale to the high/low range of bars visible in the current
+   * time window. Called every render frame so the scale tracks panning/zooming.
+   */
+  private _autoFitPriceToData(): void {
+    if (this._priceScaleManual) return;
+    const { from, to } = this._timeScale.visibleRange;
+    let low = Infinity, high = -Infinity;
+    for (const series of this._series) {
+      for (const bar of series.data()) {
+        if (bar.time < from || bar.time > to) continue;
+        if (bar.low  < low)  low  = bar.low;
+        if (bar.high > high) high = bar.high;
+      }
+    }
+    if (!isFinite(low) || !isFinite(high)) return;
+    const pad = (high - low) * 0.05;
+    this._priceScale.setVisibleRange({ min: low - pad, max: high + pad });
+  }
+
+  /**
+   * Renders the last-price dotted line, price label, and countdown timer.
+   * Drawn on the overlay canvas above all series but below the crosshair.
+   */
+  private _renderLastPriceLine(ctx: CanvasRenderingContext2D): void {
+    if (this._series.length === 0) return;
+    const data = this._series[0]!.data();
+    if (data.length === 0) return;
+    const lastBar = data[data.length - 1]!;
+
+    const plotWidth  = this._transform.plotWidth;
+    const plotHeight = this._transform.plotHeight;
+    const psWidth    = this._transform.priceScaleWidth;
+    const price      = lastBar.close;
+    const y          = this._transform.priceToY(price);
+
+    if (y < 0 || y > plotHeight) return;
+
+    const isUp      = lastBar.close >= lastBar.open;
+    const lineColor = isUp ? '#26a641' : '#f85149';
+
+    ctx.save();
+
+    // Dotted horizontal line across the plot area
+    ctx.beginPath();
+    ctx.strokeStyle = lineColor;
+    ctx.lineWidth = 1;
+    ctx.setLineDash([2, 3]);
+    ctx.moveTo(0, y);
+    ctx.lineTo(plotWidth, y);
+    ctx.stroke();
+    ctx.setLineDash([]);
+
+    // Countdown calculation
+    const tfSecs    = _tfToSeconds(this._interval);
+    const now       = Math.floor(Date.now() / 1000);
+    const remaining = lastBar.time + tfSecs - now;
+    const showCd    = remaining > 0 && remaining <= tfSecs;
+
+    // Label box — taller when countdown is shown
+    const priceLabel = _formatLastPrice(price);
+    const lineH = 15;
+    const boxH  = showCd ? lineH * 2 + 1 : lineH;
+    const boxY  = y - lineH / 2;
+
+    ctx.fillStyle = lineColor;
+    ctx.fillRect(plotWidth, boxY, psWidth, boxH);
+
+    ctx.fillStyle = '#ffffff';
+    ctx.textAlign = 'left';
+    ctx.textBaseline = 'middle';
+    ctx.font = 'bold 11px system-ui, sans-serif';
+    ctx.fillText(priceLabel, plotWidth + 5, boxY + lineH / 2);
+
+    if (showCd) {
+      ctx.font = '10px system-ui, sans-serif';
+      ctx.fillStyle = 'rgba(255,255,255,0.85)';
+      ctx.fillText(_formatCountdown(remaining), plotWidth + 5, boxY + lineH + 1 + lineH / 2);
+    }
+
+    ctx.restore();
+  }
+
+  /** Pans the viewport so the latest bar sits near the right edge. */
+  private _scrollToLatestBar(): void {
+    let latestTime = -Infinity;
+    for (const s of this._series) {
+      const data = s.data();
+      const last = data[data.length - 1];
+      if (last && last.time > latestTime) latestTime = last.time;
+    }
+    if (!isFinite(latestTime)) return;
+    const pad = this._transform.plotWidth * 0.05;
+    const px  = this._transform.timeToX(latestTime);
+    this._transform.pan(-(px - (this._transform.plotWidth - pad)), 0);
+  }
+
+  /**
+   * Returns the current visible time and price ranges.
+   */
+  getViewport(): import('@forgecharts/types').Viewport {
+    return {
+      timeRange:  this._timeScale.visibleRange,
+      priceRange: this._priceScale.visibleRange,
+    };
+  }
+
+  /**
+   * Restores a previously saved viewport (time range + manual price range).
+   */
+  restoreViewport(v: import('@forgecharts/types').Viewport): void {
+    this._timeScale.setVisibleRange(v.timeRange);
+    this._priceScale.setVisibleRange(v.priceRange);
+    this._priceScaleManual = true;
+    this._dirty = true;
+  }
+
+  /**
+   * Clears the manual-price-scale flag so the price axis returns to auto-fit mode.
+   * Call this after restoring a saved viewport so stale price ranges don't persist.
+   */
+  resetPriceScale(): void {
+    this._priceScaleManual = false;
+    this._dirty = true;
+  }
+
+  /**
+   * Sets the default viewport: shows 10 days of price history with the latest
+   * bar positioned near the right edge (5% right margin for breathing room).
+   * Also resets the price scale to auto-fit so prices center vertically.
+   * Called on initial data load and when the user double-clicks either axis.
+   */
+  fitDefaultView(): void {
+    let latestTime = -Infinity;
+    for (const s of this._series) {
+      const data = s.data();
+      const last = data[data.length - 1];
+      if (last && last.time > latestTime) latestTime = last.time;
+    }
+    if (!isFinite(latestTime)) return;
+    // Show ~150 candles worth of history, scaled to the current timeframe.
+    // Latest bar sits at the 90% position (10% breathing room on the right).
+    const tfSec = _tfToSeconds(this._interval);
+    const WINDOW = tfSec * 150;
+    this._timeScale.setVisibleRange({
+      from: latestTime - WINDOW * 0.9,
+      to:   latestTime + WINDOW * 0.1,
+    });
+    // Reset manual price scale so prices auto-fit to visible bars
+    this._priceScaleManual = false;
+    this._dirty = true;
+  }
+
+  // ─── Drawing tool API ──────────────────────────────────────────────────────
+
+  /** Returns the DrawingManager owned by this chart. */
+  drawingManager(): DrawingManager {
+    return this._drawingMgr;
+  }
+
+  /** Force a redraw on the next animation frame. */
+  markDirty(): void {
+    this._dirty = true;
+  }
+
+  /**
+   * Activates a drawing tool. While active, mouse clicks place anchors.
+   * The tool auto-cancels after each commit. Press Escape to cancel mid-placement.
+   */
+  startDrawingTool(type: DrawingType): void {
+    this._drawingTool  = type;
+    this._drawingState = 'idle';
+    this._drawingP0    = null;
+    this._drawingP1    = null;
+    this._drawingCursorPt = null;
+    this._interaction.setDrawingMode(true);
+    this._dirty = true;
+  }
+
+  /** Cancels any in-progress drawing and returns to cursor mode. */
+  cancelDrawingTool(): void {
+    this._drawingTool  = null;
+    this._drawingState = 'idle';
+    this._drawingP0    = null;
+    this._drawingP1    = null;
+    this._drawingCursorPt = null;
+    this._interaction.setDrawingMode(false);
+    this._dirty = true;
+  }
+
+  /**
+   * Show or hide the interactive crosshair lines.
+   * Pass `false` for Arrow/cursor mode; `true` for crosshair / dot / demonstration.
+   */
+  setCrosshairEnabled(enabled: boolean): void {
+    this._crosshairEnabled = enabled;
+    this._interaction.setHideCursor(enabled);
+    if (!enabled) {
+      this._crosshair.hide();
+      this._dirty = true;
+    }
+  }
+
+  /**
+   * Hides (`true`) or restores (`false`) the native OS cursor.
+   * Call with `true` for dot and demonstration pointer modes whose visuals
+   * come from PointerOverlay rather than the SDK crosshair.
+   */
+  setNativeCursorHidden(hidden: boolean): void {
+    this._interaction.setHideCursor(hidden);
+  }
+
+  /** Deletes the currently selected drawing (if any). */
+  deleteSelectedDrawing(): void {
+    const id = this._interaction.selectedDrawingId;
+    if (!id) return;
+    this._drawingMgr.remove(id);
+    this._interaction.clearSelection();
+    this.onDrawingDeleted?.(id);
+    this._dirty = true;
+  }
+
+  // ─── Drawing placement state machine ──────────────────────────────────────
+
+  private _handleDrawClick(x: number, y: number): void {
+    const tool = this._drawingTool;
+    if (!tool) return;
+
+    const snapped = this._snapToBar(x, y);
+
+    const isSingleAnchor =
+      tool === 'horizontal' || tool === 'vertical' || tool === 'text' ||
+      tool === 'horizontalRay' || tool === 'crossLine';
+
+    if (isSingleAnchor) {
+      let label: string | undefined;
+      if (tool === 'text') {
+        const input = window.prompt('Enter text:');
+        if (input === null) return; // cancelled
+        label = input || 'Text';
+      }
+      const id = this._drawingMgr.add({
+        type: tool,
+        points: [snapped],
+        color: this._colors.crosshair,
+        ...(label !== undefined ? { text: label } : {}),
+      });
+      const drawing = this._drawingMgr.get(id)!;
+      this.onDrawingCommitted?.(drawing);
+      this.cancelDrawingTool();
+      return;
+    }
+
+    const isThreeAnchor =
+      tool === 'parallelChannel' || tool === 'flatTopBottom' ||
+      tool === 'pitchfork' || tool === 'schiffPitchfork' ||
+      tool === 'modifiedSchiffPitchfork' || tool === 'insidePitchfork';
+
+    if (isThreeAnchor) {
+      if (this._drawingState === 'idle') {
+        this._drawingP0    = snapped;
+        this._drawingState = 'placing_second';
+        this._dirty = true;
+      } else if (this._drawingState === 'placing_second') {
+        this._drawingP1    = snapped;
+        this._drawingState = 'placing_third';
+        this._dirty = true;
+      } else {
+        // For parallel channel, only the cursor's Y/price matters for the offset;
+        // lock p2.time to p1.time so the handle sits at the channel corner.
+        const p2: DrawingPoint = tool === 'parallelChannel'
+          ? { time: this._drawingP1!.time, price: snapped.price }
+          : snapped;
+        const id = this._drawingMgr.add({
+          type: tool,
+          points: [this._drawingP0!, this._drawingP1!, p2],
+          color: this._colors.crosshair,
+        });
+        const drawing = this._drawingMgr.get(id)!;
+        this.onDrawingCommitted?.(drawing);
+        this.cancelDrawingTool();
+      }
+      return;
+    }
+
+    // Two-anchor tools
+    if (this._drawingState === 'idle') {
+      this._drawingP0    = snapped;
+      this._drawingState = 'placing_second';
+      this._dirty = true;
+    } else {
+      const p0 = this._drawingP0!;
+
+      if (tool === 'disjointChannel') {
+        // Auto-place the second line below the first by a default pixel offset.
+        // This gives an immediate wedge shape the user can then drag to reshape.
+        const DEFAULT_OFFSET_PX = 60;
+        const p2: DrawingPoint = {
+          time: p0.time,
+          price: this._transform.yToPrice(this._transform.priceToY(p0.price) + DEFAULT_OFFSET_PX),
+        };
+        const p3: DrawingPoint = {
+          time: snapped.time,
+          price: this._transform.yToPrice(this._transform.priceToY(snapped.price) + DEFAULT_OFFSET_PX),
+        };
+        const id = this._drawingMgr.add({
+          type: tool,
+          points: [p0, snapped, p2, p3],
+          color: this._colors.crosshair,
+        });
+        const drawing = this._drawingMgr.get(id)!;
+        this.onDrawingCommitted?.(drawing);
+        this.cancelDrawingTool();
+      } else {
+        const id = this._drawingMgr.add({ type: tool, points: [p0, snapped], color: this._colors.crosshair });
+        const drawing = this._drawingMgr.get(id)!;
+        this.onDrawingCommitted?.(drawing);
+        this.cancelDrawingTool();
+      }
+    }
+  }
+
+  private _buildDraftPreview(): Omit<Drawing, 'id'> | null {
+    const tool   = this._drawingTool;
+    const cursor = this._drawingCursorPt;
+    if (!tool || !cursor) return null;
+
+    const isSingleAnchor =
+      tool === 'horizontal' || tool === 'vertical' || tool === 'text' ||
+      tool === 'horizontalRay' || tool === 'crossLine';
+
+    if (isSingleAnchor) {
+      return { type: tool, points: [cursor], color: this._colors.crosshair };
+    }
+
+    if (this._drawingState === 'placing_third' && this._drawingP0 && this._drawingP1) {
+      // For parallel channel, lock p2 to p1's time so the cursor tracks the channel corner
+      const p2 = tool === 'parallelChannel'
+        ? { time: this._drawingP1.time, price: cursor.price }
+        : cursor;
+      return { type: tool, points: [this._drawingP0, this._drawingP1, p2], color: this._colors.crosshair };
+    }
+    if (this._drawingState === 'placing_second' && this._drawingP0) {
+      return { type: tool, points: [this._drawingP0, cursor], color: this._colors.crosshair };
+    }
+    if (this._drawingP0 === null) {
+      return { type: tool, points: [cursor], color: this._colors.crosshair };
+    }
+    return null;
+  }
+
+  /**
+   * Snaps the pixel position to the nearest bar's time within SNAP_PX.
+   * Returns a DrawingPoint with the snapped time and the raw price at y.
+   */
+  private _snapToBar(x: number, y: number): DrawingPoint {
+    const SNAP_PX = 10;
+    const t = this._transform;
+    const price = t.yToPrice(y);
+    const time  = t.xToTime(x);
+
+    let bestBar: OHLCV | null = null;
+    let bestDist = SNAP_PX;
+
+    for (const series of this._series) {
+      for (const bar of series.data()) {
+        const bx   = t.timeToX(bar.time);
+        const dist = Math.abs(bx - x);
+        if (dist < bestDist) {
+          bestDist = dist;
+          bestBar  = bar;
+        }
+      }
+    }
+
+    return { time: bestBar ? bestBar.time : time, price };
+  }
+
+  private _resolveOptions(opts: ChartOptions): Required<ChartOptions> {
+    return {
+      theme: opts.theme ?? 'dark',
+      colors: opts.colors ?? {},
+      timeScale: opts.timeScale ?? {},
+      priceScale: opts.priceScale ?? {},
+      crosshair: opts.crosshair ?? {},
+      handleScroll: opts.handleScroll ?? true,
+      handleScale: opts.handleScale ?? true,
+      timezone: opts.timezone ?? 'UTC',
+    };
+  }
+
+  private _resolveColors(
+    theme: ChartTheme,
+    overrides: Partial<import('@forgecharts/types').ChartColors>,
+  ): ChartColors {
+    const base = theme === 'dark' ? DARK_COLORS : LIGHT_COLORS;
+    return { ...base, ...overrides };
+  }
+}