@livo-build/charts 0.2.1 → 0.2.3

package/dist/core/feed.js

@@ -40,14 +40,24 @@ export function connectFeed(chart, feed, opts) {
             return;
         loadingOlder = true;
         try {
+            const oldest = buf.length ? buf[0].time : Infinity;
             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)
+            // Merge by time. An incoming candle for an EXISTING bucket replaces it — a feed that
+            // re-buckets accumulated data (e.g. signalsFeed) returns a more-complete boundary
+            // candle than the partial one already shown. Strictly-older candles extend history.
+            // Stop only when nothing older than the current oldest arrives.
+            let addedOlder = false;
+            const byTime = new Map(buf.map((c) => [c.time, c]));
+            for (const c of older) {
+                if (c.time < oldest)
+                    addedOlder = true;
+                byTime.set(c.time, c);
+            }
+            if (!addedOlder)
                 exhausted = true;
             else
-                push([...fresh, ...buf]);
+                push([...byTime.values()].sort((a, b) => a.time - b.time));
         }
         catch (e) {
             opts.onError?.(e);
@@ -58,6 +68,10 @@ export function connectFeed(chart, feed, opts) {
     };
     chart.setInterval(opts.interval);
     chart.setNeedHistory(() => void loadOlder());
+    // Clear any candles from a previous connection (e.g. an interval switch reconnects with a
+    // new feed): otherwise the old bars linger, mislabeled at the new interval, until the first
+    // page arrives. Reset to empty so the host's loading state shows instead of stale data.
+    chart.setCandles([]);
     // initial page + live subscription
     void (async () => {
         try {
@@ -67,12 +81,19 @@ export function connectFeed(chart, feed, opts) {
         catch (e) {
             opts.onError?.(e);
         }
-        if (feed.subscribe) {
-            unsub = feed.subscribe({ interval: opts.interval }, (c) => {
+        // Guard against a disconnect that happened DURING the initial load: don't open a live
+        // stream after teardown (it would leak a WebSocket / poll timer), and if disconnect
+        // races the subscribe call, tear the stream down immediately.
+        if (feed.subscribe && live) {
+            const u = feed.subscribe({ interval: opts.interval }, (c) => {
                 const next = mergeLive(buf, c);
                 if (next !== buf)
                     push(next);
             });
+            if (live)
+                unsub = u;
+            else
+                u();
         }
     })();
     return {

package/dist/core/format.d.ts

@@ -1,5 +1,17 @@
-/** Compact value formatter: large numbers grouped (K/M/B), small numbers to significant digits. */
+/**
+ * Value formatter for price axes + OHLC readouts. M/B compaction only kicks in at
+ * a million — between $1k and $1M the FULL grouped number is shown (1,730 not the
+ * lossy "1.73K"), so adjacent axis gridlines and a candle's O/H/L/C stay
+ * distinguishable on mid-priced assets. Trailing zeros are dropped.
+ */
 export declare function formatValue(v: number): string;
+/**
+ * Axis value formatter that adapts decimal precision to the tick `step` so adjacent
+ * gridline labels stay distinct. The compact formatter rounds to 2 decimals (≈$10 at
+ * the "K" scale), which collapses a 1.71K–1.75K axis into duplicate "1.73K"s; passing
+ * the per-tick step keeps just enough digits to separate them (e.g. 1.7350K / 1.7430K).
+ */
+export declare function formatAxisValue(v: number, step?: number): string;
 /** Volume formatter with a leading `$`. */
 export declare function formatVolume(v: number): string;
 /** Axis time label whose granularity follows the bucket `interval` (seconds). */

package/dist/core/format.js

@@ -1,4 +1,9 @@
-/** Compact value formatter: large numbers grouped (K/M/B), small numbers to significant digits. */
+/**
+ * Value formatter for price axes + OHLC readouts. M/B compaction only kicks in at
+ * a million — between $1k and $1M the FULL grouped number is shown (1,730 not the
+ * lossy "1.73K"), so adjacent axis gridlines and a candle's O/H/L/C stay
+ * distinguishable on mid-priced assets. Trailing zeros are dropped.
+ */
 export function formatValue(v) {
     if (!isFinite(v))
         return "-";
@@ -8,13 +13,43 @@ export function formatValue(v) {
     if (a >= 1e6)
         return (v / 1e6).toFixed(2) + "M";
     if (a >= 1e3)
-        return (v / 1e3).toFixed(2) + "K";
+        return v.toLocaleString("en-US", { maximumFractionDigits: a >= 1e4 ? 0 : 2 });
     if (a >= 1)
-        return v.toFixed(2);
+        return v.toLocaleString("en-US", { maximumFractionDigits: a >= 100 ? 2 : 4 });
     if (a > 0)
         return v.toPrecision(4);
     return "0";
 }
+/**
+ * Axis value formatter that adapts decimal precision to the tick `step` so adjacent
+ * gridline labels stay distinct. The compact formatter rounds to 2 decimals (≈$10 at
+ * the "K" scale), which collapses a 1.71K–1.75K axis into duplicate "1.73K"s; passing
+ * the per-tick step keeps just enough digits to separate them (e.g. 1.7350K / 1.7430K).
+ */
+export function formatAxisValue(v, step = 0) {
+    if (!isFinite(v))
+        return "-";
+    const a = Math.abs(v);
+    let div = 1;
+    let suf = "";
+    if (a >= 1e9) {
+        div = 1e9;
+        suf = "B";
+    }
+    else if (a >= 1e6) {
+        div = 1e6;
+        suf = "M";
+    }
+    else if (a >= 1e3) {
+        div = 1e3;
+        suf = "K";
+    }
+    // decimals fine enough to tell two ticks `step` apart; floor at 1 for K/M/B, 2 otherwise.
+    const floor = div > 1 ? 1 : 2;
+    const s = Math.abs(step) / div;
+    const dec = s > 0 ? Math.max(floor === 2 ? 0 : floor, Math.min(8, Math.ceil(-Math.log10(s)))) : floor;
+    return (v / div).toFixed(dec) + suf;
+}
 /** Volume formatter with a leading `$`. */
 export function formatVolume(v) {
     const a = Math.abs(v);

package/dist/core/indicators.d.ts

@@ -30,6 +30,56 @@ export declare function bollingerBands(values: number[], period?: number, mult?:
     mid: (number | null)[];
     lower: (number | null)[];
 };
+/**
+ * Wilder's Relative Strength Index over `period` (default 14). Output aligned to input;
+ * null until `period` deltas are available. Bounded 0–100 (100 when there are no losses).
+ */
+export declare function rsi(values: number[], period?: number): (number | null)[];
+/**
+ * MACD: the difference of a `fast` and `slow` EMA, its `signal` EMA, and the histogram
+ * (macd − signal). Three series aligned to input; null until each EMA's window fills.
+ */
+export declare function macd(values: number[], fast?: number, slow?: number, signal?: number): {
+    macd: (number | null)[];
+    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

@@ -93,6 +93,187 @@ export function bollingerBands(values, period = 20, mult = 2) {
     }
     return { upper, mid, lower };
 }
+/**
+ * Wilder's Relative Strength Index over `period` (default 14). Output aligned to input;
+ * null until `period` deltas are available. Bounded 0–100 (100 when there are no losses).
+ */
+export function rsi(values, period = 14) {
+    const out = new Array(values.length).fill(null);
+    if (!(period > 0) || values.length <= period)
+        return out;
+    let gain = 0;
+    let loss = 0;
+    for (let i = 1; i <= period; i++) {
+        const d = values[i] - values[i - 1];
+        if (d >= 0)
+            gain += d;
+        else
+            loss -= d;
+    }
+    let avgG = gain / period;
+    let avgL = loss / period;
+    out[period] = avgL === 0 ? 100 : 100 - 100 / (1 + avgG / avgL);
+    for (let i = period + 1; i < values.length; i++) {
+        const d = values[i] - values[i - 1];
+        avgG = (avgG * (period - 1) + (d > 0 ? d : 0)) / period;
+        avgL = (avgL * (period - 1) + (d < 0 ? -d : 0)) / period;
+        out[i] = avgL === 0 ? 100 : 100 - 100 / (1 + avgG / avgL);
+    }
+    return out;
+}
+/** EMA over a sparse series (nulls before the first value), seeded with the SMA of the
+ *  first `period` defined values. Used to take the signal EMA of the MACD line. */
+function emaNullable(series, period) {
+    const out = new Array(series.length).fill(null);
+    const start = series.findIndex((v) => v != null);
+    if (start < 0 || !(period > 0) || series.length - start < period)
+        return out;
+    const k = 2 / (period + 1);
+    let seed = 0;
+    for (let i = start; i < start + period; i++)
+        seed += series[i];
+    let prev = seed / period;
+    out[start + period - 1] = prev;
+    for (let i = start + period; i < series.length; i++) {
+        const v = series[i];
+        if (v == null)
+            continue;
+        prev = v * k + prev * (1 - k);
+        out[i] = prev;
+    }
+    return out;
+}
+/**
+ * MACD: the difference of a `fast` and `slow` EMA, its `signal` EMA, and the histogram
+ * (macd − signal). Three series aligned to input; null until each EMA's window fills.
+ */
+export function macd(values, fast = 12, slow = 26, signal = 9) {
+    const ef = ema(values, fast);
+    const es = ema(values, slow);
+    const line = values.map((_, i) => (ef[i] != null && es[i] != null ? ef[i] - es[i] : null));
+    const sig = emaNullable(line, signal);
+    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,44 @@
+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;
+    /** Override "now" (ms) — for tests/determinism. */
+    now?: number;
+}
+/**
+ * A {@link ChartFeed} for a Polymarket outcome: paged price history bucketed into OHLC
+ * candles, plus a polling "live" candle (Polymarket has no public candle socket, so the
+ * latest bucket is re-fetched on an interval). Price-history has no volume, so candles
+ * carry `vol: 0`. Pass it to `connectFeed` with `bucketSeconds` as the interval.
+ */
+export declare function polymarketFeed(opts: PolymarketFeedOptions): ChartFeed;

package/dist/core/polymarket.js

@@ -0,0 +1,92 @@
+// 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 polling "live" candle (Polymarket has no public candle socket, so the
+ * latest bucket is re-fetched on an interval). Price-history has no volume, so candles
+ * carry `vol: 0`. Pass it to `connectFeed` with `bucketSeconds` as the interval.
+ */
+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));
+    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) {
+            const ms = opts.refetchMs ?? 30000;
+            if (ms <= 0)
+                return () => { };
+            let stopped = false;
+            let timer;
+            const tick = async () => {
+                if (stopped)
+                    return;
+                try {
+                    // re-fetch the last few buckets and emit the most recent candle.
+                    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);
+            };
+        },
+    };
+}