wickchart 1.6.0 → 1.7.0

package/src/wick-feed.js

@@ -30,6 +30,15 @@ import {
   openBinanceSocket,
   tfToSeconds,
   BASE_PRICES,
+  parseAggregate,
+  aggregateTrades,
+  genSyntheticTrades,
+  makeSynthTradeStream,
+  synthTradesPerBar,
+  fetchBinanceAggTrades,
+  fetchBinanceAggTradesSince,
+  openBinanceTradeSocket,
+  normalizeTrades,
 } from './feeds.js';
 
 const LIVE_TICK_MS = 650;
@@ -38,7 +47,7 @@ const HTMLElementBase = typeof HTMLElement !== 'undefined' ? HTMLElement : class
 
 class WickFeed extends HTMLElementBase {
   static get observedAttributes() {
-    return ['for', 'binance', 'demo', 'url', 'tf', 'limit', 'poll', 'live'];
+    return ['for', 'binance', 'demo', 'url', 'tf', 'limit', 'poll', 'live', 'aggregate'];
   }
 
   constructor() {
@@ -127,9 +136,19 @@ class WickFeed extends HTMLElementBase {
       });
       return;
     }
+    // aggregate="tick:200|volume:50|dollar:25000" switches the feed from
+    // time bars to information-based bars built client-side from raw trades
+    const agg = parseAggregate(this.getAttribute('aggregate'));
+    if (this.hasAttribute('aggregate') && !agg) {
+      this._setStatus('error', { message: 'aggregate must be tick|volume|dollar[:N]' });
+      return;
+    }
     if (!chart.hasAttribute('label')) {
       const sym = this.getAttribute('binance') || this.getAttribute('demo');
-      if (sym) chart.setAttribute('label', `${String(sym).toUpperCase()} · ${this.getAttribute('tf') || '1h'}`);
+      if (sym) {
+        const sub = agg ? `${agg.kind}:${String(+(+agg.threshold).toFixed(6))} bars` : (this.getAttribute('tf') || '1h');
+        chart.setAttribute('label', `${String(sym).toUpperCase()} · ${sub}`);
+      }
     }
 
     const gen = this._gen;
@@ -140,6 +159,14 @@ class WickFeed extends HTMLElementBase {
     const url = this.getAttribute('url');
     const demo = this.getAttribute('demo');
 
+    if (agg) {
+      if (sym) this._binanceTrades(gen, chart, String(sym).toUpperCase(), agg, limit, live);
+      else if (url) this._restTrades(gen, chart, url, agg, limit, live);
+      else if (demo != null) {
+        this._syntheticTrades(gen, chart, demo === '' ? 'DEMO' : demo, agg, limit, live);
+      } else this._setStatus('idle');
+      return;
+    }
     if (sym) this._binance(gen, chart, String(sym).toUpperCase(), tfId, limit, live);
     else if (url) this._rest(gen, chart, url, limit, live);
     else if (demo != null) {
@@ -220,6 +247,180 @@ class WickFeed extends HTMLElementBase {
     this._synthetic(gen, chart, sym, tfId, limit, live, 'fallback');
   }
 
+  /* ---------------- aggregate sources (information-based bars) ------------- */
+
+  /**
+   * Wrap chart.update for aggregated bars: the chart keys bars by timestamp,
+   * and two groups can close inside the same millisecond, so emitted times
+   * are nudged +1ms to stay strictly increasing (keeps the one-bar-per-
+   * timestamp integrity invariant; display-only, values are untouched).
+   */
+  _aggEmit(gen, chart) {
+    let last = -Infinity;
+    return (bar) => {
+      if (!bar || this._gen !== gen || !this.isConnected) return;
+      if (bar.time <= last) bar = { ...bar, time: last + 1 };
+      last = bar.time;
+      chart.update(bar);
+    };
+  }
+
+  /** Seed + stream one aggregator onto the chart (shared by all sources). */
+  _aggAttach(gen, chart, res, bars, limit, status) {
+    chart.setData([...bars.slice(-limit), ...(res.pending ? [res.pending] : [])].slice(-limit));
+    this._setStatus(status);
+    return {
+      emit: this._aggEmit(gen, chart),
+      aggregator: res.aggregator,
+      /** Push one print through; emits the closed bar, then the forming one. */
+      push(t) {
+        const closed = res.aggregator.add(t);
+        if (closed) this.emit(closed);
+        this.emit(res.aggregator.current());
+      },
+    };
+  }
+
+  _syntheticTrades(gen, chart, key, agg, limit, live, status = 'live') {
+    const base = BASE_PRICES[key.toUpperCase()] || 100;
+    const perBar = synthTradesPerBar(agg, base);
+    const seed = Math.max(2000, Math.min(48000, Math.ceil(limit * perBar) * 2));
+    const full = aggregateTrades(genSyntheticTrades(`${key}:agg`, seed, base), agg.kind, agg.threshold);
+    const bars = full.bars;
+    chart.onloadmore = (fromTime) => bars.filter((b) => b.time < fromTime).slice(-limit);
+    const handle = this._aggAttach(gen, chart, full, bars, limit, status);
+    if (!live) return;
+    const lastPrice = (full.pending || bars[bars.length - 1] || { close: base }).close;
+    const next = makeSynthTradeStream(lastPrice);
+    const timer = setInterval(() => {
+      if (this._gen !== gen || !this.isConnected) return;
+      const n = 2 + ((Math.random() * 6) | 0); // a burst of prints per tick
+      for (let i = 0; i < n; i++) handle.push(next());
+    }, LIVE_TICK_MS);
+    this._closers.push(() => clearInterval(timer));
+  }
+
+  async _binanceTrades(gen, chart, sym, agg, limit, live) {
+    this._setStatus('loading');
+    try {
+      // prints-per-bar is instrument-specific — size the seed from a first page
+      const first = await fetchBinanceAggTrades(sym, 1000, 1);
+      let perBar = agg.kind === 'tick' ? agg.threshold : 40;
+      if (agg.kind !== 'tick' && first.trades.length) {
+        let vol = 0;
+        let notl = 0;
+        for (const t of first.trades) {
+          vol += t.size;
+          notl += t.price * t.size;
+        }
+        const n = first.trades.length;
+        perBar = agg.kind === 'volume'
+          ? agg.threshold / Math.max(1e-12, vol / n)
+          : agg.threshold / Math.max(1e-12, notl / n);
+      }
+      let trades = first.trades;
+      let oldestId = first.oldestId;
+      const target = Math.max(1000, Math.min(25000, Math.ceil(limit * perBar)));
+      if (trades.length < target) {
+        const older = await fetchBinanceAggTrades(sym, target - trades.length, 25, oldestId);
+        trades = older.trades.concat(trades);
+        if (older.oldestId != null) oldestId = older.oldestId;
+      }
+      if (this._gen !== gen || !this.isConnected) return;
+      const res = aggregateTrades(trades, agg.kind, agg.threshold);
+      const handle = this._aggAttach(gen, chart, res, res.bars, limit, 'loaded');
+      let lastId = trades.length ? trades[trades.length - 1].id : 0;
+      chart.onloadmore = async (fromTime) => {
+        const older = await fetchBinanceAggTrades(sym, Math.ceil(limit * perBar), 10, oldestId);
+        if (older.oldestId != null) oldestId = older.oldestId;
+        return aggregateTrades(older.trades, agg.kind, agg.threshold).bars
+          .filter((b) => b.time < fromTime)
+          .slice(-limit);
+      };
+      if (!live) return;
+      const ws = openBinanceTradeSocket(
+        sym,
+        (t) => {
+          if (this._gen !== gen || !this.isConnected) return;
+          if (!(t.id > lastId)) return; // seed/WS overlap
+          lastId = t.id;
+          handle.push(t);
+          this._setStatus('live');
+        },
+        () => {
+          if (this._gen !== gen || !this.isConnected) return;
+          this._pollBinanceTrades(gen, chart, sym, handle, lastId, agg, limit, live);
+        }
+      );
+      this._closers.push(() => ws.close());
+    } catch (err) {
+      if (this._gen !== gen || !this.isConnected) return;
+      this._fire('fallback', { reason: err && err.message });
+      this._syntheticTrades(gen, chart, sym, agg, limit, live, 'fallback');
+    }
+  }
+
+  _pollBinanceTrades(gen, chart, sym, handle, fromId, agg, limit, live) {
+    this._setStatus('polling');
+    let lastId = fromId;
+    const timer = setInterval(async () => {
+      if (this._gen !== gen || !this.isConnected) return;
+      try {
+        const { trades, latestId } = await fetchBinanceAggTradesSince(sym, lastId + 1);
+        for (const t of trades) {
+          if (!(t.id > lastId)) continue;
+          lastId = t.id;
+          handle.push(t);
+        }
+        if (latestId > lastId) lastId = latestId;
+      } catch (_) {
+        clearInterval(timer);
+        this._fire('fallback', { reason: 'trade poll failed' });
+        this._syntheticTrades(gen, chart, sym, agg, limit, live, 'fallback');
+      }
+    }, 10000);
+    this._closers.push(() => clearInterval(timer));
+  }
+
+  async _restTrades(gen, chart, url, agg, limit, live) {
+    this._setStatus('loading');
+    const pull = async () => {
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const body = await res.json();
+      return normalizeTrades(Array.isArray(body) ? body : body.trades || body.bars);
+    };
+    try {
+      const trades = await pull();
+      if (this._gen !== gen || !this.isConnected) return;
+      const res = aggregateTrades(trades, agg.kind, agg.threshold);
+      this._aggAttach(gen, chart, res, res.bars, limit, 'loaded');
+      if (!live) return;
+      const pollSec = Math.max(1, parseInt(this.getAttribute('poll') || '0', 10) || 0);
+      if (!pollSec) return;
+      // dedupe by print time: a same-ms reprint would double-count notional
+      let lastTime = trades.length ? trades[trades.length - 1].time : 0;
+      const emit = this._aggEmit(gen, chart);
+      const timer = setInterval(async () => {
+        if (this._gen !== gen || !this.isConnected) return;
+        try {
+          for (const t of await pull()) {
+            if (t.time <= lastTime) continue;
+            lastTime = t.time;
+            const closed = res.aggregator.add(t);
+            if (closed) emit(closed);
+          }
+          emit(res.aggregator.current());
+          this._setStatus('polling');
+        } catch (_) {}
+      }, pollSec * 1000);
+      this._closers.push(() => clearInterval(timer));
+    } catch (err) {
+      if (this._gen !== gen || !this.isConnected) return;
+      this._setStatus('error', { message: err && err.message });
+    }
+  }
+
   /* ---------------- generic REST source ---------------- */
 
   async _rest(gen, chart, url, limit, live) {
@@ -268,3 +469,13 @@ if (typeof customElements !== 'undefined') {
 
 export default WickFeed;
 export { WickFeed };
+// pure aggregation helpers — exported so apps can pipe their own trade
+// streams through the same machinery `aggregate=` uses
+export {
+  parseAggregate,
+  TickBarAggregator,
+  aggregateTrades,
+  normalizeTrades,
+  genSyntheticTrades,
+  makeSynthTradeStream,
+} from './feeds.js';

package/src/worker-core.js

@@ -0,0 +1,89 @@
+/* ==========================================================================
+ * worker-core — the worker side of the worker compute path.
+ *
+ * Runs inside a module Worker spawned by src/worker.js. Tasks arrive with a
+ * correlation id; replies carry { id, ok, ... }. The chart sends its dataset
+ * once per data epoch as six Float64Arrays (transferred, not cloned — a
+ * structured clone of a million bar objects costs ~1 s, the columnar fill
+ * ~25 ms), and indicator tasks afterwards reference that data by
+ * (sid, epoch). Sessions are keyed per chart so one shared worker can serve
+ * several charts; the two most recent are kept (1M bars of columns plus the
+ * rebuilt object tape is ~50 MB each).
+ *
+ * handle() is exported (and pure with respect to its state object) so the
+ * dispatch is unit-testable in Node with no Worker at all.
+ * ========================================================================== */
+
+import { BUILTIN_INDICATORS } from './core.js';
+
+/** Rebuild the bar-object tape from a columnar snapshot (worker-side only —
+ *  this cost never touches the main thread). */
+export function barsFromCols(cols) {
+  const n = cols.time.length;
+  const out = new Array(n);
+  for (let i = 0; i < n; i++) {
+    out[i] = {
+      time: cols.time[i],
+      open: cols.open[i],
+      high: cols.high[i],
+      low: cols.low[i],
+      close: cols.close[i],
+      volume: cols.volume[i],
+    };
+  }
+  return out;
+}
+
+/**
+ * Create a worker-core state + dispatcher.
+ * @returns {{sessions: Map, handle(message: object): object}} the reply object
+ */
+export function createWorkerCore() {
+  const sessions = new Map(); // sid → { epoch, cols, bars: Array|null }
+  return {
+    sessions,
+
+    handle(msg) {
+      const { id, type, sid } = msg || {};
+      if (type === 'epoch') {
+        // keep at most two chart sessions resident
+        while (sessions.size >= 2) sessions.delete(sessions.keys().next().value);
+        sessions.set(sid, { epoch: msg.epoch, cols: msg.cols, bars: null });
+        return { id, ok: true };
+      }
+      if (type === 'indicator') {
+        const s = sessions.get(sid);
+        if (!s || s.epoch !== msg.epoch) {
+          // the worker no longer holds this epoch's data (evicted, or the
+          // chart is ahead) — the chart resends and retries
+          return { id, ok: false, stale: true };
+        }
+        const def = BUILTIN_INDICATORS.get(msg.name);
+        if (!def) return { id, ok: false, error: 'unknown indicator: ' + msg.name };
+        let res = null;
+        try {
+          if (!s.bars) s.bars = barsFromCols(s.cols); // once per epoch
+          res = def.compute(s.bars, msg.params || {});
+        } catch (_) {
+          res = null; // same contract as the sync path: a failed compute draws nothing
+        }
+        return { id, ok: true, res };
+      }
+      return { id, ok: false, error: 'unknown task type: ' + type };
+    },
+  };
+}
+
+/* ---------------- worker bootstrap (real Worker scope only) ---------------- */
+
+const inWorker =
+  typeof WorkerGlobalScope !== 'undefined' &&
+  typeof self !== 'undefined' &&
+  self instanceof WorkerGlobalScope;
+
+if (inWorker) {
+  const core = createWorkerCore();
+  self.onmessage = (e) => {
+    self.postMessage(core.handle(e.data));
+  };
+}

package/src/worker.js

@@ -0,0 +1,128 @@
+/* ==========================================================================
+ * <wick-chart> worker compute path — the main-thread side.
+ *
+ *   import 'wickchart/worker';            // once, anywhere
+ *   <wick-chart worker indicators="sma:20 bb:20 rsi:14"></wick-chart>
+ *
+ * Importing this module wires a shared ChartWorkerPool into the chart class;
+ * from then on, any chart with the `worker` attribute computes its built-in
+ * indicators off the main thread once the dataset crosses WORKER_MIN_BARS
+ * (50k bars). Custom/scripted indicators are closures and stay sync; so does
+ * everything below the threshold. Data crosses once per bulk load as six
+ * transferable Float64Arrays — never as cloned objects.
+ *
+ *   import { ChartWorkerPool, getSharedPool, setChartWorkerPool } from 'wickchart/worker';
+ *   const pool = new ChartWorkerPool();   // a private pool (e.g. one per tab view)
+ *   setChartWorkerPool(pool);
+ *
+ * No Worker available (old browsers, non-HTTP contexts where module workers
+ * fail, Node)? pool.available is false and every chart silently stays on the
+ * synchronous path — the attribute is an optimization, never a dependency.
+ * ========================================================================== */
+
+import { WickChart } from './wick-chart.js';
+
+export { WickChart };
+
+/**
+ * A single-Worker task runner. The factory is injectable so tests can drive
+ * the protocol with a fake Worker; the default spawns the module worker
+ * sitting next to this file.
+ */
+export class ChartWorkerPool {
+  /** @param {() => Worker} [factory] */
+  constructor(factory) {
+    this._factory =
+      typeof factory === 'function'
+        ? factory
+        : typeof Worker === 'function'
+          ? () => new Worker(new URL('./worker-core.js', import.meta.url), { type: 'module' })
+          : null;
+    this.available = this._factory != null;
+    this._worker = null;
+    this._seq = 0;
+    this._pending = new Map(); // id → { resolve, reject }
+  }
+
+  /**
+   * Post a task; resolves with the reply's `res`, rejects on failure or
+   * worker death (a `stale` rejection means: resend the epoch data first).
+   * @param {object} msg task message without the id
+   * @returns {Promise<any>}
+   */
+  run(msg) {
+    if (!this.available) return Promise.reject(new Error('worker unavailable'));
+    if (!this._worker) this._spawn();
+    const id = ++this._seq;
+    return new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+      try {
+        this._worker.postMessage({ ...msg, id });
+      } catch (err) {
+        this._pending.delete(id);
+        reject(err);
+      }
+    });
+  }
+
+  _spawn() {
+    try {
+      this._worker = this._factory();
+    } catch (err) {
+      this.available = false;
+      throw err;
+    }
+    this._worker.onmessage = (e) => {
+      const reply = e.data || {};
+      const p = this._pending.get(reply.id);
+      if (!p) return;
+      this._pending.delete(reply.id);
+      if (reply.stale) p.reject(Object.assign(new Error('stale epoch'), { stale: true }));
+      else if (reply.ok) p.resolve(reply.res);
+      else p.reject(new Error(reply.error || 'worker task failed'));
+    };
+    this._worker.onerror = () => this._die();
+    this._worker.onmessageerror = () => this._die();
+  }
+
+  /** Reject everything in flight and drop the worker; the next run() respawns
+   *  — a transient worker crash must not permanently kill the mode. */
+  _die() {
+    for (const p of this._pending.values()) p.reject(new Error('worker died'));
+    this._pending.clear();
+    if (this._worker) {
+      try {
+        this._worker.terminate();
+      } catch (_) {}
+    }
+    this._worker = null;
+  }
+
+  /** Shut the pool down for good (in-flight tasks reject). */
+  terminate() {
+    this._die();
+    this.available = false;
+  }
+}
+
+let shared = null;
+
+/** The page-wide pool (created on first use). */
+export function getSharedPool() {
+  return shared || (shared = new ChartWorkerPool());
+}
+
+/**
+ * Point the chart class at a pool (or null to disable the worker path).
+ * @param {ChartWorkerPool|null} pool
+ */
+export function setChartWorkerPool(pool) {
+  WickChart._workerPool = pool;
+  return pool;
+}
+
+// importing 'wickchart/worker' is the whole setup: wire the shared pool into
+// the chart class so <wick-chart worker> just works afterwards
+if (typeof Worker === 'function') {
+  setChartWorkerPool(getSharedPool());
+}

package/types/core.d.ts

@@ -190,6 +190,27 @@ export declare const SEC = 1000;
 export declare const MIN: number;
 export declare const HOUR: number;
 export declare const DAY: number;
+/**
+ * Interpret a timestamp as milliseconds. Numbers may be seconds or ms, so
+ * some threshold is unavoidable; pass a `Date` for anything before 1973,
+ * which is unambiguous. Single source of truth — everything that reads a
+ * caller-supplied time goes through here.
+ * @param {number|Date} t
+ * @returns {number} milliseconds
+ */
+export declare const toMs: (t: number | Date) => number;
+/**
+ * Milliseconds east of UTC in `zone` at the instant `at`.
+ *   'utc'            → 0
+ *   'local' / null   → the browser's zone (DST-correct via Date)
+ *   number           → a fixed offset in ms (exchange sessions)
+ *   IANA name        → DST-correct via Intl
+ * Never throws: an unusable zone reads as UTC.
+ * @param {number} at epoch ms
+ * @param {string|number|null} [zone]
+ * @returns {number} offset in ms
+ */
+export declare function zoneOffset(at: number, zone?: string | number | null): number;
 export declare const TIME_STEPS: {
     ms: number;
     label: string;
@@ -308,12 +329,22 @@ export declare function calcTrueRange(bars: Bar[]): Array<number | null>;
  */
 export declare function calcATR(bars: Bar[], period?: number): Array<number | null>;
 /**
- * Volume-weighted average price over the hlc3 typical price, anchored to
- * each UTC day (resets at the session boundary).
+ * Volume-weighted average price over the hlc3 typical price, resetting at
+ * each session boundary.
+ *
+ * The anchor defaults to the UTC day — the crypto convention, and what this
+ * has always done. Equities, futures and FX rarely open at UTC midnight, so
+ * pass the session's zone (or a fixed offset) to move the reset. Note this is
+ * deliberately independent of the chart's `timezone`, which only governs how
+ * times are displayed: changing the axis to Stockholm should not silently
+ * re-anchor a BTC chart's VWAP.
+ *
  * @param {Bar[]} bars
+ * @param {string|number} [anchor='utc'] 'utc' | 'local' | IANA zone | fixed
+ *   offset in ms — see zoneOffset()
  * @returns {Array<number|null>}
  */
-export declare function calcVWAP(bars: Bar[]): Array<number | null>;
+export declare function calcVWAP(bars: Bar[], anchor?: string | number): Array<number | null>;
 /**
  * On-balance volume: cumulative volume signed by close-to-close direction.
  * @param {Bar[]} bars
@@ -523,10 +554,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         smooth?: undefined;
     };
     compute: (bars: any, p: any) => number[];
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -538,10 +569,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         smooth?: undefined;
     };
     compute: (bars: any, p: any) => number[];
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -552,11 +583,11 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         smooth?: undefined;
         period?: undefined;
     };
-    compute: (bars: any) => number[];
-    color?: undefined;
+    compute: (bars: any, p: any) => number[];
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -568,10 +599,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         smooth?: undefined;
     };
     compute: (bars: any, p: any) => number[];
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -588,10 +619,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
             values: number[];
         }[];
     };
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -608,10 +639,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
             values: number[];
         }[];
     };
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -628,10 +659,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
             values: number[];
         }[];
     };
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -648,7 +679,6 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     color: string;
     compute: (bars: any, p: any) => number[];
 } | {
-    color?: undefined;
     kind: string;
     params: {
         mult?: undefined;
@@ -668,8 +698,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         histogram: number[];
     };
     range?: undefined;
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -683,8 +713,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     compute: (bars: any, p: any) => number[];
     guides?: undefined;
     range?: undefined;
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -703,8 +733,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
             values: number[];
         }[];
     };
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -718,8 +748,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     compute: (bars: any) => number[];
     guides?: undefined;
     range?: undefined;
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -733,8 +763,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     fmt: string;
     compute: (bars: any, p: any) => number[];
     range?: undefined;
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -748,6 +778,7 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     range: number[];
     fmt: string;
     compute: (bars: any, p: any) => number[];
+    color?: undefined;
 }>;
 /**
  * Parse an `indicators` attribute string against a registry.
@@ -814,6 +845,18 @@ export declare function positionPnl(pos: {
     entry: number;
     qty?: number;
 }, price: number): number;
+/**
+ * Percent return of a position at `price` — the move per unit, so it does
+ * NOT scale with `qty` the way positionPnl() does. Deriving this by dividing
+ * positionPnl() by the entry price reports qty × the true return.
+ * @param {{side?: 'long'|'short', entry: number}} pos
+ * @param {number} price
+ * @returns {number} percent (10 means +10%)
+ */
+export declare function positionPnlPct(pos: {
+    side?: 'long' | 'short';
+    entry: number;
+}, price: number): number;
 /**
  * Edge-triggered alert crossing test between two consecutive prices.
  * @param {{price: number, direction?: 'above'|'below'|'cross'}} alert