@livo-build/charts 0.2.1

package/dist/core/feed.js

@@ -0,0 +1,87 @@
+// Feed connector — drive a Chart from a data source that can serve paged OHLCV
+// history AND live updates. `connectFeed` does the plumbing: an initial page, lazy
+// loading of older candles as the user scrolls left, and merging live candles
+// (updating the in-progress bucket or appending a new one). Dependency-free.
+// Merge a candle into an ascending buffer: replace the same-time bucket, or append
+// a strictly-newer one. Returns a NEW array iff something changed, else the same ref.
+function mergeLive(buf, c) {
+    const last = buf[buf.length - 1];
+    if (last && c.time === last.time) {
+        const next = buf.slice();
+        next[next.length - 1] = c;
+        return next;
+    }
+    if (!last || c.time > last.time)
+        return [...buf, c];
+    return buf; // stale (older than last) — ignore
+}
+/**
+ * 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 function connectFeed(chart, feed, opts) {
+    const limit = opts.pageSize ?? 500;
+    let buf = [];
+    let loadingOlder = false;
+    let exhausted = false;
+    let unsub;
+    let live = true;
+    const push = (next) => {
+        buf = next;
+        if (!live)
+            return;
+        chart.setCandles(buf);
+        opts.onCandles?.(buf);
+    };
+    const loadOlder = async () => {
+        if (loadingOlder || exhausted)
+            return;
+        loadingOlder = true;
+        try {
+            const before = buf.length ? buf[0].time * 1000 : undefined;
+            const older = await feed.loadHistory({ interval: opts.interval, before, limit });
+            const seen = new Set(buf.map((c) => c.time));
+            const fresh = older.filter((c) => !seen.has(c.time)).sort((a, b) => a.time - b.time);
+            if (fresh.length === 0)
+                exhausted = true;
+            else
+                push([...fresh, ...buf]);
+        }
+        catch (e) {
+            opts.onError?.(e);
+        }
+        finally {
+            loadingOlder = false;
+        }
+    };
+    chart.setInterval(opts.interval);
+    chart.setNeedHistory(() => void loadOlder());
+    // initial page + live subscription
+    void (async () => {
+        try {
+            const first = await feed.loadHistory({ interval: opts.interval, limit });
+            push(first.slice().sort((a, b) => a.time - b.time));
+        }
+        catch (e) {
+            opts.onError?.(e);
+        }
+        if (feed.subscribe) {
+            unsub = feed.subscribe({ interval: opts.interval }, (c) => {
+                const next = mergeLive(buf, c);
+                if (next !== buf)
+                    push(next);
+            });
+        }
+    })();
+    return {
+        disconnect() {
+            live = false;
+            chart.setNeedHistory(undefined);
+            unsub?.();
+        },
+        candles: () => buf,
+    };
+}
+export { mergeLive as _mergeLive };

package/dist/core/format.d.ts

@@ -0,0 +1,6 @@
+/** Compact value formatter: large numbers grouped (K/M/B), small numbers to significant digits. */
+export declare function formatValue(v: number): string;
+/** Volume formatter with a leading `$`. */
+export declare function formatVolume(v: number): string;
+/** Axis time label whose granularity follows the bucket `interval` (seconds). */
+export declare function formatTime(t: number, interval: number): string;

package/dist/core/format.js

@@ -0,0 +1,40 @@
+/** Compact value formatter: large numbers grouped (K/M/B), small numbers to significant digits. */
+export function formatValue(v) {
+    if (!isFinite(v))
+        return "-";
+    const a = Math.abs(v);
+    if (a >= 1e9)
+        return (v / 1e9).toFixed(2) + "B";
+    if (a >= 1e6)
+        return (v / 1e6).toFixed(2) + "M";
+    if (a >= 1e3)
+        return (v / 1e3).toFixed(2) + "K";
+    if (a >= 1)
+        return v.toFixed(2);
+    if (a > 0)
+        return v.toPrecision(4);
+    return "0";
+}
+/** Volume formatter with a leading `$`. */
+export function formatVolume(v) {
+    const a = Math.abs(v);
+    if (a >= 1e9)
+        return "$" + (v / 1e9).toFixed(1) + "B";
+    if (a >= 1e6)
+        return "$" + (v / 1e6).toFixed(1) + "M";
+    if (a >= 1e3)
+        return "$" + (v / 1e3).toFixed(1) + "K";
+    return "$" + v.toFixed(0);
+}
+/** Axis time label whose granularity follows the bucket `interval` (seconds). */
+export function formatTime(t, interval) {
+    const d = new Date(t * 1000);
+    const p = (n) => String(n).padStart(2, "0");
+    if (interval < 60)
+        return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+    if (interval < 3600)
+        return `${p(d.getHours())}:${p(d.getMinutes())}`;
+    if (interval < 86400)
+        return `${d.getMonth() + 1}/${d.getDate()} ${p(d.getHours())}:${p(d.getMinutes())}`;
+    return `${d.getMonth() + 1}/${d.getDate()}`;
+}

package/dist/core/indicators.d.ts

@@ -0,0 +1,36 @@
+import type { Candle, Indicator, PriceSource } from "./types";
+/** Default overlay colors, assigned by indicator position when none is given. */
+export declare const INDICATOR_PALETTE: string[];
+/**
+ * Simple moving average. Output is aligned to the input (same length); the first
+ * `period - 1` entries are null (not enough history). Uses a rolling sum — O(n).
+ */
+export declare function sma(values: number[], period: number): (number | null)[];
+/**
+ * Exponential moving average, seeded with the SMA of the first `period` values
+ * (the conventional seed). Aligned to input; first `period - 1` entries are null.
+ */
+export declare function ema(values: number[], period: number): (number | null)[];
+/**
+ * Weighted moving average — linear weights 1..period (most recent heaviest).
+ * Aligned to input; first `period - 1` entries are null.
+ */
+export declare function wma(values: number[], period: number): (number | null)[];
+/**
+ * Volume-weighted average price, cumulative from the start of the series. Uses the
+ * typical price (h+l+c)/3 weighted by volume. Single line aligned to candles.
+ */
+export declare function vwap(candles: Candle[]): (number | null)[];
+/**
+ * Bollinger Bands: a `period` SMA (mid) ± `mult` standard deviations. Returns three
+ * series aligned to input — feed them as three overlays for a band.
+ */
+export declare function bollingerBands(values: number[], period?: number, mult?: number): {
+    upper: (number | null)[];
+    mid: (number | null)[];
+    lower: (number | null)[];
+};
+/** Pull a price series (default close) out of candles. */
+export declare function sourceValues(candles: Candle[], source?: PriceSource): number[];
+/** Compute an indicator's value series, aligned to `candles` (null where undefined). */
+export declare function computeIndicator(candles: Candle[], ind: Indicator): (number | null)[];

package/dist/core/indicators.js

@@ -0,0 +1,112 @@
+/** Default overlay colors, assigned by indicator position when none is given. */
+export const INDICATOR_PALETTE = ["#2962ff", "#ff9800", "#ab47bc", "#26a69a", "#ef5350"];
+/**
+ * Simple moving average. Output is aligned to the input (same length); the first
+ * `period - 1` entries are null (not enough history). Uses a rolling sum — O(n).
+ */
+export function sma(values, period) {
+    const out = new Array(values.length).fill(null);
+    if (!(period > 0))
+        return out;
+    let sum = 0;
+    for (let i = 0; i < values.length; i++) {
+        sum += values[i];
+        if (i >= period)
+            sum -= values[i - period];
+        if (i >= period - 1)
+            out[i] = sum / period;
+    }
+    return out;
+}
+/**
+ * Exponential moving average, seeded with the SMA of the first `period` values
+ * (the conventional seed). Aligned to input; first `period - 1` entries are null.
+ */
+export function ema(values, period) {
+    const out = new Array(values.length).fill(null);
+    if (!(period > 0) || values.length < period)
+        return out;
+    const k = 2 / (period + 1);
+    let seed = 0;
+    for (let i = 0; i < period; i++)
+        seed += values[i];
+    let prev = seed / period;
+    out[period - 1] = prev;
+    for (let i = period; i < values.length; i++) {
+        prev = values[i] * k + prev * (1 - k);
+        out[i] = prev;
+    }
+    return out;
+}
+/**
+ * Weighted moving average — linear weights 1..period (most recent heaviest).
+ * Aligned to input; first `period - 1` entries are null.
+ */
+export function wma(values, period) {
+    const out = new Array(values.length).fill(null);
+    if (!(period > 0))
+        return out;
+    const denom = (period * (period + 1)) / 2;
+    for (let i = period - 1; i < values.length; i++) {
+        let s = 0;
+        for (let k = 0; k < period; k++)
+            s += values[i - period + 1 + k] * (k + 1);
+        out[i] = s / denom;
+    }
+    return out;
+}
+/**
+ * Volume-weighted average price, cumulative from the start of the series. Uses the
+ * typical price (h+l+c)/3 weighted by volume. Single line aligned to candles.
+ */
+export function vwap(candles) {
+    const out = new Array(candles.length).fill(null);
+    let cumPV = 0;
+    let cumV = 0;
+    for (let i = 0; i < candles.length; i++) {
+        const tp = (candles[i].h + candles[i].l + candles[i].c) / 3;
+        const v = candles[i].vol || 0;
+        cumPV += tp * v;
+        cumV += v;
+        out[i] = cumV > 0 ? cumPV / cumV : tp;
+    }
+    return out;
+}
+/**
+ * Bollinger Bands: a `period` SMA (mid) ± `mult` standard deviations. Returns three
+ * series aligned to input — feed them as three overlays for a band.
+ */
+export function bollingerBands(values, period = 20, mult = 2) {
+    const mid = sma(values, period);
+    const upper = new Array(values.length).fill(null);
+    const lower = new Array(values.length).fill(null);
+    for (let i = period - 1; i < values.length; i++) {
+        const m = mid[i];
+        if (m == null)
+            continue;
+        let sq = 0;
+        for (let k = i - period + 1; k <= i; k++)
+            sq += (values[k] - m) ** 2;
+        const sd = Math.sqrt(sq / period);
+        upper[i] = m + mult * sd;
+        lower[i] = m - mult * sd;
+    }
+    return { upper, mid, lower };
+}
+const SOURCE_KEY = { open: "o", high: "h", low: "l", close: "c" };
+/** Pull a price series (default close) out of candles. */
+export function sourceValues(candles, source = "close") {
+    const key = SOURCE_KEY[source];
+    return candles.map((c) => c[key]);
+}
+/** Compute an indicator's value series, aligned to `candles` (null where undefined). */
+export function computeIndicator(candles, ind) {
+    if (ind.type === "vwap")
+        return vwap(candles);
+    const vals = sourceValues(candles, ind.source);
+    if (ind.type === "ema")
+        return ema(vals, ind.period);
+    if (ind.type === "wma")
+        return wma(vals, ind.period);
+    return sma(vals, ind.period);
+}

package/dist/core/live.d.ts

@@ -0,0 +1,60 @@
+import type { Candle } from "./types";
+import type { ChartFeed } from "./feed";
+/** A raw Hyperliquid candleSnapshot row (numeric fields are strings; `t`/`T` are ms). */
+export interface HlRawCandle {
+    t: number;
+    T: number;
+    s: string;
+    i: string;
+    o: string;
+    c: string;
+    h: string;
+    l: string;
+    v: string;
+    n: number;
+}
+/** Map Hyperliquid candleSnapshot rows to chart Candles (ms→seconds, string→number). */
+export declare function mapHlCandles(rows: HlRawCandle[]): Candle[];
+/** Hyperliquid candle interval → bucket seconds (drives the chart's time axis). */
+export declare const HL_INTERVAL_SECONDS: Record<string, number>;
+export interface FetchHlCandlesOptions {
+    coin: string;
+    /** Hyperliquid interval string (default "1h"). */
+    interval?: string;
+    /** How far back from now to load (default 24h). */
+    lookbackMs?: number;
+    testnet?: boolean;
+    /** Override the API base (e.g. a CORS proxy). */
+    baseUrl?: string;
+    /** Override "now" (ms) — for tests/determinism. */
+    now?: number;
+}
+/** Fetch a Hyperliquid candle window [startTime, endTime] (ms) as chart Candles. */
+export declare function fetchHlCandleWindow(args: {
+    coin: string;
+    interval: string;
+    startTime: number;
+    endTime: number;
+    testnet?: boolean;
+    baseUrl?: string;
+}): Promise<Candle[]>;
+/** Fetch recent Hyperliquid candles for a coin/interval as chart Candles (no key). */
+export declare function fetchHyperliquidCandles(opts: FetchHlCandlesOptions): Promise<Candle[]>;
+export interface HyperliquidFeedOptions {
+    coin: string;
+    /** Hyperliquid interval string (default "1h"). */
+    interval?: string;
+    testnet?: boolean;
+    /** Override the REST base URL. */
+    baseUrl?: string;
+    /** Override the WebSocket URL (default wss://api.hyperliquid[-testnet].xyz/ws). */
+    wsUrl?: string;
+    /** Override "now" (ms) for the latest-page request — for tests/determinism. */
+    now?: number;
+}
+/**
+ * A {@link ChartFeed} backed by Hyperliquid: paged candle history over REST and a
+ * live candle stream over WebSocket (no key). Pass it to `connectFeed` together with
+ * `HL_INTERVAL_SECONDS[interval]` for a realtime, infinitely-scrollable chart.
+ */
+export declare function hyperliquidFeed(opts: HyperliquidFeedOptions): ChartFeed;

package/dist/core/live.js

@@ -0,0 +1,107 @@
+// Live-data adapters — turn an external market-data source into chart Candles.
+// Dependency-free (uses the global fetch). Hyperliquid's public `info` endpoint
+// needs no key, so this works from the browser or a Worker alike.
+/** Map Hyperliquid candleSnapshot rows to chart Candles (ms→seconds, string→number). */
+export function mapHlCandles(rows) {
+    return rows.map((r) => ({
+        time: Math.floor(r.t / 1000),
+        o: +r.o,
+        h: +r.h,
+        l: +r.l,
+        c: +r.c,
+        vol: +r.v,
+    }));
+}
+/** Hyperliquid candle interval → bucket seconds (drives the chart's time axis). */
+export const HL_INTERVAL_SECONDS = {
+    "1m": 60, "3m": 180, "5m": 300, "15m": 900, "30m": 1800,
+    "1h": 3600, "2h": 7200, "4h": 14400, "8h": 28800, "12h": 43200,
+    "1d": 86400, "3d": 259200, "1w": 604800, "1M": 2592000,
+};
+function hlBase(testnet, baseUrl) {
+    return baseUrl ?? (testnet ? "https://api.hyperliquid-testnet.xyz" : "https://api.hyperliquid.xyz");
+}
+/** Fetch a Hyperliquid candle window [startTime, endTime] (ms) as chart Candles. */
+export async function fetchHlCandleWindow(args) {
+    const res = await fetch(hlBase(args.testnet, args.baseUrl) + "/info", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ type: "candleSnapshot", req: { coin: args.coin, interval: args.interval, startTime: args.startTime, endTime: args.endTime } }),
+    });
+    if (!res.ok)
+        throw new Error("Hyperliquid candles " + res.status);
+    return mapHlCandles((await res.json()));
+}
+/** Fetch recent Hyperliquid candles for a coin/interval as chart Candles (no key). */
+export async function fetchHyperliquidCandles(opts) {
+    const { coin, interval = "1h", lookbackMs = 86400000, testnet, baseUrl } = opts;
+    const endTime = opts.now ?? Date.now();
+    return fetchHlCandleWindow({ coin, interval, startTime: endTime - lookbackMs, endTime, testnet, baseUrl });
+}
+/**
+ * A {@link ChartFeed} backed by Hyperliquid: paged candle history over REST and a
+ * live candle stream over WebSocket (no key). Pass it to `connectFeed` together with
+ * `HL_INTERVAL_SECONDS[interval]` for a realtime, infinitely-scrollable chart.
+ */
+export function hyperliquidFeed(opts) {
+    const { coin, interval = "1h", testnet, baseUrl, wsUrl } = opts;
+    const secs = HL_INTERVAL_SECONDS[interval] ?? 3600;
+    return {
+        async loadHistory({ before, limit }) {
+            const endTime = before ?? opts.now ?? Date.now();
+            const startTime = endTime - secs * 1000 * limit;
+            return fetchHlCandleWindow({ coin, interval, startTime, endTime, testnet, baseUrl });
+        },
+        subscribe(_params, onUpdate) {
+            const url = wsUrl ?? (testnet ? "wss://api.hyperliquid-testnet.xyz/ws" : "wss://api.hyperliquid.xyz/ws");
+            let closed = false;
+            let ws = null;
+            let ping;
+            const connect = () => {
+                if (closed)
+                    return;
+                ws = new WebSocket(url);
+                ws.onopen = () => {
+                    ws?.send(JSON.stringify({ method: "subscribe", subscription: { type: "candle", coin, interval } }));
+                    ping = setInterval(() => ws?.readyState === 1 && ws.send(JSON.stringify({ method: "ping" })), 30000);
+                };
+                ws.onmessage = (ev) => {
+                    try {
+                        const m = JSON.parse(typeof ev.data === "string" ? ev.data : "");
+                        if (m.channel === "candle" && m.data)
+                            onUpdate(mapHlCandles([m.data])[0]);
+                    }
+                    catch {
+                        /* ignore malformed frame */
+                    }
+                };
+                ws.onclose = () => {
+                    if (ping)
+                        clearInterval(ping);
+                    if (!closed)
+                        setTimeout(connect, 2000); // reconnect with backoff
+                };
+                ws.onerror = () => {
+                    try {
+                        ws?.close();
+                    }
+                    catch {
+                        /* already closing */
+                    }
+                };
+            };
+            connect();
+            return () => {
+                closed = true;
+                if (ping)
+                    clearInterval(ping);
+                try {
+                    ws?.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            };
+        },
+    };
+}

package/dist/core/ohlc.d.ts

@@ -0,0 +1,9 @@
+import type { Candle, Point, PriceTransform } from "./types";
+/** Apply the denom/flip/supply transform to a single price. Returns 0 for invalid results. */
+export declare function transformPrice(p: number, t?: PriceTransform): number;
+/**
+ * Aggregate priced trades into OHLC+volume candles bucketed by `interval` seconds.
+ * Points may arrive unsorted; output is ascending by time. Trades whose (transformed)
+ * price is non-positive or non-finite are dropped; their volume is dropped with them.
+ */
+export declare function buildOHLC(points: Point[], interval: number, transform?: PriceTransform): Candle[];

package/dist/core/ohlc.js

@@ -0,0 +1,36 @@
+/** Apply the denom/flip/supply transform to a single price. Returns 0 for invalid results. */
+export function transformPrice(p, t = {}) {
+    let v = t.denom === "ETH" && t.ethUsd && t.ethUsd > 0 ? p / t.ethUsd : p;
+    if (t.supply && t.supply > 0)
+        return v * t.supply; // market cap; flip N/A
+    if (t.flip && v > 0)
+        v = 1 / v;
+    return v > 0 && isFinite(v) ? v : 0;
+}
+/**
+ * Aggregate priced trades into OHLC+volume candles bucketed by `interval` seconds.
+ * Points may arrive unsorted; output is ascending by time. Trades whose (transformed)
+ * price is non-positive or non-finite are dropped; their volume is dropped with them.
+ */
+export function buildOHLC(points, interval, transform = {}) {
+    if (!(interval > 0))
+        return [];
+    const rows = points
+        .map((s) => ({ t: s.t, p: transformPrice(s.p, transform), v: s.v || 0 }))
+        .filter((s) => s.p > 0)
+        .sort((a, b) => a.t - b.t);
+    const buckets = new Map();
+    for (const { t, p, v } of rows) {
+        const bt = Math.floor(t / interval) * interval;
+        const b = buckets.get(bt);
+        if (!b)
+            buckets.set(bt, { time: bt, o: p, h: p, l: p, c: p, vol: v });
+        else {
+            b.h = Math.max(b.h, p);
+            b.l = Math.min(b.l, p);
+            b.c = p;
+            b.vol += v;
+        }
+    }
+    return [...buckets.values()].sort((a, b) => a.time - b.time);
+}

package/dist/core/renderer.d.ts

@@ -0,0 +1,49 @@
+import type { Candle, ChartTheme, ChartType, Indicator } from "./types";
+export interface Viewport {
+    /** candles visible. */
+    count: number;
+    /** candles scrolled off the right edge (0 = latest pinned right). */
+    offset: number;
+}
+export interface Pads {
+    right: number;
+    bottom: number;
+    top: number;
+}
+export interface RenderInput {
+    ctx: CanvasRenderingContext2D;
+    width: number;
+    height: number;
+    candles: Candle[];
+    view: Viewport;
+    hover: {
+        x: number;
+        y: number;
+    } | null;
+    interval: number;
+    type: ChartType;
+    /** manual Y-zoom factor (1 = auto-fit). */
+    yZoom: number;
+    /** max candle slot width in px. */
+    maxBarWidth: number;
+    /** volume-panel height in px. */
+    volH: number;
+    theme: ChartTheme;
+    pads: Pads;
+    /** moving-average overlays as config — computed here if `overlays` isn't supplied. */
+    indicators?: Indicator[];
+    /** precomputed overlay value-series (aligned to `candles`); preferred over `indicators`. */
+    overlays?: ResolvedOverlay[];
+}
+/** A resolved indicator overlay: a color and a value-series aligned to the candles. */
+export interface ResolvedOverlay {
+    color: string;
+    values: (number | null)[];
+}
+/**
+ * Pure draw pass: renders grid, axes, the price series (candles or line), a volume
+ * panel, the last-price tag and the crosshair + axis labels. Returns the candle under
+ * the crosshair (or the last candle when idle, or null when empty) so the host can
+ * drive an OHLCV legend. No state is retained between calls.
+ */
+export declare function draw(input: RenderInput): Candle | null;