wickchart 1.6.0 → 2.0.0

package/src/feeds.js

@@ -111,6 +111,225 @@ export function makeSynthStream(sec, startPrice) {
   };
 }
 
+/* ---------------- information-based bar aggregation ---------------- */
+//
+// Tick / volume / dollar bars ("advanced bars"): a bar closes when a threshold
+// of *information* is reached — N prints, N base units, or $N notional — not
+// when the clock says so. Same discipline as the rest of this file: plain
+// data in, plain data out; the aggregator itself has no DOM and no network.
+
+/** Default thresholds per kind. They are per-instrument — there is no
+ *  universal "one bar" size, treat these as starting points to tune. */
+export const AGG_DEFAULTS = { tick: 100, volume: 10, dollar: 25000 };
+
+/**
+ * Parse an `aggregate` spec — `tick`, `volume:50`, `dollar:25000` (case and
+ * whitespace tolerant; the value is the bar size in trades / base units /
+ * quote units respectively).
+ * @param {string} spec attribute value
+ * @returns {{kind: 'tick'|'volume'|'dollar', threshold: number}|null} null when invalid
+ */
+export function parseAggregate(spec) {
+  if (spec == null || spec === false) return null;
+  const m = /^\s*(tick|volume|dollar)(?:\s*:\s*([0-9]*\.?[0-9]+))?\s*$/i.exec(String(spec));
+  if (!m) return null;
+  const kind = m[1].toLowerCase();
+  const threshold = m[2] != null ? Number(m[2]) : AGG_DEFAULTS[kind];
+  if (!Number.isFinite(threshold) || threshold <= 0) return null;
+  return { kind, threshold };
+}
+
+/**
+ * Streaming aggregator: feed it trades, get bars back. `add()` returns a
+ * bar the moment the threshold is crossed ({@link current} keeps exposing
+ * the forming bar meanwhile). The completing trade belongs entirely to the
+ * closing bar — a whale print is never split across two bars.
+ */
+export class TickBarAggregator {
+  /**
+   * @param {'tick'|'volume'|'dollar'} kind what the threshold counts
+   * @param {number} threshold bar size (trades / base units / quote units)
+   */
+  constructor(kind = 'tick', threshold = AGG_DEFAULTS.tick) {
+    this.kind = kind === 'volume' || kind === 'dollar' ? kind : 'tick';
+    this.threshold = Number.isFinite(+threshold) && +threshold > 0 ? +threshold : AGG_DEFAULTS[this.kind];
+    this._bar = null;
+  }
+
+  /**
+   * Feed one trade `{ time, price, size }` (seconds auto-upgraded to ms,
+   * same heuristic as the chart). Returns the completed bar —
+   * `{ time, open, high, low, close, volume, closed: true }` — when the
+   * threshold is reached, else null.
+   * @returns {object|null}
+   */
+  add(trade) {
+    const price = Number(trade && trade.price);
+    const size = Number(trade && trade.size);
+    let time = Number(trade && trade.time);
+    if (!(price > 0) || !Number.isFinite(price)) return null;
+    const qty = Number.isFinite(size) && size > 0 ? size : 0;
+    if (!Number.isFinite(time)) time = Date.now();
+    if (time < 1e11) time *= 1000;
+    if (!this._bar) {
+      this._bar = {
+        time: Math.round(time), open: price, high: price, low: price, close: price,
+        volume: 0, n: 0, notional: 0,
+      };
+    }
+    const b = this._bar;
+    if (price > b.high) b.high = price;
+    if (price < b.low) b.low = price;
+    b.close = price;
+    b.volume += qty;
+    b.n++;
+    b.notional += price * qty;
+    const filled = this.kind === 'tick' ? b.n : this.kind === 'volume' ? b.volume : b.notional;
+    if (filled >= this.threshold) {
+      this._bar = null;
+      return {
+        time: b.time, open: b.open, high: b.high, low: b.low, close: b.close,
+        volume: +b.volume.toFixed(8), closed: true,
+      };
+    }
+    return null;
+  }
+
+  /** The forming bar as plain chart-bar fields (no internals), or null. */
+  current() {
+    if (!this._bar) return null;
+    const { time, open, high, low, close } = this._bar;
+    return { time, open, high, low, close, volume: +this._bar.volume.toFixed(8) };
+  }
+
+  /** Close the forming bar as-is (end of tape / teardown), or null. */
+  flush() {
+    const c = this.current();
+    this._bar = null;
+    return c ? { ...c, closed: true } : null;
+  }
+}
+
+/**
+ * One-pass batch aggregation of a trade history. Returns the closed bars,
+ * the still-forming remainder, and the live aggregator positioned at the end
+ * of the tape so streaming can continue without a seam.
+ * @param {Array<object>} trades `{ time, price, size }` prints
+ * @param {'tick'|'volume'|'dollar'} kind
+ * @param {number} threshold
+ */
+export function aggregateTrades(trades, kind, threshold) {
+  const aggregator = new TickBarAggregator(kind, threshold);
+  const bars = [];
+  for (const t of Array.isArray(trades) ? trades : []) {
+    const closed = aggregator.add(t);
+    if (closed) bars.push(closed);
+  }
+  return { bars, pending: aggregator.current(), aggregator };
+}
+
+/**
+ * Coerce a generic JSON trades array into plain `{ time, price, size }`
+ * (ms, seconds auto-upgraded; `size` also read from `qty`/`amount`).
+ * Invalid entries are dropped, never thrown — same contract as the chart's
+ * other normalizers. Output is sorted by time.
+ */
+export function normalizeTrades(list) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const r of list) {
+    if (!r || typeof r !== 'object') continue;
+    const price = Number(r.price);
+    const size = Number(r.size != null ? r.size : r.qty != null ? r.qty : r.amount);
+    let time = Number(r.time != null ? r.time : r.t);
+    if (!(price > 0) || !(size > 0) || !Number.isFinite(time)) continue;
+    if (time < 1e11) time *= 1000;
+    out.push({ time: Math.round(time), price, size });
+  }
+  out.sort((a, b) => a.time - b.time);
+  return out;
+}
+
+/* ------------- synthetic trade prints (offline aggregate demos) ------------- */
+
+// Synthetic prints model human-sized notionals: $20 + U³·$8000, mean ≈ $2,020
+// regardless of instrument — sizes are notional / price, so the tape adapts
+// to a $100 demo stock and a $64k BTC the same way.
+const SYNTH_NOTIONAL_MIN = 20;
+const SYNTH_NOTIONAL_SPAN = 8000;
+const SYNTH_NOTIONAL_MEAN = SYNTH_NOTIONAL_MIN + SYNTH_NOTIONAL_SPAN / 4;
+
+/**
+ * Deterministic synthetic trade prints (random-walk price with volatility
+ * regimes, heavy-tailed sizes). Same key → same tape.
+ * @param {string} key seed key
+ * @param {number} [n=24000] print count
+ * @param {number} [base=100] starting price
+ */
+export function genSyntheticTrades(key, n = 24000, base = 100) {
+  const rnd = mulberry32(hashStr('trades:' + key) ^ 0x2545f491);
+  const dt = 250; // ms between prints
+  const t0 = Math.floor(Date.now() / dt) * dt - (n - 1) * dt;
+  let price = base;
+  let vol = 0.0006;
+  let regimeLeft = 0;
+  const trades = [];
+  for (let i = 0; i < n; i++) {
+    if (regimeLeft-- <= 0) {
+      regimeLeft = 200 + ((rnd() * 1200) | 0);
+      vol = 0.0002 + rnd() * 0.0014;
+    }
+    price = Math.max(1e-8, price * Math.exp(vol * gauss(rnd)));
+    const notional = SYNTH_NOTIONAL_MIN + Math.pow(rnd(), 3) * SYNTH_NOTIONAL_SPAN;
+    trades.push({
+      time: t0 + i * dt,
+      price: +price.toFixed(8),
+      size: +Math.max(1e-8, notional / price).toFixed(8),
+    });
+  }
+  return trades;
+}
+
+/**
+ * Stateful synthetic live tape: one print per call, bridging from
+ * `startPrice` (e.g. the last price of a seeded history).
+ * @param {number} [startPrice=100]
+ */
+export function makeSynthTradeStream(startPrice = 100) {
+  const rnd = mulberry32((Math.random() * 1e9) >>> 0);
+  let price = startPrice;
+  let vol = 0.0006;
+  let regimeLeft = 0;
+  let t = Date.now();
+  return () => {
+    if (regimeLeft-- <= 0) {
+      regimeLeft = 50 + ((rnd() * 350) | 0);
+      vol = 0.0002 + rnd() * 0.0014;
+    }
+    t += 60 + ((rnd() * 420) | 0);
+    price = Math.max(1e-8, price * Math.exp(vol * gauss(rnd)));
+    const notional = SYNTH_NOTIONAL_MIN + Math.pow(rnd(), 3) * SYNTH_NOTIONAL_SPAN;
+    return {
+      time: t,
+      price: +price.toFixed(8),
+      size: +Math.max(1e-8, notional / price).toFixed(8),
+    };
+  };
+}
+
+/**
+ * Expected synthetic prints per bar — used to size the offline seed so a
+ * demo chart starts with roughly the requested bar count.
+ * @param {{kind: string, threshold: number}} agg
+ * @param {number} [base=100]
+ */
+export function synthTradesPerBar(agg, base = 100) {
+  if (agg.kind === 'tick') return agg.threshold;
+  const meanSize = SYNTH_NOTIONAL_MEAN / Math.max(1e-8, base);
+  const per = agg.kind === 'volume' ? agg.threshold / meanSize : agg.threshold / SYNTH_NOTIONAL_MEAN;
+  return Math.max(1, per);
+}
+
 /* ---------------- Binance public API ---------------- */
 
 /**
@@ -168,7 +387,120 @@ export function openBinanceSocket(symbol, tfId, onBar, onDown, timeoutMs = 8000)
     try {
       const k = JSON.parse(ev.data).k;
       if (!k) return;
-      onBar({ time: k.t, open: +k.o, high: +k.h, low: +k.l, close: +k.c, volume: +k.v });
+      // k.x is Binance's "this kline is final" flag — pass it through so
+      // close-mode alerts can fire the moment the candle closes rather than
+      // waiting for the next one to arrive.
+      onBar({
+        time: k.t, open: +k.o, high: +k.h, low: +k.l, close: +k.c, volume: +k.v,
+        closed: k.x === true,
+      });
+    } catch (_) {}
+  };
+  ws.onclose = () => {
+    if (dead) return;
+    dead = true;
+    clearTimeout(failTimer);
+    onDown(new Error('closed'));
+  };
+  ws.onerror = () => {};
+  return {
+    close() {
+      dead = true;
+      ws.onclose = null;
+      ws.onerror = null;
+      clearTimeout(failTimer);
+      try {
+        ws.close();
+      } catch (_) {}
+    },
+  };
+}
+
+/**
+ * Fetch Binance aggTrades, paging backwards from the newest prints (or from
+ * below `beforeId`) until `minTrades` prints / `maxPages` requests / the
+ * start of the symbol's history. Returns `{ trades, oldestId }` ascending by
+ * time; each print carries its Binance id so live streams can resume without
+ * overlaps.
+ * @param {string} symbol e.g. 'BTCUSDT'
+ * @param {number} [minTrades=1000] stop once at least this many prints are held
+ * @param {number} [maxPages=25] hard request cap (1000 prints per page)
+ * @param {number} [beforeId] only fetch prints with an id lower than this
+ */
+export async function fetchBinanceAggTrades(symbol, minTrades = 1000, maxPages = 25, beforeId) {
+  const out = [];
+  let oldest = beforeId != null && Number.isFinite(+beforeId) ? +beforeId : null;
+  for (let page = 0; page < maxPages && out.length < minTrades; page++) {
+    let url =
+      `https://api.binance.com/api/v3/aggTrades?symbol=${encodeURIComponent(symbol)}&limit=1000`;
+    if (oldest != null) url += `&fromId=${Math.max(0, oldest - 1000)}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Binance HTTP ${res.status}`);
+    const rows = await res.json();
+    if (!Array.isArray(rows) || !rows.length) break;
+    for (const r of rows) {
+      if (beforeId != null && r.a >= beforeId) continue; // window overlap guard
+      out.push({ id: r.a, time: r.T, price: +r.p, size: +r.q });
+    }
+    oldest = rows[0].a;
+    if (rows.length < 1000) break; // reached the beginning of the tape
+  }
+  out.sort((a, b) => a.time - b.time || a.id - b.id);
+  return { trades: out, oldestId: oldest };
+}
+
+/**
+ * One forward window of aggTrades starting at `fromId` — the catch-up call
+ * for REST polling after a trade socket drops. Returns `{ trades, latestId }`.
+ * @param {string} symbol
+ * @param {number} fromId first print id to fetch (use lastSeenId + 1)
+ */
+export async function fetchBinanceAggTradesSince(symbol, fromId) {
+  const url =
+    `https://api.binance.com/api/v3/aggTrades?symbol=${encodeURIComponent(symbol)}` +
+    `&fromId=${Math.max(0, Number(fromId) || 0)}&limit=1000`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Binance HTTP ${res.status}`);
+  const rows = await res.json();
+  const trades = (Array.isArray(rows) ? rows : []).map((r) => ({
+    id: r.a, time: r.T, price: +r.p, size: +r.q,
+  }));
+  return { trades, latestId: trades.length ? trades[trades.length - 1].id : Number(fromId) || 0 };
+}
+
+/**
+ * Open a Binance aggTrade WebSocket — raw prints for information-based bar
+ * aggregation. Same lifecycle contract as openBinanceSocket: `onDown(err)`
+ * fires on error/close/timeout, after which the socket is dead and the
+ * caller should fall back.
+ * @returns {{close(): void}}
+ */
+export function openBinanceTradeSocket(symbol, onTrade, onDown, timeoutMs = 8000) {
+  let ws;
+  try {
+    ws = new WebSocket(
+      `wss://stream.binance.com:9443/ws/${symbol.toLowerCase()}@aggTrade`
+    );
+  } catch (err) {
+    onDown(err);
+    return { close() {} };
+  }
+  let dead = false;
+  const failTimer = setTimeout(() => {
+    if (!dead && ws.readyState !== WebSocket.OPEN) {
+      dead = true;
+      try {
+        ws.close();
+      } catch (_) {}
+      onDown(new Error('timeout'));
+    }
+  }, timeoutMs);
+  ws.onopen = () => clearTimeout(failTimer);
+  ws.onmessage = (ev) => {
+    try {
+      const t = JSON.parse(ev.data);
+      if (!t || t.e !== 'aggTrade') return;
+      onTrade({ id: t.a, time: t.T, price: +t.p, size: +t.q });
     } catch (_) {}
   };
   ws.onclose = () => {

package/src/react-core.js

@@ -107,7 +107,13 @@ export function applyChartProps(el, split) {
   }
   // The element exposes `data` as a getter-only accessor — feed it through
   // setData() (guarded by identity so unchanged arrays never re-ingest).
-  if (split.data != null && el.data !== split.data) {
+  // setData() normalizes into a *fresh* array, so `el.data` never matches
+  // what we passed in; the identity we compare against is tracked on the
+  // element, exactly as overlays do below. Comparing `el.data` instead would
+  // re-ingest on every render — which resets the viewport, since setData()
+  // sets `_needsFit` and clears the hover.
+  if (split.data != null && el.__wickDataRef !== split.data) {
+    el.__wickDataRef = split.data;
     if (typeof el.setData === 'function') el.setData(split.data);
     else el.data = split.data;
   }

package/src/report.js

@@ -0,0 +1,309 @@
+/* ==========================================================================
+ * <wick-chart> report export — the branded snapshot: chart + visible-range
+ * stats + watermark, composed into one shareable PNG.
+ *
+ *   import { exportReport, downloadReport } from 'wickchart/report';
+ *
+ *   const url = await exportReport(chart);          // PNG data URL
+ *   const blob = await exportReport(chart, { as: 'blob' });
+ *   await downloadReport(chart, 'btc-1h.png');      // triggers a download
+ *
+ * Composes from public surfaces only — exportPNG() (the DPR-crisp canvas),
+ * getVisibleRange(), the chart's own --wick-* CSS variables for theming —
+ * so there are zero core changes. The model (title, stats rows, layout,
+ * colors, formatting) is plain data built by reportModel() and unit-tested
+ * in Node; only the actual canvas composition needs a browser.
+ *
+ * Options: title (default: the chart's label attribute), source (a string
+ * credited in the footer, e.g. 'binance: BTCUSDT'), brand ('WickChart'),
+ * theme ('dark' | 'light' | 'auto' — auto reads the chart's CSS variables),
+ * scale (1..4, default 2), precision (price decimals, default derived),
+ * as ('url' | 'blob' | 'canvas').
+ * ========================================================================== */
+
+import { computeStats } from './core.js';
+
+/* ---------------- layout constants (CSS px, pre-scale) ---------------- */
+
+const HEADER_H = 64;
+const STATS_H = 104;
+const FOOTER_H = 40;
+const PAD = 18;
+const GRID_COLS = 4;
+const FONT = 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif';
+
+/* ---------------- pure helpers ---------------- */
+
+/** Decimals worth showing for a price of this magnitude. */
+export function decimalsFor(price) {
+  const p = Math.abs(Number(price));
+  if (!Number.isFinite(p) || p === 0) return 2;
+  if (p >= 10000) return 2;
+  if (p >= 100) return 2;
+  if (p >= 1) return 3;
+  return 6;
+}
+
+/** 1234 → '1.2k', 1234567 → '1.23M', 12 → '12'. */
+export function compact(v) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return '—';
+  const a = Math.abs(n);
+  if (a >= 1e9) return (n / 1e9).toFixed(2) + 'B';
+  if (a >= 1e6) return (n / 1e6).toFixed(2) + 'M';
+  if (a >= 1e4) return (n / 1e3).toFixed(1) + 'k';
+  return String(Math.round(n));
+}
+
+export function pct(v, digits = 2) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return '—';
+  return (n > 0 ? '+' : '') + n.toFixed(digits) + '%';
+}
+
+const fmtDate = (t) =>
+  Number.isFinite(t)
+    ? new Date(t).toLocaleString('en-US', { month: 'short', day: 'numeric', year: '2-digit', hour: '2-digit', minute: '2-digit' })
+    : '—';
+
+/** Greatest index whose time is <= t (binary search; bars are ascending). */
+export function indexForTime(bars, t) {
+  let lo = 0;
+  let hi = bars.length - 1;
+  if (t < bars[0].time) return 0;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (bars[mid].time <= t) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+}
+
+const PALETTES = {
+  dark: {
+    bg: '#0d1117', panel: '#11141c', text: '#e6edf3', muted: '#8b949e',
+    up: '#16c784', down: '#ea3943', accent: '#4c8dff',
+  },
+  light: {
+    bg: '#ffffff', panel: '#f4f6f9', text: '#111827', muted: '#6b7280',
+    up: '#0e9f6e', down: '#e02424', accent: '#2563eb',
+  },
+};
+
+/** Resolve the report colors: theme palettes, overridden by the chart's own
+ *  --wick-* variables when readable (browser) and theme is 'auto'. */
+export function reportColors(chart, theme = 'auto') {
+  const key = theme === 'light' || theme === 'dark' ? theme : 'auto';
+  const pal = { ...PALETTES[key === 'auto' ? 'dark' : key] };
+  if (key === 'auto' && typeof getComputedStyle === 'function' && chart && chart.nodeType) {
+    const cs = getComputedStyle(chart);
+    const v = (name, fb) => cs.getPropertyValue(name).trim() || fb;
+    pal.bg = v('--wick-bg', pal.bg);
+    pal.text = v('--wick-text-strong', pal.text);
+    pal.muted = v('--wick-text', pal.muted);
+    pal.up = v('--wick-up', pal.up);
+    pal.down = v('--wick-down', pal.down);
+    pal.accent = v('--wick-accent', pal.accent);
+  }
+  // a light chart background flips the panel/band contrast to match
+  if (key === 'auto') {
+    pal.light = luminance(pal.bg) > 0.5;
+    if (pal.light) {
+      pal.panel = PALETTES.light.panel;
+      pal.muted = PALETTES.light.muted;
+    } else {
+      pal.panel = PALETTES.dark.panel;
+    }
+  } else {
+    pal.panel = PALETTES[key].panel;
+  }
+  return pal;
+}
+
+/** Relative luminance of a #hex / rgb() string (0..1, best effort). */
+export function luminance(color) {
+  const m = /#([0-9a-f]{6})/i.exec(String(color || ''));
+  if (!m) return 0;
+  const n = parseInt(m[1], 16);
+  return (0.2126 * ((n >> 16) & 255) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255)) / 255;
+}
+
+/* ---------------- the model (pure, Node-testable) ---------------- */
+
+/**
+ * Build the whole report as data: sizes, bands, stat rows, colors, labels.
+ * @param {object} chart a <wick-chart> (public API only: data,
+ *   getVisibleRange, exportPNG, clientWidth/Height, getAttribute)
+ * @param {{title?: string, source?: string, brand?: string, theme?: string,
+ *   scale?: number, precision?: number}} [opts]
+ */
+export function reportModel(chart, opts = {}) {
+  const d = chart && chart.data;
+  if (!Array.isArray(d) || d.length < 2) {
+    throw new Error('exportReport(chart): the chart needs data (2+ bars)');
+  }
+  const range = typeof chart.getVisibleRange === 'function' ? chart.getVisibleRange() : null;
+  if (!range) throw new Error('exportReport(chart): the chart needs a rendered view');
+  const i0 = indexForTime(d, range.from);
+  const i1 = indexForTime(d, range.to);
+  const dt = d.length > 1 ? d[i1].time - d[i1 - 1].time : 3600e3;
+  const stats = computeStats(d, i0, i1, dt) || computeStats(d, 0, d.length - 1, dt);
+  const precision =
+    Number.isInteger(opts.precision) && opts.precision >= 0 && opts.precision <= 10
+      ? opts.precision
+      : decimalsFor(stats.max);
+  const last = d[d.length - 1].close;
+
+  const rows = [
+    { label: 'Return', value: pct(stats.changePct), color: stats.changePct >= 0 ? 'up' : 'down' },
+    { label: 'Ann. vol', value: stats.annVolPct.toFixed(1) + '%' },
+    { label: 'Max drawdown', value: '-' + stats.maxDDPct.toFixed(1) + '%', color: 'down' },
+    { label: 'Bars', value: String(stats.n) },
+    { label: 'Up / down', value: stats.up + ' / ' + stats.dn },
+    { label: 'Avg volume', value: compact(stats.avgVolume) },
+    { label: 'High', value: stats.max.toFixed(precision), color: 'up' },
+    { label: 'Low', value: stats.min.toFixed(precision), color: 'down' },
+  ];
+
+  const s = Number(opts.scale);
+  const scale = Number.isFinite(s) && s > 0 ? Math.max(1, Math.min(4, Math.round(s))) : 2;
+  const chartW = Math.max(320, Math.round(chart.clientWidth || 900));
+  const chartH = Math.max(160, Math.round(chart.clientHeight || 420));
+  const title =
+    (typeof opts.title === 'string' && opts.title.trim()) ||
+    (typeof chart.getAttribute === 'function' ? chart.getAttribute('label') : '') ||
+    'WickChart';
+  return {
+    scale,
+    width: chartW,
+    height: HEADER_H + chartH + STATS_H + FOOTER_H,
+    bands: { header: HEADER_H, stats: STATS_H, footer: FOOTER_H, chart: chartH },
+    grid: { cols: GRID_COLS },
+    title,
+    brand: (typeof opts.brand === 'string' && opts.brand.trim()) || 'WickChart',
+    source: typeof opts.source === 'string' ? opts.source : '',
+    range: { from: range.from, to: range.to },
+    last,
+    precision,
+    rows,
+    generatedAt: Date.now(),
+    colors: reportColors(chart, opts.theme),
+    stats,
+  };
+}
+
+/* ---------------- the composition (browser) ---------------- */
+
+const loadImage = (src) =>
+  new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error('exportReport: the chart PNG failed to decode'));
+    img.src = src;
+  });
+
+/**
+ * Compose the branded report and return it as a PNG data URL (default), a
+ * Blob, or the canvas itself.
+ * @returns {Promise<string|Blob|HTMLCanvasElement>}
+ */
+export async function exportReport(chart, opts = {}) {
+  if (typeof document === 'undefined' || typeof Image === 'undefined') {
+    throw new Error('exportReport requires a browser (canvas + Image)');
+  }
+  const model = reportModel(chart, opts);
+  const img = await loadImage(chart.exportPNG());
+  const { width, height, scale, colors: pal } = model;
+
+  const canvas = document.createElement('canvas');
+  canvas.width = width * scale;
+  canvas.height = height * scale;
+  const ctx = canvas.getContext('2d');
+  ctx.scale(scale, scale);
+  const b = model.bands;
+
+  // header band
+  ctx.fillStyle = pal.panel;
+  ctx.fillRect(0, 0, width, b.header);
+  ctx.fillStyle = pal.text;
+  ctx.font = '700 22px ' + FONT;
+  ctx.textBaseline = 'alphabetic';
+  ctx.fillText(model.title, PAD, 34);
+  ctx.fillStyle = pal.muted;
+  ctx.font = '400 12px ' + FONT;
+  const sub = fmtDate(model.range.from) + '  →  ' + fmtDate(model.range.to);
+  ctx.fillText(sub, PAD, 52);
+  ctx.textAlign = 'right';
+  ctx.fillStyle = pal.accent;
+  ctx.font = '700 14px ' + FONT;
+  ctx.fillText(model.brand, width - PAD, 30);
+  ctx.fillStyle = pal.muted;
+  ctx.font = '400 11px ' + FONT;
+  ctx.fillText('last ' + model.last.toFixed(model.precision), width - PAD, 48);
+  ctx.textAlign = 'left';
+
+  // chart image (full-res source drawn into the band — stays crisp)
+  ctx.drawImage(img, 0, b.header, width, b.chart);
+  // watermark over the chart's bottom-right corner
+  ctx.save();
+  ctx.globalAlpha = 0.5;
+  ctx.fillStyle = pal.muted;
+  ctx.font = '600 13px ' + FONT;
+  ctx.textAlign = 'right';
+  ctx.fillText(model.brand, width - PAD - 6, b.header + b.chart - 10);
+  ctx.restore();
+
+  // stats band — a grid of label-over-value cards
+  ctx.fillStyle = pal.bg;
+  ctx.fillRect(0, b.header + b.chart, width, b.stats);
+  const cols = model.grid.cols;
+  const cw = (width - PAD * 2) / cols;
+  const rows = Math.ceil(model.rows.length / cols);
+  const rh = (b.stats - 16) / rows;
+  model.rows.forEach((r, i) => {
+    const cx = PAD + (i % cols) * cw;
+    const cy = b.header + b.chart + 8 + Math.floor(i / cols) * rh;
+    ctx.fillStyle = pal.muted;
+    ctx.font = '500 10px ' + FONT;
+    ctx.fillText(r.label.toUpperCase(), cx, cy + 12);
+    ctx.fillStyle = r.color === 'up' ? pal.up : r.color === 'down' ? pal.down : pal.text;
+    ctx.font = '700 15px ' + FONT;
+    ctx.fillText(r.value, cx, cy + 32);
+  });
+
+  // footer band
+  ctx.fillStyle = pal.panel;
+  ctx.fillRect(0, height - b.footer, width, b.footer);
+  ctx.fillStyle = pal.muted;
+  ctx.font = '400 11px ' + FONT;
+  const credit = 'Generated with ' + model.brand + (model.source ? ' · ' + model.source : '');
+  ctx.fillText(credit + ' · ' + fmtDate(model.generatedAt), PAD, height - 16);
+  ctx.textAlign = 'right';
+  ctx.fillText(model.stats.n + ' bars · wickchart', width - PAD, height - 16);
+  ctx.textAlign = 'left';
+
+  const as = opts.as || 'url';
+  if (as === 'canvas') return canvas;
+  if (as === 'blob') {
+    return new Promise((resolve, reject) =>
+      canvas.toBlob((bl) => (bl ? resolve(bl) : reject(new Error('exportReport: toBlob failed'))), 'image/png')
+    );
+  }
+  return canvas.toDataURL('image/png');
+}
+
+/**
+ * Compose and trigger a download (browser only).
+ * @returns {Promise<void>}
+ */
+export async function downloadReport(chart, filename = 'wickchart-report.png', opts = {}) {
+  const blob = await exportReport(chart, { ...opts, as: 'blob' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 4000);
+}