@livo-build/charts 0.2.2 → 0.2.4

package/dist/core/indicators.d.ts

@@ -44,6 +44,42 @@ export declare function macd(values: number[], fast?: number, slow?: number, sig
     signal: (number | null)[];
     hist: (number | null)[];
 };
+/**
+ * Stochastic oscillator. `%K = 100·(close − lowestLow) / (highestHigh − lowestLow)` over
+ * `kPeriod` (default 14), optionally smoothed by an SMA of `smooth` (default 1 = "fast"),
+ * and `%D` = SMA(%K, `dPeriod`, default 3). Both bounded 0–100, aligned to input.
+ */
+export declare function stochastic(candles: Candle[], kPeriod?: number, dPeriod?: number, smooth?: number): {
+    k: (number | null)[];
+    d: (number | null)[];
+};
+/**
+ * Average True Range (Wilder) — a volatility measure in price units. TR is the greatest of
+ * (high−low), |high−prevClose|, |low−prevClose|; ATR seeds with the SMA of the first
+ * `period` TRs (default 14) then Wilder-smooths. Aligned to input; null in the warmup.
+ */
+export declare function atr(candles: Candle[], period?: number): (number | null)[];
+/** One price level of a {@link volumeProfile} histogram. `lo`/`hi` bound the bucket. */
+export interface VolumeBucket {
+    lo: number;
+    hi: number;
+    vol: number;
+}
+/** A computed volume-by-price profile: equal-height buckets plus the point of control. */
+export interface VolumeProfileResult {
+    buckets: VolumeBucket[];
+    /** Largest bucket volume (for scaling the bars). */
+    maxVol: number;
+    /** Mid-price of the highest-volume bucket (the Point of Control). */
+    poc: number;
+}
+/**
+ * Volume-by-price histogram. Splits the candles' price range into `buckets` equal bands
+ * and distributes each candle's volume evenly across the bands its low→high spans (so a
+ * wide bar contributes to several levels). Returns the bands, the peak volume, and the
+ * Point of Control (mid-price of the heaviest band).
+ */
+export declare function volumeProfile(candles: Candle[], buckets?: number): VolumeProfileResult;
 /** 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). */

package/dist/core/indicators.js

@@ -155,6 +155,125 @@ export function macd(values, fast = 12, slow = 26, signal = 9) {
     const hist = line.map((m, i) => (m != null && sig[i] != null ? m - sig[i] : null));
     return { macd: line, signal: sig, hist };
 }
+/**
+ * Stochastic oscillator. `%K = 100·(close − lowestLow) / (highestHigh − lowestLow)` over
+ * `kPeriod` (default 14), optionally smoothed by an SMA of `smooth` (default 1 = "fast"),
+ * and `%D` = SMA(%K, `dPeriod`, default 3). Both bounded 0–100, aligned to input.
+ */
+export function stochastic(candles, kPeriod = 14, dPeriod = 3, smooth = 1) {
+    const n = candles.length;
+    const rawK = new Array(n).fill(null);
+    if (!(kPeriod > 0))
+        return { k: rawK, d: rawK.slice() };
+    for (let i = kPeriod - 1; i < n; i++) {
+        let lo = Infinity;
+        let hi = -Infinity;
+        for (let j = i - kPeriod + 1; j <= i; j++) {
+            lo = Math.min(lo, candles[j].l);
+            hi = Math.max(hi, candles[j].h);
+        }
+        const rng = hi - lo;
+        rawK[i] = rng > 0 ? (100 * (candles[i].c - lo)) / rng : 100;
+    }
+    const k = smooth > 1 ? smaNullable(rawK, smooth) : rawK;
+    const d = smaNullable(k, dPeriod);
+    return { k, d };
+}
+/** SMA over a series that may contain leading nulls (used to smooth %K / %D). */
+function smaNullable(series, period) {
+    const out = new Array(series.length).fill(null);
+    if (!(period > 0))
+        return out;
+    let sum = 0;
+    let cnt = 0;
+    const win = [];
+    for (let i = 0; i < series.length; i++) {
+        const v = series[i];
+        if (v == null) {
+            // a null breaks the window — restart so we never average across a gap.
+            sum = 0;
+            cnt = 0;
+            win.length = 0;
+            continue;
+        }
+        win.push(v);
+        sum += v;
+        cnt++;
+        if (cnt > period)
+            sum -= win[cnt - period - 1];
+        if (cnt >= period)
+            out[i] = sum / period;
+    }
+    return out;
+}
+/**
+ * Average True Range (Wilder) — a volatility measure in price units. TR is the greatest of
+ * (high−low), |high−prevClose|, |low−prevClose|; ATR seeds with the SMA of the first
+ * `period` TRs (default 14) then Wilder-smooths. Aligned to input; null in the warmup.
+ */
+export function atr(candles, period = 14) {
+    const n = candles.length;
+    const out = new Array(n).fill(null);
+    if (!(period > 0) || n <= period)
+        return out;
+    const tr = new Array(n).fill(0);
+    tr[0] = candles[0].h - candles[0].l;
+    for (let i = 1; i < n; i++) {
+        const pc = candles[i - 1].c;
+        tr[i] = Math.max(candles[i].h - candles[i].l, Math.abs(candles[i].h - pc), Math.abs(candles[i].l - pc));
+    }
+    // seed = SMA of the first `period` TRs (placed at index `period`, like RSI's warmup).
+    let prev = 0;
+    for (let i = 1; i <= period; i++)
+        prev += tr[i];
+    prev /= period;
+    out[period] = prev;
+    for (let i = period + 1; i < n; i++) {
+        prev = (prev * (period - 1) + tr[i]) / period;
+        out[i] = prev;
+    }
+    return out;
+}
+/**
+ * Volume-by-price histogram. Splits the candles' price range into `buckets` equal bands
+ * and distributes each candle's volume evenly across the bands its low→high spans (so a
+ * wide bar contributes to several levels). Returns the bands, the peak volume, and the
+ * Point of Control (mid-price of the heaviest band).
+ */
+export function volumeProfile(candles, buckets = 24) {
+    const B = Math.max(1, Math.round(buckets));
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const c of candles) {
+        lo = Math.min(lo, c.l);
+        hi = Math.max(hi, c.h);
+    }
+    if (!isFinite(lo) || !isFinite(hi) || hi <= lo) {
+        const v = candles.reduce((a, c) => a + (c.vol || 0), 0);
+        const p = isFinite(lo) ? lo : 0;
+        return { buckets: [{ lo: p, hi: p, vol: v }], maxVol: v, poc: p };
+    }
+    const step = (hi - lo) / B;
+    const bins = new Array(B).fill(0);
+    for (const c of candles) {
+        const from = Math.max(0, Math.min(B - 1, Math.floor((c.l - lo) / step)));
+        const to = Math.max(0, Math.min(B - 1, Math.floor((c.h - lo) / step)));
+        const span = to - from + 1;
+        const share = (c.vol || 0) / span;
+        for (let b = from; b <= to; b++)
+            bins[b] += share;
+    }
+    let maxVol = 0;
+    let pocIdx = 0;
+    const out = bins.map((vol, i) => {
+        if (vol > maxVol) {
+            maxVol = vol;
+            pocIdx = i;
+        }
+        return { lo: lo + i * step, hi: lo + (i + 1) * step, vol };
+    });
+    return { buckets: out, maxVol: maxVol || 1, poc: lo + (pocIdx + 0.5) * step };
+}
 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") {

package/dist/core/ohlc.d.ts

@@ -7,3 +7,13 @@ export declare function transformPrice(p: number, t?: PriceTransform): number;
  * 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[];
+/**
+ * Heikin-Ashi transform: smoothed candles that filter noise and make trends easier to
+ * read. Each output keeps the input's `time` and `vol`; only OHLC are recomputed:
+ *   HA_close = (o+h+l+c)/4
+ *   HA_open  = (prevHA_open + prevHA_close)/2   (seed: (o+c)/2)
+ *   HA_high  = max(h, HA_open, HA_close)
+ *   HA_low   = min(l, HA_open, HA_close)
+ * Input must be ascending by time; output is aligned 1:1.
+ */
+export declare function heikinAshi(candles: Candle[]): Candle[];

package/dist/core/ohlc.js

@@ -34,3 +34,33 @@ export function buildOHLC(points, interval, transform = {}) {
     }
     return [...buckets.values()].sort((a, b) => a.time - b.time);
 }
+/**
+ * Heikin-Ashi transform: smoothed candles that filter noise and make trends easier to
+ * read. Each output keeps the input's `time` and `vol`; only OHLC are recomputed:
+ *   HA_close = (o+h+l+c)/4
+ *   HA_open  = (prevHA_open + prevHA_close)/2   (seed: (o+c)/2)
+ *   HA_high  = max(h, HA_open, HA_close)
+ *   HA_low   = min(l, HA_open, HA_close)
+ * Input must be ascending by time; output is aligned 1:1.
+ */
+export function heikinAshi(candles) {
+    const out = new Array(candles.length);
+    let prevO = 0;
+    let prevC = 0;
+    for (let i = 0; i < candles.length; i++) {
+        const c = candles[i];
+        const haC = (c.o + c.h + c.l + c.c) / 4;
+        const haO = i === 0 ? (c.o + c.c) / 2 : (prevO + prevC) / 2;
+        out[i] = {
+            time: c.time,
+            o: haO,
+            h: Math.max(c.h, haO, haC),
+            l: Math.min(c.l, haO, haC),
+            c: haC,
+            vol: c.vol,
+        };
+        prevO = haO;
+        prevC = haC;
+    }
+    return out;
+}

package/dist/core/polymarket.d.ts

@@ -0,0 +1,53 @@
+import type { Point } from "./types";
+import type { ChartFeed } from "./feed";
+/** The public Polymarket CLOB host. */
+export declare const POLYMARKET_CLOB = "https://clob.polymarket.com";
+/** One raw `/prices-history` row: `t` is unix seconds, `p` is the price (probability 0–1). */
+export interface PolyHistoryPoint {
+    t: number;
+    p: number;
+}
+export interface FetchPolyHistoryOptions {
+    /** The CLOB token id (an outcome of a market — see Polymarket's resolveMarket). */
+    tokenId: string;
+    /** Window start (unix seconds). Omit to use `interval` instead. */
+    startTs?: number;
+    /** Window end (unix seconds). Omit to use `interval` instead. */
+    endTs?: number;
+    /** Coarse window when `startTs`/`endTs` aren't given (default "1d"). */
+    interval?: "1m" | "1h" | "6h" | "1d" | "1w" | "max";
+    /** Resolution in minutes per point (e.g. 60 = hourly points). */
+    fidelity?: number;
+    /** Override the CLOB host. */
+    host?: string;
+}
+/** Fetch raw Polymarket price-history points (probabilities) for a token. */
+export declare function fetchPolymarketPriceHistory(opts: FetchPolyHistoryOptions): Promise<Point[]>;
+export interface PolymarketFeedOptions {
+    /** The CLOB token id to chart. */
+    tokenId: string;
+    /** Candle bucket size in seconds (default 3600 = 1h). Drives the price-history fidelity. */
+    bucketSeconds?: number;
+    /** Override the CLOB host. */
+    host?: string;
+    /** Live poll cadence in ms (default 30s; 0 disables the live poll). */
+    refetchMs?: number;
+    /**
+     * Optional Livo indexer base (e.g. "https://polymarket.livo.build"). When set (and
+     * EventSource is available), the live candle is driven by the indexer's `/stream` SSE
+     * — INSTANT updates on every price/trade — instead of the 30s history poll. History
+     * still loads from the public CLOB, so this is a pure realtime upgrade. Omit to keep
+     * the dependency-free poll-only behavior.
+     */
+    liveUrl?: string;
+    /** Override "now" (ms) — for tests/determinism. */
+    now?: number;
+}
+/**
+ * A {@link ChartFeed} for a Polymarket outcome: paged price history bucketed into OHLC
+ * candles, plus a "live" candle. By default the latest bucket is re-fetched on an
+ * interval (Polymarket has no public candle socket). Pass `liveUrl` (a Livo indexer) to
+ * upgrade the live candle to INSTANT SSE updates. Price-history has no volume, so
+ * history candles carry `vol: 0`. Pass it to `connectFeed` with `bucketSeconds`.
+ */
+export declare function polymarketFeed(opts: PolymarketFeedOptions): ChartFeed;

package/dist/core/polymarket.js

@@ -0,0 +1,173 @@
+// Polymarket adapter — chart any prediction-market outcome from the public CLOB
+// price-history endpoint. Dependency-free (uses the global fetch); no API key needed
+// for read-only price history. Prices are probabilities in [0, 1].
+//
+//   import { Chart, connectFeed, polymarketFeed } from "@livo-build/charts";
+//   const chart = new Chart(el, { height: 420 });
+//   connectFeed(chart, polymarketFeed({ tokenId, bucketSeconds: 3600 }), { interval: 3600 });
+import { buildOHLC } from "./ohlc";
+/** The public Polymarket CLOB host. */
+export const POLYMARKET_CLOB = "https://clob.polymarket.com";
+/** fetch with an abort timeout so a stalled CLOB request can't wedge lazy-loading forever. */
+async function fetchT(input, init = {}, timeoutMs = 12000) {
+    const ac = typeof AbortController !== "undefined" ? new AbortController() : null;
+    const timer = ac ? setTimeout(() => ac.abort(), timeoutMs) : undefined;
+    try {
+        return await fetch(input, ac ? { ...init, signal: ac.signal } : init);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Fetch raw Polymarket price-history points (probabilities) for a token. */
+export async function fetchPolymarketPriceHistory(opts) {
+    const host = opts.host ?? POLYMARKET_CLOB;
+    const p = new URLSearchParams({ market: opts.tokenId });
+    if (opts.startTs != null && opts.endTs != null) {
+        p.set("startTs", String(Math.floor(opts.startTs)));
+        p.set("endTs", String(Math.floor(opts.endTs)));
+    }
+    else {
+        p.set("interval", opts.interval ?? "1d");
+    }
+    if (opts.fidelity)
+        p.set("fidelity", String(Math.max(1, Math.round(opts.fidelity))));
+    const res = await fetchT(`${host}/prices-history?${p.toString()}`);
+    if (!res.ok)
+        throw new Error("Polymarket prices-history " + res.status);
+    const json = (await res.json());
+    return (json.history ?? []).map((h) => ({ t: h.t, p: h.p, v: 0 }));
+}
+/**
+ * A {@link ChartFeed} for a Polymarket outcome: paged price history bucketed into OHLC
+ * candles, plus a "live" candle. By default the latest bucket is re-fetched on an
+ * interval (Polymarket has no public candle socket). Pass `liveUrl` (a Livo indexer) to
+ * upgrade the live candle to INSTANT SSE updates. Price-history has no volume, so
+ * history candles carry `vol: 0`. Pass it to `connectFeed` with `bucketSeconds`.
+ */
+export function polymarketFeed(opts) {
+    const secs = opts.bucketSeconds ?? 3600;
+    const host = opts.host ?? POLYMARKET_CLOB;
+    const tokenId = opts.tokenId;
+    const fidelity = Math.max(1, Math.round(secs / 60));
+    const ES = globalThis.EventSource;
+    return {
+        async loadHistory({ before, limit }) {
+            const endTs = Math.floor((before ?? opts.now ?? Date.now()) / 1000);
+            const startTs = endTs - secs * limit;
+            const points = await fetchPolymarketPriceHistory({ tokenId, host, startTs, endTs, fidelity });
+            return buildOHLC(points, secs);
+        },
+        subscribe(_params, onUpdate) {
+            // Poll the latest buckets from the public CLOB (the default + the SSE fallback).
+            const startPoll = () => {
+                const ms = opts.refetchMs ?? 30000;
+                if (ms <= 0)
+                    return () => { };
+                let stopped = false;
+                let timer;
+                const tick = async () => {
+                    if (stopped)
+                        return;
+                    try {
+                        const endTs = Math.floor((opts.now ?? Date.now()) / 1000);
+                        const points = await fetchPolymarketPriceHistory({ tokenId, host, startTs: endTs - secs * 3, endTs, fidelity });
+                        const candles = buildOHLC(points, secs);
+                        const last = candles[candles.length - 1];
+                        if (last && !stopped)
+                            onUpdate(last);
+                    }
+                    catch {
+                        /* transient fetch error — try again next tick */
+                    }
+                    if (!stopped)
+                        timer = setTimeout(tick, ms);
+                };
+                timer = setTimeout(tick, ms);
+                return () => {
+                    stopped = true;
+                    if (timer)
+                        clearTimeout(timer);
+                };
+            };
+            // Realtime via the Livo indexer's SSE stream (instant), when configured + available.
+            // Falls back to polling if the stream can't connect (e.g. the indexer is down).
+            if (opts.liveUrl && ES)
+                return subscribeIndexerSse(opts.liveUrl, tokenId, secs, opts.now, onUpdate, ES, startPoll);
+            return startPoll();
+        },
+    };
+}
+/**
+ * Drive the live candle from Livo's Polymarket indexer SSE (`/stream`): `price` frames
+ * (mid) and `trade` frames (price + size → volume) for our token roll the in-progress
+ * bucket. If the stream can't connect (indexer down), it falls back to `startPoll` so the
+ * chart still gets a building candle. Returns an unsubscribe fn.
+ */
+function subscribeIndexerSse(liveUrl, tokenId, secs, nowOverride, onUpdate, ES, startPoll) {
+    let cur = null;
+    let gotMessage = false;
+    let pollStop;
+    const es = new ES(`${liveUrl.replace(/\/$/, "")}/stream`);
+    // If the stream errors before ever delivering a frame, it's almost certainly down —
+    // close it and fall back to the poll. (A drop AFTER messages auto-reconnects via ES.)
+    es.onerror = () => {
+        if (!gotMessage && !pollStop) {
+            try {
+                es.close();
+            }
+            catch {
+                /* already closing */
+            }
+            pollStop = startPoll();
+        }
+    };
+    const tick = (price, vol = 0) => {
+        gotMessage = true;
+        if (!(price > 0) || !isFinite(price))
+            return;
+        const nowSec = Math.floor((nowOverride ?? Date.now()) / 1000);
+        const bt = Math.floor(nowSec / secs) * secs;
+        if (!cur || bt > cur.time)
+            cur = { time: bt, o: price, h: price, l: price, c: price, vol };
+        else {
+            cur.h = Math.max(cur.h, price);
+            cur.l = Math.min(cur.l, price);
+            cur.c = price;
+            cur.vol += vol;
+        }
+        onUpdate({ ...cur });
+    };
+    const onPrice = (ev) => {
+        try {
+            const d = JSON.parse(ev.data);
+            if (d.tokenId === tokenId)
+                tick(d.mid || d.last || 0);
+        }
+        catch {
+            /* ignore malformed frame */
+        }
+    };
+    const onTrade = (ev) => {
+        try {
+            const d = JSON.parse(ev.data);
+            if (d.tokenId === tokenId && d.price)
+                tick(d.price, d.size || 0);
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    es.addEventListener("price", onPrice);
+    es.addEventListener("trade", onTrade);
+    return () => {
+        try {
+            es.close();
+        }
+        catch {
+            /* already closed */
+        }
+        pollStop?.();
+    };
+}

package/dist/core/renderer.d.ts

@@ -1,4 +1,4 @@
-import type { Candle, ChartTheme, ChartType, Drawing, Indicator, Oscillator } from "./types";
+import type { Candle, ChartTheme, ChartType, Drawing, Indicator, Oscillator, VolumeProfileConfig } from "./types";
 /**
  * Width of one candle slot (px). By default the slot is capped at `maxBarWidth` and the
  * series is right-anchored — sparse data stays tight in the corner. With `fitContent`,
@@ -8,13 +8,17 @@ import type { Candle, ChartTheme, ChartType, Drawing, Indicator, Oscillator } fr
 export declare function slotWidth(plotW: number, count: number, maxBarWidth: number, fitContent?: boolean): number;
 /** Convert a `#rrggbb` color to `rgba(...)` with the given alpha (passes other formats through). */
 export declare function withAlpha(color: string, alpha: number): string;
-/** The visible candle window (which slice is on screen and the per-candle slot width). */
+/** The visible candle window (which slice is on screen and the per-candle slot width).
+ *  A negative `view.offset` scrolls past the newest candle into the future: `end` exceeds
+ *  the data length and `rightGap` counts the empty slots between the newest candle and the
+ *  right edge (so the user can pull the current price left of the edge / toward center). */
 export declare function windowOf(candles: Candle[], view: Viewport, plotW: number, maxBarWidth: number, fitContent?: boolean): {
     start: number;
     end: number;
     vis: Candle[];
     n: number;
     count: number;
+    rightGap: number;
     cw: number;
 };
 /**
@@ -31,8 +35,9 @@ export declare function priceScale(vis: Candle[], yZoom: number, logScale: boole
     lo: number;
     hi: number;
 };
-/** Time ↔ pixel mapping for the visible window (candle index and arbitrary unix-second time). */
-export declare function timeScale(vis: Candle[], n: number, cw: number, plotW: number, interval: number): {
+/** Time ↔ pixel mapping for the visible window (candle index and arbitrary unix-second time).
+ *  `rightGap` (empty future slots, see windowOf) shifts the candles left of the right edge. */
+export declare function timeScale(vis: Candle[], n: number, cw: number, plotW: number, interval: number, rightGap?: number): {
     xOf: (j: number) => number;
     xOfTime: (t: number) => number;
     timeOfX: (x: number) => number;
@@ -65,6 +70,10 @@ export interface RenderInput {
     width: number;
     height: number;
     candles: Candle[];
+    /** Candles used for the price series + axis (Heikin-Ashi in `heikin` mode). The Chart
+     *  controller precomputes this on data/type change; if omitted, `draw` derives it. The
+     *  RAW `candles` still drive volume, indicators, oscillators and the crosshair readout. */
+    priceCandles?: Candle[];
     view: Viewport;
     hover: {
         x: number;
@@ -88,6 +97,12 @@ export interface RenderInput {
     overlays?: ResolvedOverlay[];
     /** logarithmic price axis — equal vertical distance = equal % move. */
     logScale?: boolean;
+    /** centered text when there are no candles (default "no priced trades yet"; "" = nothing). */
+    emptyText?: string;
+    /** reference price for the `baseline` chart type (default: the first visible candle's close). */
+    baselinePrice?: number;
+    /** volume-by-price histogram drawn on the price pane (default off). */
+    volumeProfile?: VolumeProfileConfig;
     /** spread candles across the full plot width instead of right-anchoring at a capped slot. */
     fitContent?: boolean;
     /** y-axis price label formatter (default: range-aware {@link formatAxisValue}). */