@tradejs/cli 3.1.29-beta.289 → 3.1.29-beta.291

package/dist/scripts/researchVisuals.js

@@ -0,0 +1,955 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/scripts/researchVisuals.ts
+var researchVisuals_exports = {};
+__export(researchVisuals_exports, {
+  main: () => main
+});
+module.exports = __toCommonJS(researchVisuals_exports);
+
+// src/lib/researchVisuals.ts
+var import_promises = __toESM(require("fs/promises"));
+var import_node_path = __toESM(require("path"));
+var import_node_zlib = require("zlib");
+var import_node_crypto2 = require("crypto");
+var import_sharp = __toESM(require("sharp"));
+
+// src/lib/researchVisuals/model.ts
+var object = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+var finite = (v) => typeof v === "number" && Number.isFinite(v);
+var number = (v, label) => {
+  if (!finite(v)) throw new Error(`Invalid ${label}`);
+  return v;
+};
+var text = (v, label) => {
+  if (typeof v !== "string" || !v.trim()) throw new Error(`Missing ${label}`);
+  return v;
+};
+var time = (v, label) => {
+  const n = number(v, label);
+  if (!Number.isSafeInteger(n) || n < 0 || n > 864e13)
+    throw new Error(`Invalid ${label}`);
+  return n;
+};
+var nullable = (v) => v == null ? null : number(v, "price");
+var point = (v) => {
+  const p = object(v);
+  return {
+    timestamp: time(p.timestamp, "point timestamp"),
+    value: number(p.value, "point value")
+  };
+};
+function normalizeFigures(v) {
+  const f = object(v);
+  const groups = (key) => (Array.isArray(f[key]) ? f[key] : []).map((g) => {
+    const a = object(g);
+    return { points: (Array.isArray(a.points) ? a.points : []).map(point) };
+  });
+  return {
+    lines: groups("lines"),
+    points: groups("points"),
+    zones: (Array.isArray(f.zones) ? f.zones : []).map((z) => ({
+      start: point(object(z).start),
+      end: point(object(z).end)
+    }))
+  };
+}
+function normalizeCandles(v) {
+  if (v === void 0) return [];
+  if (!Array.isArray(v)) throw new Error("Candles must be an array");
+  const out = v.map((raw) => {
+    const b = object(raw);
+    const c = {
+      timestamp: time(b.timestamp, "candle timestamp"),
+      open: number(b.open, "open"),
+      high: number(b.high, "high"),
+      low: number(b.low, "low"),
+      close: number(b.close, "close"),
+      volume: number(b.volume, "volume")
+    };
+    if (c.low > Math.min(c.open, c.close) || c.high < Math.max(c.open, c.close) || c.low > c.high || c.low <= 0 || c.volume < 0)
+      throw new Error("Invalid OHLCV");
+    for (const key of ["smaFast", "smaSlow", "bbUpper", "bbLower"])
+      if (b[key] != null) c[key] = number(b[key], key);
+    return c;
+  }).sort((a, b) => a.timestamp - b.timestamp);
+  if (out.some((b, i) => i > 0 && b.timestamp === out[i - 1].timestamp))
+    throw new Error("Duplicate candle timestamp");
+  return out;
+}
+function normalizeTrade(raw, fallbackStrategy, candlesBySymbol = {}) {
+  const r = object(raw), payload = object(r.payload), s = object(payload.signal), t = object(r.trade ?? r.tradeResult), prices = object(r.prices ?? s.prices), features = {}, pockets = {}, groups = {};
+  for (const [key, value] of Object.entries(object(r.features)))
+    if (finite(value)) features[key] = value;
+    else throw new Error(`Invalid feature ${key}`);
+  const snapshot = object(payload.featureSnapshot), values = object(snapshot.values);
+  for (const def of Array.isArray(snapshot.definitions) ? snapshot.definitions : []) {
+    const d = object(def);
+    const value = typeof d.id === "string" ? values[d.id] : void 0;
+    if (d.role === "input" && typeof d.id === "string" && finite(value))
+      features[d.id] = value;
+  }
+  for (const [key, value] of Object.entries(object(r.pockets))) {
+    if (typeof value !== "boolean") throw new Error(`Invalid pocket ${key}`);
+    pockets[key] = value;
+  }
+  if (typeof r.approved === "boolean") pockets.nativeGate = r.approved;
+  for (const [key, value] of Object.entries(object(r.groups))) {
+    if (typeof value !== "string") throw new Error(`Invalid group ${key}`);
+    groups[key] = value;
+  }
+  const additional = object(payload.additionalIndicators), profile = object(
+    additional.tickerProfile ?? object(additional.baseContext).tickerProfile
+  );
+  for (const key of [
+    "moneyGroup",
+    "volatilityGroup",
+    "btcCorrelationGroup",
+    "ethCorrelationGroup"
+  ])
+    if (typeof profile[key] === "string") groups[key] = profile[key];
+  const direction = r.direction ?? s.direction;
+  if (direction !== "LONG" && direction !== "SHORT")
+    throw new Error("Invalid trade direction");
+  const symbol = text(r.symbol ?? s.symbol, "symbol");
+  if (!symbol.endsWith("USDT"))
+    throw new Error(`Only USDT contracts: ${symbol}`);
+  const strategy = text(
+    r.strategy ?? r.strategyName ?? s.strategy ?? fallbackStrategy,
+    "strategy"
+  );
+  const entryTime = time(r.entryTime ?? t.entryTimestamp, "entryTime"), exitTime = time(r.exitTime ?? t.exitTimestamp, "exitTime"), signalTime = time(r.signalTime ?? r.timestamp ?? s.timestamp, "signalTime");
+  if (exitTime < entryTime || entryTime < signalTime)
+    throw new Error("Invalid trade chronology");
+  const entryPrice = number(r.entryPrice ?? t.entryPrice, "entryPrice"), exitPrice = number(r.exitPrice ?? t.exitPrice, "exitPrice");
+  if (entryPrice <= 0 || exitPrice <= 0)
+    throw new Error("Invalid execution price");
+  return {
+    id: text(
+      r.id ?? r.key ?? `${strategy}:${symbol}:${direction}:${text(r.signalId ?? s.signalId, "signalId")}:${entryTime}:${exitTime}`,
+      "trade id"
+    ),
+    strategy,
+    symbol,
+    direction,
+    entryTime,
+    exitTime,
+    signalTime,
+    entryPrice,
+    exitPrice,
+    pnl: number(r.pnl ?? t.netProfit, "net PnL"),
+    stop: nullable(r.stop ?? prices.stopLossPrice),
+    target: nullable(r.target ?? prices.takeProfitPrice),
+    pockets,
+    features,
+    groups,
+    candles: normalizeCandles(r.candles ?? candlesBySymbol[symbol]),
+    figures: normalizeFigures(r.figures ?? payload.figures)
+  };
+}
+function normalizeDataset(input, options = {}) {
+  const root = object(input);
+  const archived = root.schema === "trade-atlas-chart-points/v1";
+  if (!Array.isArray(input) && !archived && root.schema !== "tradejs-research-visuals/v1")
+    throw new Error("Unsupported research visual schema");
+  const population = archived || root.population === "selected" ? "selected" : options.population ?? root.population;
+  if (population !== "complete" && population !== "selected")
+    throw new Error("Declare population: complete or selected");
+  const intervalMs = options.intervalMs ?? (archived ? Number(root.timeframe) * 6e4 : root.intervalMs);
+  if (!finite(intervalMs) || !Number.isSafeInteger(intervalMs) || intervalMs <= 0)
+    throw new Error("Positive intervalMs is required");
+  const rows = Array.isArray(input) ? input : archived ? root.cards : root.trades;
+  if (!Array.isArray(rows)) throw new Error("Trades must be an array");
+  const runs = new Set(
+    rows.map((r) => object(r).backtestRunId).filter(Boolean)
+  );
+  if (runs.size > 1)
+    throw new Error("Mixed backtest runs; provide one immutable lineage");
+  const trades = rows.map(
+    (r) => normalizeTrade(
+      r,
+      options.strategy ?? String(root.strategy ?? ""),
+      options.candlesBySymbol ?? object(root.candlesBySymbol)
+    )
+  );
+  const ids = /* @__PURE__ */ new Set();
+  for (const t of trades) {
+    const key = `${t.strategy}:${t.id}`;
+    if (ids.has(key)) throw new Error(`Duplicate trade: ${key}`);
+    ids.add(key);
+  }
+  return {
+    schema: "tradejs-research-visuals/v1",
+    population,
+    source: options.source ?? String(root.source ?? root.runId ?? [...runs][0] ?? "caller-supplied"),
+    intervalMs,
+    trades
+  };
+}
+
+// src/lib/researchVisuals/analysis.ts
+var import_node_crypto = require("crypto");
+var summarize = (rows) => {
+  const wins = rows.filter((t) => t.pnl > 0), losses = rows.filter((t) => t.pnl < 0), grossProfit = wins.reduce((s, t) => s + t.pnl, 0), grossLoss = -losses.reduce((s, t) => s + t.pnl, 0);
+  return {
+    n: rows.length,
+    wins: wins.length,
+    losses: losses.length,
+    breakeven: rows.length - wins.length - losses.length,
+    pnl: grossProfit - grossLoss,
+    pf: grossLoss ? grossProfit / grossLoss : null,
+    mean: rows.length ? (grossProfit - grossLoss) / rows.length : null
+  };
+};
+var hash = (s) => (0, import_node_crypto.createHash)("sha256").update(s).digest("hex");
+function selectAtlas(trades, count = 100, seed = "trade-atlas/v1") {
+  if (!Number.isSafeInteger(count) || count < 1 || count > 1e3)
+    throw new Error("count must be 1..1000");
+  const selected = [];
+  for (const strategy of [...new Set(trades.map((t) => t.strategy))].sort())
+    for (const sign of [1, -1]) {
+      const population = trades.filter((t) => t.strategy === strategy && Math.sign(t.pnl) === sign).sort(
+        (a, b) => a.signalTime - b.signalTime || a.id.localeCompare(b.id)
+      );
+      const n = Math.min(count, population.length);
+      for (let i = 0; i < n; i++)
+        selected.push(
+          population.slice(
+            Math.floor(i * population.length / n),
+            Math.floor((i + 1) * population.length / n)
+          ).sort(
+            (a, b) => hash(`${seed}:${a.id}`).localeCompare(
+              hash(`${seed}:${b.id}`)
+            ) || a.id.localeCompare(b.id)
+          )[0]
+        );
+    }
+  return selected;
+}
+var median = (a) => {
+  const s = [...a].sort((a2, b) => a2 - b);
+  return s.length ? (s[Math.floor((s.length - 1) / 2)] + s[Math.floor(s.length / 2)]) / 2 : null;
+};
+function analyzeVisualTrades(trades) {
+  const scopes = ["ALL", "LONG", "SHORT"];
+  return Object.fromEntries(
+    scopes.map((direction) => {
+      const rows = trades.filter(
+        (t) => direction === "ALL" || t.direction === direction
+      );
+      const pockets = Object.fromEntries(
+        [...new Set(rows.flatMap((t) => Object.keys(t.pockets)))].sort().map((p) => [
+          p,
+          {
+            pass: summarize(rows.filter((t) => t.pockets[p] === true)),
+            fail: summarize(rows.filter((t) => t.pockets[p] === false)),
+            unknown: rows.filter((t) => t.pockets[p] === void 0).length
+          }
+        ])
+      );
+      const contrasts = [
+        ...new Set(rows.flatMap((t) => Object.keys(t.features)))
+      ].sort().map((feature) => {
+        const known = rows.filter((t) => t.features[feature] !== void 0), wins = known.filter((t) => t.pnl > 0).map((t) => t.features[feature]), losses = known.filter((t) => t.pnl < 0).map((t) => t.features[feature]);
+        const values = known.map((t) => t.features[feature]).sort((a, b) => a - b);
+        const iqr = values.length ? values[Math.floor((values.length - 1) * 0.75)] - values[Math.floor((values.length - 1) * 0.25)] : 0;
+        const winMedian = median(wins), lossMedian = median(losses);
+        return {
+          feature,
+          n: known.length,
+          missing: rows.length - known.length,
+          wins: wins.length,
+          losses: losses.length,
+          winMedian,
+          lossMedian,
+          iqr,
+          medianDifferenceIqr: iqr && winMedian !== null && lossMedian !== null ? (winMedian - lossMedian) / iqr : null
+        };
+      });
+      return [direction, { summary: summarize(rows), pockets, contrasts }];
+    })
+  );
+}
+function drawdownEpisodes(dataset) {
+  if (dataset.population !== "complete")
+    throw new Error(
+      "Drawdowns require the complete population, never a selected atlas"
+    );
+  const events = /* @__PURE__ */ new Map();
+  for (const t of dataset.trades) {
+    const group = events.get(t.exitTime) ?? [];
+    group.push(t);
+    events.set(t.exitTime, group);
+  }
+  const output = [];
+  let equity = 0, peak = 0, peakTime = dataset.trades.length ? dataset.trades.reduce((min, t) => Math.min(min, t.entryTime), Infinity) : 0;
+  let episode;
+  let members = [];
+  const finish = () => {
+    if (!episode) return;
+    const groups = /* @__PURE__ */ new Map();
+    for (const t of members)
+      for (const key of [
+        `strategy:${t.strategy}`,
+        `symbol:${t.symbol}`,
+        `direction:${t.direction}`,
+        ...Object.entries(t.groups).map(([k, v]) => `group:${k}:${v}`)
+      ]) {
+        const a = groups.get(key) ?? [];
+        a.push(t);
+        groups.set(key, a);
+      }
+    episode.contributions = Object.fromEntries(
+      [...groups].map(([k, rows]) => [k, summarize(rows)])
+    );
+    output.push(episode);
+    episode = void 0;
+    members = [];
+  };
+  for (const [timestamp, rows] of [...events].sort((a, b) => a[0] - b[0])) {
+    rows.sort(
+      (a, b) => a.strategy.localeCompare(b.strategy) || a.id.localeCompare(b.id)
+    );
+    equity += rows.reduce((s, t) => s + t.pnl, 0);
+    if (!episode && equity < peak)
+      episode = {
+        id: `drawdown-${output.length + 1}`,
+        start: peakTime,
+        trough: timestamp,
+        end: timestamp,
+        recovered: false,
+        depth: 0,
+        peak,
+        points: [[peakTime, peak]],
+        tradeIds: [],
+        contributions: {}
+      };
+    if (episode) {
+      episode.points.push([timestamp, equity]);
+      episode.end = timestamp;
+      members.push(...rows);
+      episode.tradeIds.push(...rows.map((t) => `${t.strategy}:${t.id}`));
+      if (peak - equity > episode.depth) {
+        episode.depth = peak - equity;
+        episode.trough = timestamp;
+      }
+      if (equity >= peak) {
+        episode.recovered = true;
+        finish();
+      }
+    }
+    if (equity >= peak) {
+      peak = equity;
+      peakTime = timestamp;
+    }
+  }
+  finish();
+  return output;
+}
+
+// src/lib/strategyResearch/reportFormat.ts
+var escapeResearchHtml = (value) => String(value ?? "").replace(
+  /[&<>"']/g,
+  (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character]
+);
+
+// src/lib/strategyResearch/charts.ts
+var sampleResearchCurve = (points, maximum = 1200) => {
+  if (!Number.isInteger(maximum) || maximum < 4)
+    throw new Error("Curve point budget must be at least four");
+  if (points.length <= maximum) return points;
+  const indexes = /* @__PURE__ */ new Set([0, points.length - 1]);
+  const buckets = Math.floor((maximum - 2) / 2);
+  const width = Math.ceil((points.length - 2) / buckets);
+  for (let start = 1; start < points.length - 1; start += width) {
+    const end = Math.min(points.length - 1, start + width);
+    let low = start, high = start;
+    for (let index = start + 1; index < end; index++) {
+      if (points[index][1] < points[low][1]) low = index;
+      if (points[index][1] > points[high][1]) high = index;
+    }
+    indexes.add(low);
+    indexes.add(high);
+  }
+  return [...indexes].sort((a, b) => a - b).map((index) => points[index]);
+};
+var researchLineChart = (series, title) => {
+  const populated = series.filter((item) => item.points.length);
+  if (!populated.length)
+    return `<p class="empty">${escapeResearchHtml(title)}: \u043D\u0435\u0442 \u043D\u0430\u0431\u043B\u044E\u0434\u0435\u043D\u0438\u0439.</p>`;
+  let minX = Infinity, maxX = -Infinity, minY = 0, maxY = 0;
+  for (const item of populated)
+    for (const [time2, value] of item.points) {
+      minX = Math.min(minX, time2);
+      maxX = Math.max(maxX, time2);
+      minY = Math.min(minY, value);
+      maxY = Math.max(maxY, value);
+    }
+  const span = Math.max(1e-9, maxY - minY), x = (time2) => 72 + 852 * (time2 - minX) / Math.max(1, maxX - minX), y = (value) => 238 - 196 * (value - minY) / span;
+  const paths = populated.map((item) => {
+    const points = sampleResearchCurve(item.points);
+    const path2 = points.map(
+      ([time2, value], index) => `${index ? "H" : "M"}${x(time2).toFixed(2)}${index ? "V" : ","}${y(value).toFixed(2)}`
+    ).join(" ");
+    return `<path d="${path2}" fill="none" stroke="${escapeResearchHtml(item.color)}" stroke-width="2.5" stroke-linejoin="round"/>`;
+  }).join("");
+  return `<figure class="chart"><figcaption>${escapeResearchHtml(title)}</figcaption><svg viewBox="0 0 960 285" role="img" aria-label="${escapeResearchHtml(title)}"><title>${escapeResearchHtml(title)}</title>${[
+    4
+  ].map((index) => {
+    const value = minY + span * index / 4;
+    return `<path d="M72 ${y(value)}H924" stroke="#dce5ed"/><text x="60" y="${y(value) + 4}" text-anchor="end">${value.toFixed(1)}</text>`;
+  }).join(
+    ""
+  )}<path d="M72 ${y(0)}H924" stroke="#9aaebe"/>${paths}<text x="72" y="274">${new Date(minX).toISOString().slice(0, 10)}</text><text x="924" y="274" text-anchor="end">${new Date(maxX).toISOString().slice(0, 10)}</text></svg><div class="legend">${series.map((item) => `<span><i style="background:${escapeResearchHtml(item.color)}"></i>${escapeResearchHtml(item.label)}${item.points.length ? "" : " \xB7 \u043D\u0435\u0442 \u0441\u0434\u0435\u043B\u043E\u043A"}</span>`).join("")}</div><p class="chart-note">\u0417\u0430\u043A\u0440\u044B\u0442\u044B\u0435 \u0441\u0434\u0435\u043B\u043A\u0438 \xB7 USDT. \u0413\u0440\u0430\u0444\u0438\u043A \u0441\u043E\u0445\u0440\u0430\u043D\u044F\u0435\u0442 \u043B\u043E\u043A\u0430\u043B\u044C\u043D\u044B\u0435 \u044D\u043A\u0441\u0442\u0440\u0435\u043C\u0443\u043C\u044B; \u0442\u043E\u0447\u043D\u044B\u0435 \u0437\u043D\u0430\u0447\u0435\u043D\u0438\u044F \u0445\u0440\u0430\u043D\u044F\u0442\u0441\u044F \u0432 JSON.</p></figure>`;
+};
+
+// src/lib/researchVisuals/render.ts
+var fmt = (n) => n === null ? "unknown" : Number(n.toPrecision(6)).toString();
+var utc = (n) => new Date(n).toISOString().slice(0, 16).replace("T", " ");
+var text2 = (x, y, value, size = 15, color = "#213547") => `<text x="${x}" y="${y}" font-family="Arial,sans-serif" font-size="${size}" fill="${color}">${escapeResearchHtml(String(value))}</text>`;
+function chartCandles(trade) {
+  const closes = [];
+  return trade.candles.map((b) => {
+    closes.push(b.close);
+    const sma = (n) => closes.length < n ? null : closes.slice(-n).reduce((s, v) => s + v, 0) / n;
+    const mid = sma(20), sd = mid === null ? null : Math.sqrt(
+      closes.slice(-20).reduce((s, v) => s + (v - mid) ** 2, 0) / 20
+    );
+    return {
+      ...b,
+      smaFast: b.smaFast ?? sma(14),
+      smaSlow: b.smaSlow ?? sma(50),
+      bbUpper: b.bbUpper ?? (mid !== null && sd !== null ? mid + 2 * sd : null),
+      bbLower: b.bbLower ?? (mid !== null && sd !== null ? mid - 2 * sd : null)
+    };
+  });
+}
+function pricePanel(t, c, step, x, y, w, h) {
+  if (!c.length) return text2(x, y + 30, "No cached candles in this window");
+  const times = c.map((b) => b.timestamp), start = times[0], end = times.at(-1) + step;
+  let low = Math.min(t.entryPrice, t.exitPrice, ...c.map((b) => b.low)), high = Math.max(t.entryPrice, t.exitPrice, ...c.map((b) => b.high));
+  for (const v of [t.stop, t.target])
+    if (v !== null) {
+      low = Math.min(low, v);
+      high = Math.max(high, v);
+    }
+  const pad = (high - low) * 0.05 || 1;
+  low -= pad;
+  high += pad;
+  const X = (v) => x + w * (v - start) / Math.max(1, end - start), Y = (v) => y + h - h * (v - low) / (high - low);
+  const id = `clip-${x}-${y}`;
+  let s = `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="white" stroke="#cbd5df"/>`;
+  for (let i = 0; i <= 4; i++)
+    s += `<path d="M${x} ${y + h * i / 4}h${w}" stroke="#e5eaf0"/>` + text2(
+      x + w + 5,
+      y + h * i / 4 + 4,
+      fmt(high - (high - low) * i / 4),
+      11
+    );
+  s += `<defs><clipPath id="${id}"><rect x="${x}" y="${y}" width="${w}" height="${h}"/></clipPath></defs><g clip-path="url(#${id})">`;
+  for (const z of t.figures.zones)
+    s += `<rect x="${Math.min(X(z.start.timestamp), X(z.end.timestamp))}" y="${Math.min(Y(z.start.value), Y(z.end.value))}" width="${Math.abs(X(z.end.timestamp) - X(z.start.timestamp))}" height="${Math.abs(Y(z.end.value) - Y(z.start.value))}" fill="#dceafa" opacity=".5"/>`;
+  const stride = Math.max(1, Math.ceil(c.length / 900)), width = Math.max(0.7, w * step / (end - start) * stride * 0.65);
+  for (let i = 0; i < c.length; i += stride) {
+    const a = c.slice(i, i + stride), first = a[0], last = a.at(-1), hi = Math.max(...a.map((b) => b.high)), lo = Math.min(...a.map((b) => b.low)), color = last.close >= first.open ? "#0a8069" : "#c73f52", xx = X(first.timestamp);
+    s += `<path d="M${xx} ${Y(lo)}V${Y(hi)}" stroke="${color}"/><rect x="${xx - width / 2}" y="${Math.min(Y(first.open), Y(last.close))}" width="${width}" height="${Math.max(0.8, Math.abs(Y(first.open) - Y(last.close)))}" fill="${color}"/>`;
+  }
+  for (const [key, color] of [
+    ["smaFast", "#d88b00"],
+    ["smaSlow", "#8555cc"],
+    ["bbUpper", "#8898ab"],
+    ["bbLower", "#8898ab"]
+  ]) {
+    let previous = null;
+    const path2 = c.map((b) => {
+      const v = b[key];
+      if (v == null) {
+        previous = null;
+        return "";
+      }
+      const command = previous === null || b.timestamp - previous !== step ? "M" : "L";
+      previous = b.timestamp;
+      return `${command}${X(b.timestamp)},${Y(v)}`;
+    }).join(" ");
+    s += `<path d="${path2}" fill="none" stroke="${color}" stroke-width="1.4"/>`;
+  }
+  for (const line of t.figures.lines)
+    s += `<polyline points="${line.points.map((p) => `${X(p.timestamp)},${Y(p.value)}`).join(" ")}" fill="none" stroke="#0284c7" stroke-width="2"/>`;
+  for (const group of t.figures.points)
+    for (const p of group.points)
+      s += `<circle cx="${X(p.timestamp)}" cy="${Y(p.value)}" r="3" fill="#0284c7"/>`;
+  for (const [label, value, color] of [
+    ["SL", t.stop, "#c73f52"],
+    ["TP", t.target, "#0a8069"]
+  ])
+    if (value !== null)
+      s += `<path d="M${x} ${Y(value)}h${w}" stroke="${color}" stroke-dasharray="5 4"/>` + text2(x + 4, Y(value) - 5, label, 12, color);
+  for (const [i, [label, timestamp, value]] of [
+    ["SIGNAL", t.signalTime, null],
+    ["ENTRY", t.entryTime, t.entryPrice],
+    ["EXIT", t.exitTime, t.exitPrice]
+  ].entries())
+    if (timestamp >= start && timestamp <= end) {
+      s += `<path d="M${X(timestamp)} ${y}v${h}" stroke="#2563eb" stroke-dasharray="3 4"/>` + text2(
+        Math.max(x + 3, Math.min(x + w - 75, X(timestamp) + 4)),
+        y + 17 + i * 17,
+        label,
+        12
+      );
+      if (value !== null)
+        s += `<circle cx="${X(timestamp)}" cy="${Y(value)}" r="5" fill="white" stroke="#2563eb" stroke-width="2"/>`;
+    }
+  return s + "</g>" + text2(x, y + h + 20, utc(start), 12) + text2(x + w - 145, y + h + 20, utc(end), 12) + text2(
+    x,
+    y - 8,
+    `OHLC aggregation: ${stride} native bars per displayed candle`,
+    11
+  );
+}
+function renderTradeSvg(t, intervalMs) {
+  const candles = chartCandles(t);
+  const start = Math.min(
+    t.signalTime - 90 * intervalMs,
+    t.entryTime - 90 * intervalMs
+  ), end = t.exitTime + 20 * intervalMs;
+  const visible = candles.filter(
+    (c) => c.timestamp >= start && c.timestamp <= end
+  );
+  const held = candles.filter(
+    (b) => b.timestamp >= t.entryTime && b.timestamp + intervalMs <= t.exitTime
+  ), risk = t.stop === null ? null : Math.abs(t.entryPrice - t.stop), sign = t.direction === "LONG" ? 1 : -1;
+  const expected = visible.length ? Math.floor(
+    (visible.at(-1).timestamp - visible[0].timestamp) / intervalMs
+  ) + 1 : 0;
+  const complete = held.length > 0 && held[0].timestamp === t.entryTime && held.at(-1).timestamp + intervalMs === t.exitTime && held.every(
+    (b, i) => !i || b.timestamp - held[i - 1].timestamp === intervalMs
+  );
+  const mfe = complete && risk ? Math.max(
+    0,
+    ...held.map(
+      (b) => (sign === 1 ? b.high - t.entryPrice : t.entryPrice - b.low) / risk
+    )
+  ) : null, mae = complete && risk ? Math.max(
+    0,
+    ...held.map(
+      (b) => (sign === 1 ? t.entryPrice - b.low : b.high - t.entryPrice) / risk
+    )
+  ) : null;
+  let svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1050" viewBox="0 0 1600 1050"><rect width="1600" height="1050" fill="#f3f6fa"/>`;
+  svg += text2(40, 35, `${t.strategy} \xB7 ${t.symbol} \xB7 ${t.direction}`, 25) + text2(
+    40,
+    64,
+    `${t.pnl > 0 ? "WIN" : t.pnl < 0 ? "LOSS" : "FLAT"} \xB7 net ${fmt(t.pnl)} USDT \xB7 ${utc(t.entryTime)} \u2192 ${utc(t.exitTime)} UTC`,
+    17
+  );
+  svg += text2(
+    40,
+    88,
+    "Saved indicator series when supplied; otherwise analytical SMA14/50 and BB20 \xB12\u03C3 (not strategy calculations).",
+    12
+  );
+  svg += pricePanel(t, visible, intervalMs, 40, 120, 1440, 330);
+  const maxVolume = Math.max(1, ...visible.map((b) => b.volume));
+  svg += text2(40, 497, "Native-bar volume", 13);
+  for (const b of visible) {
+    const x = 40 + 1440 * (b.timestamp - (visible[0]?.timestamp ?? 0)) / Math.max(
+      1,
+      (visible.at(-1)?.timestamp ?? 0) + intervalMs - (visible[0]?.timestamp ?? 0)
+    );
+    svg += `<path d="M${x} 575v${-65 * b.volume / maxVolume}" stroke="#8cabbc"/>`;
+  }
+  svg += text2(
+    40,
+    615,
+    "Entry detail: signal and actual fill are separate events",
+    15
+  ) + pricePanel(
+    t,
+    candles.filter(
+      (b) => b.timestamp >= t.signalTime - 30 * intervalMs && b.timestamp <= t.entryTime + 12 * intervalMs
+    ),
+    intervalMs,
+    40,
+    645,
+    960,
+    260
+  );
+  const details = [
+    `Entry ${fmt(t.entryPrice)} / exit ${fmt(t.exitPrice)}`,
+    `MFE ${fmt(mfe)} R / MAE ${fmt(mae)} R`,
+    `Full held bars available: ${complete}`,
+    `Missing display bars: ${expected - visible.length}`,
+    `Pockets: ${Object.entries(t.pockets).map(([k, v]) => `${k}=${v ? "pass" : "fail"}`).join(", ") || "unknown"}`
+  ];
+  details.forEach(
+    (v, i) => svg += text2(
+      1080,
+      665 + i * 38,
+      v.length > 58 ? v.slice(0, 55) + "\u2026" : v,
+      13
+    )
+  );
+  svg += text2(
+    40,
+    960,
+    "MFE/MAE exclude partial entry/exit bars and require complete held coverage; these are retrospective diagnostics.",
+    13
+  ) + text2(40, 988, `Trade ID: ${t.id}`.slice(0, 180), 12) + text2(
+    40,
+    1015,
+    "Outcome-balanced charts describe cases, not the population win rate. Pocket overlays do not simulate skipped entries.",
+    12
+  );
+  return {
+    svg: svg + "</svg>",
+    audit: {
+      visibleCandles: visible.length,
+      missingCandles: expected - visible.length,
+      completeHeld: complete,
+      mfeR: mfe,
+      maeR: mae,
+      entryCovered: visible.some(
+        (b) => b.timestamp <= t.entryTime && b.timestamp + intervalMs > t.entryTime
+      ),
+      exitCovered: visible.some(
+        (b) => b.timestamp <= t.exitTime && b.timestamp + intervalMs > t.exitTime
+      )
+    }
+  };
+}
+function renderDrawdownSvg(episode) {
+  const curve = researchLineChart(
+    [
+      { label: "Realized equity", points: episode.points, color: "#2563eb" },
+      {
+        label: "Prior peak",
+        points: [
+          [episode.start, episode.peak],
+          [episode.end, episode.peak]
+        ],
+        color: "#c73f52"
+      }
+    ],
+    episode.id
+  );
+  const plot = curve.slice(curve.indexOf("<svg"), curve.indexOf("</svg>") + 6).replace(
+    'viewBox="0 0 960 285"',
+    'x="20" y="100" width="1160" height="360" viewBox="0 0 960 285"'
+  );
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="700"><rect width="1200" height="700" fill="#f3f6fa"/>${text2(35, 35, `${episode.id}: depth ${fmt(episode.depth)} USDT`, 24)}${text2(35, 65, `${utc(episode.start)} \u2192 ${utc(episode.end)} UTC \xB7 ${episode.recovered ? "recovered" : "unrecovered / right-censored"}`, 16)}${plot}${Object.entries(
+    episode.contributions
+  ).filter(([k]) => k.startsWith("symbol:")).sort((a, b) => a[1].pnl - b[1].pnl).slice(0, 5).map(
+    ([k, v], i) => text2(40, 500 + i * 30, `${k} \xB7 N=${v.n} \xB7 PnL=${fmt(v.pnl)}`, 16)
+  ).join(
+    ""
+  )}${text2(35, 675, "Completed-trade equity; simultaneous exits netted. Includes recovery trades. Not mark-to-market drawdown.", 13)}</svg>`;
+}
+
+// src/lib/researchVisuals.ts
+var sha = (v) => (0, import_node_crypto2.createHash)("sha256").update(v).digest("hex");
+async function readInput(file) {
+  const stat = await import_promises.default.stat(file);
+  if (stat.size > 512 * 1024 * 1024)
+    throw new Error("Visual input exceeds 512 MiB");
+  const bytes = await import_promises.default.readFile(file), decoded = file.endsWith(".gz") ? (0, import_node_zlib.gunzipSync)(bytes, { maxOutputLength: 512 * 1024 * 1024 }) : bytes;
+  const source = decoded.toString("utf8");
+  const value = /\.jsonl(?:\.gz)?$/.test(file) ? source.split(/\r?\n/).filter((l) => l.trim()).map((l) => JSON.parse(l)) : JSON.parse(source);
+  return {
+    value,
+    receipt: {
+      path: import_node_path.default.resolve(file),
+      sha256: sha(bytes),
+      bytes: bytes.length
+    }
+  };
+}
+async function generateResearchVisuals(options) {
+  if (!options.inputs.length) throw new Error("At least one input is required");
+  const inputs = await Promise.all(options.inputs.map(readInput));
+  if (inputs.length > 1 && inputs.some((i) => !Array.isArray(i.value)))
+    throw new Error(
+      "Multiple inputs are supported only for JSONL/array shards"
+    );
+  const candles = options.candlesFile ? await readInput(options.candlesFile) : void 0;
+  const dataset = normalizeDataset(
+    inputs.length === 1 ? inputs[0].value : inputs.flatMap((i) => Array.isArray(i.value) ? i.value : []),
+    {
+      population: options.population,
+      intervalMs: options.intervalMs,
+      strategy: options.strategy,
+      candlesBySymbol: candles ? object(candles.value) : void 0
+    }
+  );
+  const selected = selectAtlas(
+    dataset.trades,
+    options.count ?? 100,
+    options.seed ?? "trade-atlas/v1"
+  );
+  const episodes = dataset.population === "complete" ? Object.fromEntries(
+    ["ALL", "LONG", "SHORT"].map((direction) => [
+      direction,
+      drawdownEpisodes({
+        ...dataset,
+        trades: dataset.trades.filter(
+          (t) => direction === "ALL" || t.direction === direction
+        )
+      })
+    ])
+  ) : null;
+  const analysis = Object.fromEntries(
+    [...new Set(dataset.trades.map((t) => t.strategy))].sort().map((strategy) => [
+      strategy,
+      analyzeVisualTrades(
+        dataset.trades.filter((t) => t.strategy === strategy)
+      )
+    ])
+  );
+  const out = import_node_path.default.resolve(options.outDir);
+  await import_promises.default.mkdir(import_node_path.default.dirname(out), { recursive: true });
+  await import_promises.default.mkdir(out);
+  const receipts = {};
+  const write = async (name, data) => {
+    const bytes = typeof data === "string" ? Buffer.from(data) : data;
+    await import_promises.default.writeFile(import_node_path.default.join(out, name), bytes, { flag: "wx" });
+    receipts[name] = { sha256: sha(bytes), bytes: bytes.length };
+  };
+  const manifest = {
+    schema: "tradejs-research-visual-report/v1",
+    status: "running",
+    source: dataset.source,
+    population: dataset.population,
+    populationClaim: dataset.population === "complete" ? "Caller declares complete reconciled population" : "Selected cases; no population or drawdown inference",
+    inputs: inputs.map((i) => i.receipt),
+    candles: candles?.receipt,
+    selection: {
+      countPerOutcomePerStrategy: options.count ?? 100,
+      seed: options.seed ?? "trade-atlas/v1",
+      method: "Equal chronological strata; SHA256 choice within stratum; no replacement"
+    },
+    summary: summarize(dataset.trades),
+    selected: selected.length,
+    semantics: "Retrospective associations, not causal validation. Pocket labels are supplied snapshots, not a native portfolio rerun."
+  };
+  await import_promises.default.writeFile(
+    import_node_path.default.join(out, "manifest.json"),
+    JSON.stringify(manifest, null, 2)
+  );
+  try {
+    await import_promises.default.mkdir(import_node_path.default.join(out, "trades"));
+    await import_promises.default.mkdir(import_node_path.default.join(out, "drawdowns"));
+    const cards = [];
+    for (const [index, trade] of selected.entries()) {
+      const name = `trades/${String(index + 1).padStart(4, "0")}-${sha(trade.strategy + ":" + trade.id).slice(0, 12)}`;
+      const { svg, audit } = renderTradeSvg(trade, dataset.intervalMs);
+      await write(name + ".svg", svg);
+      if (options.png)
+        await write(
+          name + ".png",
+          await (0, import_sharp.default)(Buffer.from(svg)).png().toBuffer()
+        );
+      cards.push({
+        id: trade.id,
+        strategy: trade.strategy,
+        symbol: trade.symbol,
+        direction: trade.direction,
+        pnl: trade.pnl,
+        outcome: trade.pnl > 0 ? "win" : "loss",
+        pockets: trade.pockets,
+        svg: name + ".svg",
+        image: name + (options.png ? ".png" : ".svg"),
+        audit
+      });
+    }
+    const drawdownCards = [];
+    for (const [direction, group] of Object.entries(episodes ?? {}))
+      for (const episode of group) {
+        const name = `drawdowns/${direction}-${episode.id}`;
+        const svg = renderDrawdownSvg(episode);
+        await write(name + ".svg", svg);
+        if (options.png)
+          await write(
+            name + ".png",
+            await (0, import_sharp.default)(Buffer.from(svg)).png().toBuffer()
+          );
+        drawdownCards.push({
+          ...episode,
+          direction,
+          image: name + (options.png ? ".png" : ".svg")
+        });
+      }
+    const retained = {
+      ...dataset,
+      population: "selected",
+      trades: selected.map((trade) => ({
+        ...trade,
+        candles: trade.candles.filter(
+          (bar) => bar.timestamp >= trade.signalTime - 140 * dataset.intervalMs && bar.timestamp <= trade.exitTime + 20 * dataset.intervalMs
+        )
+      }))
+    };
+    await write("chart-inputs.json.gz", (0, import_node_zlib.gzipSync)(JSON.stringify(retained)));
+    await write(
+      "analysis.json",
+      JSON.stringify(
+        {
+          schema: "tradejs-visual-analysis/v1",
+          population: dataset.population,
+          analysis,
+          drawdowns: episodes,
+          cards
+        },
+        null,
+        2
+      )
+    );
+    const option = (value) => `<option value="${escapeResearchHtml(value)}">${escapeResearchHtml(value)}</option>`;
+    const selectors = [
+      ["strategy", [...new Set(cards.map((c) => c.strategy))]],
+      ["outcome", ["win", "loss"]],
+      ["direction", ["LONG", "SHORT"]],
+      ["pocket", [...new Set(cards.flatMap((c) => Object.keys(c.pockets)))]]
+    ].map(
+      ([key, values]) => `<label>${key} <select id="${key}"><option value="">all</option>${values.map(option).join("")}</select></label>`
+    ).join(" ");
+    const contrastTables = Object.entries(analysis).map(
+      ([strategy, bySide]) => `<h3>${escapeResearchHtml(strategy)}</h3>${Object.entries(bySide).map(
+        ([side, info]) => `<h4>${side}</h4><table><tr><th>Pocket</th><th>Pass N / PnL</th><th>Fail N / PnL</th><th>Unknown</th></tr>${Object.entries(
+          info.pockets
+        ).map(
+          ([name, p]) => `<tr><td>${escapeResearchHtml(name)}</td><td>${p.pass.n} / ${p.pass.pnl.toFixed(2)}</td><td>${p.fail.n} / ${p.fail.pnl.toFixed(2)}</td><td>${p.unknown}</td></tr>`
+        ).join(
+          ""
+        )}</table><table><tr><th>Feature</th><th>Win / loss N</th><th>Win median</th><th>Loss median</th><th>Difference / IQR</th><th>Missing</th></tr>${info.contrasts.filter(
+          (c) => c.wins >= 5 && c.losses >= 5 && c.medianDifferenceIqr !== null
+        ).sort(
+          (a, b) => Math.abs(b.medianDifferenceIqr) - Math.abs(a.medianDifferenceIqr)
+        ).slice(0, 20).map(
+          (c) => `<tr><td>${escapeResearchHtml(c.feature)}</td><td>${c.wins} / ${c.losses}</td><td>${c.winMedian}</td><td>${c.lossMedian}</td><td>${c.medianDifferenceIqr?.toFixed(2)}</td><td>${c.missing}</td></tr>`
+        ).join("")}</table>`
+      ).join("")}`
+    ).join("");
+    const html = `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Trade atlas and drawdown groups</title><style>body{font:16px system-ui;color:#213547;background:#f3f6fa;margin:28px}h1{font-size:30px}section{margin:32px 0}.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(420px,1fr));gap:18px}article{background:white;padding:16px;border-radius:12px}img{width:100%}select{padding:8px}table{border-collapse:collapse;background:white;margin:16px 0;font-size:14px}td,th{padding:8px;border:1px solid #d9e2ec;text-align:left}a{color:#175eb9}.note{max-width:1100px}article[hidden]{display:none}</style><h1>Trade atlas and drawdown groups</h1><p class="note">${escapeResearchHtml(manifest.populationClaim)}. Source: ${escapeResearchHtml(dataset.source)}. ${escapeResearchHtml(manifest.semantics)}</p><p>Input N=${dataset.trades.length}; selected charts=${cards.length}. Balanced win/loss selection is not a win-rate estimate. Associations below use ${dataset.population === "complete" ? "all supplied completed trades" : "selected cases only, with selection bias"}.</p><p><a href="analysis.json">Full analysis and coverage</a> \xB7 <a href="manifest.json">Provenance</a> \xB7 <a href="chart-inputs.json.gz">Retained chart inputs</a></p><section><h2>Trade cases</h2>${selectors}<div class="grid">${cards.map((c) => `<article class="trade" data-strategy="${escapeResearchHtml(c.strategy)}" data-outcome="${c.outcome}" data-direction="${c.direction}" data-pockets="${escapeResearchHtml(JSON.stringify(c.pockets))}"><h3>${escapeResearchHtml(c.strategy)} \xB7 ${escapeResearchHtml(c.symbol)} \xB7 ${c.direction} \xB7 ${c.pnl.toFixed(2)}</h3><a href="${c.image}"><img loading="lazy" src="${c.image}" alt="${escapeResearchHtml(c.id)}"></a><p>${escapeResearchHtml(JSON.stringify(c.pockets))}</p><p>Missing bars: ${c.audit.missingCandles}; entry covered: ${c.audit.entryCovered}; exit covered: ${c.audit.exitCovered}</p><a href="${c.svg}">SVG</a></article>`).join("")}</div></section><section><h2>Pockets and feature contrasts</h2><p>Descriptive differences only. No optimized threshold, significance or profitability claim. Tables show features with at least 5 wins and 5 losses; JSON retains all support counts.</p>${contrastTables}</section><section><h2>Drawdown episodes</h2><p>${episodes ? "Completed-trade equity; same-time exits netted. ALL is portfolio equity, LONG/SHORT are side-only equity. Group contributions overlap across dimensions and include recovery trades." : "Unavailable: selected charts cannot reconstruct portfolio drawdowns."}</p><div class="grid">${drawdownCards.map(
+      (e) => `<article><h3>${e.direction} \xB7 ${e.id} \xB7 ${e.depth.toFixed(2)} USDT</h3><a href="${e.image}"><img loading="lazy" src="${e.image}" alt="${e.id}"></a><details><summary>Group contributions</summary><table><tr><th>Group</th><th>N</th><th>PnL</th></tr>${Object.entries(
+        e.contributions
+      ).map(
+        ([name, v]) => `<tr><td>${escapeResearchHtml(name)}</td><td>${v.n}</td><td>${v.pnl.toFixed(2)}</td></tr>`
+      ).join("")}</table></details></article>`
+    ).join(
+      ""
+    )}</div></section><script>for(const id of ['strategy','outcome','direction','pocket'])document.getElementById(id).addEventListener('change',()=>{for(const card of document.querySelectorAll('.trade'))card.hidden=['strategy','outcome','direction'].some(k=>document.getElementById(k).value&&card.dataset[k]!==document.getElementById(k).value)||(document.getElementById('pocket').value&&JSON.parse(card.dataset.pockets)[document.getElementById('pocket').value]!==true);});</script></html>`;
+    await write("index.html", html);
+    await import_promises.default.writeFile(
+      import_node_path.default.join(out, "manifest.json"),
+      JSON.stringify(
+        { ...manifest, status: "complete", files: receipts },
+        null,
+        2
+      )
+    );
+    return {
+      outDir: out,
+      selected: cards.length,
+      episodes: drawdownCards.length
+    };
+  } catch (error) {
+    await import_promises.default.writeFile(
+      import_node_path.default.join(out, "manifest.json"),
+      JSON.stringify(
+        {
+          ...manifest,
+          status: "failed",
+          error: error instanceof Error ? error.message : String(error)
+        },
+        null,
+        2
+      )
+    );
+    throw error;
+  }
+}
+
+// src/scripts/researchVisuals.ts
+async function main() {
+  const args = process.argv.slice(2);
+  const options = { inputs: [], outDir: "" };
+  for (let i = 0; i < args.length; i++) {
+    const key = args[i];
+    if (key === "research-visuals") continue;
+    if (key === "--help") {
+      console.log(
+        "tradejs research-visuals --input FILE [--input SHARD] --outDir NEW_DIR [--population complete|selected] [--intervalMs N] [--strategy NAME] [--candles FILE] [--count 100] [--seed TEXT] [--png]"
+      );
+      return;
+    }
+    if (key === "--png") {
+      options.png = true;
+      continue;
+    }
+    const value = args[++i];
+    if (!value || value.startsWith("--"))
+      throw new Error(`Value required: ${key}`);
+    switch (key) {
+      case "--input":
+        options.inputs.push(value);
+        break;
+      case "--outDir":
+        options.outDir = value;
+        break;
+      case "--population":
+        if (value !== "complete" && value !== "selected")
+          throw new Error("Invalid population");
+        options.population = value;
+        break;
+      case "--intervalMs":
+        options.intervalMs = Number(value);
+        break;
+      case "--count":
+        options.count = Number(value);
+        break;
+      case "--seed":
+        options.seed = value;
+        break;
+      case "--strategy":
+        options.strategy = value;
+        break;
+      case "--candles":
+        options.candlesFile = value;
+        break;
+      default:
+        throw new Error(`Unknown option ${key}`);
+    }
+  }
+  if (!options.outDir) throw new Error("--outDir is required");
+  console.log(JSON.stringify(await generateResearchVisuals(options)));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main
+});