@livo-build/charts 0.2.2 → 0.2.3

package/dist/core/renderer.js

@@ -1,5 +1,8 @@
-import { formatAxisValue, formatTime } from "./format";
-import { computeIndicator, sourceValues, bollingerBands, INDICATOR_PALETTE, rsi, macd } from "./indicators";
+import { formatAxisValue, formatTime, formatValue } from "./format";
+import { computeIndicator, sourceValues, bollingerBands, INDICATOR_PALETTE, rsi, macd, stochastic, atr, volumeProfile } from "./indicators";
+import { heikinAshi } from "./ohlc";
+/** Standard Fibonacci retracement ratios (0 and 1 are the anchors themselves). */
+const FIB_LEVELS = [0, 0.236, 0.382, 0.5, 0.618, 0.786, 1];
 /**
  * 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`,
@@ -18,13 +21,17 @@ export function withAlpha(color, alpha) {
     const n = parseInt(m[1], 16);
     return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${alpha})`;
 }
-/** 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 function windowOf(candles, view, plotW, maxBarWidth, fitContent = false) {
     const count = Math.min(view.count, candles.length);
-    const end = candles.length - view.offset;
+    const end = candles.length - view.offset; // virtual right edge (may exceed length when offset < 0)
     const start = Math.max(0, end - count);
-    const vis = candles.slice(start, end);
-    return { start, end, vis, n: vis.length, count, cw: slotWidth(plotW, count, maxBarWidth, fitContent) };
+    const vis = candles.slice(start, Math.min(candles.length, end));
+    const rightGap = Math.max(0, end - candles.length); // empty slots to the right of the newest candle
+    return { start, end, vis, n: vis.length, count, rightGap, cw: slotWidth(plotW, count, maxBarWidth, fitContent) };
 }
 /**
  * Price ↔ pixel mapping for the price pane, shared by the renderer and the drawing-tool
@@ -38,7 +45,9 @@ export function priceScale(vis, yZoom, logScale, top, priceH) {
         hi = Math.max(hi, c.h);
     }
     const log = !!logScale && lo > 0;
-    const fwd = (v) => (log ? Math.log10(v) : v);
+    // In log mode, clamp the forward input to a tiny positive epsilon so an arbitrary drawing
+    // anchor or crosshair price ≤ 0 yields a finite (off-screen) y instead of NaN/-Infinity.
+    const fwd = (v) => (log ? Math.log10(v > 0 ? v : 1e-12) : v);
     const inv = (s) => (log ? 10 ** s : s);
     let sLo = fwd(lo);
     let sHi = fwd(hi);
@@ -51,9 +60,10 @@ export function priceScale(vis, yZoom, logScale, top, priceH) {
     const priceOfY = (y) => inv(sLo + sRng * (1 - (y - top) / priceH));
     return { yOfPrice, priceOfY, fwd, inv, sLo, sRng, lo, hi };
 }
-/** Time ↔ pixel mapping for the visible window (candle index and arbitrary unix-second time). */
-export function timeScale(vis, n, cw, plotW, interval) {
-    const xOf = (j) => plotW - (n - 1 - j) * cw - cw / 2;
+/** 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 function timeScale(vis, n, cw, plotW, interval, rightGap = 0) {
+    const xOf = (j) => plotW - (rightGap + n - 1 - j) * cw - cw / 2;
     const t0 = n ? vis[0].time : 0;
     const iv = interval || 1;
     const xOfTime = (t) => xOf((t - t0) / iv);
@@ -62,14 +72,17 @@ export function timeScale(vis, n, cw, plotW, interval) {
 }
 /** Compute the {@link Projection} for interaction/hit-testing without rendering. */
 export function computeProjection(input) {
-    const { candles, view, pads, width, maxBarWidth, volH, height, yZoom, interval } = input;
+    const { view, pads, width, maxBarWidth, volH, height, yZoom, interval } = input;
+    // The visible price axis is the Heikin-Ashi range in `heikin` mode, so map against it.
+    // Prefer the controller's precomputed series; derive only for standalone callers.
+    const candles = input.priceCandles ?? (input.type === "heikin" ? heikinAshi(input.candles) : input.candles);
     if (!candles.length)
         return null;
     const plotW = width - pads.right;
     const panesH = (input.oscillators ?? []).map((o) => Math.max(24, o.height ?? 84)).reduce((a, b) => a + b, 0);
     const priceH = height - pads.bottom - pads.top - volH - panesH;
-    const { vis, n, cw } = windowOf(candles, view, plotW, maxBarWidth, input.fitContent);
-    const ts = timeScale(vis, n, cw, plotW, interval);
+    const { vis, n, cw, rightGap } = windowOf(candles, view, plotW, maxBarWidth, input.fitContent);
+    const ts = timeScale(vis, n, cw, plotW, interval, rightGap);
     const ps = priceScale(vis, yZoom, !!input.logScale, pads.top, priceH);
     return {
         xOfTime: ts.xOfTime,
@@ -127,21 +140,33 @@ export function draw(input) {
     }
     ctx.font = input.axisFont ?? "10px ui-monospace, monospace";
     ctx.textBaseline = "middle";
-    const fmtTime = input.timeFormat ?? formatTime;
+    let fmtTime = input.timeFormat ?? formatTime;
     // Snap 1px strokes to the pixel grid so gridlines/axes render crisp, not blurred across 2px.
     const crisp = (v) => Math.round(v) + 0.5;
     if (!candles.length) {
-        ctx.fillStyle = theme.axis;
-        ctx.textAlign = "center";
-        ctx.fillText("no priced trades yet", plotW / 2, H / 2);
+        const msg = input.emptyText ?? "no priced trades yet";
+        if (msg) {
+            ctx.fillStyle = theme.axis;
+            ctx.textAlign = "center";
+            ctx.fillText(msg, plotW / 2, H / 2);
+        }
         return null;
     }
     // Slot width fills the plot by default (`fitContent`, on by default in the wrappers and
     // the core Chart) so sparse data spreads out instead of bunching on the right; the candle
     // BODY is capped separately (`maxBodyWidth`) below. fitContent:false caps the slot at
     // `maxBarWidth` and right-anchors (the tight, TradingView-style look).
-    const { start, vis, n, cw } = windowOf(candles, view, plotW, maxBarWidth, input.fitContent);
-    const { xOf, xOfTime } = timeScale(vis, n, cw, plotW, interval);
+    // The price series + axis use Heikin-Ashi candles in `heikin` mode (same times/volumes,
+    // smoothed OHLC); indicators/oscillators still read the RAW closes (`candles`) below.
+    // The controller precomputes this on data/type change (it's O(n)); derive only standalone.
+    const priceCandles = input.priceCandles ?? (type === "heikin" ? heikinAshi(candles) : candles);
+    const { start, vis, n, cw, rightGap } = windowOf(priceCandles, view, plotW, maxBarWidth, input.fitContent);
+    const { xOf, xOfTime } = timeScale(vis, n, cw, plotW, interval, rightGap);
+    // When sub-daily candles span more than a day, time-only labels read as out-of-order across
+    // midnight — include the date (M/D h:m) so the axis stays chronological & legible.
+    if (!input.timeFormat && n > 1 && vis[n - 1].time - vis[0].time > 86400 && interval < 86400) {
+        fmtTime = (t) => formatTime(t, 3600);
+    }
     let vmax = 0;
     for (const c of vis)
         vmax = Math.max(vmax, c.vol);
@@ -241,6 +266,51 @@ export function draw(input) {
         ctx.stroke();
         ctx.lineWidth = 1;
     }
+    else if (type === "baseline") {
+        // Two-tone area around a reference price: above the baseline is "up", below is "down".
+        const priceBot = pads.top + priceH;
+        const baseP = input.baselinePrice ?? vis[0].c;
+        const by = Math.max(pads.top, Math.min(priceBot, yOf(baseP)));
+        const pts = [];
+        for (let j = 0; j < n; j++)
+            pts.push({ x: xOf(j), y: yOf(vis[j].c) });
+        const area = (color, clipTop, clipH) => {
+            if (clipH <= 0)
+                return;
+            ctx.save();
+            ctx.beginPath();
+            ctx.rect(0, clipTop, plotW, clipH);
+            ctx.clip();
+            // faint filled body…
+            ctx.fillStyle = withAlpha(color, 0.16);
+            ctx.beginPath();
+            ctx.moveTo(pts[0].x, by);
+            for (const p of pts)
+                ctx.lineTo(p.x, p.y);
+            ctx.lineTo(pts[n - 1].x, by);
+            ctx.closePath();
+            ctx.fill();
+            // …with a solid line on top (clipped to this side of the baseline)
+            ctx.strokeStyle = color;
+            ctx.lineWidth = 2;
+            ctx.lineJoin = "round";
+            ctx.beginPath();
+            for (let j = 0; j < n; j++)
+                (j ? ctx.lineTo(pts[j].x, pts[j].y) : ctx.moveTo(pts[j].x, pts[j].y));
+            ctx.stroke();
+            ctx.restore();
+        };
+        area(theme.up, pads.top, by - pads.top);
+        area(theme.down, by, priceBot - by);
+        ctx.strokeStyle = theme.grid;
+        ctx.setLineDash([4, 4]);
+        ctx.beginPath();
+        ctx.moveTo(0, crisp(by));
+        ctx.lineTo(plotW, crisp(by));
+        ctx.stroke();
+        ctx.setLineDash([]);
+        ctx.lineWidth = 1;
+    }
     else {
         for (let j = 0; j < n; j++) {
             const c = vis[j];
@@ -257,6 +327,25 @@ export function draw(input) {
             ctx.fillRect(x - bw / 2, Math.min(yo, yc), bw, Math.max(1, Math.abs(yc - yo)));
         }
     }
+    // volume-by-price histogram — translucent bars grown leftward from the right gutter,
+    // peaked at the Point of Control. Computed over the visible window so it tracks zoom/pan.
+    if (input.volumeProfile) {
+        const cfg = typeof input.volumeProfile === "object" ? input.volumeProfile : {};
+        const vp = volumeProfile(vis, cfg.buckets ?? 24);
+        const maxW = (cfg.width ?? 0.16) * plotW;
+        const color = cfg.color ?? withAlpha(theme.axis, 0.22);
+        for (const b of vp.buckets) {
+            if (b.vol <= 0)
+                continue;
+            const yTop = yOf(b.hi);
+            const yBot = yOf(b.lo);
+            const bh = Math.max(1, yBot - yTop - 1);
+            const wpx = (b.vol / vp.maxVol) * maxW;
+            // the Point-of-Control band gets a slightly stronger tint
+            ctx.fillStyle = Math.abs((b.lo + b.hi) / 2 - vp.poc) < (b.hi - b.lo) / 2 ? withAlpha(theme.line, 0.32) : color;
+            ctx.fillRect(plotW - wpx, yTop, wpx, bh);
+        }
+    }
     // indicator overlays (moving averages) — drawn from precomputed value-series when
     // supplied (the Chart controller precomputes them on data change), else computed
     // here from the indicator config for pure/standalone callers. Series align to the
@@ -316,11 +405,13 @@ export function draw(input) {
     ctx.fillStyle = theme.tagText;
     ctx.textAlign = "left";
     ctx.fillText(fmtPrice(last.c), plotW + 6, ly);
-    // crosshair + axis labels
-    let active = last;
+    // crosshair + axis labels. `active` is the candle returned to onCrosshair — always the
+    // RAW candle (real OHLC), even in heikin mode where the drawn body is smoothed.
+    let active = candles[start + n - 1];
     if (hover && hover.x < plotW && hover.y > 0 && hover.y < H - pads.bottom) {
-        const idx = Math.max(0, Math.min(n - 1, Math.round((hover.x - (plotW - (n - 1) * cw - cw / 2)) / cw)));
-        active = vis[idx];
+        // invert xOf (which now accounts for rightGap whitespace); clamp into the data range.
+        const idx = Math.max(0, Math.min(n - 1, Math.round((hover.x - xOf(0)) / cw)));
+        active = candles[start + idx];
         const cx = xOf(idx);
         ctx.strokeStyle = theme.crosshair;
         ctx.setLineDash([3, 3]);
@@ -355,23 +446,61 @@ function drawDrawing(ctx, d, xOfTime, yOfPrice, plotW, theme, selected) {
     ctx.strokeStyle = color;
     ctx.lineWidth = selected ? 2.5 : 1.5;
     const pts = [];
-    ctx.beginPath();
-    if (d.type === "hline") {
-        const y = yOfPrice(d.a.price);
-        ctx.moveTo(0, y);
-        ctx.lineTo(plotW, y);
-        pts.push({ x: plotW / 2, y });
+    if (d.type === "fib" && d.b) {
+        // Retracement levels between the two anchor prices; lines extend to the right edge.
+        const ax = xOfTime(d.a.time);
+        const bx = xOfTime(d.b.time);
+        const xL = Math.min(ax, bx);
+        const p0 = d.a.price;
+        const p1 = d.b.price;
+        ctx.textAlign = "left";
+        for (const r of FIB_LEVELS) {
+            const price = p0 + (p1 - p0) * r;
+            const y = yOfPrice(price);
+            ctx.strokeStyle = withAlpha(color, r === 0 || r === 1 ? 0.9 : 0.55);
+            ctx.beginPath();
+            ctx.moveTo(xL, y);
+            ctx.lineTo(plotW, y);
+            ctx.stroke();
+            ctx.fillStyle = withAlpha(color, 0.95);
+            ctx.fillText(`${(r * 100).toFixed(1)}%  ${formatValue(price)}`, xL + 4, y - 6);
+        }
+        pts.push({ x: ax, y: yOfPrice(p0) }, { x: bx, y: yOfPrice(p1) });
     }
-    else if (d.b) {
+    else if (d.type === "rect" && d.b) {
         const ax = xOfTime(d.a.time);
         const ay = yOfPrice(d.a.price);
         const bx = xOfTime(d.b.time);
         const by = yOfPrice(d.b.price);
-        ctx.moveTo(ax, ay);
-        ctx.lineTo(bx, by);
+        const x = Math.min(ax, bx);
+        const y = Math.min(ay, by);
+        const w = Math.abs(bx - ax);
+        const h = Math.abs(by - ay);
+        ctx.fillStyle = withAlpha(color, 0.12);
+        ctx.fillRect(x, y, w, h);
+        ctx.strokeStyle = color;
+        ctx.strokeRect(x, y, w, h);
         pts.push({ x: ax, y: ay }, { x: bx, y: by });
     }
-    ctx.stroke();
+    else {
+        ctx.beginPath();
+        if (d.type === "hline") {
+            const y = yOfPrice(d.a.price);
+            ctx.moveTo(0, y);
+            ctx.lineTo(plotW, y);
+            pts.push({ x: plotW / 2, y });
+        }
+        else if (d.b) {
+            const ax = xOfTime(d.a.time);
+            const ay = yOfPrice(d.a.price);
+            const bx = xOfTime(d.b.time);
+            const by = yOfPrice(d.b.price);
+            ctx.moveTo(ax, ay);
+            ctx.lineTo(bx, by);
+            pts.push({ x: ax, y: ay }, { x: bx, y: by });
+        }
+        ctx.stroke();
+    }
     if (selected) {
         ctx.fillStyle = color;
         for (const p of pts)
@@ -380,7 +509,7 @@ function drawDrawing(ctx, d, xOfTime, yOfPrice, plotW, theme, selected) {
     ctx.lineWidth = 1;
 }
 /** Default oscillator colors. */
-const OSC_COLORS = { rsi: "#ab47bc", macdLine: "#2962ff", macdSignal: "#ff9800" };
+const OSC_COLORS = { rsi: "#ab47bc", macdLine: "#2962ff", macdSignal: "#ff9800", stochK: "#2962ff", stochD: "#ff9800", atr: "#26a69a" };
 /** Last non-null value of a series (for the pane's inline readout). */
 function lastDefined(s) {
     for (let i = s.length - 1; i >= 0; i--)
@@ -453,6 +582,60 @@ function drawPane(ctx, osc, paneH, top, env) {
         ctx.fillText(`RSI ${period}${lv != null ? "  " + lv.toFixed(1) : ""}`, 6, top + padY);
         return;
     }
+    if (osc.type === "stoch") {
+        const kP = osc.period ?? 14;
+        const dP = osc.dPeriod ?? 3;
+        const sm = osc.smooth ?? 1;
+        const { k, d } = stochastic(candles, kP, dP, sm);
+        const yOf = (v) => innerTop + innerH * (1 - v / 100);
+        // 80 / 20 guide rails
+        ctx.setLineDash([2, 3]);
+        for (const lvl of [80, 20]) {
+            const y = yOf(lvl);
+            ctx.strokeStyle = theme.grid;
+            ctx.beginPath();
+            ctx.moveTo(0, y);
+            ctx.lineTo(plotW, y);
+            ctx.stroke();
+            ctx.fillStyle = theme.axis;
+            ctx.fillText(String(lvl), plotW + 6, y);
+        }
+        ctx.setLineDash([]);
+        strokeSeries(ctx, k, env, yOf, osc.color ?? OSC_COLORS.stochK);
+        strokeSeries(ctx, d, env, yOf, OSC_COLORS.stochD);
+        const lv = lastDefined(k);
+        ctx.fillStyle = theme.axis;
+        ctx.fillText(`STOCH ${kP} ${dP}${lv != null ? "  " + lv.toFixed(1) : ""}`, 6, top + padY);
+        return;
+    }
+    if (osc.type === "atr") {
+        const period = osc.period ?? 14;
+        const series = atr(candles, period);
+        // auto-scale to the visible ATR range (price units, always ≥ 0)
+        let lo = Infinity;
+        let hi = -Infinity;
+        for (let j = 0; j < n; j++) {
+            const v = series[start + j];
+            if (v != null) {
+                lo = Math.min(lo, v);
+                hi = Math.max(hi, v);
+            }
+        }
+        if (!isFinite(lo)) {
+            lo = 0;
+            hi = 1;
+        }
+        const padR = (hi - lo) * 0.1 || hi * 0.1 || 1;
+        lo = Math.max(0, lo - padR);
+        hi += padR;
+        const rng = hi - lo || 1;
+        const yOf = (v) => innerTop + innerH * (1 - (v - lo) / rng);
+        strokeSeries(ctx, series, env, yOf, osc.color ?? OSC_COLORS.atr);
+        const lv = lastDefined(series);
+        ctx.fillStyle = theme.axis;
+        ctx.fillText(`ATR ${period}${lv != null ? "  " + formatValue(lv) : ""}`, 6, top + padY);
+        return;
+    }
     // MACD: histogram + macd line + signal line, symmetric around zero
     const fast = osc.fast ?? 12;
     const slow = osc.slow ?? 26;

package/dist/core/signals.d.ts

@@ -0,0 +1,63 @@
+import type { Candle, Point } from "./types";
+import type { ChartFeed } from "./feed";
+/** The public Livo signals engine. */
+export declare const DEFAULT_SIGNALS_URL = "https://signals.livo.build";
+/** The fields of a Signal Radar market this adapter needs. `spark` is recent closes (oldest→newest). */
+export interface SignalsMarket {
+    pair: string;
+    base: string;
+    pool: string;
+    price: number;
+    spark: number[];
+}
+/** Fetch one Signal Radar market (price + spark) from the engine snapshot, or null if absent. */
+export declare function fetchSignalsMarket(token: string, url?: string): Promise<SignalsMarket | null>;
+/**
+ * Fetch a page of indexed swaps for a pool from the engine's GraphQL API (`allSwaps`,
+ * newest-first), mapped to priced {@link Point}s. `pool` must be the 0x-prefixed address.
+ * Returns one point per swap (unpriceable swaps keep `p: 0` and are dropped by `buildOHLC`),
+ * so the caller can advance its offset by `points.length`.
+ */
+export declare function fetchSignalsSwaps(pool: string, opts?: {
+    url?: string;
+    first?: number;
+    offset?: number;
+}): Promise<Point[]>;
+/**
+ * Drop swaps whose price is a wild outlier — the engine occasionally mis-prices historical
+ * swaps (e.g. a thin pool's old trades priced at $2.5M for a $3 token). Uses the median of
+ * the newest swaps as a robust reference (recent prices are reliable) and rejects anything
+ * more than `factor`× off it. Input is newest-first; output preserves order.
+ */
+export declare function rejectPriceOutliers(pts: Point[], factor?: number): Point[];
+/** Turn a `spark` (recent closes, oldest→newest) into flat candles ending at `nowSec`. */
+export declare function sparkCandles(spark: number[], bucketSeconds: number, nowSec: number, lastClose?: number): Candle[];
+export interface SignalsFeedOptions {
+    /** Token to chart — pool address, base-token address, or pair symbol (e.g. "PEPE"). */
+    token: string;
+    /** Engine base URL (default https://signals.livo.build). */
+    url?: string;
+    /** Candle bucket size in seconds (default 300 = 5m). */
+    bucketSeconds?: number;
+    /** Swaps fetched per history page from the index (default 1500); older pages load lazily. */
+    swapPageSize?: number;
+    /** Candles to load before the first paint, so the chart opens filled rather than a sliver
+     *  on the right (default 160). Active pools pack many swaps per bucket, so this may take a
+     *  few index pages. */
+    initialCandles?: number;
+    /** Force `"spark"` (snapshot closes only) instead of the default `"index"` (GraphQL history). */
+    history?: "index" | "spark";
+    /** Live poll cadence in ms (default 15s; 0 disables the live poll). */
+    refetchMs?: number;
+    /** Override "now" (ms) — for tests/determinism. */
+    now?: number;
+}
+/**
+ * A {@link ChartFeed} for a Signal Radar token. History comes from the engine's indexed
+ * swaps (`/graphql allSwaps` for the pool → bucketed into OHLC at `bucketSeconds`), paged
+ * lazily on back-scroll, so it shows real candles days deep. The live candle is polled from
+ * `/data` (current price). If the index is unreachable (or `history: "spark"`), it falls back
+ * to seeding from the snapshot's `spark`. Pass it to `connectFeed` with `bucketSeconds` as
+ * the interval.
+ */
+export declare function signalsFeed(opts: SignalsFeedOptions): ChartFeed;

package/dist/core/signals.js

@@ -0,0 +1,234 @@
+// Signal Radar adapter — chart a token tracked by the Livo on-chain signals engine.
+// The engine ("Signal Radar") indexes every Ethereum mainnet DEX swap into Postgres and
+// exposes it over a PostGraphile GraphQL API (`/graphql`), plus a live `/data` snapshot
+// (no key) with the current USD `price` and a short `spark` of recent closes.
+//
+// This adapter pulls REAL history from the index — `allSwaps` for the pool, bucketed into
+// OHLC candles at any interval — so it shows true 1m / 5m candles days back (the index has
+// no TTL), and lazy-loads older pages as you scroll. It polls `/data` for the live, building
+// candle. If `/graphql` is unreachable (e.g. CORS), it falls back to seeding from `spark`.
+//
+//   import { Chart, connectFeed, signalsFeed } from "@livo-build/charts";
+//   const chart = new Chart(el, { height: 420 });
+//   connectFeed(chart, signalsFeed({ token: "PEPE" }), { interval: 300 });
+import { buildOHLC } from "./ohlc";
+/** The public Livo signals engine. */
+export const DEFAULT_SIGNALS_URL = "https://signals.livo.build";
+/** fetch with an abort timeout so a stalled engine 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);
+    }
+}
+const bare = (s) => s.replace(/^0x/i, "").toLowerCase();
+/** Find the snapshot market for a token by pool address, base-token address, or pair symbol. */
+function findMarket(markets, token) {
+    const q = bare(token);
+    const byAddr = markets.find((m) => bare(m.pool) === q || bare(m.base) === q);
+    if (byAddr)
+        return byAddr;
+    const sym = token.toLowerCase();
+    // symbol match → the deepest (first listed; the snapshot is hottest-first) market.
+    return markets.find((m) => m.pair.toLowerCase().split("/")[0] === sym);
+}
+/** Fetch one Signal Radar market (price + spark) from the engine snapshot, or null if absent. */
+export async function fetchSignalsMarket(token, url = DEFAULT_SIGNALS_URL) {
+    const res = await fetchT(`${url}/data`);
+    if (!res.ok)
+        throw new Error("signals /data " + res.status);
+    const snap = (await res.json());
+    return findMarket(snap.markets ?? [], token) ?? null;
+}
+/**
+ * Fetch a page of indexed swaps for a pool from the engine's GraphQL API (`allSwaps`,
+ * newest-first), mapped to priced {@link Point}s. `pool` must be the 0x-prefixed address.
+ * Returns one point per swap (unpriceable swaps keep `p: 0` and are dropped by `buildOHLC`),
+ * so the caller can advance its offset by `points.length`.
+ */
+export async function fetchSignalsSwaps(pool, opts = {}) {
+    const url = opts.url ?? DEFAULT_SIGNALS_URL;
+    const first = opts.first ?? 1500;
+    const offset = opts.offset ?? 0;
+    const query = `{ allSwaps(condition:{pool:"${pool}"}, orderBy: BLOCK_TIME_DESC, first:${first}, offset:${offset}){ nodes{ blockTime priceUsd amountUsd } } }`;
+    const res = await fetchT(`${url}/graphql`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ query }),
+    });
+    if (!res.ok)
+        throw new Error("signals /graphql " + res.status);
+    const j = (await res.json());
+    const nodes = j?.data?.allSwaps?.nodes;
+    if (!nodes)
+        throw new Error("signals /graphql: no allSwaps");
+    return nodes.map((s) => ({ t: +s.blockTime, p: +(s.priceUsd ?? 0), v: +(s.amountUsd ?? 0) || 0 }));
+}
+/**
+ * Drop swaps whose price is a wild outlier — the engine occasionally mis-prices historical
+ * swaps (e.g. a thin pool's old trades priced at $2.5M for a $3 token). Uses the median of
+ * the newest swaps as a robust reference (recent prices are reliable) and rejects anything
+ * more than `factor`× off it. Input is newest-first; output preserves order.
+ */
+export function rejectPriceOutliers(pts, factor = 100) {
+    const priced = pts.filter((p) => p.p > 0 && isFinite(p.p));
+    if (priced.length < 8)
+        return priced;
+    const recent = priced
+        .slice(0, 200)
+        .map((p) => p.p)
+        .sort((a, b) => a - b);
+    const ref = recent[Math.floor(recent.length / 2)] || 0;
+    if (!(ref > 0))
+        return priced;
+    return priced.filter((p) => p.p >= ref / factor && p.p <= ref * factor);
+}
+/** Turn a `spark` (recent closes, oldest→newest) into flat candles ending at `nowSec`. */
+export function sparkCandles(spark, bucketSeconds, nowSec, lastClose) {
+    const n = spark.length;
+    const endBucket = Math.floor(nowSec / bucketSeconds) * bucketSeconds;
+    return spark.map((p, i) => {
+        const c = i === n - 1 && lastClose != null ? lastClose : p;
+        const time = endBucket - (n - 1 - i) * bucketSeconds;
+        return { time, o: p, h: Math.max(p, c), l: Math.min(p, c), c, vol: 0 };
+    });
+}
+/**
+ * A {@link ChartFeed} for a Signal Radar token. History comes from the engine's indexed
+ * swaps (`/graphql allSwaps` for the pool → bucketed into OHLC at `bucketSeconds`), paged
+ * lazily on back-scroll, so it shows real candles days deep. The live candle is polled from
+ * `/data` (current price). If the index is unreachable (or `history: "spark"`), it falls back
+ * to seeding from the snapshot's `spark`. Pass it to `connectFeed` with `bucketSeconds` as
+ * the interval.
+ */
+export function signalsFeed(opts) {
+    const url = opts.url ?? DEFAULT_SIGNALS_URL;
+    const secs = opts.bucketSeconds ?? 300;
+    const token = opts.token;
+    const swapPage = opts.swapPageSize ?? 1500;
+    const initialCandles = opts.initialCandles ?? 160;
+    const sparkOnly = opts.history === "spark";
+    const MAX_SWAPS = 60000; // memory/CPU bound on deep back-scroll
+    // Resolve the market once (gives the pool to query + the spark fallback), cached.
+    let marketP = null;
+    const market = () => (marketP ?? (marketP = fetchSignalsMarket(token, url).catch(() => null)));
+    // Accumulate ALL fetched swaps and re-bucket the full set each page, so a candle bucket
+    // that straddles a swap-page boundary is always COMPLETE (no partial O/H/L/volume). The
+    // feed returns the full ascending candle set; connectFeed merges it (replacing the partial
+    // boundary it already showed). `offset` pages older swaps; bounded by MAX_SWAPS.
+    // When `token` is a pool address, query the index by it DIRECTLY — the index keys on the
+    // pool (permanent) so history works even after the market rotates out of the live `/data`
+    // snapshot. /data is then only needed for the spark fallback + the live price.
+    const directPool = /^(0x)?[0-9a-fA-F]{40}$/.test(token) ? `0x${bare(token)}` : null;
+    let allSwaps = [];
+    let offset = 0;
+    let sparkMode = sparkOnly; // flipped on if the index is unreachable
+    let histLatest = null; // newest indexed candle (seeds the live bucket)
+    const spark = async (m) => {
+        if (!m)
+            return [];
+        const nowSec = (opts.now ?? Date.now()) / 1000;
+        const cs = sparkCandles(m.spark ?? [], secs, nowSec, m.price);
+        histLatest = cs[cs.length - 1] ?? null;
+        return cs;
+    };
+    return {
+        async loadHistory({ before }) {
+            const m = await market(); // for the spark fallback + the live price (best-effort)
+            // Prefer the pool straight from the token (rotation-proof); else resolve it via /data.
+            const pool = directPool ?? (m && m.pool ? `0x${bare(m.pool)}` : null);
+            if (!pool)
+                return [];
+            // Spark mode (forced via `history:"spark"`, or fell back): only the initial page has
+            // data (the snapshot's recent closes); there are no deeper pages.
+            if (sparkMode)
+                return before == null ? spark(m) : [];
+            if (allSwaps.length >= MAX_SWAPS)
+                return []; // depth cap reached
+            try {
+                // On the FIRST load, keep pulling pages until we have a full screen of candles, so the
+                // chart paints filled rather than a sliver on the right (active pools pack many swaps
+                // into each bucket, so one page can be only an hour or two). Lazy scroll-back fetches
+                // one page at a time. `rejectPriceOutliers` drops engine mis-pricings (e.g. $2.5M).
+                const want = before == null ? initialCandles : 0;
+                let got = 0;
+                do {
+                    const pts = await fetchSignalsSwaps(pool, { url, first: swapPage, offset });
+                    offset += pts.length;
+                    got += pts.length;
+                    if (pts.length === 0)
+                        break;
+                    allSwaps = allSwaps.concat(pts);
+                } while (allSwaps.length < MAX_SWAPS && buildOHLC(rejectPriceOutliers(allSwaps), secs).length < want);
+                if (got === 0) {
+                    if (allSwaps.length === 0) {
+                        sparkMode = true; // index empty for this pool — seed from spark
+                        return before == null ? spark(m) : [];
+                    }
+                    return []; // no older swaps — history exhausted
+                }
+                const candles = buildOHLC(rejectPriceOutliers(allSwaps), secs); // clean, complete buckets
+                histLatest = candles[candles.length - 1] ?? null; // newest (may be the live bucket) — seeds the live poll
+                // EXCLUDE the in-progress (current wall-clock) bucket: the live poll owns it. Otherwise a
+                // history re-fetch (lazy load) would overwrite the live candle with the stale indexed close,
+                // and the next poll would restore the live price — making the latest candle oscillate.
+                const curBucket = Math.floor((opts.now ?? Date.now()) / 1000 / secs) * secs;
+                return candles.filter((c) => c.time < curBucket);
+            }
+            catch {
+                // index unreachable (e.g. /graphql CORS) — fall back to the snapshot spark, once.
+                sparkMode = true;
+                return before == null ? spark(m) : [];
+            }
+        },
+        subscribe(_params, onUpdate) {
+            const ms = opts.refetchMs ?? 15000;
+            if (ms <= 0)
+                return () => { };
+            let stopped = false;
+            let timer;
+            // Track the in-progress bucket so polled prices accumulate high/low instead of
+            // overwriting the whole candle each tick.
+            let cur = null;
+            const tick = async () => {
+                if (stopped)
+                    return;
+                try {
+                    const m = await fetchSignalsMarket(token, url);
+                    if (m && !stopped) {
+                        const nowSec = (opts.now ?? Date.now()) / 1000;
+                        const bt = Math.floor(nowSec / secs) * secs;
+                        if (!cur || cur.time !== bt) {
+                            // Seed the in-progress bucket from the latest INDEXED candle when it's the same
+                            // bucket, so the live price extends real OHLC/volume instead of flattening it.
+                            const base = histLatest && histLatest.time === bt ? histLatest : null;
+                            cur = base
+                                ? { ...base, h: Math.max(base.h, m.price), l: Math.min(base.l, m.price), c: m.price }
+                                : { time: bt, o: m.price, h: m.price, l: m.price, c: m.price, vol: 0 };
+                        }
+                        else {
+                            cur = { ...cur, h: Math.max(cur.h, m.price), l: Math.min(cur.l, m.price), c: m.price };
+                        }
+                        onUpdate(cur);
+                    }
+                }
+                catch {
+                    /* transient fetch error — try again next tick */
+                }
+                if (!stopped)
+                    timer = setTimeout(tick, ms);
+            };
+            void tick(); // fire immediately so the live (current-bucket) candle appears at once
+            return () => {
+                stopped = true;
+                if (timer)
+                    clearTimeout(timer);
+            };
+        },
+    };
+}