@forgecharts/sdk 1.1.23

package/src/api/createChart.ts

@@ -0,0 +1,43 @@
+import type { ChartConfig } from '@forgecharts/types';
+import { TChart } from './TChart';
+
+/**
+ * Creates a new ForgeCharts chart instance and mounts it into the provided container.
+ *
+ * This is the primary entry point for the ForgeCharts SDK. The returned `TChart`
+ * instance exposes the full public API — including data loading hooks, indicators,
+ * drawings, layout persistence, and the typed event bus.
+ *
+ * @param config - Chart configuration. `container` and `symbol` are required.
+ * @returns A fully initialised `TChart` instance.
+ *
+ * @example
+ * ```ts
+ * import { createChart } from '@forgecharts/sdk';
+ *
+ * const chart = createChart({
+ *   container: document.getElementById('chart')!,
+ *   symbol: 'BTCUSDT',
+ *   interval: '5m',
+ *   theme: 'dark',
+ * });
+ *
+ * chart.on('symbolChanged', ({ symbol }) => {
+ *   document.title = symbol;
+ * });
+ *
+ * chart.addIndicator({ type: 'ema', params: { period: 20 }, overlay: true });
+ *
+ * const layout = chart.saveLayout();
+ * localStorage.setItem('layout', JSON.stringify(layout));
+ *
+ * // Later...
+ * chart.destroy();
+ * ```
+ */
+export function createChart(config: ChartConfig): TChart {
+  if (!config.container) {
+    throw new Error('[ForgeCharts] createChart() requires a valid container element.');
+  }
+  return new TChart(config);
+}

package/src/api/drawing tools/fib gann menu/fibRetracement.ts

@@ -0,0 +1,27 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderFibRetracement(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+  const priceHigh = Math.max(p0.price, p1.price);
+  const priceLow  = Math.min(p0.price, p1.price);
+  const span = priceHigh - priceLow;
+  const x0 = Math.min(t.timeToX(p0.time), t.timeToX(p1.time));
+  const x1 = Math.max(t.timeToX(p0.time), t.timeToX(p1.time));
+  ctx.save();
+  for (const ratio of [0, 0.236, 0.382, 0.5, 0.618, 0.786, 1]) {
+    const ly = t.priceToY(priceLow + span * (1 - ratio));
+    ctx.globalAlpha = 0.6;
+    ctx.beginPath();
+    ctx.moveTo(x0, ly);
+    ctx.lineTo(x1, ly);
+    ctx.stroke();
+  }
+  ctx.restore();
+}

package/src/api/drawing tools/lines menu/crossLine.ts

@@ -0,0 +1,21 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderCrossLine(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  if (!p0) return;
+  const x = t.timeToX(p0.time);
+  const y = t.priceToY(p0.price);
+  ctx.beginPath();
+  ctx.moveTo(0, y);
+  ctx.lineTo(t.plotWidth, y);
+  ctx.stroke();
+  ctx.beginPath();
+  ctx.moveTo(x, 0);
+  ctx.lineTo(x, t.plotHeight);
+  ctx.stroke();
+}

package/src/api/drawing tools/lines menu/disjointChannel.ts

@@ -0,0 +1,74 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+// ─── Renderer ─────────────────────────────────────────────────────────────────
+
+/**
+ * Disjoint Channel — two fully independent trend lines forming a channel.
+ *
+ * Anchors (4 points):
+ *   p0 — left  endpoint of line 1  (top-left)
+ *   p1 — right endpoint of line 1  (top-right)
+ *   p2 — left  endpoint of line 2  (bottom-left)
+ *   p3 — right endpoint of line 2  (bottom-right)
+ *
+ * The tool places p2/p3 automatically when p0→p1 is drawn (offset downward).
+ * The user can then drag any of the 4 handles to reshape freely — including
+ * crossing the lines to create a bowtie / expanding wedge shape.
+ */
+export function renderDisjointChannel(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+
+  const x0 = t.timeToX(p0.time), y0 = t.priceToY(p0.price);
+  const x1 = t.timeToX(p1.time), y1 = t.priceToY(p1.price);
+
+  const p2 = d.points[2];
+  const p3 = d.points[3];
+
+  // During drawing (only 2 points placed yet) — show just the first segment
+  if (!p2 || !p3) {
+    ctx.beginPath();
+    ctx.moveTo(x0, y0);
+    ctx.lineTo(x1, y1);
+    ctx.stroke();
+    return;
+  }
+
+  const x2 = t.timeToX(p2.time), y2 = t.priceToY(p2.price);
+  const x3 = t.timeToX(p3.time), y3 = t.priceToY(p3.price);
+
+  const color = d.color ?? '#2196f3';
+  ctx.strokeStyle = color;
+
+  // Fill the quadrilateral first (behind the lines)
+  ctx.save();
+  ctx.globalAlpha = 0.07;
+  ctx.fillStyle = color;
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x1, y1);
+  ctx.lineTo(x3, y3);
+  ctx.lineTo(x2, y2);
+  ctx.closePath();
+  ctx.fill();
+  ctx.restore();
+
+  // Line 1: p0 → p1
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x1, y1);
+  ctx.stroke();
+
+  // Line 2: p2 → p3
+  ctx.beginPath();
+  ctx.moveTo(x2, y2);
+  ctx.lineTo(x3, y3);
+  ctx.stroke();
+}
+

package/src/api/drawing tools/lines menu/extendedLine.ts

@@ -0,0 +1,22 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+import { rayExit } from '../../drawingUtils';
+
+export function renderExtendedLine(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+  const x0 = t.timeToX(p0.time), y0 = t.priceToY(p0.price);
+  const x1 = t.timeToX(p1.time), y1 = t.priceToY(p1.price);
+  const dx = x1 - x0, dy = y1 - y0;
+  const exitFwd  = rayExit(t.plotWidth, t.plotHeight, x1, y1,  dx,  dy);
+  const exitBack = rayExit(t.plotWidth, t.plotHeight, x0, y0, -dx, -dy);
+  ctx.beginPath();
+  ctx.moveTo(exitBack.x, exitBack.y);
+  ctx.lineTo(exitFwd.x, exitFwd.y);
+  ctx.stroke();
+}

package/src/api/drawing tools/lines menu/flatTopBottom.ts

@@ -0,0 +1,45 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderFlatTopBottom(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+  const x0 = t.timeToX(p0.time), y0 = t.priceToY(p0.price);
+  const x1 = t.timeToX(p1.time), y1 = t.priceToY(p1.price);
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x1, y1);
+  ctx.stroke();
+  const p2 = d.points[2];
+  if (!p2) return;
+  const yFlat = t.priceToY(p2.price);
+  ctx.beginPath();
+  ctx.moveTo(x0, yFlat);
+  ctx.lineTo(x1, yFlat);
+  ctx.stroke();
+  ctx.save();
+  ctx.globalAlpha = 0.35;
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x0, yFlat);
+  ctx.stroke();
+  ctx.beginPath();
+  ctx.moveTo(x1, y1);
+  ctx.lineTo(x1, yFlat);
+  ctx.stroke();
+  ctx.globalAlpha = 0.07;
+  ctx.fillStyle = d.color ?? '#2196f3';
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x1, y1);
+  ctx.lineTo(x1, yFlat);
+  ctx.lineTo(x0, yFlat);
+  ctx.closePath();
+  ctx.fill();
+  ctx.restore();
+}

package/src/api/drawing tools/lines menu/horizontal.ts

@@ -0,0 +1,24 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderHorizontal(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  if (!p0) return;
+  const y = t.priceToY(p0.price);
+  ctx.beginPath();
+  ctx.moveTo(0, y);
+  ctx.lineTo(t.plotWidth, y);
+  ctx.stroke();
+  // Price label
+  ctx.save();
+  ctx.font = '10px -apple-system, sans-serif';
+  ctx.fillStyle = d.color ?? '#2196f3';
+  ctx.textAlign = 'left';
+  ctx.textBaseline = 'middle';
+  ctx.fillText(p0.price.toFixed(2), t.plotWidth + 4, y);
+  ctx.restore();
+}

package/src/api/drawing tools/lines menu/horizontalRay.ts

@@ -0,0 +1,25 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderHorizontalRay(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  if (!p0) return;
+  const x0 = t.timeToX(p0.time);
+  const y   = t.priceToY(p0.price);
+  ctx.beginPath();
+  ctx.moveTo(x0, y);
+  ctx.lineTo(t.plotWidth, y);
+  ctx.stroke();
+  // Price label
+  ctx.save();
+  ctx.font = '10px -apple-system, sans-serif';
+  ctx.fillStyle = d.color ?? '#2196f3';
+  ctx.textAlign = 'left';
+  ctx.textBaseline = 'middle';
+  ctx.fillText(p0.price.toFixed(2), t.plotWidth + 4, y);
+  ctx.restore();
+}

package/src/api/drawing tools/lines menu/infoLine.ts

@@ -0,0 +1,127 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+import { TF_SECS, formatDuration } from '../../drawingUtils';
+
+export function renderInfoLine(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+  interval = '1h',
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+
+  const x0 = t.timeToX(p0.time), y0 = t.priceToY(p0.price);
+  const x1 = t.timeToX(p1.time), y1 = t.priceToY(p1.price);
+  const dx = x1 - x0;
+  const dy = y1 - y0;
+  const len = Math.sqrt(dx * dx + dy * dy) || 1;
+  const ux = dx / len;
+  const uy = dy / len;
+
+  const color = d.color ?? '#2196f3';
+  ctx.strokeStyle = color;
+  ctx.fillStyle   = color;
+
+  // ── Line segment from p0 to p1 ────────────────────────────────────────────
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x1, y1);
+  ctx.stroke();
+
+  // ── Stats banner ─────────────────────────────────────────────────────────
+  const priceDiff = p1.price - p0.price;
+  const pctChange = p0.price !== 0 ? (priceDiff / p0.price) * 100 : 0;
+  const timeDiff  = Math.abs(p1.time - p0.time);
+  const tfSecs    = TF_SECS[interval] ?? 3600;
+  const bars      = Math.round(timeDiff / tfSecs);
+  const duration  = formatDuration(timeDiff);
+  const pixDist   = Math.round(len);
+  const angleRad  = Math.atan2(-(y1 - y0), x1 - x0);
+  const angleDeg  = (angleRad * 180 / Math.PI).toFixed(2);
+  const sign      = priceDiff >= 0 ? '+' : '';
+  const decimals  = p0.price < 1 ? 6 : 2;
+  const priceStr  = `${sign}${priceDiff.toFixed(decimals)} (${sign}${pctChange.toFixed(2)}%)`;
+  const barsStr   = `\u2194 ${bars} bars (${duration}), distance: ${pixDist} px`;
+  const angleStr  = `\u25b3 ${angleDeg}\u00b0`;
+  const labels    = [priceStr, barsStr, angleStr];
+  const icons     = ['\u21d5', '', ''];
+
+  const PAD_X    = 8;
+  const PAD_Y    = 6;
+  const LINE_H   = 16;
+  const BANNER_W = 240;
+  const BANNER_H = PAD_Y * 2 + labels.length * LINE_H;
+
+  // Place banner perpendicular to the line, offset from the midpoint
+  const midX = (x0 + x1) / 2;
+  const midY = (y0 + y1) / 2;
+  // Perpendicular unit vector (rotated 90° counter-clockwise)
+  const px = -uy;
+  const py =  ux;
+  const OFFSET = BANNER_H / 2 + 12; // enough to clear the line
+
+  // Try offset in the "up" perpendicular direction first
+  let bx = midX + px * OFFSET - BANNER_W / 2;
+  let by = midY + py * OFFSET - BANNER_H / 2;
+
+  // If that clips vertically, flip to the other side
+  if (by < 2 || by + BANNER_H > t.plotHeight - 2) {
+    bx = midX - px * OFFSET - BANNER_W / 2;
+    by = midY - py * OFFSET - BANNER_H / 2;
+  }
+
+  // Clamp to plot area
+  bx = Math.max(2, Math.min(bx, t.plotWidth  - BANNER_W - 2));
+  by = Math.max(2, Math.min(by, t.plotHeight - BANNER_H - 2));
+
+  ctx.save();
+
+  const hex = color.replace('#', '');
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+
+  // Background
+  ctx.fillStyle = `rgba(${r},${g},${b},0.12)`;
+  ctx.beginPath();
+  const radius = 4;
+  ctx.moveTo(bx + radius, by);
+  ctx.lineTo(bx + BANNER_W - radius, by);
+  ctx.arcTo(bx + BANNER_W, by,             bx + BANNER_W, by + radius,           radius);
+  ctx.lineTo(bx + BANNER_W, by + BANNER_H - radius);
+  ctx.arcTo(bx + BANNER_W, by + BANNER_H,  bx + BANNER_W - radius, by + BANNER_H, radius);
+  ctx.lineTo(bx + radius,  by + BANNER_H);
+  ctx.arcTo(bx,            by + BANNER_H,  bx, by + BANNER_H - radius,            radius);
+  ctx.lineTo(bx,           by + radius);
+  ctx.arcTo(bx,            by,             bx + radius, by,                        radius);
+  ctx.closePath();
+  ctx.fill();
+
+  // Border
+  ctx.strokeStyle = `rgba(${r},${g},${b},0.5)`;
+  ctx.lineWidth = 1;
+  ctx.setLineDash([]);
+  ctx.stroke();
+
+  // Text rows
+  const FONT = '11px -apple-system, BlinkMacSystemFont, sans-serif';
+  ctx.font       = FONT;
+  ctx.textAlign  = 'left';
+  ctx.textBaseline = 'top';
+  labels.forEach((line, i) => {
+    const ty = by + PAD_Y + i * LINE_H;
+    if (icons[i]) {
+      ctx.fillStyle = `rgba(${r},${g},${b},0.7)`;
+      ctx.fillText(icons[i], bx + PAD_X, ty + 1);
+      ctx.fillStyle = color;
+      ctx.fillText(line, bx + PAD_X + 14, ty + 1);
+    } else {
+      ctx.fillStyle = color;
+      ctx.fillText(line, bx + PAD_X, ty + 1);
+    }
+  });
+
+  ctx.restore();
+}

package/src/api/drawing tools/lines menu/insidePitchfork.ts

@@ -0,0 +1,21 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+import { getPF3 } from '../../drawingUtils';
+import { renderTrendline } from './trendline';
+
+export function renderInsidePitchfork(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const pf = getPF3(d, t);
+  if (!pf) { renderTrendline(ctx, d, t); return; }
+  const { x0, y0, x1, y1, x2, y2 } = pf;
+  const midX = (x1 + x2) / 2, midY = (y1 + y2) / 2;
+  ctx.beginPath(); ctx.moveTo(x0, y0); ctx.lineTo(midX, midY); ctx.stroke();
+  ctx.beginPath(); ctx.moveTo(x0, y0); ctx.lineTo(x1, y1); ctx.stroke();
+  ctx.beginPath(); ctx.moveTo(x0, y0); ctx.lineTo(x2, y2); ctx.stroke();
+  ctx.save(); ctx.globalAlpha = 0.4;
+  ctx.beginPath(); ctx.moveTo(x1, y1); ctx.lineTo(x2, y2); ctx.stroke();
+  ctx.restore();
+}

package/src/api/drawing tools/lines menu/modifiedSchiffPitchfork.ts

@@ -0,0 +1,18 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+import { getPF3, drawPitchforkLines } from '../../drawingUtils';
+import { renderTrendline } from './trendline';
+
+export function renderModifiedSchiffPitchfork(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const pf = getPF3(d, t);
+  if (!pf) { renderTrendline(ctx, d, t); return; }
+  const { x0, y0, x1, y1, x2, y2 } = pf;
+  const midX = (x1 + x2) / 2, midY = (y1 + y2) / 2;
+  const pivX = (x0 + x1) / 2;
+  const pivY = (y0 + y1) / 2;
+  drawPitchforkLines(ctx, t, pivX, pivY, midX, midY, x1, y1, x2, y2);
+}

package/src/api/drawing tools/lines menu/parallelChannel.ts

@@ -0,0 +1,47 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderParallelChannel(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+  const x0 = t.timeToX(p0.time), y0 = t.priceToY(p0.price);
+  const x1 = t.timeToX(p1.time), y1 = t.priceToY(p1.price);
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x1, y1);
+  ctx.stroke();
+  const p2 = d.points[2];
+  if (!p2) return;
+  // Offset from y1 so dragging from p1 starts with zero width
+  const off = t.priceToY(p2.price) - y1;
+  // Parallel line
+  ctx.beginPath();
+  ctx.moveTo(x0, y0 + off);
+  ctx.lineTo(x1, y1 + off);
+  ctx.stroke();
+  // Midline (dashed)
+  ctx.save();
+  ctx.globalAlpha = 0.5;
+  ctx.setLineDash([4, 4]);
+  ctx.beginPath();
+  ctx.moveTo(x0, y0 + off / 2);
+  ctx.lineTo(x1, y1 + off / 2);
+  ctx.stroke();
+  ctx.setLineDash([]);
+  // Fill
+  ctx.globalAlpha = 0.07;
+  ctx.fillStyle = d.color ?? '#2196f3';
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x1, y1);
+  ctx.lineTo(x1, y1 + off);
+  ctx.lineTo(x0, y0 + off);
+  ctx.closePath();
+  ctx.fill();
+  ctx.restore();
+}

package/src/api/drawing tools/lines menu/pitchfork.ts

@@ -0,0 +1,15 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+import { getPF3, drawPitchforkLines } from '../../drawingUtils';
+import { renderTrendline } from './trendline';
+
+export function renderPitchfork(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const pf = getPF3(d, t);
+  if (!pf) { renderTrendline(ctx, d, t); return; }
+  const { x0, y0, x1, y1, x2, y2 } = pf;
+  drawPitchforkLines(ctx, t, x0, y0, (x1 + x2) / 2, (y1 + y2) / 2, x1, y1, x2, y2);
+}

package/src/api/drawing tools/lines menu/ray.ts

@@ -0,0 +1,28 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+import { rayExit } from '../../drawingUtils';
+
+export function renderRay(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0) return;
+  const x0 = t.timeToX(p0.time);
+  const y0 = t.priceToY(p0.price);
+  if (!p1) {
+    ctx.beginPath();
+    ctx.arc(x0, y0, 3, 0, Math.PI * 2);
+    ctx.fill();
+    return;
+  }
+  const dx = t.timeToX(p1.time) - x0;
+  const dy = t.priceToY(p1.price) - y0;
+  const exit = rayExit(t.plotWidth, t.plotHeight, x0, y0, dx, dy);
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(exit.x, exit.y);
+  ctx.stroke();
+}