acttrader-charts 1.0.0

package/README.md

@@ -0,0 +1,676 @@
+# @acttrader/stockchart
+
+A performant, zero-dependency stock charting library built on Canvas 2D.
+Dual ESM/CJS output, TypeScript-first.
+
+**Features:** 13 chart series types · 30+ indicators (overlay + sub-pane) · 80+ drawing tools · Trade-From-Chart (TFC) with drag-to-modify levels · Real-time WebSocket streaming · Dark & Light themes · Fully configurable labels for i18n · Fullscreen support
+
+---
+
+## Installation
+
+```bash
+npm install @acttrader/stockchart
+```
+
+---
+
+## Basic Usage
+
+```ts
+import { ChartEngine } from '@acttrader/stockchart';
+
+const chart = new ChartEngine({
+    container: document.getElementById('chart')!,
+    theme:     'dark',
+    series:    'candlestick',
+    symbol:    'XAUUSD',
+    timeframe: '1D',
+    duration:  '1Y',
+});
+
+chart.loadData(ohlcvBars); // OHLCVBar[]
+```
+
+Load OHLCV data and the chart is ready. All UI (top bar, bottom bar, drawing toolbar) is rendered automatically unless `showUI: false`.
+
+### Respond to duration / timeframe changes
+
+```ts
+chart.on('durationChange', ({ duration, timeframe }) => {
+    fetchBars(timeframe, duration).then(bars => chart.loadData(bars));
+});
+```
+
+### Programmatic data loading via `dataLoader`
+
+```ts
+const chart = new ChartEngine({
+    container,
+    dataLoader: async ({ start, end, interval }) => {
+        const res = await fetch(`/api/bars?from=${start.getTime()}&to=${end.getTime()}&tf=${interval}`);
+        return res.json(); // OHLCVBar[]
+    },
+});
+// No manual loadData() needed — the engine calls dataLoader on start and on timeframe/duration changes.
+```
+
+---
+
+## Advanced Usage
+
+### Adding Indicators
+
+```ts
+import { SMA, EMA, RSI } from '@acttrader/stockchart';
+
+chart.addIndicator(new SMA(20, '#f59e0b'));      // overlay
+chart.addIndicator(new RSI(14, '#818cf8'));      // sub-pane
+chart.removeIndicator('SMA');
+```
+
+Indicator pills appear inline above the chart (up to 2 visible; beyond that collapses into a dropdown).
+
+### Drawing Tools
+
+```ts
+chart.setDrawingTool('trendLine');   // activate
+chart.setDrawingTool(null);          // back to pointer mode
+```
+
+Keyboard shortcuts: `Escape` cancel / deselect · `Delete`/`Backspace` remove selected · `Ctrl+Z` undo · `Ctrl+Y` redo
+
+### Real-time Streaming
+
+```ts
+import { WebSocketAdapter } from '@acttrader/stockchart';
+
+const adapter = new WebSocketAdapter(
+    'wss://feed.example.com/ticks',
+    (msg) => ({ time: msg.t, bid: msg.p, ask: msg.p, volume: msg.v }),
+);
+
+chart.connectStream(adapter);
+// chart.disconnectStream();
+```
+
+Auto-reconnects with exponential backoff (2 s → 30 s). Stream status is reflected in the top-bar dot and emitted via `streamStatus`.
+
+To push ticks directly without an adapter (e.g. from your own WebSocket handler):
+
+```ts
+chart.pushTick({ time: Date.now(), bid: 1.2055, ask: 1.2057, volume: 120 });
+```
+
+### Trade From Chart (TFC) — `setLevels`
+
+TFC renders draggable price levels for open positions and pending orders.
+The library is broker-agnostic: it draws the lines and emits typed events after the user confirms; your app owns the API calls.
+
+**Pending order** (dashed line, draggable with optional SL/TP brackets):
+
+```ts
+chart.setLevels(
+    [{
+        label:           'ORD-1',
+        price:           1.2050,
+        side:            'buy',
+        orderType:       'limit',
+        lots:            1.0,
+        stopLossPrice:   1.1980,
+        takeProfitPrice: 1.2150,
+        text:            'Buy Limit',
+    }],
+    'label',   // unique key field
+    'price',   // price field
+    'pending', // level type
+);
+```
+
+**Open position** (solid line + live P&L + optional SL/TP brackets):
+
+```ts
+chart.setLevels(
+    [{
+        label:           'POS-1',
+        price:           1.2010,
+        pnl:             42.5,
+        pnlText:         '+$42.50',
+        side:            'buy',
+        stopLossPrice:   1.1960,
+        takeProfitPrice: 1.2120,
+    }],
+    'label', 'price', 'position',
+);
+```
+
+**Bracket orders via `ToClose`** — link a separate SL/TP pending order to a parent level:
+
+```ts
+chart.setLevels([
+    { label: 'POS-1',  price: 1.2010, side: 'buy',  type: 'position' },
+    { label: 'ORD-SL', price: 1.1960, side: 'sell', orderType: 'stop', ToClose: 'POS-1' },
+], 'label', 'price', 'pending');
+```
+
+**Remove levels:**
+
+```ts
+chart.removeLevelByLabel('ORD-1');
+chart.setLevels([], 'label', 'price', 'pending'); // clear all of one type
+```
+
+**TFC events:**
+
+```ts
+// Confirmed drag of a pending order entry
+chart.on('tradeLevelEdit', ({ label, type, changes }) => {
+    for (const c of changes) {
+        if (c.field === 'MAIN') myApi.modifyOrder(label, { price: c.newPrice });
+        if (c.field === 'SL')   myApi.modifyOrder(label, { stopLoss: c.newPrice });
+        if (c.field === 'TP')   myApi.modifyOrder(label, { takeProfit: c.newPrice });
+    }
+});
+
+// User clicked × on a level
+chart.on('tradeLevelClose', ({ label, type, action }) => {
+    if (type === 'pending')  myApi.cancelOrder(label);
+    if (type === 'position') myApi.closePosition(label);
+});
+```
+
+**Drag constraints (enforced live):**
+
+| Order side | Stop Loss | Take Profit |
+|---|---|---|
+| `buy`  | must stay ≤ order price | must stay ≥ order price |
+| `sell` | must stay ≥ order price | must stay ≤ order price |
+
+---
+
+## Default Configuration
+
+### `ChartConfig`
+
+| Property | Required | Default | Description |
+|---|:---:|---|---|
+| `container` | ✓ | — | Host `HTMLElement` |
+| `theme` | | `"dark"` | `"dark"` or `"light"` |
+| `series` | | `"candlestick"` | Initial chart type |
+| `showVolume` | | `true` | Show volume overlay |
+| `showUI` | | `true` | Render top / bottom / left bars |
+| `timeframe` | | `"1D"` | Initial timeframe label |
+| `duration` | | — | Initial active duration button |
+| `symbol` | | — | Symbol name shown in the top bar |
+| `padding` | | `{top:8,right:0,bottom:0,left:0}` | Canvas padding (px) |
+| `minLots` | | `1` | Default lot size in the trade popover |
+| `tickActivityMs` | | `30000` | ms the stream dot stays green after last tick |
+| `maxCandles` | | `200` | Max bars fetched per data-load request |
+| `durationTimeframeMap` | | *(see below)* | Override duration → timeframe pairings |
+| `dataLoader` | | — | `(params) => Promise<OHLCVBar[]>` auto-called on load / change |
+| `uiConfig` | | `DEFAULT_UI_CONFIG` | Deep-partial size / font overrides per component |
+| `labels` | | `DEFAULT_LABELS` | Deep-partial string overrides for i18n/translation |
+| `onOrderSubmit` | | — | Called when user submits a trade via the floating button |
+| `onLevelEdit` | | — | Called when user confirms a TFC level edit |
+| `onLevelDragEnd` | | — | *(deprecated — use `onLevelEdit`)* |
+
+### `OHLCVBar`
+
+| Field | Required | Type | Description |
+|---|:---:|---|---|
+| `time` | ✓ | `number` | Unix ms timestamp |
+| `open` | ✓ | `number` | Open price |
+| `high` | ✓ | `number` | High price |
+| `low` | ✓ | `number` | Low price |
+| `close` | ✓ | `number` | Close price |
+| `volume` | | `number` | Volume (omit to hide volume overlay) |
+
+### Duration → Auto Timeframe Map
+
+| Duration | Default timeframe |
+|---|---|
+| `1D` | `5m` |
+| `5D` | `15m` |
+| `1M` | `30m` |
+| `3M` | `1h` |
+| `6M` | `4h` |
+| `1Y` | `1D` |
+| `5Y` | `1W` |
+| `All` | `1M` |
+
+Override individual entries via `durationTimeframeMap`:
+
+```ts
+new ChartEngine({ ..., durationTimeframeMap: { '1Y': '4h', '5Y': '1D' } });
+```
+
+### `UiConfig` — sizes & fonts
+
+All values are optional; unset keys fall back to `DEFAULT_UI_CONFIG`.
+
+```ts
+import { DEFAULT_UI_CONFIG } from '@acttrader/stockchart';
+```
+
+| Component key | Configurable properties |
+|---|---|
+| `drawingToolbar` | `iconBtnSize`, `iconFontSize`, `iconFontFamily`, `flyoutLabelFontSize`, `flyoutLabelFontFamily`, `shortcutFontSize`, `soonBadgeFontSize`, `flyoutHeadingFontSize`, `flyoutHeadingLetterSpacing`, `scrollBtnHeight`, `scrollBtnFontSize`, `barPadding`, `btnGap` |
+| `topBar` | `height`, `dropBtnFontSize`, `dropBtnFontFamily`, `drawBtnSize`, `drawBtnIconFontSize`, `flyoutRowFontSize`, `flyoutRowFontFamily`, `flyoutCategoryFontSize`, `flyoutCategoryLetterSpacing`, `flyoutCheckFontSize`, `streamDotSize` |
+| `bottomBar` | `height`, `btnFontSize`, `btnFontFamily` |
+| `priceAxis` | `fontSize`, `fontFamily` |
+| `timeAxis` | `fontSize`, `fontFamily` |
+| `crosshair` | `labelHeight`, `labelPaddingX`, `fontSize`, `fontFamily` |
+| `indicatorOverlay` | `pillFontSize`, `pillFontFamily`, `dotFontSize`, `pillIconFontSize`, `collapseBtnFontSize`, `collapseBtnFontFamily`, `dropdownRowFontSize`, `dropdownRowFontFamily`, `dropdownIconFontSize` |
+
+**Example:**
+
+```ts
+import { resolveUiConfig } from '@acttrader/stockchart';
+
+new ChartEngine({
+    container,
+    uiConfig: {
+        topBar:    { height: '40px', dropBtnFontSize: '13px' },
+        priceAxis: { fontSize: '12px', fontFamily: 'Inter, sans-serif' },
+    },
+});
+```
+
+You can also import individual section defaults:
+
+```ts
+import {
+    DEFAULT_UI_CONFIG,
+    DEFAULT_TOP_BAR_CONFIG,
+    DEFAULT_PRICE_AXIS_CONFIG,
+    DEFAULT_CROSSHAIR_CONFIG,
+    // ...
+} from '@acttrader/stockchart';
+```
+
+### `ChartLabels` — i18n / translation
+
+All user-visible strings can be overridden for translation. Only keys you supply are replaced; the rest fall back to `DEFAULT_LABELS` (English).
+
+```ts
+import { DEFAULT_LABELS, resolveLabels } from '@acttrader/stockchart';
+```
+
+Pass overrides directly in `ChartConfig`:
+
+```ts
+new ChartEngine({
+    container,
+    labels: {
+        trade: { buy: 'Acheter', sell: 'Vendre', limit: 'Limite', stop: 'Stop' },
+        ohlc:  { open: 'O', high: 'H', low: 'L', close: 'C', volume: 'V' },
+        chart: { loading: 'Chargement…', scrollToLatest: 'Aller à la fin' },
+    },
+});
+```
+
+| Section | Key | Default | Description |
+|---|---|---|---|
+| `topBar.series` | `candlestick` | `'Candles'` | Series dropdown label |
+| `topBar.series` | `hollow` | `'Hollow'` | |
+| `topBar.series` | `ohlc` | `'OHLC'` | |
+| `topBar.series` | `line` | `'Line'` | |
+| `topBar.series` | `area` | `'Area'` | |
+| `topBar` | `indicatorsBtn` | `'Indicators'` | Indicators button (no active) |
+| `topBar` | `indicatorsBtnActive` | `'Indicators ({count})'` | `{count}` replaced at runtime |
+| `topBar` | `toggleDrawingTitle` | `'Toggle Drawing Tools'` | Toolbar toggle tooltip |
+| `topBar` | `toggleFullscreenTitle` | `'Toggle Fullscreen'` | Fullscreen button tooltip |
+| `topBar` | `exitFullscreenTitle` | `'Exit Fullscreen'` | |
+| `topBar` | `settingsTitle` | `'Settings'` | Settings button tooltip |
+| `topBar.timeframes` | `'1m'`…`'1Y'` | same as key | Timeframe dropdown labels |
+| `bottomBar.durations` | `'1D'`…`'All'` | same as key | Duration button labels |
+| `drawingToolbar.categories` | `trendLines` | `'Trend Lines & Channels'` | Category flyout heading |
+| `drawingToolbar.categories` | `fibonacci` | `'Fibonacci & Gann Tools'` | |
+| `drawingToolbar.categories` | `shapes` | `'Geometric Shapes'` | |
+| `drawingToolbar.categories` | `measurements` | `'Measurement Tools'` | |
+| `drawingToolbar.categories` | `pitchforks` | `'Pitchfork Tools'` | |
+| `drawingToolbar.categories` | `volume` | `'Volume & Statistical Tools'` | |
+| `drawingToolbar.categories` | `annotations` | `'Annotation Tools'` | |
+| `drawingToolbar.categories` | `patterns` | `'Pattern Recognition'` | |
+| `drawingToolbar.categories` | `elliott` | `'Elliott Wave Tools'` | |
+| `drawingToolbar.categories` | `brushes` | `'Brush & Highlighter'` | |
+| `drawingToolbar.categories` | `advanced` | `'Advanced Tools'` | |
+| `drawingToolbar.categories` | `priceProjection` | `'Price Projection Tools'` | |
+| `drawingToolbar.tools` | *(DrawingToolType)* | English name per tool | One entry per `DrawingToolType` |
+| `drawingToolbar.actions` | `undo` | `'Undo (Ctrl+Z)'` | Action button tooltips |
+| `drawingToolbar.actions` | `redo` | `'Redo (Ctrl+Y)'` | |
+| `drawingToolbar.actions` | `deleteSelected` | `'Delete Selected (Del)'` | |
+| `drawingToolbar.actions` | `clearAll` | `'Clear All'` | |
+| `drawingToolbar.actions` | `showAll` | `'Show All'` | |
+| `drawingToolbar.actions` | `hideAll` | `'Hide All'` | |
+| `drawingToolbar.actions` | `lockAll` | `'Lock All'` | |
+| `drawingToolbar.actions` | `unlockAll` | `'Unlock All'` | |
+| `drawingToolbar` | `soonBadge` | `'soon'` | Badge on unimplemented tools |
+| `drawingToolbar` | `scrollUp` | `'Scroll up'` | Scroll indicator tooltip |
+| `drawingToolbar` | `scrollDown` | `'Scroll down'` | |
+| `ohlc` | `open` | `'O'` | OHLC strip label |
+| `ohlc` | `high` | `'H'` | |
+| `ohlc` | `low` | `'L'` | |
+| `ohlc` | `close` | `'C'` | |
+| `ohlc` | `volume` | `'V'` | |
+| `trade` | `buy` | `'Buy'` | Trade popover label |
+| `trade` | `sell` | `'Sell'` | |
+| `trade` | `limit` | `'Limit'` | Order type label |
+| `trade` | `stop` | `'Stop'` | |
+| `trade` | `market` | `'Market'` | |
+| `trade` | `qty` | `'Qty'` | Draft order qty input label |
+| `trade` | `placeOrderTitle` | `'Place order at this price'` | Trade button tooltip |
+| `dialogs.settings` | `title` | `'Chart Settings'` | Dialog title |
+| `dialogs.settings` | `tfcSection` | `'Trade from Charts'` | Section heading |
+| `dialogs.settings` | `showLabel` | `'Show'` | Radio group label |
+| `dialogs.settings` | `positionStyleLabel` | `'Position Style'` | |
+| `dialogs.settings` | `showAll` | `'All'` | Filter option |
+| `dialogs.settings` | `showPositions` | `'Positions Only'` | |
+| `dialogs.settings` | `showOrders` | `'Orders Only'` | |
+| `dialogs.settings` | `styleLine` | `'Full Line'` | Style option |
+| `dialogs.settings` | `styleDot` | `'Dot'` | |
+| `dialogs.indicator` | `titleSuffix` | `'Settings'` | Appended to indicator name in dialog title |
+| `dialogs.indicator` | `noParams` | `'No configurable parameters.'` | Empty-state message |
+| `chart` | `loading` | `'Loading…'` | Loading overlay text |
+| `chart` | `scrollToLatest` | `'Scroll to latest'` | Jump-to-end button tooltip |
+| `chart` | `nIndicators` | `'{count} indicators'` | Collapse button; `{count}` replaced at runtime |
+
+### `ChartTheme` — colors
+
+```ts
+import { DARK_THEME, LIGHT_THEME } from '@acttrader/stockchart';
+import type { ChartTheme } from '@acttrader/stockchart';
+```
+
+Pass a full or partial theme object to customize colors:
+
+```ts
+const myTheme: ChartTheme = {
+    ...DARK_THEME,
+    background: '#0a0a0a',
+    candle: { up: '#00c853', down: '#ff1744', wickUp: '#00c853', wickDown: '#ff1744' },
+};
+
+new ChartEngine({ container, theme: 'dark' });
+// Theme override is applied via setTheme() after construction:
+chart.setTheme('light');
+```
+
+| Top-level key | Type | Description |
+|---|---|---|
+| `background` | `string` | Canvas background color |
+| `grid` | `string` | Grid line color |
+| `axisText` | `string` | Axis tick label color |
+| `axisBorder` | `string` | Axis border / separator color |
+| `crosshair` | `string` | Crosshair line color |
+| `tooltip` | `{background, text, border}` | Floating label colors |
+| `candle` | `{up, down, wickUp, wickDown}` | Candlestick colors |
+| `volume` | `{up, down}` | Volume bar colors |
+| `ui` | `ChartThemeUi` | Accent and interactive-state colors |
+| `drawingToolbar` | `DrawingToolbarColors` | Icon and flyout colors |
+| `topBar` | `TopBarColors` | Top bar button and flyout colors |
+| `bottomBar` | `BottomBarColors` | Duration button colors |
+| `indicatorOverlay` | `IndicatorOverlayColors` | Pill and dropdown colors |
+| `tradeLevels` | `TradeLevelColors` | Level line and info box colors |
+| `tradePanel` | `TradePanelColors` | Trade panel side-drawer colors |
+
+---
+
+## API Reference
+
+### Data
+
+```ts
+chart.loadData(bars: OHLCVBar[]): this
+chart.prependData(bars: OHLCVBar[]): this   // prepend historical bars (infinite scroll back)
+chart.correctBar(barTime: number, bar: OHLCVBar): void  // replace a bar with authoritative data after close
+chart.setLoading(loading: boolean): this
+```
+
+### Series & Appearance
+
+```ts
+chart.setSeries(series: SeriesType): this
+chart.setTheme('dark' | 'light'): this
+chart.setVolume(show: boolean): this
+```
+
+`SeriesType` values: `candlestick` · `hollow` · `line` · `area` · `ohlc` · `heikinashi` · `volumecandles` · `linemarkers` · `step` · `hlcarea` · `baseline` · `columns` · `highlow`
+
+### Indicators
+
+```ts
+chart.addIndicator(indicator: IIndicator): this
+chart.removeIndicator(name: string): this
+```
+
+### Drawing Tools
+
+```ts
+chart.setDrawingTool(tool: DrawingToolType | null): this
+```
+
+### Trade Levels (TFC)
+
+```ts
+chart.setLevels(levels, labelField, priceField, type): this
+chart.removeLevelByLabel(label: string): this
+```
+
+### Trade Button
+
+```ts
+chart.setOrderLots(lots: number): void   // update default qty at runtime
+```
+
+### Viewport
+
+```ts
+chart.isAtLiveEdge(): boolean
+```
+
+### Streaming
+
+```ts
+chart.connectStream(adapter: IWebSocketAdapter): this
+chart.disconnectStream(): this
+chart.pushTick(tick: { time: number; bid: number; ask: number; volume?: number }): void  // push a tick directly without an adapter
+```
+
+### State Persistence
+
+```ts
+// Capture the full current configuration as a serializable object
+const state: ChartState = chart.getState();
+// → { symbol, timeframe, duration, series, showVolume, theme, indicators[], drawings[] }
+
+// Restore a previously saved state (call after construction, before loadData)
+chart.setState(state);
+```
+
+Use together with the `stateChange` event to persist chart config per symbol:
+
+```ts
+import type { ChartState } from '@acttrader/stockchart';
+
+chart.on('stateChange', ({ symbol, state }) => {
+    localStorage.setItem(`chart:${symbol}`, JSON.stringify(state));
+});
+
+// On init — restore if available
+const saved = localStorage.getItem(`chart:${symbol}`);
+if (saved) chart.setState(JSON.parse(saved) as ChartState);
+```
+
+### Lifecycle
+
+```ts
+chart.destroy(): void
+```
+
+---
+
+## Built-in Indicators
+
+### Trend / Price Overlay
+
+| Class | Constructor defaults |
+|---|---|
+| `SMA(period?, color?)` | period 20 |
+| `EMA(period?, color?)` | period 20 |
+| `WMA(period?, color?)` | period 20 |
+| `HMA(period?, color?)` | period 20 — Hull MA |
+| `BollingerBands(period?, mult?, color?)` | 20, 2 |
+| `KeltnerChannels(period?, mult?, color?)` | 20, 2 |
+| `DonchianChannels(period?, color?)` | 20 |
+| `IchimokuCloud(tenkan?, kijun?, senkou?, color?)` | 9, 26, 52 |
+| `ParabolicSAR(step?, max?, color?)` | 0.02, 0.2 |
+| `Supertrend(period?, mult?, color?)` | 10, 3 |
+| `MARibbon(color?)` | 8 EMAs (10–80) |
+| `PivotPoints(color?)` | Standard pivot levels |
+| `FibRetracementIndicator(color?)` | Auto swing high/low |
+| `HeikinAshi(color?)` | Heikin-Ashi candle overlay |
+| `LinearRegression(period?, color?)` | Linear regression line overlay |
+
+### Sub-pane Oscillators
+
+| Class | Constructor defaults |
+|---|---|
+| `RSI(period?, color?)` | 14 |
+| `MACD(fast?, slow?, signal?, color?)` | 12, 26, 9 |
+| `Stochastic(kPeriod?, dPeriod?, color?)` | 14, 3 |
+| `StochRSI(rsiPeriod?, stochPeriod?, kPeriod?, dPeriod?, color?)` | 14, 14, 3, 3 |
+| `CCI(period?, color?)` | 20 |
+| `WilliamsR(period?, color?)` | 14 |
+| `ROC(period?, color?)` | 12 |
+| `ATR(period?, color?)` | 14 |
+| `ADX(period?, color?)` | 14 — includes +DI / -DI |
+| `OBV(color?)` | On Balance Volume |
+| `VWAP(color?)` | Intra-day weighted average |
+| `AccDistribution(color?)` | Accumulation/Distribution |
+| `MFI(period?, color?)` | 14 — Money Flow Index |
+| `CMF(period?, color?)` | 20 — Chaikin Money Flow |
+| `AwesomeOscillator(color?)` | 5 / 34 SMA difference |
+| `VOL(color?)` | Volume oscillator sub-pane |
+
+Sub-pane heights are user-resizable by dragging the separator between panes.
+
+---
+
+## Drawing Tools
+
+### Lines & Channels
+
+| Key | Tool | Placement |
+|---|---|---|
+| `horizontalLine` | Horizontal Line | Single click |
+| `verticalLine` | Vertical Line | Single click |
+| `trendLine` | Trend Line | 2 clicks |
+| `trendAngle` | Trend Angle | 2 clicks (shows angle) |
+| `crossLine` | Cross Line | Single click (H+V) |
+| `parallelChannel` | Parallel Channel | 3 clicks |
+| `flatChannel` | Flat Channel | 2 clicks |
+| `disjointChannel` | Disjoint Channel | 3 clicks |
+
+### Fibonacci & Gann
+
+`fibRetracement` · `fibExtension` · `fibChannel` · `fibTimezone` · `fibCircles` · `fibSpiral` · `fibFan` · `fibProjection` · `gannFan` · `gannSquare` · `gannBox`
+
+### Shapes
+
+`rectangle` · `rotatedRectangle` · `ellipse` · `triangle` · `circle` · `arc` · `polyline` · `path` · `brush` · `highlighter`
+
+### Measurements & Annotations
+
+`priceRange` · `dateRange` · `datePriceRange` · `ruler` · `priceLabel` · `priceNote` · `priceProjection` · `projection` · `arrowUp` · `arrowDown` · `arrowMarker` · `text` · `callout` · `anchoredNote` · `flag` · `sineLine` · `regressionTrend` · `ghostFeed`
+
+### Volume Profile
+
+`volumeProfile` · `anchoredVP` · `fixedRangeVP`
+
+### Cyclic & Time
+
+`cyclicLines` · `timeCycles`
+
+### Harmonic & Elliott Patterns
+
+`abcdPattern` · `headShoulders` · `trianglePattern` · `batPattern` · `butterflyPattern` · `crabPattern` · `gartleyPattern` · `cypherPattern` · `sharkPattern` · `threeDrives` · `elliottImpulse` · `elliottCorrective` · `elliottTriangle` · `elliottCombination` · `elliottWxy`
+
+### Pitchforks
+
+`pitchfork` · `schiffPitchfork` · `modifiedSchiff` · `insidePitchfork`
+
+---
+
+## Events
+
+```ts
+chart.on('crosshair',      ({ x, y, barIndex, price, bar }) => {});
+chart.on('click',          ({ x, y, barIndex, price, bar }) => {});
+chart.on('zoom',           ({ viewport }) => {});
+chart.on('pan',            ({ viewport }) => {});
+chart.on('timeframeChange',({ timeframe }) => {});
+chart.on('durationChange', ({ duration, timeframe }) => {});
+chart.on('seriesChange',   ({ series }) => {});
+chart.on('streamStatus',   ({ status }) => {}); // 'connected' | 'reconnecting' | 'disconnected'
+chart.on('dataLoaded',     ({ timeframe, interval, start, end }) => {});
+chart.on('newBar',         ({ completedBar, openingBar, intervalMs }) => {});
+chart.on('stateChange',    ({ symbol, state }) => {
+    // Fires after every user-driven config change (timeframe, series, theme,
+    // indicators, drawings, volume). `state` is a full serializable snapshot.
+    localStorage.setItem(`chart:${symbol}`, JSON.stringify(state));
+});
+
+// TFC events
+chart.on('tradeLevelEdit',     ({ label, type, data, changes }) => {});
+chart.on('tradeLevelClose',    ({ label, type, action, data }) => {});
+chart.on('tradeLevelDragEnd',  ({ label, type, newPrice, data }) => {}); // deprecated
+chart.on('tradeLevelBracketDrag', ({ label, bracketType, newPrice, data }) => {}); // deprecated
+chart.on('tradeLevelEditOpen', ({ label, type, price, side, stopLossPrice, takeProfitPrice, data }) => {});
+chart.on('tradeLevelConfirmed',({ label, type }) => {});
+```
+
+---
+
+## Custom Indicator
+
+Implement `IIndicator` and pass it to `addIndicator()`:
+
+```ts
+import type { IIndicator, OHLCVBar, IndicatorResult } from '@acttrader/stockchart';
+
+class MyIndicator implements IIndicator {
+    name       = 'MyInd';
+    color      = '#e91e63';
+    pane       = 'sub' as const;  // 'main' = overlay, 'sub' = dedicated pane
+    paneHeight = 80;
+
+    compute(data: OHLCVBar[]): IndicatorResult[] {
+        return data.map((bar, i) => ({ index: i, value: bar.close }));
+    }
+
+    render(ctx, results, scale, viewport, chartHeight) {
+        // draw with ctx (Canvas 2D)
+    }
+}
+
+chart.addIndicator(new MyIndicator());
+```
+
+---
+
+## Build & Dev
+
+```bash
+npm run dev        # Vite dev server with demo chart
+npm run build      # ESM + CJS via tsup → dist/
+npm run test       # Vitest unit tests
+npm run typecheck  # tsc --noEmit
+npm run lint       # ESLint
+```
+
+---
+
+## License
+
+MIT