desic-okx-agent 0.2.1 → 0.3.0

package/dist/report/compare-html.js

@@ -0,0 +1,254 @@
+import { activeLocale, activeMessages } from "../i18n/locale.js";
+import { COMPARE_SCRIPT } from "./compare-script.js";
+import { COMPARE_STYLES, escapeAttribute, escapeHtml } from "./html.js";
+/** One colour per curve. Distinguishable in both colour schemes and when printed. */
+const SERIES_COLOURS = ["#4f9cf9", "#f2777a", "#3fb950", "#d29922", "#a371f7", "#22b8cf"];
+/**
+ * Renders a self-contained comparison of two or more runs.
+ *
+ * Same constraints as a single report: everything inlined, nothing fetched at view
+ * time, so it opens offline and never sends a strategy anywhere.
+ */
+export function renderComparisonHtml(report) {
+    const text = activeMessages();
+    const title = report.runs.map((run) => run.id).join(" · ");
+    return `<!DOCTYPE html>
+<html lang="${activeLocale()}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(text.comparisonHeading)} · ${escapeHtml(title)}</title>
+<style>${COMPARE_STYLES}</style>
+</head>
+<body>
+<main>
+  <header>
+    <div>
+      <h1>${escapeHtml(text.comparisonHeading)}</h1>
+      <p class="sub">${escapeHtml(report.runs.map((run) => run.strategyName).join(" · "))}</p>
+    </div>
+  </header>
+
+  ${renderWarnings(report, text)}
+  ${renderLegend(report)}
+
+  <section>
+    <h2>${escapeHtml(text.normalizedEquityHeading)}</h2>
+    ${renderOverlay(report, text)}
+  </section>
+
+  ${renderMetrics(report, text)}
+  ${renderAssumptions(report, text)}
+
+  <footer>
+    <p>${escapeHtml(text.compareNormalizedNote)}</p>
+    <p>${escapeHtml(text.simulationNote)}</p>
+  </footer>
+</main>
+<script>${COMPARE_SCRIPT}</script>
+</body>
+</html>`;
+}
+function renderWarnings(report, text) {
+    if (report.warnings.length === 0)
+        return "";
+    // Placed above the chart on purpose: a reader who scrolls straight to the curves
+    // should not have to look for the reason they may not be comparable.
+    return `<div class="warnings">${report.warnings
+        .map((warning) => `<p>${escapeHtml(warning.message)}</p>`)
+        .join("")}</div>`;
+}
+function renderLegend(report) {
+    return `<div class="legend">${report.series
+        .map((series, index) => `<div><i style="background:${colour(index)}"></i><span>${escapeHtml(series.label)}</span></div>`)
+        .join("")}</div>`;
+}
+/**
+ * Overlays every curve on one indexed axis.
+ *
+ * The x axis is wall-clock time spanning the union of all runs, so two runs over
+ * different windows sit where they actually happened rather than being stretched
+ * to the same width — which would imply they covered the same period.
+ */
+function renderOverlay(report, text) {
+    const plotted = report.series.filter((series) => series.indexed.length > 1);
+    if (plotted.length === 0)
+        return `<p class="empty">${escapeHtml(text.notEnoughPoints)}</p>`;
+    const width = 1000;
+    const height = 300;
+    const startMs = Math.min(...plotted.map((series) => series.timeMs[0]));
+    const endMs = Math.max(...plotted.map((series) => series.timeMs.at(-1)));
+    const span = endMs - startMs || 1;
+    const values = plotted.flatMap((series) => series.indexed);
+    const minimum = Math.min(...values, 100);
+    const maximum = Math.max(...values, 100);
+    const range = maximum - minimum || 1;
+    const x = (timeMs) => ((timeMs - startMs) / span) * width;
+    const y = (value) => height - ((value - minimum) / range) * height;
+    const paths = plotted
+        .map((series, index) => {
+        const path = series.indexed
+            .map((value, point) => `${point === 0 ? "M" : "L"}${x(series.timeMs[point]).toFixed(1)},${y(value).toFixed(1)}`)
+            .join("");
+        return `<path d="${path}" fill="none" stroke="${colour(index)}" stroke-width="1.6" vector-effect="non-scaling-stroke"/>`;
+    })
+        .join("");
+    // Index 100 is break-even. Without it, "did this make money" is unanswerable
+    // from a curve scaled to its own range.
+    const baseline = minimum < 100 && maximum > 100
+        ? `<line class="baseline" x1="0" y1="${y(100).toFixed(1)}" x2="${width}" y2="${y(100).toFixed(1)}"/>`
+        : "";
+    const payload = {
+        startMs,
+        endMs,
+        series: plotted.map((series, index) => ({
+            label: series.label,
+            colour: colour(index),
+            t: series.timeMs,
+            v: series.indexed.map((value) => Number(value.toFixed(3)))
+        })),
+        labels: { time: text.hoverTime, equity: text.normalizedEquityHeading }
+    };
+    return `
+  <div class="chart" id="compare-chart" data-series='${escapeAttribute(JSON.stringify(payload))}'>
+    <svg viewBox="0 -8 ${width} ${height + 16}" preserveAspectRatio="none" role="img" aria-label="normalized equity comparison">
+      ${baseline}
+      ${paths}
+      <line class="crosshair" x1="0" y1="-8" x2="0" y2="${height}" hidden/>
+    </svg>
+    <div class="axis"><span>${maximum.toFixed(1)}</span><span>${minimum.toFixed(1)}</span></div>
+    <div class="tooltip" hidden></div>
+  </div>
+  <p class="range mono">${escapeHtml(isoMinute(startMs))} → ${escapeHtml(isoMinute(endMs))} UTC · ${escapeHtml(text.hoverPrompt)}</p>`;
+}
+/**
+ * Metrics table, one column per run.
+ *
+ * The best value in each row is marked. On a six-run table that is the difference
+ * between reading the comparison and doing arithmetic across columns — and the
+ * direction differs per metric, since a low drawdown is good and a low return is
+ * not.
+ */
+function renderMetrics(report, text) {
+    const rows = COMPARED_ROWS.map(([label, key, better, kind]) => {
+        const values = report.runs.map((run) => num(run.metrics?.[key]));
+        const best = bestIndex(values, better);
+        return `<tr>
+      <th scope="row">${escapeHtml(label(text))}</th>
+      ${values
+            .map((value, index) => `<td class="n${index === best ? " best" : ""}">${escapeHtml(format(value, kind))}</td>`)
+            .join("")}
+    </tr>`;
+    }).join("");
+    return `
+  <section>
+    <h2>${escapeHtml(text.comparedRunsHeading)}</h2>
+    <div class="scroll">
+    <table class="matrix">
+      <thead><tr><th></th>${report.runs
+        .map((run, index) => `<th class="n"><i style="background:${colour(index)}"></i>${escapeHtml(run.id)}<span class="dim">${escapeHtml(run.instId)}</span></th>`)
+        .join("")}</tr></thead>
+      <tbody>${rows}</tbody>
+    </table>
+    </div>
+  </section>`;
+}
+/** `higher` and `lower` say which direction is an improvement for each metric. */
+const COMPARED_ROWS = [
+    [(text) => text.returnLabel, "returnPct", "higher", "signed"],
+    [(text) => text.maxDrawdown, "maxDrawdownPct", "lower", "pct"],
+    [(text) => text.calmarLabel, "calmar", "higher", "plain"],
+    [(text) => text.sharpeLabel, "sharpe", "higher", "plain"],
+    [(text) => text.sortinoLabel, "sortino", "higher", "plain"],
+    [(text) => text.tradesLabel, "tradeCount", "none", "plain"],
+    [(text) => text.winRate, "winRatePct", "higher", "pct"],
+    [(text) => text.profitFactor, "profitFactor", "higher", "plain"],
+    [(text) => text.expectancy, "expectancyUsdt", "higher", "signed"],
+    [(text) => text.feesLabel, "totalFeesUsdt", "lower", "plain"],
+    [(text) => text.feesOfGross, "feesPctOfGross", "lower", "pct"],
+    [(text) => text.turnover, "turnoverUsdt", "none", "plain"],
+    [(text) => text.exposure, "exposurePct", "none", "pct"]
+];
+/**
+ * Assumption rows, differences first.
+ *
+ * The shared ones are listed after and collapsed to a single column, because the
+ * question a comparison answers is what changed.
+ */
+function renderAssumptions(report, text) {
+    if (report.differingAssumptions.length === 0) {
+        return `<section><h2>${escapeHtml(text.differingAssumptionsHeading)}</h2><p class="empty">${escapeHtml(text.assumptionsIdentical)}</p></section>`;
+    }
+    const rows = report.differingAssumptions
+        .map((entry) => `<tr>
+      <th scope="row">${escapeHtml(entry.key)}</th>
+      ${entry.values.map((value) => `<td class="n differs">${escapeHtml(value ?? "-")}</td>`).join("")}
+    </tr>`)
+        .join("");
+    const shared = report.sharedAssumptions.length > 0
+        ? `<p class="empty">${escapeHtml(text.sharedAssumptionsNote(String(report.sharedAssumptions.length)))}</p>`
+        : "";
+    return `
+  <section>
+    <h2>${escapeHtml(text.differingAssumptionsHeading)}</h2>
+    <div class="scroll">
+    <table class="matrix">
+      <thead><tr><th></th>${report.runs.map((run) => `<th class="n">${escapeHtml(run.id)}</th>`).join("")}</tr></thead>
+      <tbody>${rows}</tbody>
+    </table>
+    </div>
+    ${shared}
+  </section>`;
+}
+/**
+ * Index of the best value in a row, or -1 when there is no winner.
+ *
+ * A tie is left unmarked: highlighting one of two identical numbers invents a
+ * distinction that is not in the data.
+ */
+function bestIndex(values, better) {
+    if (better === "none")
+        return -1;
+    let best = -1;
+    let bestValue = better === "higher" ? -Infinity : Infinity;
+    let ties = 0;
+    values.forEach((value, index) => {
+        if (value === null)
+            return;
+        if (value === bestValue) {
+            ties += 1;
+            return;
+        }
+        if (better === "higher" ? value > bestValue : value < bestValue) {
+            bestValue = value;
+            best = index;
+            ties = 0;
+        }
+    });
+    return ties > 0 ? -1 : best;
+}
+function num(value) {
+    if (value === null || value === undefined)
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function format(value, kind) {
+    if (value === null)
+        return "-";
+    const magnitude = Math.abs(value);
+    const body = magnitude >= 1_000_000
+        ? `${(value / 1_000_000).toFixed(2)}M`
+        : magnitude >= 1_000
+            ? value.toFixed(0)
+            : value.toFixed(2);
+    const sign = kind === "signed" && value > 0 ? "+" : "";
+    return `${sign}${body}${kind === "plain" ? "" : "%"}`;
+}
+function colour(index) {
+    return SERIES_COLOURS[index % SERIES_COLOURS.length];
+}
+function isoMinute(ms) {
+    return new Date(ms).toISOString().slice(0, 16).replace("T", " ");
+}
+//# sourceMappingURL=compare-html.js.map

package/dist/report/compare-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-html.js","sourceRoot":"","sources":["../../src/report/compare-html.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGjE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAExE,qFAAqF;AACrF,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAE1F;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAwB;IAC3D,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAE3D,OAAO;cACK,YAAY,EAAE;;;;SAInB,UAAU,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,UAAU,CAAC,KAAK,CAAC;SACzD,cAAc;;;;;;YAMX,UAAU,CAAC,IAAI,CAAC,iBAAiB,CAAC;uBACvB,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;;;IAIrF,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC;IAC5B,YAAY,CAAC,MAAM,CAAC;;;UAGd,UAAU,CAAC,IAAI,CAAC,uBAAuB,CAAC;MAC5C,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC;;;IAG7B,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC;IAC3B,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC;;;SAG1B,UAAU,CAAC,IAAI,CAAC,qBAAqB,CAAC;SACtC,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC;;;UAG9B,cAAc;;QAEhB,CAAC;AACT,CAAC;AAED,SAAS,cAAc,CAAC,MAAwB,EAAE,IAAc;IAC9D,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5C,iFAAiF;IACjF,qEAAqE;IACrE,OAAO,yBAAyB,MAAM,CAAC,QAAQ;SAC5C,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC;SACzD,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC;AACtB,CAAC;AAED,SAAS,YAAY,CAAC,MAAwB;IAC5C,OAAO,uBAAuB,MAAM,CAAC,MAAM;SACxC,GAAG,CACF,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAChB,6BAA6B,MAAM,CAAC,KAAK,CAAC,eAAe,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CACnG;SACA,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC;AACtB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,MAAwB,EAAE,IAAc;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,oBAAoB,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;IAE5F,MAAM,KAAK,GAAG,IAAI,CAAC;IACnB,MAAM,MAAM,GAAG,GAAG,CAAC;IACnB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAG,KAAK,GAAG,OAAO,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,OAAO,GAAG,OAAO,IAAI,CAAC,CAAC;IAErC,MAAM,CAAC,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;IAC1E,MAAM,CAAC,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG,OAAO,CAAC,GAAG,KAAK,CAAC,GAAG,MAAM,CAAC;IAEnF,MAAM,KAAK,GAAG,OAAO;SAClB,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;QACrB,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO;aACxB,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;aAChH,IAAI,CAAC,EAAE,CAAC,CAAC;QACZ,OAAO,YAAY,IAAI,yBAAyB,MAAM,CAAC,KAAK,CAAC,2DAA2D,CAAC;IAC3H,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,6EAA6E;IAC7E,wCAAwC;IACxC,MAAM,QAAQ,GACZ,OAAO,GAAG,GAAG,IAAI,OAAO,GAAG,GAAG;QAC5B,CAAC,CAAC,qCAAqC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK;QACrG,CAAC,CAAC,EAAE,CAAC;IAET,MAAM,OAAO,GAAG;QACd,OAAO;QACP,KAAK;QACL,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACtC,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC;YACrB,CAAC,EAAE,MAAM,CAAC,MAAM;YAChB,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;SAC3D,CAAC,CAAC;QACH,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,uBAAuB,EAAE;KACvE,CAAC;IAEF,OAAO;uDAC8C,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;yBACtE,KAAK,IAAI,MAAM,GAAG,EAAE;QACrC,QAAQ;QACR,KAAK;0DAC6C,MAAM;;8BAElC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;;;0BAGxD,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,MAAM,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,UAAU,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;AACvI,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAAC,MAAwB,EAAE,IAAc;IAC7D,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE;QAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,OAAO;wBACa,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM;aACL,GAAG,CACF,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CACf,eAAe,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,OAAO,CAC1F;aACA,IAAI,CAAC,EAAE,CAAC;UACP,CAAC;IACT,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,OAAO;;UAEC,UAAU,CAAC,IAAI,CAAC,mBAAmB,CAAC;;;4BAGlB,MAAM,CAAC,IAAI;SAC9B,GAAG,CACF,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CACb,sCAAsC,MAAM,CAAC,KAAK,CAAC,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,qBAAqB,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,CAC1I;SACA,IAAI,CAAC,EAAE,CAAC;eACF,IAAI;;;aAGN,CAAC;AACd,CAAC;AAED,kFAAkF;AAClF,MAAM,aAAa,GAEf;IACF,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC;IAC7D,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,gBAAgB,EAAE,OAAO,EAAE,KAAK,CAAC;IAC9D,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC;IACzD,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC;IACzD,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC;IAC3D,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC;IAC3D,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,CAAC;IACvD,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,CAAC;IAChE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,CAAC;IACjE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,CAAC;IAC7D,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,gBAAgB,EAAE,OAAO,EAAE,KAAK,CAAC;IAC9D,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC;IAC1D,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,CAAC;CACxD,CAAC;AAEF;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,MAAwB,EAAE,IAAc;IACjE,IAAI,MAAM,CAAC,oBAAoB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,gBAAgB,UAAU,CAAC,IAAI,CAAC,2BAA2B,CAAC,yBAAyB,UAAU,CAAC,IAAI,CAAC,oBAAoB,CAAC,gBAAgB,CAAC;IACpJ,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,oBAAoB;SACrC,GAAG,CACF,CAAC,KAAK,EAAE,EAAE,CAAC;wBACO,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;QACrC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,yBAAyB,UAAU,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;UAC5F,CACL;SACA,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,MAAM,MAAM,GACV,MAAM,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC;QACjC,CAAC,CAAC,oBAAoB,UAAU,CAAC,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QAC3G,CAAC,CAAC,EAAE,CAAC;IACT,OAAO;;UAEC,UAAU,CAAC,IAAI,CAAC,2BAA2B,CAAC;;;4BAG1B,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,iBAAiB,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;eAC1F,IAAI;;;MAGb,MAAM;aACC,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAS,SAAS,CAAC,MAA4B,EAAE,MAAmC;IAClF,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC;IACjC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC;IACd,IAAI,SAAS,GAAG,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC3D,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC9B,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO;QAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,IAAI,CAAC,CAAC;YACV,OAAO;QACT,CAAC;QACD,IAAI,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,KAAK,GAAG,SAAS,EAAE,CAAC;YAChE,SAAS,GAAG,KAAK,CAAC;YAClB,IAAI,GAAG,KAAK,CAAC;YACb,IAAI,GAAG,CAAC,CAAC;QACX,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9B,CAAC;AAED,SAAS,GAAG,CAAC,KAAc;IACzB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED,SAAS,MAAM,CAAC,KAAoB,EAAE,IAAgC;IACpE,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC;IAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,IAAI,GACR,SAAS,IAAI,SAAS;QACpB,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;QACtC,CAAC,CAAC,SAAS,IAAI,KAAK;YAClB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAClB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,cAAc,CAAC,KAAK,GAAG,cAAc,CAAC,MAAM,CAAE,CAAC;AACxD,CAAC;AAED,SAAS,SAAS,CAAC,EAAU;IAC3B,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACnE,CAAC"}

package/dist/report/compare-script.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hover readout for the comparison overlay.
+ *
+ * Shows every curve's value at one instant, which is the question an overlay
+ * raises and a static image cannot answer: two lines crossing tells you they
+ * crossed, not by how much.
+ *
+ * Same constraints as the single-run script — one IIFE, no network, no storage,
+ * data read from a `data-series` attribute — so the report stays a self-contained
+ * file that sends nothing.
+ */
+export declare const COMPARE_SCRIPT: string;

package/dist/report/compare-script.js

@@ -0,0 +1,109 @@
+/**
+ * Hover readout for the comparison overlay.
+ *
+ * Shows every curve's value at one instant, which is the question an overlay
+ * raises and a static image cannot answer: two lines crossing tells you they
+ * crossed, not by how much.
+ *
+ * Same constraints as the single-run script — one IIFE, no network, no storage,
+ * data read from a `data-series` attribute — so the report stays a self-contained
+ * file that sends nothing.
+ */
+export const COMPARE_SCRIPT = String.raw `
+(function () {
+  var chart = document.getElementById("compare-chart");
+  if (!chart) return;
+
+  var payload;
+  try {
+    payload = JSON.parse(chart.getAttribute("data-series") || "");
+  } catch (error) {
+    return;
+  }
+  if (!payload || !payload.series || !payload.series.length) return;
+
+  var svg = chart.querySelector("svg");
+  var tooltip = chart.querySelector(".tooltip");
+  var crosshair = chart.querySelector(".crosshair");
+  if (!svg || !tooltip) return;
+
+  var span = payload.endMs - payload.startMs || 1;
+
+  function formatTime(ms) {
+    return new Date(ms).toISOString().slice(0, 16).replace("T", " ");
+  }
+
+  // Nearest sample at or before the cursor's time, by binary search: a linear scan
+  // per mouse move is visibly slow once six series carry 900 points each.
+  function sampleAt(series, timeMs) {
+    var times = series.t;
+    if (timeMs < times[0] || timeMs > times[times.length - 1]) return null;
+    var low = 0;
+    var high = times.length - 1;
+    while (low < high) {
+      var mid = (low + high + 1) >> 1;
+      if (times[mid] <= timeMs) low = mid;
+      else high = mid - 1;
+    }
+    return { time: times[low], value: series.v[low] };
+  }
+
+  function show(clientX) {
+    var box = svg.getBoundingClientRect();
+    if (box.width <= 0) return;
+    var ratio = Math.min(1, Math.max(0, (clientX - box.left) / box.width));
+    var timeMs = payload.startMs + ratio * span;
+
+    var rows = '<div class="row head"><span>' + payload.labels.time + "</span><b>" + formatTime(timeMs) + "</b></div>";
+    for (var index = 0; index < payload.series.length; index += 1) {
+      var series = payload.series[index];
+      var sample = sampleAt(series, timeMs);
+      // A run whose window does not cover this instant shows a dash rather than
+      // its nearest endpoint, which would imply data it does not have.
+      var reading = sample === null ? "-" : sample.value.toFixed(2);
+      rows +=
+        '<div class="row"><span><i class="swatch" style="background:' +
+        series.colour +
+        '"></i>' +
+        series.label +
+        "</span><b>" +
+        reading +
+        "</b></div>";
+    }
+    tooltip.innerHTML = rows;
+    tooltip.hidden = false;
+
+    // Flip the tooltip to the other side near the right edge so it stays on screen.
+    var offset = ratio > 0.6 ? 12 : box.width * ratio + 18;
+    if (ratio > 0.6) {
+      tooltip.style.left = "auto";
+      tooltip.style.right = offset + "px";
+    } else {
+      tooltip.style.right = "auto";
+      tooltip.style.left = offset + "px";
+    }
+
+    if (crosshair) {
+      var viewBox = svg.viewBox.baseVal;
+      crosshair.setAttribute("x1", String(ratio * viewBox.width));
+      crosshair.setAttribute("x2", String(ratio * viewBox.width));
+      crosshair.hidden = false;
+    }
+  }
+
+  function hide() {
+    tooltip.hidden = true;
+    if (crosshair) crosshair.hidden = true;
+  }
+
+  chart.addEventListener("mousemove", function (event) {
+    show(event.clientX);
+  });
+  chart.addEventListener("mouseleave", hide);
+  chart.addEventListener("touchmove", function (event) {
+    if (event.touches && event.touches.length) show(event.touches[0].clientX);
+  });
+  chart.addEventListener("touchend", hide);
+})();
+`;
+//# sourceMappingURL=compare-script.js.map

package/dist/report/compare-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-script.js","sourceRoot":"","sources":["../../src/report/compare-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgGvC,CAAC"}

package/dist/report/compare.d.ts

@@ -0,0 +1,61 @@
+import type { EquityPoint, RunSummary } from "../strategy/types.js";
+/**
+ * Upper bound on runs in one comparison.
+ *
+ * Beyond a handful the overlay stops being readable: six curves already crowd a
+ * chart, and the metric table needs a column per run.
+ */
+export declare const MAX_COMPARED_RUNS = 6;
+export declare const MIN_COMPARED_RUNS = 2;
+export interface ComparedRun {
+    run: RunSummary;
+    equity: EquityPoint[];
+}
+/** One reason two runs may not be directly comparable. */
+export interface ComparisonWarning {
+    code: "data_snapshot" | "instrument" | "window" | "assumptions" | "incomplete";
+    message: string;
+}
+export interface ComparisonInput {
+    runs: ComparedRun[];
+}
+/**
+ * A normalized curve, indexed to 100 at its own first point.
+ *
+ * Two runs starting from different equity cannot be read off one axis: the larger
+ * balance simply draws higher. Indexing makes the shapes comparable, which is the
+ * only thing an overlay is good for.
+ */
+export interface NormalizedSeries {
+    runId: string;
+    label: string;
+    /** Wall-clock time of each sample, so runs over different windows still align. */
+    timeMs: number[];
+    /** Equity as a percentage of that run's own starting equity. */
+    indexed: number[];
+}
+export interface ComparisonReport {
+    runs: RunSummary[];
+    warnings: ComparisonWarning[];
+    /** Assumption keys whose values are not identical across every run. */
+    differingAssumptions: Array<{
+        key: string;
+        values: Array<string | null>;
+    }>;
+    /** Assumption keys every run agrees on, collapsed to one value each. */
+    sharedAssumptions: Array<{
+        key: string;
+        value: string;
+    }>;
+    series: NormalizedSeries[];
+}
+/**
+ * Builds a comparison from already-collected runs.
+ *
+ * Warnings come first in the output because the most common mistake this guards
+ * against is comparing runs whose numbers were never comparable — different data,
+ * different instrument, or different costs. Refusing outright would be worse:
+ * sometimes that difference is exactly what is being examined. Stating it is the
+ * useful middle.
+ */
+export declare function buildComparison(input: ComparisonInput): ComparisonReport;

package/dist/report/compare.js

@@ -0,0 +1,205 @@
+import { RuntimeError } from "../core/errors.js";
+import { activeMessages } from "../i18n/locale.js";
+/**
+ * Upper bound on runs in one comparison.
+ *
+ * Beyond a handful the overlay stops being readable: six curves already crowd a
+ * chart, and the metric table needs a column per run.
+ */
+export const MAX_COMPARED_RUNS = 6;
+export const MIN_COMPARED_RUNS = 2;
+/**
+ * Assumption keys never shown in the difference table.
+ *
+ * The contract specification is a property of the instrument rather than a choice
+ * the user made, so surfacing it as a "difference" between two instruments repeats
+ * what the instrument warning already said.
+ *
+ * `params` is deliberately *not* here. Strategy parameters are the most common
+ * thing that varies between two runs — it is the whole point of comparing them —
+ * and they are flattened below so each one gets its own row instead of appearing
+ * as one opaque JSON blob.
+ */
+const OPAQUE_ASSUMPTIONS = new Set(["contract"]);
+/**
+ * Builds a comparison from already-collected runs.
+ *
+ * Warnings come first in the output because the most common mistake this guards
+ * against is comparing runs whose numbers were never comparable — different data,
+ * different instrument, or different costs. Refusing outright would be worse:
+ * sometimes that difference is exactly what is being examined. Stating it is the
+ * useful middle.
+ */
+export function buildComparison(input) {
+    const runs = input.runs.map((item) => item.run);
+    if (runs.length < MIN_COMPARED_RUNS) {
+        throw new RuntimeError("VALIDATION", `A comparison needs at least ${MIN_COMPARED_RUNS} runs`);
+    }
+    if (runs.length > MAX_COMPARED_RUNS) {
+        throw new RuntimeError("VALIDATION", `A comparison holds at most ${MAX_COMPARED_RUNS} runs; ${runs.length} were given`);
+    }
+    const duplicate = runs.find((run, index) => runs.findIndex((item) => item.id === run.id) !== index);
+    if (duplicate) {
+        throw new RuntimeError("VALIDATION", `${duplicate.id} appears twice; a run cannot be compared with itself`);
+    }
+    return {
+        runs,
+        warnings: collectWarnings(input.runs),
+        ...partitionAssumptions(runs),
+        series: input.runs.map(normalize)
+    };
+}
+function collectWarnings(items) {
+    const warnings = [];
+    const runs = items.map((item) => item.run);
+    // Warnings are prose shown to a person, so they follow the display language like
+    // the rest of the shell. The codes stay English for programmatic callers.
+    const text = activeMessages();
+    const unfinished = runs.filter((run) => run.status !== "completed");
+    if (unfinished.length > 0) {
+        warnings.push({
+            code: "incomplete",
+            message: text.warnIncompleteRuns(unfinished.map((run) => `${run.id} (${run.status})`).join(", "))
+        });
+    }
+    const instruments = unique(runs.map((run) => run.instId));
+    if (instruments.length > 1) {
+        warnings.push({
+            code: "instrument",
+            message: text.warnDifferentInstruments(instruments.join(", "))
+        });
+    }
+    // The one that matters most. Two runs over different bars are not two results
+    // for one question, and this is the easiest mistake to make by accident —
+    // downloading more history between runs is enough to cause it.
+    const snapshots = unique(runs.map((run) => run.dataSnapshotId ?? "none"));
+    if (snapshots.length > 1) {
+        warnings.push({
+            code: "data_snapshot",
+            message: text.warnDifferentData
+        });
+    }
+    else {
+        // Identical bars are not implied by an identical snapshot when the evaluated
+        // window differs, because the snapshot covers the loaded range.
+        const windows = unique(runs.map((run) => `${run.assumptions?.evaluationStartMs ?? "?"}-${run.assumptions?.evaluationEndMs ?? "?"}`));
+        if (windows.length > 1) {
+            warnings.push({
+                code: "window",
+                message: text.warnDifferentWindows
+            });
+        }
+    }
+    const costKeys = ["leverage", "takerFeeRate", "makerFeeRate", "entrySlippageBps", "exitSlippageBps", "entryBudgetPct"];
+    const differingCosts = costKeys.filter((key) => unique(runs.map((run) => String(run.assumptions?.[key] ?? "?"))).length > 1);
+    if (differingCosts.length > 0) {
+        warnings.push({
+            code: "assumptions",
+            message: text.warnDifferentAssumptions(differingCosts.join(", "))
+        });
+    }
+    return warnings;
+}
+/**
+ * Splits assumptions into the ones that differ and the ones every run shares.
+ *
+ * Collapsing the shared ones is the point: with twenty assumption rows per run, a
+ * full matrix buries the two values that actually changed.
+ */
+function partitionAssumptions(runs) {
+    const flattened = runs.map(flattenAssumptions);
+    const keys = unique(flattened.flatMap((entry) => Object.keys(entry)));
+    const differing = [];
+    const shared = [];
+    for (const key of keys.sort()) {
+        const values = flattened.map((entry) => entry[key] ?? null);
+        // Null folds to a sentinel rather than being compared directly, so "absent"
+        // and "absent" count as agreement while "absent" and "0" do not.
+        if (unique(values.map((value) => value ?? "\u0000")).length === 1) {
+            shared.push({ key, value: values[0] ?? "-" });
+        }
+        else {
+            differing.push({ key, values });
+        }
+    }
+    return { differingAssumptions: differing, sharedAssumptions: shared };
+}
+/**
+ * One flat map of comparable values per run.
+ *
+ * Strategy parameters are lifted to `params.<name>` so each takes its own row. Left
+ * as a single JSON blob, changing `fastPeriod` from 20 to 40 shows up as two
+ * unreadable strings the reader has to diff by eye — for the value most likely to
+ * be the reason the two runs differ at all.
+ */
+function flattenAssumptions(run) {
+    const flat = {};
+    for (const [key, value] of Object.entries(run.assumptions ?? {})) {
+        if (OPAQUE_ASSUMPTIONS.has(key))
+            continue;
+        if (key === "params" && value !== null && typeof value === "object" && !Array.isArray(value)) {
+            for (const [name, param] of Object.entries(value)) {
+                flat[`params.${name}`] = stringify(param);
+            }
+            continue;
+        }
+        flat[key] = stringify(value, key);
+    }
+    return flat;
+}
+/**
+ * Indexes one curve to 100 at its own first point.
+ *
+ * Downsampled to a fixed budget so an overlay of six year-long runs stays a
+ * readable file rather than several megabytes of path data.
+ */
+function normalize(item, index) {
+    const sampled = downsample(item.equity, 900);
+    const base = sampled[0]?.equityUsdt ?? 0;
+    return {
+        runId: item.run.id,
+        label: `${item.run.strategyName} · ${item.run.id.slice(0, 10)}`,
+        timeMs: sampled.map((point) => point.timeMs),
+        // A zero or negative starting equity has no meaningful index; those points
+        // read as flat rather than as an infinite spike.
+        indexed: sampled.map((point) => (base > 0 ? (point.equityUsdt / base) * 100 : 100))
+    };
+}
+function downsample(points, budget) {
+    if (points.length <= budget)
+        return points;
+    const step = (points.length - 1) / (budget - 1);
+    const out = [];
+    for (let index = 0; index < budget; index += 1) {
+        out.push(points[Math.round(index * step)]);
+    }
+    return out;
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+/**
+ * Keys whose numeric value is an epoch millisecond.
+ *
+ * Rendered as a UTC timestamp rather than the raw number: every other window in
+ * the tool is shown that way, and `1786605120000` beside `1784937600000` cannot be
+ * read as "eight days earlier" by anyone.
+ */
+const TIME_ASSUMPTIONS = new Set(["evaluationStartMs", "evaluationEndMs"]);
+function stringify(value, key) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "number" && key !== undefined && TIME_ASSUMPTIONS.has(key)) {
+        return new Date(value).toISOString().slice(0, 16).replace("T", " ");
+    }
+    if (typeof value === "number")
+        return String(Number(value.toFixed(10)));
+    if (typeof value === "boolean")
+        return value ? "on" : "off";
+    if (Array.isArray(value))
+        return value.join(",");
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+//# sourceMappingURL=compare.js.map