@livo-build/charts 0.2.1

package/README.md

@@ -0,0 +1,189 @@
+# @livo-build/charts (livo-charts)
+
+A lightweight, **dependency-free** canvas charting library. The core renders to a
+`<canvas>` with zero runtime dependencies; a thin, self-styled React wrapper is
+shipped under a separate entry so non-React consumers never pull React into their
+bundle.
+
+It ships a **TradingView-style trading chart**: candlesticks **or** a line series, a
+**volume panel**, a **crosshair with price + time axis labels**, an **OHLCV legend**,
+independent **X and Y zoom** (+ pan), and a toolbar for **intervals, USD/ETH,
+price/market-cap and fullscreen**. The architecture (a framework-agnostic `Chart`
+controller + a pure `draw()` pass) is built to keep growing — indicators, overlays,
+multiple panes — without touching consumers.
+
+## Install
+
+```bash
+npm i @livo-build/charts
+```
+
+`react` / `react-dom` are **optional** peers — only needed for the React entry.
+
+## React
+
+```tsx
+import { PriceChart } from "@livo-build/charts/react";
+
+<PriceChart
+  swaps={trades}          // [{ t: unixSeconds, p: priceUsd, v: usdVolume }, …]
+  ethUsd={1711.81}        // enables the USD↔ETH toggle
+  tokenAddress="0x…"      // enables the Price↔MCap toggle (reads totalSupply())
+  decimals={18}
+  symbol="PEPE"
+  quote="WETH"
+  height={420}
+/>
+```
+
+`swaps` are aggregated into OHLC+volume candles client-side. The toolbar
+(`1s 1m 5m 15m 1h 4h 1d`, candle/line, Price/MCap, USD/ETH, flip, fullscreen) and the
+OHLCV legend are built in. The canvas is long-lived, so zoom/pan survive prop updates
+(streaming trades won't reset the user's view). The wrapper is styled inline — no CSS
+framework required.
+
+Market cap = `price × totalSupply()`, fetched once via `rpcUrl` (default
+`https://cloudflare-eth.com`) and cached; it silently falls back to price if the RPC
+is unavailable.
+
+### Live Hyperliquid chart
+
+A turnkey, **live** trading chart for any Hyperliquid market — fetches the public
+candle feed (no API key), polls for updates (preserving the user's zoom/pan), and
+supports moving-average overlays:
+
+```tsx
+import { HyperliquidChart } from "@livo-build/charts/react";
+
+<HyperliquidChart
+  coin="BTC"                 // or "ETH", or a builder-dex name like "xyz:TSLA"
+  interval="15m"             // 1m 5m 15m 1h 4h 1d (toolbar lets the user switch)
+  indicators={[{ type: "ema", period: 21 }, { type: "sma", period: 50 }]}
+  refetchMs={15000}          // poll cadence; 0 = fetch once
+  height={420}
+/>
+```
+
+`<HyperliquidChart>` is **realtime**: live candles stream over WebSocket, and older
+history loads lazily as the user scrolls left (infinite back-scroll) — both with no
+API key. Zoom/pan survive every update.
+
+### Indicators
+
+`PriceChart` and `HyperliquidChart` accept `indicators` — overlays drawn on the price
+pane. Each is `{ type: "sma" | "ema" | "wma" | "vwap", period, color?, source? }`
+(`source` defaults to `close`; `vwap` is cumulative and ignores period/source).
+Colors fall back to a built-in palette by position. The pure
+`sma`/`ema`/`wma`/`vwap`/`bollingerBands`/`computeIndicator` helpers are exported from
+the core (e.g. feed `bollingerBands(values).{upper,mid,lower}` as three overlays).
+
+### Realtime feeds + lazy history (any data source)
+
+Connect a chart to a **feed** — a source that serves paged OHLCV history *and* live
+updates — and `connectFeed` handles the latest page, lazy older-history loading on
+left-scroll, and merging live candles (updating the in-progress bucket or appending):
+
+```ts
+import { Chart, connectFeed, hyperliquidFeed, HL_INTERVAL_SECONDS } from "@livo-build/charts";
+
+const chart = new Chart(el, { height: 420 });
+const conn = connectFeed(chart, hyperliquidFeed({ coin: "BTC", interval: "1m" }), {
+  interval: HL_INTERVAL_SECONDS["1m"],
+  pageSize: 500,
+});
+// …later
+conn.disconnect();
+```
+
+Bring your own source by implementing `ChartFeed`:
+
+```ts
+const feed = {
+  loadHistory: ({ interval, before, limit }) => fetchMyCandles(before, limit), // [] at the end
+  subscribe: ({ interval }, onCandle) => mySocket.onCandle(onCandle),          // returns unsubscribe
+};
+```
+
+The chart's right-anchored view means prepending history keeps the visible window
+stable, and the controller only asks for more when you scroll near the start.
+
+## Vanilla / framework-agnostic
+
+```ts
+import { Chart, buildOHLC } from "@livo-build/charts";
+
+const chart = new Chart(containerEl, {
+  height: 420,
+  onCrosshair: (candle) => renderLegend(candle), // null when empty; last candle when idle
+});
+chart.setInterval(300).setChartType("candle");
+chart.setCandles(buildOHLC(trades, 300, { denom: "ETH", ethUsd: 1711.81 }));
+
+// streaming update — view (zoom/pan) is preserved
+chart.setCandles(buildOHLC(moreTrades, 300));
+
+chart.destroy();
+```
+
+### `Chart` API
+
+| Method | Description |
+| --- | --- |
+| `new Chart(container, options?)` | Creates a `<canvas>`, wires interaction, observes resize. |
+| `setCandles(candles)` | Replace the series (each candle has `vol`) and redraw. |
+| `setInterval(seconds)` | Bucket interval — drives time-axis label granularity. |
+| `setChartType("candle" \| "line")` | Switch series style. |
+| `setIndicators(indicators)` | Set the moving-average overlays and redraw. |
+| `setNeedHistory(cb)` | Callback fired when the view nears the start of loaded data (lazy history). |
+| `setHeight(px)` / `setTheme(partial)` | Resize / merge theme overrides. |
+| `resetView()` | Reset zoom/pan (same as double-click). |
+| `destroy()` | Remove listeners, observer and the canvas. |
+
+`ChartOptions`: `height`, `theme`, `initialBars` (120), `minBars` (20),
+`maxBarWidth` (18 — caps candle spacing so sparse series stay tight, right-anchored),
+`volumeRatio` (0.18), `rightPad`/`bottomPad`/`topPad`, `onCrosshair`, `indicators`,
+and `onNeedHistory`.
+
+### Helpers
+
+- `buildOHLC(points, interval, transform?)` — bucket priced trades into OHLC+volume
+  candles. `transform` = `{ denom, ethUsd, flip, supply }` (`supply` → market cap).
+- `transformPrice(p, transform?)` — apply the transform to one price.
+- `sma` / `ema` / `wma` / `vwap` / `bollingerBands` / `computeIndicator` — pure
+  indicator math (aligned to input, null until the window fills).
+- `connectFeed(chart, feed, opts)` — wire a `ChartFeed` (paged history + live stream)
+  to a chart: latest page, lazy older history, live merge. Returns `{ disconnect }`.
+- `hyperliquidFeed({ coin, interval, testnet })` — a ready `ChartFeed` (REST history +
+  WebSocket live). `fetchHyperliquidCandles` / `fetchHlCandleWindow` / `mapHlCandles` /
+  `HL_INTERVAL_SECONDS` are exported for custom fetching.
+- `draw(input)` — the pure render pass (exported for custom hosts/tests); returns the
+  crosshair candle.
+- `DEFAULT_THEME`, `formatValue`, `formatVolume`, `formatTime`.
+
+## Interaction
+
+- **Scroll** over the plot → zoom time; over the price axis → zoom price.
+- **Drag** the plot → pan; drag the time axis → zoom X; drag the price axis → zoom Y.
+- **Hover** → crosshair + price/time axis labels + the OHLCV legend.
+- **Double-click** → reset zoom/pan.
+
+## Design notes
+
+- **No dependencies.** The core is plain canvas 2D + `ResizeObserver`.
+- **Core vs bindings.** `@livo-build/charts` is vanilla (and tailwind-free);
+  `@livo-build/charts/react` adds the toolbar/legend. Add more bindings the same way.
+- **`draw()` is stateless.** All zoom/pan/hover state lives in the `Chart` controller.
+- **Render coalescing.** High-frequency input (drag/hover/wheel) is batched into one
+  `requestAnimationFrame` redraw, and indicator series are precomputed on data change
+  (not per frame) — so panning a large series stays smooth.
+
+## Develop
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm run test        # vitest (OHLC/volume aggregation + transforms)
+npm run build       # tsc → dist/ (index + react entries, with .d.ts)
+```
+
+Published to npm via CI (`.github/workflows/publish-charts.yml`) on push to `main`
+when `packages/charts/**` changes. Bump `version` in `package.json` to release.

package/dist/core/chart.d.ts

@@ -0,0 +1,81 @@
+import type { Candle, ChartOptions, ChartTheme, ChartType, Indicator } from "./types";
+/**
+ * Framework-agnostic candlestick/line chart with a volume panel. Creates and owns a
+ * `<canvas>` inside the given container and wires the interactions:
+ *   - wheel over the plot → zoom the time axis; wheel over the price axis → zoom price
+ *   - drag the plot → pan; drag the time axis → zoom X; drag the price axis → zoom Y
+ *   - hover → crosshair + axis labels, and `onCrosshair(candle)` for an external legend
+ *   - double-click → reset zoom/pan
+ *
+ * ```ts
+ * const chart = new Chart(el, { height: 420, onCrosshair: (c) => renderLegend(c) });
+ * chart.setInterval(300).setCandles(buildOHLC(trades, 300));
+ * chart.setChartType("line");
+ * chart.destroy();
+ * ```
+ * The React wrapper in `@livo-build/charts/react` adds the toolbar (intervals, line/candle,
+ * USD/ETH, price/mcap, fullscreen) on top of this.
+ */
+export declare class Chart {
+    private readonly container;
+    private readonly canvas;
+    private readonly ctx;
+    private readonly ro;
+    private readonly pads;
+    private readonly minBars;
+    private readonly maxBarWidth;
+    private readonly volumeRatio;
+    private readonly onCrosshair?;
+    private theme;
+    private height;
+    private candles;
+    private indicators;
+    /** Indicator values precomputed on data/indicator change (not per frame). */
+    private overlays;
+    private interval;
+    private type;
+    /** requestAnimationFrame handle coalescing high-frequency redraws (0 = none queued). */
+    private raf;
+    private onNeedHistory?;
+    private historyReqLen;
+    private readonly historyThreshold;
+    private width;
+    private view;
+    private yZoom;
+    private hover;
+    private drag;
+    private lastActive;
+    constructor(container: HTMLElement, opts?: ChartOptions);
+    setCandles(candles: Candle[]): this;
+    setInterval(interval: number): this;
+    setChartType(type: ChartType): this;
+    setIndicators(indicators: Indicator[]): this;
+    /** Register a callback fired when the user pans/zooms near the start of loaded data
+     *  (so a feed can lazily load older candles). See connectFeed. */
+    setNeedHistory(cb: (() => void) | undefined): this;
+    setHeight(height: number): this;
+    setTheme(theme: Partial<ChartTheme>): this;
+    resetView(): this;
+    destroy(): void;
+    private get volH();
+    private get plotW();
+    private measure;
+    private clampView;
+    private render;
+    /** Coalesce high-frequency redraws (drag/hover/wheel) into one per animation frame. */
+    private scheduleRender;
+    /** Recompute indicator value-series once when data or config changes (not per frame). */
+    private recomputeOverlays;
+    /** When the view nears the start of loaded data, ask the feed for older candles
+     *  (once per data length, so it stops at the end of history). */
+    private maybeRequestHistory;
+    private region;
+    private readonly onWheel;
+    /** Zoom the time axis by factor `f`, keeping the candle under `cursorX` anchored. */
+    private zoomTimeAt;
+    private readonly onDown;
+    private readonly onMove;
+    private readonly onUp;
+    private readonly onLeave;
+    private readonly onDouble;
+}

package/dist/core/chart.js

@@ -0,0 +1,299 @@
+import { DEFAULT_THEME } from "./theme";
+import { draw } from "./renderer";
+import { computeIndicator, INDICATOR_PALETTE } from "./indicators";
+const DEFAULTS = {
+    height: 420,
+    initialBars: 120,
+    minBars: 20,
+    maxBarWidth: 18,
+    volumeRatio: 0.18,
+    rightPad: 66,
+    bottomPad: 22,
+    topPad: 8,
+};
+/**
+ * Framework-agnostic candlestick/line chart with a volume panel. Creates and owns a
+ * `<canvas>` inside the given container and wires the interactions:
+ *   - wheel over the plot → zoom the time axis; wheel over the price axis → zoom price
+ *   - drag the plot → pan; drag the time axis → zoom X; drag the price axis → zoom Y
+ *   - hover → crosshair + axis labels, and `onCrosshair(candle)` for an external legend
+ *   - double-click → reset zoom/pan
+ *
+ * ```ts
+ * const chart = new Chart(el, { height: 420, onCrosshair: (c) => renderLegend(c) });
+ * chart.setInterval(300).setCandles(buildOHLC(trades, 300));
+ * chart.setChartType("line");
+ * chart.destroy();
+ * ```
+ * The React wrapper in `@livo-build/charts/react` adds the toolbar (intervals, line/candle,
+ * USD/ETH, price/mcap, fullscreen) on top of this.
+ */
+export class Chart {
+    constructor(container, opts = {}) {
+        this.container = container;
+        this.candles = [];
+        this.indicators = [];
+        /** Indicator values precomputed on data/indicator change (not per frame). */
+        this.overlays = [];
+        this.interval = 300;
+        this.type = "candle";
+        /** requestAnimationFrame handle coalescing high-frequency redraws (0 = none queued). */
+        this.raf = 0;
+        this.historyReqLen = -1;
+        this.historyThreshold = 8;
+        this.width = 0;
+        this.yZoom = 1;
+        this.hover = null;
+        this.drag = null;
+        this.lastActive = null;
+        this.onWheel = (e) => {
+            e.preventDefault();
+            const f = e.deltaY > 0 ? 1.15 : 0.87;
+            if (e.offsetX > this.plotW) {
+                this.yZoom = Math.min(50, Math.max(0.2, this.yZoom / f));
+                this.scheduleRender();
+                return;
+            }
+            this.zoomTimeAt(e.offsetX, f);
+            this.scheduleRender();
+        };
+        this.onDown = (e) => {
+            const r = this.canvas.getBoundingClientRect();
+            this.drag = {
+                reg: this.region(e.clientX - r.left, e.clientY - r.top),
+                x: e.clientX,
+                y: e.clientY,
+                offset: this.view.offset,
+                count: this.view.count,
+                yZoom: this.yZoom,
+            };
+        };
+        this.onMove = (e) => {
+            const r = this.canvas.getBoundingClientRect();
+            const d = this.drag;
+            if (d) {
+                if (d.reg === "y") {
+                    this.yZoom = Math.min(50, Math.max(0.2, d.yZoom * Math.exp(-(e.clientY - d.y) / 160)));
+                }
+                else if (d.reg === "x") {
+                    const n = this.candles.length;
+                    this.view = { ...this.view, count: Math.min(Math.max(this.minBars, Math.round(d.count * Math.exp((e.clientX - d.x) / 260))), Math.max(this.minBars, n)) };
+                }
+                else {
+                    const cw = Math.min(this.plotW / Math.max(Math.min(this.view.count, this.candles.length || 1), 1), this.maxBarWidth);
+                    const offset = Math.max(0, Math.min(this.candles.length - this.minBars, d.offset + Math.round((e.clientX - d.x) / cw)));
+                    this.view = { ...this.view, offset };
+                }
+                this.canvas.style.cursor = "grabbing";
+            }
+            this.hover = { x: e.clientX - r.left, y: e.clientY - r.top };
+            this.scheduleRender();
+        };
+        this.onUp = () => {
+            this.drag = null;
+            this.canvas.style.cursor = "crosshair";
+        };
+        this.onLeave = () => {
+            this.drag = null;
+            this.hover = null;
+            this.canvas.style.cursor = "crosshair";
+            this.scheduleRender();
+        };
+        this.onDouble = () => {
+            this.resetView();
+        };
+        this.theme = { ...DEFAULT_THEME, ...(opts.theme || {}) };
+        this.height = opts.height ?? DEFAULTS.height;
+        this.minBars = opts.minBars ?? DEFAULTS.minBars;
+        this.maxBarWidth = opts.maxBarWidth ?? DEFAULTS.maxBarWidth;
+        this.volumeRatio = opts.volumeRatio ?? DEFAULTS.volumeRatio;
+        this.onCrosshair = opts.onCrosshair;
+        this.pads = {
+            right: opts.rightPad ?? DEFAULTS.rightPad,
+            bottom: opts.bottomPad ?? DEFAULTS.bottomPad,
+            top: opts.topPad ?? DEFAULTS.topPad,
+        };
+        this.view = { count: opts.initialBars ?? DEFAULTS.initialBars, offset: 0 };
+        this.indicators = opts.indicators ?? [];
+        this.onNeedHistory = opts.onNeedHistory;
+        const doc = container.ownerDocument;
+        this.canvas = doc.createElement("canvas");
+        this.canvas.style.display = "block";
+        this.canvas.style.cursor = "crosshair";
+        container.appendChild(this.canvas);
+        const ctx = this.canvas.getContext("2d");
+        if (!ctx)
+            throw new Error("livo-charts: 2d canvas context unavailable");
+        this.ctx = ctx;
+        this.canvas.addEventListener("wheel", this.onWheel, { passive: false });
+        this.canvas.addEventListener("mousedown", this.onDown);
+        this.canvas.addEventListener("mousemove", this.onMove);
+        this.canvas.addEventListener("mouseup", this.onUp);
+        this.canvas.addEventListener("mouseleave", this.onLeave);
+        this.canvas.addEventListener("dblclick", this.onDouble);
+        this.ro = new ResizeObserver(() => this.measure());
+        this.ro.observe(container);
+        this.measure();
+    }
+    setCandles(candles) {
+        this.candles = candles;
+        this.recomputeOverlays();
+        this.clampView();
+        this.render();
+        return this;
+    }
+    setInterval(interval) {
+        this.interval = interval;
+        this.render();
+        return this;
+    }
+    setChartType(type) {
+        this.type = type;
+        this.render();
+        return this;
+    }
+    setIndicators(indicators) {
+        this.indicators = indicators;
+        this.recomputeOverlays();
+        this.render();
+        return this;
+    }
+    /** Register a callback fired when the user pans/zooms near the start of loaded data
+     *  (so a feed can lazily load older candles). See connectFeed. */
+    setNeedHistory(cb) {
+        this.onNeedHistory = cb;
+        this.historyReqLen = -1;
+        return this;
+    }
+    setHeight(height) {
+        this.height = height;
+        this.measure();
+        return this;
+    }
+    setTheme(theme) {
+        this.theme = { ...this.theme, ...theme };
+        this.render();
+        return this;
+    }
+    resetView() {
+        this.view = { count: DEFAULTS.initialBars, offset: 0 };
+        this.yZoom = 1;
+        this.clampView();
+        this.render();
+        return this;
+    }
+    destroy() {
+        this.canvas.removeEventListener("wheel", this.onWheel);
+        this.canvas.removeEventListener("mousedown", this.onDown);
+        this.canvas.removeEventListener("mousemove", this.onMove);
+        this.canvas.removeEventListener("mouseup", this.onUp);
+        this.canvas.removeEventListener("mouseleave", this.onLeave);
+        this.canvas.removeEventListener("dblclick", this.onDouble);
+        this.ro.disconnect();
+        if (this.raf)
+            this.container.ownerDocument.defaultView?.cancelAnimationFrame(this.raf);
+        this.canvas.remove();
+    }
+    get volH() {
+        return Math.round((this.height - this.pads.bottom - this.pads.top) * this.volumeRatio);
+    }
+    get plotW() {
+        return this.width - this.pads.right;
+    }
+    measure() {
+        this.width = this.container.clientWidth || this.width;
+        const dpr = this.container.ownerDocument.defaultView?.devicePixelRatio || 1;
+        this.canvas.width = this.width * dpr;
+        this.canvas.height = this.height * dpr;
+        this.canvas.style.width = this.width + "px";
+        this.canvas.style.height = this.height + "px";
+        this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        this.render();
+    }
+    clampView() {
+        const n = this.candles.length;
+        const count = Math.min(Math.max(this.minBars, this.view.count), Math.max(this.minBars, n || this.minBars));
+        const offset = Math.min(Math.max(0, this.view.offset), Math.max(0, n - this.minBars));
+        this.view = { count, offset };
+    }
+    render() {
+        if (!this.width)
+            return;
+        const active = draw({
+            ctx: this.ctx,
+            width: this.width,
+            height: this.height,
+            candles: this.candles,
+            view: this.view,
+            hover: this.hover,
+            interval: this.interval,
+            type: this.type,
+            yZoom: this.yZoom,
+            maxBarWidth: this.maxBarWidth,
+            volH: this.volH,
+            theme: this.theme,
+            pads: this.pads,
+            overlays: this.overlays,
+        });
+        if (this.onCrosshair && active !== this.lastActive) {
+            this.lastActive = active;
+            this.onCrosshair(active);
+        }
+        this.maybeRequestHistory();
+    }
+    /** Coalesce high-frequency redraws (drag/hover/wheel) into one per animation frame. */
+    scheduleRender() {
+        if (this.raf)
+            return;
+        const win = this.container.ownerDocument.defaultView;
+        if (!win || !win.requestAnimationFrame) {
+            this.render();
+            return;
+        }
+        this.raf = win.requestAnimationFrame(() => {
+            this.raf = 0;
+            this.render();
+        });
+    }
+    /** Recompute indicator value-series once when data or config changes (not per frame). */
+    recomputeOverlays() {
+        this.overlays = this.indicators.map((ind, i) => ({
+            color: ind.color || INDICATOR_PALETTE[i % INDICATOR_PALETTE.length],
+            values: computeIndicator(this.candles, ind),
+        }));
+    }
+    /** When the view nears the start of loaded data, ask the feed for older candles
+     *  (once per data length, so it stops at the end of history). */
+    maybeRequestHistory() {
+        if (!this.onNeedHistory || !this.candles.length)
+            return;
+        const end = this.candles.length - this.view.offset;
+        const start = Math.max(0, end - Math.min(this.view.count, this.candles.length));
+        if (start <= this.historyThreshold && this.historyReqLen !== this.candles.length) {
+            this.historyReqLen = this.candles.length;
+            this.onNeedHistory();
+        }
+    }
+    region(x, y) {
+        if (x > this.plotW)
+            return "y";
+        if (y > this.height - this.pads.bottom)
+            return "x";
+        return "plot";
+    }
+    /** Zoom the time axis by factor `f`, keeping the candle under `cursorX` anchored. */
+    zoomTimeAt(cursorX, f) {
+        const n = this.candles.length;
+        if (!n)
+            return;
+        const nVisOld = Math.min(this.view.count, n);
+        const startOld = Math.max(0, n - this.view.offset - nVisOld);
+        const frac = Math.max(0, Math.min(1, cursorX / this.plotW));
+        const absUnder = startOld + Math.round(frac * (nVisOld - 1));
+        const count = Math.round(Math.min(Math.max(this.minBars, this.view.count * f), Math.max(this.minBars, n)));
+        const nVisNew = Math.min(count, n);
+        const startNew = absUnder - Math.round(frac * (nVisNew - 1));
+        const offset = Math.max(0, Math.min(Math.max(0, n - this.minBars), n - startNew - nVisNew));
+        this.view = { count, offset };
+    }
+}

package/dist/core/feed.d.ts

@@ -0,0 +1,43 @@
+import type { Candle } from "./types";
+import type { Chart } from "./chart";
+export interface LoadHistoryParams {
+    /** Bucket interval in seconds. */
+    interval: number;
+    /** Load candles ending strictly before this time (ms epoch). Omit for the latest page. */
+    before?: number;
+    /** Max candles to return. */
+    limit: number;
+}
+export interface ChartFeed {
+    /** Resolve a page of historical candles (ascending by time). Return [] at the end. */
+    loadHistory(params: LoadHistoryParams): Promise<Candle[]>;
+    /** Optional live stream. Call `onUpdate` per candle; return an unsubscribe fn. */
+    subscribe?(params: {
+        interval: number;
+    }, onUpdate: (candle: Candle) => void): () => void;
+}
+export interface ConnectFeedOptions {
+    /** Bucket interval in seconds. */
+    interval: number;
+    /** Candles per history page (default 500). */
+    pageSize?: number;
+    /** Called on every candle-set change (e.g. to update a header). */
+    onCandles?: (candles: Candle[]) => void;
+    /** Called when a history/live load throws. */
+    onError?: (err: unknown) => void;
+}
+export interface FeedConnection {
+    /** Tear down: unsubscribe live + detach the lazy-history hook. */
+    disconnect(): void;
+    /** The current candle buffer (ascending). */
+    candles(): Candle[];
+}
+declare function mergeLive(buf: Candle[], c: Candle): Candle[];
+/**
+ * Wire a {@link ChartFeed} to a {@link Chart}: load the latest page, lazily prepend
+ * older candles when the user scrolls near the start, and merge live updates. The
+ * chart's right-anchored view means prepending history keeps the visible window
+ * stable automatically.
+ */
+export declare function connectFeed(chart: Chart, feed: ChartFeed, opts: ConnectFeedOptions): FeedConnection;
+export { mergeLive as _mergeLive };