# d3kline-engine User Guide

## 1. Scope

This guide explains how to run the repository from GitHub and use the current public APIs after the renderer migration.

Current public surface:

- shared contracts/utilities in `@d3kline/core`
- chart runtime in `@d3kline/renderer` (migrated from quant-web `d3Kline`)
- aggregation package in `@d3kline/engine` (re-exports core + renderer)

## 2. Requirements

- Node.js 20+
- pnpm 10+

## 3. Clone and Start

```bash
git clone https://github.com/RookieTao998/d3kline-engine.git
cd d3kline-engine
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm dev:examples
```

Open the Vite URL in your browser.

## 4. Package Usage

### 4.1 Use `@d3kline/renderer`

```ts
import { D3KlineChart, type KLineData } from '@d3kline/renderer'

const host = document.getElementById('chart')!
const chart = new D3KlineChart(host, { theme: 'dark' })

const bars: KLineData[] = [
  { timestamp: 1712000000000, open: 100, high: 105, low: 98, close: 103, volume: 1200 },
  { timestamp: 1712000060000, open: 103, high: 108, low: 102, close: 107, volume: 980 },
]

chart.resetData(bars)
chart.loadIndicator({ name: 'MA' })
chart.loadIndicator({ name: 'VOL', isMain: false, height: 120 })
```

### 4.2 Use `@d3kline/core`

`@d3kline/core` now focuses on shared contracts and helpers (types/period/options/events/chart-state) and no longer provides indicator registry runtime.

```ts
import type { KLineBar, PeriodType } from '@d3kline/core'

const bar: KLineBar = {
  timestamp: Date.now(),
  open: 1,
  high: 2,
  low: 0.5,
  close: 1.4,
}

const period: PeriodType = 'M1'
```

## 5. Indicator Usage

- Built-in indicators are loaded by name via `chart.loadIndicator(...)`.
- For custom indicator data pipelines, use `chart.createIndicator(...)` and `chart.updateIndicator(...)` with `CalcResult`-compatible series data.

## 6. API Reference

- Quant-web sourced API/parameter reference:
  - `docs/technical-notes/d3kline-api-reference-from-quant-web.md`

## 7. Published Packages

Published npm packages:

- `@d3kline/core`
- `@d3kline/renderer`
- `@d3kline/engine`

`@d3kline/examples` is for local development only.

## 8. Troubleshooting

### 8.1 `Cannot find module '@d3kline/...`

Run:

```bash
pnpm install
pnpm build
```

### 8.2 Example server port already in use

Run:

```bash
pnpm dev:examples -- --port 5174
```