react-klinecharts-ui 0.4.0 → 0.6.0

package/README.md

@@ -41,6 +41,11 @@ Many features in this library — including 11 TradingView-style indicators, 9 d
    - [useMeasure](#usemeasure)
    - [useAnnotations](#useannotations)
    - [useReplay](#usereplay)
+   - [useAlerts](#usealerts)
+   - [useCrosshair](#usecrosshair)
+   - [useDataExport](#usedataexport)
+   - [useHotkeys](#usehotkeys)
+   - [useChartAxes](#usechartaxes)
 6. [Utilities](#utilities)
    - [createDataLoader](#createdataloader)
    - [TA (Technical Analysis)](#ta-technical-analysis)
@@ -49,7 +54,8 @@ Many features in this library — including 11 TradingView-style indicators, 9 d
 9. [Drawing Overlays](#drawing-overlays)
 10. [Extensions](#extensions)
 11. [State Callbacks](#state-callbacks)
-12. [Full Export List](#full-export-list)
+12. [Backend Signals & Notifications](#backend-signals--notifications)
+13. [Full Export List](#full-export-list)
 
 ---
 
@@ -207,6 +213,10 @@ interface KlinechartsUIState {
   mainIndicators: string[]; // Active main chart indicators
   subIndicators: Record<string, string>; // Active sub-indicators: { name → paneId }
   indicatorAxes: Record<string, string>; // Custom Y-axis bindings: { indicatorId → yAxisId }
+  indicatorVisibility: Record<string, boolean>; // Visibility overrides: { indicatorId → false } (sparse)
+  alerts: Alert[]; // Price alerts (useAlerts) — shared across all consumers
+  measure: MeasureState; // Measure-tool state (useMeasure): { isActive, fromPoint, result }
+  replay: ReplayState; // Replay control state (useReplay): { isReplaying, isPaused, speed, barIndex, totalBars }
   styles: DeepPartial<Styles> | undefined; // Custom klinecharts styles
   screenshotUrl: string | null; // URL of the last screenshot
 }
@@ -227,6 +237,10 @@ type KlinechartsUIAction =
   | { type: "SET_MAIN_INDICATORS"; indicators: string[] }
   | { type: "SET_SUB_INDICATORS"; indicators: Record<string, string> }
   | { type: "SET_INDICATOR_AXES"; axes: Record<string, string> }
+  | { type: "SET_INDICATOR_VISIBILITY"; visibility: Record<string, boolean> }
+  | { type: "SET_ALERTS"; alerts: Alert[] }
+  | { type: "SET_MEASURE"; measure: Partial<MeasureState> }
+  | { type: "SET_REPLAY"; replay: Partial<ReplayState> }
   | { type: "SET_STYLES"; styles: DeepPartial<Styles> | undefined }
   | { type: "SET_LOCALE"; locale: string }
   | { type: "SET_SCREENSHOT_URL"; url: string | null };
@@ -457,12 +471,14 @@ const {
   moveToMain,
   moveToSub,
   setIndicatorVisible,
+  isIndicatorVisible,
   updateIndicatorParams,
   getIndicatorParams,
   isMainIndicatorActive,
   isSubIndicatorActive,
   indicatorAxes,
   getIndicatorAxis,
+  indicatorVisibility,
   bindIndicatorToNewAxis,
 } = useIndicators();
 ```
@@ -471,17 +487,20 @@ const {
 
 | Field                     | Type                     | Description                                |
 | ------------------------- | ------------------------ | ------------------------------------------ |
-| `mainIndicators`          | `IndicatorInfo[]`        | All main indicators with `isActive` flag   |
-| `subIndicators`           | `IndicatorInfo[]`        | All sub-indicators with `isActive` flag    |
+| `mainIndicators`          | `IndicatorInfo[]`        | All main indicators with `isActive` + `visible` flags |
+| `subIndicators`           | `IndicatorInfo[]`        | All sub-indicators with `isActive` + `visible` flags  |
 | `activeMainIndicators`    | `string[]`               | Active main indicator names only           |
 | `activeSubIndicators`     | `Record<string, string>` | Active sub-indicators: `{ name → paneId }` |
 | `availableMainIndicators` | `string[]`               | Full list from `MAIN_INDICATORS`           |
 | `availableSubIndicators`  | `string[]`               | Full list from `SUB_INDICATORS`            |
+| `indicatorAxes`           | `Record<string, string>` | Custom Y-axis bindings: `{ indicatorId → yAxisId }` |
+| `indicatorVisibility`     | `Record<string, boolean>`| Visibility overrides: `{ indicatorId → false }` (sparse — only hidden indicators; absent means visible) |
 
 ```typescript
 interface IndicatorInfo {
   name: string; // "MA", "MACD", "RSI", etc.
   isActive: boolean; // Whether it is currently on the chart
+  visible: boolean; // Whether it is currently shown (vs hidden); true when inactive
 }
 ```
 
@@ -497,11 +516,16 @@ interface IndicatorInfo {
 | `toggleSubIndicator(name)`                    | Same for sub-indicators                                       |
 | `moveToMain(name)`                            | Moves from sub-pane to `candle_pane`                          |
 | `moveToSub(name)`                             | Moves from `candle_pane` to a new sub-pane                    |
-| `setIndicatorVisible(name, isMain, visible)`  | Show/hide indicator via `chart.overrideIndicator`             |
+| `setIndicatorVisible(name, isMain, visible)`  | Show/hide indicator via `chart.overrideIndicator`; mirrors the flag into `indicatorVisibility` |
+| `isIndicatorVisible(name, isMain)`            | Reactive read counterpart to `setIndicatorVisible`; returns `true` for the default/inactive state |
 | `updateIndicatorParams(name, paneId, params)` | Update `calcParams` via `chart.overrideIndicator`             |
 | `getIndicatorParams(name)`                    | Returns `[{ label, defaultValue }]` or `[]` if no parameters  |
 | `isMainIndicatorActive(name)`                 | Quick active check                                            |
 | `isSubIndicatorActive(name)`                  | Quick active check                                            |
+| `collapseSubIndicator(name)`                  | Collapse a sub-indicator pane to minimal height (30px)        |
+| `expandSubIndicator(name)`                    | Expand a previously collapsed sub-indicator pane              |
+| `isSubIndicatorCollapsed(name)`               | Whether the given sub-indicator pane is currently collapsed   |
+| `reorderSubIndicator(name, direction)`        | Reorder a sub-indicator pane `"up"` or `"down"`               |
 | `getIndicatorAxis(name, isMain)`              | Returns the custom `yAxisId` an indicator is bound to, or `undefined` for the default axis |
 | `bindIndicatorToNewAxis(name, isMain, yAxis?)`| Rebinds an existing indicator to a different Y-axis (omit `yAxis` to return it to the default axis) |
 
@@ -550,12 +574,14 @@ const {
   magnetMode,
   isLocked,
   isVisible,
+  autoRetrigger,
   selectTool,
   clearActiveTool,
   setMagnetMode,
   toggleLock,
   toggleVisibility,
   removeAllDrawings,
+  setAutoRetrigger,
 } = useDrawingTools();
 ```
 
@@ -566,12 +592,14 @@ const {
 | `magnetMode`          | `"normal" \| "weak" \| "strong"` | Snap-to-OHLC mode                                       |
 | `isLocked`            | `boolean`                        | Whether all drawings are locked                         |
 | `isVisible`           | `boolean`                        | Whether all drawings are visible                        |
+| `autoRetrigger`       | `boolean`                        | Re-arm the tool after finishing a shape (default `true`) |
 | `selectTool(name)`    | —                                | Start drawing via `chart.createOverlay`                 |
 | `clearActiveTool()`   | —                                | Deselect tool (local state only)                        |
 | `setMagnetMode(mode)` | —                                | Change magnet mode for all existing and future drawings |
 | `toggleLock()`        | —                                | Toggle lock on all drawings                             |
 | `toggleVisibility()`  | —                                | Show/hide all drawings                                  |
 | `removeAllDrawings()` | —                                | Remove all drawings in the `drawing_tools` group        |
+| `setAutoRetrigger(enabled)` | —                          | Enable/disable auto re-arming                           |
 
 ```typescript
 interface DrawingToolItem {
@@ -594,6 +622,9 @@ interface DrawingCategoryItem {
 | `polygon`        | circle, rect, parallelogram, triangle                                                                                                                                  |
 | `fibonacci`      | fibonacciLine, fibonacciSegment, fibonacciCircle, fibonacciSpiral, fibonacciSpeedResistanceFan, fibonacciExtension, gannBox                                            |
 | `wave`           | xabcd, abcd, threeWaves, fiveWaves, eightWaves, anyWaves                                                                                                               |
+| `annotation`     | brush                                                                                                                                                                  |
+
+> **Freehand drawing.** The `brush` tool (category `annotation`) uses klinecharts' continuous (freehand) drawing mode — hold and drag to sketch. It is a built-in overlay added in **klinecharts 10.0.0-beta3**, so it requires beta3+ to render.
 
 ---
 
@@ -609,20 +640,25 @@ const settings = useKlinechartsUISettings();
 
 | Field                    | Type            | Default          | Description               |
 | ------------------------ | --------------- | ---------------- | ------------------------- |
-| `candleType`             | `string`        | `"candle_solid"` | Candle display type       |
-| `candleUpColor`          | `string`        | `"#2DC08E"`      | Bullish candle color      |
-| `candleDownColor`        | `string`        | `"#F92855"`      | Bearish candle color      |
-| `showLastPrice`          | `boolean`       | `true`           | Last price mark on Y-axis |
-| `showHighPrice`          | `boolean`       | `true`           | High price mark           |
-| `showLowPrice`           | `boolean`       | `true`           | Low price mark            |
-| `showIndicatorLastValue` | `boolean`       | `true`           | Indicator last value mark |
-| `priceAxisType`          | `PriceAxisType` | `"normal"`       | Y-axis scale type         |
-| `reverseCoordinate`      | `boolean`       | `false`          | Invert Y-axis             |
-| `showTimeAxis`           | `boolean`       | `true`           | Show X-axis               |
-| `showGrid`               | `boolean`       | `true`           | Show grid                 |
-| `showCrosshair`          | `boolean`       | `true`           | Show crosshair            |
-| `showCandleTooltip`      | `boolean`       | `true`           | OHLCV tooltip             |
-| `showIndicatorTooltip`   | `boolean`       | `true`           | Indicator tooltip         |
+| `candleType`             | `string`         | `"candle_solid"`  | Candle display type           |
+| `candleUpColor`          | `string`         | `"#2DC08E"`       | Bullish candle color          |
+| `candleDownColor`        | `string`         | `"#F92855"`       | Bearish candle color          |
+| `compareRule`            | `CompareRule`    | `"current_open"`  | Baseline rule for compared symbols |
+| `showLastPrice`          | `boolean`        | `true`            | Last price mark on Y-axis     |
+| `showLastPriceLine`      | `boolean`        | `true`            | Last price horizontal line    |
+| `showHighPrice`          | `boolean`        | `true`            | High price mark               |
+| `showLowPrice`           | `boolean`        | `true`            | Low price mark                |
+| `showIndicatorLastValue` | `boolean`        | `true`            | Indicator last value mark     |
+| `priceAxisType`          | `PriceAxisType`  | `"normal"`        | Y-axis scale type             |
+| `yAxisPosition`          | `YAxisPosition`  | `"right"`         | Y-axis side (`"left" \| "right"`) |
+| `yAxisInside`            | `boolean`        | `false`           | Draw the Y-axis inside the pane |
+| `reverseCoordinate`      | `boolean`        | `false`           | Invert Y-axis                 |
+| `showTimeAxis`           | `boolean`        | `true`            | Show X-axis                   |
+| `showGrid`               | `boolean`        | `true`            | Show grid                     |
+| `showCrosshair`          | `boolean`        | `true`            | Show crosshair                |
+| `showCandleTooltip`      | `boolean`        | `true`            | OHLCV tooltip                 |
+| `showIndicatorTooltip`   | `boolean`        | `true`            | Indicator tooltip             |
+| `tooltipShowRule`        | `TooltipShowRule`| `"always"`        | When to show tooltips         |
 
 **Candle types:** `candle_solid`, `candle_stroke`, `candle_up_stroke`, `candle_down_stroke`, `ohlc`, `area`
 
@@ -630,14 +666,17 @@ const settings = useKlinechartsUISettings();
 
 #### Extra fields
 
-| Field            | Type                                          | Description                                           |
-| ---------------- | --------------------------------------------- | ----------------------------------------------------- |
-| `candleTypes`    | `CandleTypeItem[]`                            | List of `{ key, localeKey }` for rendering a selector |
-| `priceAxisTypes` | `{ key: PriceAxisType; localeKey: string }[]` | List for rendering a selector                         |
+| Field              | Type                                            | Description                                           |
+| ------------------ | ----------------------------------------------- | ----------------------------------------------------- |
+| `candleTypes`      | `CandleTypeItem[]`                              | List of `{ key, localeKey }` for rendering a selector |
+| `priceAxisTypes`   | `{ key: PriceAxisType; localeKey: string }[]`   | List for rendering a selector                         |
+| `yAxisPositions`   | `{ key: YAxisPosition; localeKey: string }[]`   | List for rendering a selector                         |
+| `compareRules`     | `{ key: CompareRule; localeKey: string }[]`     | List for rendering a selector                         |
+| `tooltipShowRules` | `{ key: TooltipShowRule; localeKey: string }[]` | List for rendering a selector                         |
 
 #### Setters
 
-Each field has a corresponding setter: `setCandleType`, `setCandleUpColor`, `setCandleDownColor`, `setShowLastPrice`, `setShowHighPrice`, `setShowLowPrice`, `setShowIndicatorLastValue`, `setPriceAxisType`, `setReverseCoordinate`, `setShowTimeAxis`, `setShowGrid`, `setShowCrosshair`, `setShowCandleTooltip`, `setShowIndicatorTooltip`.
+Each field has a corresponding setter: `setCandleType`, `setCandleUpColor`, `setCandleDownColor`, `setCompareRule`, `setShowLastPrice`, `setShowLastPriceLine`, `setShowHighPrice`, `setShowLowPrice`, `setShowIndicatorLastValue`, `setPriceAxisType`, `setYAxisPosition`, `setYAxisInside`, `setReverseCoordinate`, `setShowTimeAxis`, `setShowGrid`, `setShowCrosshair`, `setShowCandleTooltip`, `setShowIndicatorTooltip`, `setTooltipShowRule`.
 
 All setters immediately apply changes via `chart.setStyles(...)`.
 
@@ -718,7 +757,7 @@ const { containerRef, toggle, isFullscreen } = useFullscreen();
 
 Create and manage horizontal price level lines (order lines).
 
-> **Requirement:** The `orderLine` overlay must be registered via `overlays={[orderLine]}` on the provider.
+> **No setup required.** The `orderLine` overlay is registered automatically by `registerExtensions()` (enabled by default). Passing `overlays={[orderLine]}` to the provider still works and is harmless, but is no longer necessary.
 
 ```typescript
 const {
@@ -1003,7 +1042,7 @@ const {
 | Property | Type | Description |
 |----------|------|-------------|
 | `symbols` | `CompareSymbol[]` | Array of comparison symbols with metadata |
-| `addSymbol` | `(ticker: string) => void` | Add a symbol to compare |
+| `addSymbol` | `(ticker: string, color?: string) => Promise<void>` | Add a symbol to compare (optional line color) |
 | `removeSymbol` | `(ticker: string) => void` | Remove a comparison symbol |
 | `toggleSymbol` | `(ticker: string) => void` | Toggle visibility of a symbol |
 | `clearAll` | `() => void` | Remove all comparison symbols |
@@ -1022,6 +1061,8 @@ const {
 
 Measure price changes, percentage swings, bar count, and time intervals between two points on the chart.
 
+> **Multi-instance safe.** State lives in the shared provider store (`state.measure`), so calling `useMeasure()` in several components (e.g. a toolbar toggle and a separate result panel) keeps them in sync — no need to hoist a single instance.
+
 ```typescript
 import { useMeasure } from "react-klinecharts-ui";
 
@@ -1030,6 +1071,8 @@ const {
   startMeasure,
   cancelMeasure,
   result,
+  clearResult,
+  fromPoint,
 } = useMeasure();
 ```
 
@@ -1041,6 +1084,8 @@ const {
 | `startMeasure` | `() => void` | Enter measurement mode (click two points) |
 | `cancelMeasure` | `() => void` | Exit measurement mode |
 | `result` | `MeasureResult \| null` | Measurement data (null if not measured yet) |
+| `clearResult` | `() => void` | Clear the current measurement result |
+| `fromPoint` | `MeasurePoint \| null` | The first picked point while measuring (null when inactive) |
 
 #### MeasureResult
 
@@ -1095,18 +1140,23 @@ const {
 
 Replay historical candles at various speeds with play/pause/step controls and progress tracking.
 
+> **Multi-instance safe.** Control state lives in the shared store (`state.replay`) and the playback timer + data buffers are owned by the provider, so there is exactly one replay session no matter how many `useReplay()` instances are mounted — start in one component and step in another, and they drive the same session.
+
 ```typescript
 import { useReplay } from "react-klinecharts-ui";
 
 const {
-  isPlaying,
+  isReplaying,
+  isPaused,
   speed,
-  currentIndex,
+  barIndex,
   totalBars,
-  play,
-  pause,
-  stop,
-  step,
+  startReplay,
+  stopReplay,
+  togglePause,
+  stepForward,
+  stepBackward,
+  seekTo,
   setSpeed,
 } = useReplay();
 ```
@@ -1115,15 +1165,245 @@ const {
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `isPlaying` | `boolean` | Whether replay is running |
-| `speed` | `number` | Current playback speed (0.25, 0.5, 1, 2, 4) |
-| `currentIndex` | `number` | Current bar index being displayed |
-| `totalBars` | `number` | Total bars in the dataset |
-| `play` | `() => void` | Start replay from current position |
-| `pause` | `() => void` | Pause replay (can resume with play) |
-| `stop` | `() => void` | Stop replay and reset to start |
-| `step` | `() => void` | Advance one bar when paused |
-| `setSpeed` | `(speed: number) => void` | Set playback speed multiplier |
+| `isReplaying` | `boolean` | Whether a replay session is active |
+| `isPaused` | `boolean` | Whether the replay is currently paused |
+| `speed` | `ReplaySpeed` | Current playback speed multiplier (`1 \| 2 \| 5 \| 10`) |
+| `barIndex` | `number` | Current bar index in the replay |
+| `totalBars` | `number` | Total bars in the saved dataset |
+| `startReplay` | `() => void` | Start replaying from the beginning |
+| `stopReplay` | `() => void` | Stop replay and restore the original data |
+| `togglePause` | `() => void` | Toggle play/pause |
+| `stepForward` | `() => void` | Advance one bar while paused |
+| `stepBackward` | `() => void` | Go back one bar while paused |
+| `seekTo` | `(index: number) => void` | Seek to a specific bar index (pauses playback) |
+| `setSpeed` | `(speed: ReplaySpeed) => void` | Change the playback speed |
+
+---
+
+### useAlerts
+
+Client-side price alerts. Draws a **labelled** locked horizontal line (price tag on the Y-axis + a bell-marked caption above the line) on the chart for each alert and polls the latest candle once per second, firing a callback when the close price crosses the alert level. This is the primary hook for reacting to price events — e.g. forwarding a buy/sell signal to your backend or triggering a push notification (see [Backend Signals & Notifications](#backend-signals--notifications)).
+
+> **Multi-instance safe.** The alert list lives in the shared store (`state.alerts`) and the crossing poller is owned by the provider (one poller, active only while alerts exist), so multiple `useAlerts()` instances share one list. Note: `onAlertTriggered` registers a **single** listener — the last registration wins.
+
+> **No manual overlay registration.** The `alertLine` overlay template the hook draws with is registered automatically (both by `registerExtensions()` and lazily inside `useAlerts` before the first overlay is created) — you don't need to pass it through the provider's `overlays` prop.
+
+```typescript
+import { useAlerts } from "react-klinecharts-ui";
+
+const {
+  alerts,
+  addAlert,
+  removeAlert,
+  clearAlerts,
+  onAlertTriggered,
+} = useAlerts();
+
+// Default: orange dashed line, bell + price/message caption.
+const id = addAlert(65000, "crossing_up", "BTC broke 65k");
+
+// Customize the look via the optional 4th argument (AlertLineExtendData).
+addAlert(70000, "crossing_up", "Take profit", {
+  color: "#e91e63",
+  showBell: true,
+});
+
+onAlertTriggered((alert) => {
+  console.log("Alert fired:", alert.message, alert.price);
+});
+```
+
+#### Return type: `UseAlertsReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `alerts` | `Alert[]` | Current alerts (active and triggered) |
+| `addAlert` | `(price: number, condition: AlertCondition, message?: string, extendData?: AlertLineExtendData) => string` | Create an alert at a price level; returns its id. The optional `extendData` customizes the line/label look |
+| `removeAlert` | `(id: string) => void` | Remove a single alert and its chart line |
+| `clearAlerts` | `() => void` | Remove all alerts |
+| `onAlertTriggered` | `(callback: (alert: Alert) => void) => void` | Register a callback fired once when an alert's condition is met |
+
+#### Types
+
+```typescript
+type AlertCondition = "crossing_up" | "crossing_down" | "crossing";
+
+interface Alert {
+  id: string;
+  price: number;
+  condition: AlertCondition;
+  message?: string;
+  triggered: boolean;
+  /** Visual style of the alert line; persisted so it survives undo/redo & layout presets. */
+  extendData?: AlertLineExtendData;
+}
+
+interface AlertLineExtendData {
+  /** Primary color for the line, the Y-axis mark bg, and label fallback. Default: "#ff9800" */
+  color?: string;
+  /** Caption above the line. Defaults to `message ?? formatted price` (symbol precision). */
+  text?: string;
+  /** Line style overrides (style / width / dashedValue). Default: dashed. */
+  line?: OrderLineLineStyle;
+  /** Y-axis price mark style overrides. */
+  mark?: OrderLineMarkStyle;
+  /** Caption text style overrides. */
+  label?: OrderLineLabelStyle;
+  /** Show a 🔔 marker before the caption. Default: true */
+  showBell?: boolean;
+}
+```
+
+The `line` / `mark` / `label` style types are shared with [`useOrderLines`](#useorderlines) (`OrderLineLineStyle`, `OrderLineMarkStyle`, `OrderLineLabelStyle`).
+
+| Condition | Fires when |
+|-----------|------------|
+| `crossing_up` | Previous close `<` price **and** current close `>=` price |
+| `crossing_down` | Previous close `>` price **and** current close `<=` price |
+| `crossing` | Either direction |
+
+> Detection is based on the **latest candle's close**, polled every second from `chart.getDataList()`. An alert fires at most once (its `triggered` flag flips to `true`); recreate it to re-arm.
+
+---
+
+### useCrosshair
+
+Tracks the OHLCV data of the bar currently under the crosshair. Returns `null` when the cursor is off-chart. Updates are throttled with `requestAnimationFrame`, making it suitable for driving a live data panel / legend that follows the cursor.
+
+```typescript
+import { useCrosshair } from "react-klinecharts-ui";
+
+const { barData } = useCrosshair();
+
+// barData is null until the cursor is over a candle
+if (barData) {
+  console.log(barData.close, barData.changePercent);
+}
+```
+
+#### Return type: `UseCrosshairReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `barData` | `CrosshairBarData \| null` | OHLCV of the hovered bar, or `null` when off-chart |
+
+#### CrosshairBarData
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `open` | `number` | Open price |
+| `high` | `number` | High price |
+| `low` | `number` | Low price |
+| `close` | `number` | Close price |
+| `volume` | `number` | Volume |
+| `timestamp` | `number` | Bar timestamp (ms) |
+| `change` | `number` | `close - open`, rounded to the symbol's price precision |
+| `changePercent` | `number` | Percent change relative to open, 2 decimals |
+
+---
+
+### useDataExport
+
+Export chart candle data to a downloaded file in CSV or JSON format. Columns: `Date` (ISO), `Open`, `High`, `Low`, `Close`, `Volume`. The file is named `<ticker>_<YYYY-MM-DD>.<format>`.
+
+```typescript
+import { useDataExport } from "react-klinecharts-ui";
+
+const { exportAll, exportVisible } = useDataExport();
+
+exportAll("csv");      // every loaded bar
+exportVisible("json"); // only the currently visible range
+```
+
+#### Return type: `UseDataExportReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `exportAll` | `(format: ExportFormat) => void` | Download all loaded candles |
+| `exportVisible` | `(format: ExportFormat) => void` | Download only the visible range (falls back to all bars if the range is unavailable) |
+
+```typescript
+type ExportFormat = "csv" | "json";
+```
+
+> No-op when the chart is not ready or holds no data.
+
+---
+
+### useHotkeys
+
+Keyboard shortcuts (klinecharts v10, requires **klinecharts 10.0.0-beta3+**). Register custom hotkeys globally and toggle hotkey handling per chart. The `action` callback receives the chart instance, the keyboard event, the matched key, and the hotkey template.
+
+```typescript
+import { useHotkeys } from "react-klinecharts-ui";
+
+const { registerHotkey, setHotkeysEnabled, supportedHotkeys } = useHotkeys();
+
+// Register a custom shortcut — Ctrl/Cmd+L removes all overlays.
+registerHotkey({
+  name: "remove-all-overlays",
+  keys: ["ctrl+l", "meta+l"],
+  preventDefault: true,
+  action: ({ chart }) => chart.removeOverlay(),
+});
+
+// Disable all built-in shortcuts except undo/redo.
+setHotkeysEnabled(true, ["undo", "redo"]);
+```
+
+#### Return type: `UseHotkeysReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `registerHotkey` | `(template: HotkeyTemplate) => void` | Register a custom hotkey globally (idempotent per `name`) |
+| `getHotkey` | `(name: string) => HotkeyTemplate \| null` | Look up a registered hotkey by name |
+| `supportedHotkeys` | `string[]` | Names of every registered hotkey (built-in + custom) |
+| `setHotkeysEnabled` | `(enabled: boolean, exclude?: string[]) => void` | Enable/disable hotkey handling for the chart; optionally exclude names |
+| `getHotkeysConfig` | `() => Hotkey \| null` | Current `{ enabled, exclude }` config for the chart |
+
+```typescript
+interface HotkeyTemplate {
+  name: string;
+  keys: string | string[];
+  preventDefault?: boolean;
+  stopPropagation?: boolean;
+  check?: (params: HotkeyActionParams) => boolean;
+  action: (params: HotkeyActionParams) => void;
+  extendData?: unknown;
+}
+
+interface Hotkey {
+  enabled: boolean;
+  exclude: string[];
+}
+```
+
+> Custom hotkeys register **globally** (shared by every chart on the page); the enable/exclude switches are per-chart. klinecharts exposes no removal API, so a registered hotkey lives for the page session.
+
+---
+
+### useChartAxes
+
+Override the chart's built-in X (time) and Y (value) axes (klinecharts v10 `overrideXAxis` / `overrideYAxis`, added in **beta2**). For binding indicators to additional secondary Y-axes, use [useIndicators](#useindicators) instead.
+
+```typescript
+import { useChartAxes } from "react-klinecharts-ui";
+
+const { overrideXAxis, overrideYAxis } = useChartAxes();
+
+overrideYAxis({ reverse: true });            // flip the price scale
+overrideYAxis({ inside: true });             // draw price labels inside the pane
+overrideXAxis({ scrollZoomEnabled: false }); // lock time-axis zoom
+```
+
+#### Return type: `UseChartAxesReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `overrideXAxis` | `(override: XAxisOverride) => void` | Override the main X (time) axis (`name`, `scrollZoomEnabled`, `createTicks`) |
+| `overrideYAxis` | `(override: YAxisOverride) => void` | Override a Y (value) axis (`reverse`, `inside`, `position`, `scrollZoomEnabled`, `createRange`, `createTicks`, `id`/`paneId` to target one) |
+
+> klinecharts beta3 ships these two methods with their parameter types **crossed** in its published typings; this hook shields you behind semantically-correct signatures, so `overrideYAxis` takes `YAxisOverride` and `overrideXAxis` takes `XAxisOverride` as expected.
 
 ---
 
@@ -1271,6 +1551,29 @@ const PRICE_AXIS_TYPES = ["normal", "percentage", "log"] as const;
 type PriceAxisType = "normal" | "percentage" | "log";
 ```
 
+### YAXIS_POSITIONS
+
+```typescript
+const YAXIS_POSITIONS = ["left", "right"] as const;
+type YAxisPosition = "left" | "right";
+```
+
+### COMPARE_RULES
+
+Baseline rule used when overlaying compared symbols (see [useCompare](#usecompare)).
+
+```typescript
+const COMPARE_RULES = ["current_open", "prev_close"] as const;
+type CompareRule = "current_open" | "prev_close";
+```
+
+### TOOLTIP_SHOW_RULES
+
+```typescript
+const TOOLTIP_SHOW_RULES = ["always", "follow_cross", "none"] as const;
+type TooltipShowRule = "always" | "follow_cross" | "none";
+```
+
 ---
 
 ## Custom Indicator Templates
@@ -1346,7 +1649,7 @@ import { indicators } from "react-klinecharts-ui";
 
 ### registerExtensions
 
-Registers all built-in drawing overlays via `registerOverlay`. Called automatically by the provider when `registerExtensions: true`.
+Registers all built-in drawing overlays plus the feature overlays (`orderLine`, `alertLine`, `depthOverlay`) via `registerOverlay`. Called automatically by the provider when `registerExtensions: true`.
 
 ```typescript
 import { registerExtensions } from "react-klinecharts-ui";
@@ -1355,12 +1658,11 @@ registerExtensions(); // Idempotent — repeated calls are ignored
 
 ### orderLine
 
-Overlay template for horizontal price level lines. **Not registered automatically** — must be passed explicitly to the provider.
+Overlay template for horizontal price level lines. **Registered automatically** by `registerExtensions()` (default), so `useOrderLines` works out of the box. Passing it through `overlays={[orderLine]}` is optional.
 
 ```typescript
-import { orderLine, KlinechartsUIProvider } from "react-klinecharts-ui";
-
-<KlinechartsUIProvider overlays={[orderLine]}>...</KlinechartsUIProvider>;
+import { orderLine } from "react-klinecharts-ui";
+// No provider wiring needed — registered automatically.
 ```
 
 **Implementation details:**
@@ -1426,14 +1728,24 @@ interface OrderLinePadding {
 
 All sub-interfaces (`OrderLineLineStyle`, `OrderLineMarkStyle`, `OrderLineLabelStyle`, `OrderLineFontStyle`, `OrderLinePadding`) are exported as named types from both the main and `extensions` entry points.
 
-### depthOverlay
+### alertLine
 
-Overlay template for visualizing order book depth as horizontal liquidity bars at each price level. Shows cumulative buy/sell volume at price levels, useful for understanding support/resistance zones.
+Overlay template drawn by [`useAlerts`](#usealerts) for price alerts: a locked horizontal line with a Y-axis price mark and a bell-marked caption above the line. **Registered automatically** by `registerExtensions()` and lazily by `useAlerts` itself, so no provider wiring is required.
 
 ```typescript
-import { depthOverlay, KlinechartsUIProvider } from "react-klinecharts-ui/extensions";
+import { alertLine } from "react-klinecharts-ui";
+// Used internally by useAlerts; exported for advanced/manual overlay use.
+```
 
-<KlinechartsUIProvider overlays={[depthOverlay]}>...</KlinechartsUIProvider>;
+Its `extendData` shape is [`AlertLineExtendData`](#types) — it reuses the `OrderLineLineStyle` / `OrderLineMarkStyle` / `OrderLineLabelStyle` sub-types from `orderLine` and adds `showBell?: boolean` (default `true`). When no `text` is supplied the caption falls back to the formatted price (using `chart.getSymbol()?.pricePrecision`).
+
+### depthOverlay
+
+Overlay template for visualizing order book depth as horizontal liquidity bars at each price level. Shows cumulative buy/sell volume at price levels, useful for understanding support/resistance zones. **Registered automatically** by `registerExtensions()` (default); explicit `overlays={[depthOverlay]}` wiring is optional.
+
+```typescript
+import { depthOverlay } from "react-klinecharts-ui/extensions";
+// No provider wiring needed — registered automatically.
 ```
 
 **Implementation details:**
@@ -1539,6 +1851,97 @@ const savedTheme = localStorage.getItem('theme') ?? 'dark';
 
 ---
 
+## Backend Signals & Notifications
+
+A common question: **how do front-end indicators connect to a backend for buy/sell signals or push notifications?**
+
+This library is **headless by design** — it owns chart state, datafeed wiring, and overlay management, but it deliberately does **not** generate trading signals, execute orders, or send notifications. Those belong to your application/backend layer. What the library provides is the full set of extension points to connect the two. Backend-driven signals are **not** a built-in feature and are not planned as one, because they fall outside the headless UI scope.
+
+There are two directions to wire up.
+
+### Backend → chart (display server signals)
+
+Push signals computed on your backend into the chart through the `Datafeed` and overlay hooks:
+
+- **`Datafeed.subscribe`** — your real-time channel (WebSocket/SSE). Stream live candles, and alongside them any backend-computed signal payloads.
+- **[`useOrderLines`](#useorderlines)** — render entry/SL/TP levels as draggable horizontal lines; `onPriceChange` reports the new price when a user drags one.
+- **[`useAnnotations`](#useannotations)** — drop markers/notes on the chart at the bars where signals fired.
+
+```tsx
+// A WebSocket carrying both candles and backend signals
+const datafeed: Datafeed = {
+  // ...searchSymbols / getHistoryKLineData
+  subscribe(symbol, period, callback) {
+    const ws = new WebSocket(`wss://api.example.com/stream/${symbol.ticker}`);
+    ws.onmessage = (e) => {
+      const msg = JSON.parse(e.data);
+      if (msg.type === "kline") callback(msg.candle);
+      if (msg.type === "signal") signalBus.emit(msg); // hand off to your UI
+    };
+    sockets.set(symbol.ticker, ws);
+  },
+  unsubscribe(symbol) {
+    sockets.get(symbol.ticker)?.close();
+    sockets.delete(symbol.ticker);
+  },
+};
+```
+
+```tsx
+// Render a backend signal as an order line + annotation
+function SignalLayer() {
+  const { createOrderLine } = useOrderLines();
+  const { addAnnotation } = useAnnotations();
+
+  useEffect(() => {
+    return signalBus.on("signal", (s) => {
+      createOrderLine({ price: s.entry, text: `${s.side} @ ${s.entry}` });
+      addAnnotation(s.side === "buy" ? "▲" : "▼", s.entry, s.timestamp);
+    });
+  }, [createOrderLine, addAnnotation]);
+
+  return null;
+}
+```
+
+### Chart → backend (react to price events)
+
+Detect a price event on the client and forward it to your backend (webhook, order placement) or fire a push notification — all inside the [`useAlerts`](#usealerts) callback:
+
+```tsx
+function PriceAlertBridge() {
+  const { addAlert, onAlertTriggered } = useAlerts();
+
+  useEffect(() => {
+    addAlert(65000, "crossing_up", "BTC > 65k");
+
+    onAlertTriggered(async (alert) => {
+      // 1. Notify your backend (e.g. to place/adjust an order)
+      await fetch("https://api.example.com/signals", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ price: alert.price, condition: alert.condition }),
+      });
+
+      // 2. Browser push notification
+      if (Notification.permission === "granted") {
+        new Notification("Price alert", { body: alert.message });
+      }
+    });
+  }, [addAlert, onAlertTriggered]);
+
+  return null;
+}
+```
+
+> The chart-side `useAlerts` detection is a convenience based on the latest candle close (polled once per second) — it is **not** a substitute for authoritative server-side alerting. For guaranteed delivery, run the alert/signal logic on your backend and use the **Backend → chart** path above to visualize it.
+
+### Observing state
+
+Use **[State Callbacks](#state-callbacks)** (`onStateChange`, `onSymbolChange`, `onSubIndicatorsChange`, …) to forward symbol/period/indicator changes to your backend — for example, to subscribe the right server-side signal stream for whatever the user is currently viewing.
+
+---
+
 ## Full Export List
 
 ```typescript
@@ -1565,7 +1968,12 @@ export { useKlinechartsUILoading, type UseKlinechartsUILoadingReturn };
 export { usePeriods, type UsePeriodsReturn };
 export { useTimezone, type UseTimezoneReturn, type TimezoneItem };
 export { useSymbolSearch, type UseSymbolSearchReturn };
-export { useIndicators, type UseIndicatorsReturn, type IndicatorInfo };
+export {
+  useIndicators,
+  type UseIndicatorsReturn,
+  type IndicatorInfo,
+  type AddIndicatorOptions,
+};
 export {
   useDrawingTools,
   type UseDrawingToolsReturn,
@@ -1598,6 +2006,19 @@ export {
   type UseScriptEditorReturn,
   type ScriptPlacement,
 };
+export { useCrosshair, type UseCrosshairReturn, type CrosshairBarData };
+export { useAlerts, type UseAlertsReturn, type Alert, type AlertCondition };
+export { useDataExport, type UseDataExportReturn, type ExportFormat };
+export { useWatchlist, type UseWatchlistReturn, type WatchlistItem };
+export { useReplay, type UseReplayReturn, type ReplaySpeed };
+export { useCompare, type UseCompareReturn, type CompareSymbol };
+export {
+  useMeasure,
+  type UseMeasureReturn,
+  type MeasureResult,
+  type MeasurePoint,
+};
+export { useAnnotations, type UseAnnotationsReturn, type Annotation };
 
 // Data
 export { DEFAULT_PERIODS, type TerminalPeriod };
@@ -1650,7 +2071,7 @@ export {
 export * from "./indicators";
 
 // Extensions
-export { registerExtensions, overlays, indicators, orderLine };
+export { registerExtensions, overlays, indicators, orderLine, alertLine, depthOverlay };
 export type {
   OrderLineExtendData,
   OrderLineLineStyle,
@@ -1658,5 +2079,8 @@ export type {
   OrderLineLabelStyle,
   OrderLineFontStyle,
   OrderLinePadding,
+  AlertLineExtendData,
+  DepthOverlayExtendData,
+  DepthOverlayRow,
 };
 ```