niceeval 0.4.6 → 0.5.1

package/src/report/report.ts

@@ -0,0 +1,69 @@
+// defineReport:一份报告 = 一个报告文件(默认导出),两扇门(show / view)共用。
+// 宿主打开结果目录、按官方口径挑好选集、注入上下文;报告函数折数据、摆积木,
+// 返回一棵组件树。计算全部发生在报告函数体里(读句柄、await 折数据只在这里合法);
+// 渲染面是纯同步函数 —— 可达百 MB 的工件永远不进渲染路径。
+//
+// renderReportToText 是 text 宿主(show)的装载入口;web 宿主(view)的
+// renderReportToStaticHtml 在 ./web.ts(那一侧才 import react-dom)。宿主接线是下一波,
+// 这两个入口先以内部函数的身份可独立测试。
+
+import type { Results, Selection } from "../results/index.ts";
+import {
+  createTextContext,
+  renderNodeToText,
+  validateReportTree,
+  type ReportNode,
+  type TextRenderOptions,
+} from "./tree.ts";
+import { prepareDefaultReportData, runWithDefaultReportData } from "./default-report.tsx";
+
+export interface ReportContext {
+  /** results.latest() 挑好的选集:现刻水位快照 + 结构化挑选警告,同官方榜单口径。 */
+  selection: Selection;
+  /** 默认挑法不合口径时,全量数据自己挑(见 docs/results-lib.md)。 */
+  results: Results;
+}
+
+const REPORT_DEFINITION: unique symbol = Symbol.for("niceeval.report.definition");
+
+export interface ReportDefinition {
+  build(ctx: ReportContext): ReportNode | Promise<ReportNode>;
+  [REPORT_DEFINITION]: true;
+}
+
+export function defineReport(
+  build: (ctx: ReportContext) => ReportNode | Promise<ReportNode>,
+): ReportDefinition {
+  if (typeof build !== "function") {
+    throw new Error(
+      "defineReport expects a build function: defineReport(async ({ selection, results }) => <Col>...</Col>).",
+    );
+  }
+  return { build, [REPORT_DEFINITION]: true };
+}
+
+/** 宿主装载报告文件时用:默认导出是不是 defineReport 的产物。 */
+export function isReportDefinition(value: unknown): value is ReportDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Partial<ReportDefinition>)[REPORT_DEFINITION] === true &&
+    typeof (value as Partial<ReportDefinition>).build === "function"
+  );
+}
+
+/**
+ * text 宿主的装载语义:build → 渲染前树校验 → 备好官方水位(DefaultReport 的数据)
+ * → 遍历渲染 text 面。不需要 react-dom。
+ */
+export async function renderReportToText(
+  definition: ReportDefinition,
+  ctx: ReportContext,
+  options?: TextRenderOptions,
+): Promise<string> {
+  const node = await definition.build(ctx);
+  validateReportTree(node);
+  const defaultData = await prepareDefaultReportData(ctx.selection);
+  const textCtx = createTextContext(options);
+  return runWithDefaultReportData(defaultData, () => renderNodeToText(node, textCtx));
+}

package/src/report/text/faces.ts

@@ -0,0 +1,356 @@
+// 官方组件的 text 面:同一份算好的数据,渲染成终端字符(niceeval show 的形态)。
+// 输出形态照 docs-site/zh/guides/report-components.mdx 的示例块;与 web 面共守
+// 诚实契约:排序随 better、samples < total 角标、缺数据 — 不补 0、截断报剩余。
+// 零 react、零 IO、纯同步 —— 这是 text 宿主不需要 react-dom 的那一半。
+
+import type {
+  CaseListData,
+  DeltaData,
+  LineData,
+  MatrixData,
+  MetricColumn,
+  OverviewData,
+  ScatterData,
+  ScoreboardData,
+  TableData,
+} from "../types.ts";
+import type { TextContext } from "../tree.ts";
+import { MISSING_TEXT, formatDurationMs, formatMetricValue, formatPlainNumber, formatUSD } from "../format.ts";
+import { indentBlock, padDisplay, renderAlignedRows, textBar, wrapDisplay } from "./layout.ts";
+import { renderCharPlot, renderCoordinateTable, type PlotPoint } from "./plot.ts";
+
+const MISSING_MARK = "—";
+
+/** 格子的文本形态:缺数据 —,覆盖不全带 samples/total 角标。 */
+export function cellText(cell: { value: number | null; display: string; samples: number; total: number }): string {
+  if (cell.value === null) return MISSING_MARK;
+  return cell.samples < cell.total ? `${cell.display} ${cell.samples}/${cell.total}` : cell.display;
+}
+
+// ───────────────────────── RunOverview ─────────────────────────
+
+export function overviewText(data: OverviewData): string {
+  const { totals, snapshots } = data;
+  const runs = new Set(snapshots.map((s) => s.startedAt)).size;
+  const latest = snapshots.map((s) => s.startedAt).sort().at(-1);
+  const head = [
+    `${snapshots.length} ${snapshots.length === 1 ? "experiment" : "experiments"}`,
+    `${totals.evals} evals`,
+    `${totals.attempts} attempts`,
+    `composed from ${runs} ${runs === 1 ? "run" : "runs"}`,
+    ...(latest ? [`latest ${latest}`] : []),
+  ].join(" · ");
+  const tallies = [
+    `passed ${totals.passed}`,
+    `failed ${totals.failed}`,
+    `errored ${totals.errored}`,
+    `skipped ${totals.skipped}`,
+    totals.costUSD === null ? MISSING_TEXT : formatUSD(totals.costUSD),
+    formatDurationMs(totals.durationMs),
+  ].join(" · ");
+  const lines = [head, tallies];
+  for (const warning of data.warnings) lines.push(`! ${warning.message}`);
+  return lines.join("\n");
+}
+
+// ───────────────────────── MetricTable ─────────────────────────
+
+export function tableText(data: TableData): string {
+  const header = [data.dimension, ...data.columns.map((c) => c.label)];
+  const rows = data.rows.map((row) => [
+    row.key,
+    ...data.columns.map((col) => {
+      const cell = (row.cells as Record<string, TableData["rows"][number]["cells"][string]>)[col.key];
+      return cell ? cellText(cell) : MISSING_MARK;
+    }),
+  ]);
+  return renderAlignedRows([header, ...rows]);
+}
+
+// ───────────────────────── MetricMatrix ─────────────────────────
+
+export function matrixText(data: MatrixData): string {
+  const rowKeys: string[] = [];
+  const columnKeys: string[] = [];
+  const byPosition = new Map<string, MatrixData["cells"][number]["cell"]>();
+  for (const entry of data.cells) {
+    if (!rowKeys.includes(entry.row)) rowKeys.push(entry.row);
+    if (!columnKeys.includes(entry.column)) columnKeys.push(entry.column);
+    byPosition.set(JSON.stringify([entry.row, entry.column]), entry.cell);
+  }
+  const header = [data.rows, ...columnKeys];
+  const rows = rowKeys.map((row) => [
+    row,
+    ...columnKeys.map((column) => {
+      const cell = byPosition.get(JSON.stringify([row, column]));
+      return cell ? cellText(cell) : MISSING_MARK; // 稀疏格子在文本里以 — 呈现,不编数
+    }),
+  ]);
+  const table = renderAlignedRows([header, ...rows]);
+
+  // 下钻命令:行维度是 eval 时,指向最值得看的一行(先挑有缺格的,再挑按 better 最差的)
+  if (data.rows !== "eval" || rowKeys.length === 0) return table;
+  const better = data.metric.better ?? "higher";
+  let next: string | undefined;
+  let worst: { key: string; value: number } | undefined;
+  for (const row of rowKeys) {
+    let sum = 0;
+    let count = 0;
+    for (const column of columnKeys) {
+      const cell = byPosition.get(JSON.stringify([row, column]));
+      if (!cell || cell.value === null) {
+        next ??= row;
+        continue;
+      }
+      sum += cell.value;
+      count += 1;
+    }
+    if (count > 0) {
+      const value = sum / count;
+      const isWorse = worst === undefined || (better === "higher" ? value < worst.value : value > worst.value);
+      if (isWorse) worst = { key: row, value };
+    }
+  }
+  next ??= worst?.key;
+  return next === undefined ? table : `${table}\n\nnext: niceeval show ${next}`;
+}
+
+// ───────────────────────── MetricBars(矩阵数据的另一种摆法)─────────────────────────
+
+const BAR_WIDTH = 20;
+
+export function barsText(data: MatrixData): string {
+  const groupKeys: string[] = [];
+  const seriesKeys: string[] = [];
+  const byPosition = new Map<string, MatrixData["cells"][number]["cell"]>();
+  for (const entry of data.cells) {
+    if (!groupKeys.includes(entry.row)) groupKeys.push(entry.row);
+    if (!seriesKeys.includes(entry.column)) seriesKeys.push(entry.column);
+    byPosition.set(JSON.stringify([entry.row, entry.column]), entry.cell);
+  }
+  const better = data.metric.better ?? "higher";
+  // 条长刻度:% 的天然域是 [0,1],其余以全图最大值为满条
+  const values = data.cells.map((c) => c.cell.value).filter((v): v is number => v !== null);
+  const maxValue = values.length > 0 ? Math.max(...values) : 0;
+  const ratioOf = (value: number) =>
+    data.metric.unit === "%" ? value : maxValue === 0 ? 0 : value / maxValue;
+
+  const seriesWidth = Math.max(...seriesKeys.map((k) => k.length), 0);
+  const lines: string[] = [];
+  for (const group of groupKeys) {
+    lines.push(group);
+    const entries = seriesKeys.map((series) => ({
+      series,
+      cell: byPosition.get(JSON.stringify([group, series])),
+    }));
+    // 组内按值排序,方向随 better(缺数据沉底)
+    entries.sort((a, b) => {
+      const va = a.cell?.value ?? null;
+      const vb = b.cell?.value ?? null;
+      if (va === null && vb === null) return 0;
+      if (va === null) return 1;
+      if (vb === null) return -1;
+      return better === "lower" ? va - vb : vb - va;
+    });
+    for (const { series, cell } of entries) {
+      const label = padDisplay(series, seriesWidth);
+      if (!cell || cell.value === null) {
+        lines.push(`  ${label}   ${MISSING_MARK}`);
+        continue;
+      }
+      lines.push(`  ${label}   ${textBar(ratioOf(cell.value), BAR_WIDTH)}  ${cellText(cell)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// ───────────────────────── Scoreboard ─────────────────────────
+
+export function scoreboardText(data: ScoreboardData): string {
+  const subjectKeys: string[] = [];
+  for (const row of data.rows) {
+    for (const subject of row.subjects) {
+      if (!subjectKeys.includes(subject.key)) subjectKeys.push(subject.key);
+    }
+  }
+  const header = [data.dimension, "total", ...subjectKeys];
+  const rows = data.rows.map((row) => [
+    row.key,
+    `${row.total.display}/${data.fullMarks}`,
+    ...subjectKeys.map((key) => {
+      const subject = row.subjects.find((s) => s.key === key);
+      if (!subject) return MISSING_MARK;
+      const score = `${formatPlainNumber(subject.earned)}/${formatPlainNumber(subject.possible)}`;
+      return subject.missing > 0 ? `${score} (${subject.missing} missing)` : score;
+    }),
+  ]);
+  const table = renderAlignedRows([header, ...rows]);
+  if (data.weights.length === 0) return table;
+  // 实际生效的权重表 —— 成绩单可审计
+  const weights = data.weights.map((w) => `${w.prefix} ×${w.weight}`).join(" · ");
+  return `${table}\nweights: ${weights} · others ×1`;
+}
+
+// ───────────────────────── MetricScatter ─────────────────────────
+
+const POINT_MARKS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+function axisLabel(col: MetricColumn): string {
+  return col.label;
+}
+
+export function scatterText(data: ScatterData, ctx: TextContext): string {
+  const drawable = data.rows.filter((r) => r.x.value !== null && r.y.value !== null);
+  const missing = data.rows.length - drawable.length;
+  const footnotes: string[] = [];
+  if (missing > 0) footnotes.push(`${missing} ${missing === 1 ? "point" : "points"} missing data`);
+
+  if (drawable.length === 0) {
+    return [MISSING_TEXT, ...footnotes].join("\n");
+  }
+
+  // 点太密排不下时降级为坐标表,不硬挤
+  if (drawable.length > POINT_MARKS.length || ctx.width < 44) {
+    const table = renderCoordinateTable(
+      drawable.map((r) => ({ key: r.key, x: r.x.display, y: r.y.display })),
+      { key: data.points, x: axisLabel(data.x), y: axisLabel(data.y) },
+    );
+    return [table, ...footnotes].join("\n");
+  }
+
+  const points: PlotPoint[] = drawable.map((r, i) => ({
+    mark: POINT_MARKS[i],
+    x: r.x.value as number,
+    y: r.y.value as number,
+  }));
+  // 同系列的点按 x 排序连线
+  const bySeries = new Map<string, { x: number; y: number }[]>();
+  for (const r of drawable) {
+    if (r.series === undefined) continue;
+    const list = bySeries.get(r.series) ?? [];
+    list.push({ x: r.x.value as number, y: r.y.value as number });
+    bySeries.set(r.series, list);
+  }
+  for (const list of bySeries.values()) list.sort((a, b) => a.x - b.x);
+
+  const invertX = data.x.better === "lower";
+  const plot = renderCharPlot({
+    width: ctx.width,
+    points,
+    lines: [...bySeries.values()].filter((l) => l.length > 1),
+    xLabel: `${axisLabel(data.x)}${invertX ? " (axis reversed: right = better)" : ""}`,
+    yLabel: axisLabel(data.y),
+    formatX: (v) => formatMetricValue(v, data.x.unit),
+    formatY: (v) => formatMetricValue(v, data.y.unit),
+    invertX,
+    invertY: data.y.better === "lower",
+  });
+  const legend = drawable.map((r, i) => `${POINT_MARKS[i]} ${r.key}`).join("   ");
+  return [plot, "", `better → upper right`, legend, ...footnotes].join("\n");
+}
+
+// ───────────────────────── MetricLine ─────────────────────────
+
+export function lineText(data: LineData, ctx: TextContext): string {
+  const drawable = data.rows.filter((r) => r.x !== null && r.y.value !== null);
+  const missing = data.rows.length - drawable.length;
+  const footnotes: string[] = [];
+  if (missing > 0) footnotes.push(`${missing} ${missing === 1 ? "point" : "points"} missing data`);
+
+  if (drawable.length === 0) return [MISSING_TEXT, ...footnotes].join("\n");
+
+  // 系列 → 字母;无系列 = 单系列
+  const seriesKeys: string[] = [];
+  for (const r of drawable) {
+    const key = r.series ?? "";
+    if (!seriesKeys.includes(key)) seriesKeys.push(key);
+  }
+
+  if (seriesKeys.length > POINT_MARKS.length || ctx.width < 44) {
+    const table = renderCoordinateTable(
+      drawable.map((r) => ({ key: r.series ? `${r.key} (${r.series})` : r.key, x: r.xDisplay, y: r.y.display })),
+      { key: "experiment", x: data.x.label, y: axisLabel(data.y) },
+    );
+    return [table, ...footnotes].join("\n");
+  }
+
+  const markOf = (r: LineData["rows"][number]) => POINT_MARKS[seriesKeys.indexOf(r.series ?? "")];
+  const points: PlotPoint[] = drawable.map((r) => ({
+    mark: markOf(r),
+    x: r.x as number,
+    y: r.y.value as number,
+  }));
+  const lines = seriesKeys.map((key) =>
+    drawable
+      .filter((r) => (r.series ?? "") === key)
+      .map((r) => ({ x: r.x as number, y: r.y.value as number }))
+      .sort((a, b) => a.x - b.x),
+  );
+
+  const plot = renderCharPlot({
+    width: ctx.width,
+    points,
+    lines: lines.filter((l) => l.length > 1),
+    xLabel: data.x.label,
+    yLabel: axisLabel(data.y),
+    formatX: (v) => formatMetricValue(v, data.x.unit),
+    formatY: (v) => formatMetricValue(v, data.y.unit),
+    invertY: data.y.better === "lower",
+  });
+  const legend = seriesKeys
+    .map((key, i) => `${POINT_MARKS[i]} ${key === "" ? data.y.label : key}`)
+    .join("   ");
+  return [plot, "", legend, ...footnotes].join("\n");
+}
+
+// ───────────────────────── DeltaTable ─────────────────────────
+
+export function deltaText(data: DeltaData): string {
+  const header = ["pair", ...data.columns.map((c) => c.label)];
+  const rows = data.rows.map((row) => [
+    row.key,
+    ...data.columns.map((col) => {
+      const cell = (row.cells as Record<string, DeltaData["rows"][number]["cells"][string]>)[col.key];
+      if (!cell) return MISSING_MARK;
+      const a = cell.a.value === null ? MISSING_MARK : cell.a.display;
+      const b = cell.b.value === null ? MISSING_MARK : cell.b.display;
+      return `${a} → ${b}   ${cell.display}`;
+    }),
+  ]);
+  return renderAlignedRows([header, ...rows]);
+}
+
+// ───────────────────────── CaseList ─────────────────────────
+
+export function caseListText(data: CaseListData, ctx: TextContext): string {
+  if (data.rows.length === 0) return "No failed or errored attempts";
+  const lines: string[] = [];
+  for (const row of data.rows) {
+    const head = [
+      `✗ ${row.eval}`,
+      row.experimentId,
+      row.outcome,
+      formatDurationMs(row.durationMs),
+      ...(row.costUSD !== undefined ? [formatUSD(row.costUSD)] : []),
+    ].join(" · ");
+    lines.push(head);
+    if (row.error) {
+      lines.push(indentBlock(wrapDisplay(row.error, ctx.width - 4).join("\n"), "    "));
+    }
+    for (const assertion of row.failedAssertions) {
+      const summary = assertion.detail
+        ? `${assertion.name} — ${assertion.detail}`
+        : `${assertion.name} — score ${assertion.score}`;
+      lines.push(indentBlock(wrapDisplay(summary, ctx.width - 4).join("\n"), "    "));
+      if (assertion.evidence) {
+        lines.push(indentBlock(wrapDisplay(assertion.evidence, ctx.width - 6).join("\n"), "      "));
+      }
+    }
+    lines.push(`    → niceeval show ${row.eval}`);
+  }
+  if (data.truncated > 0) {
+    lines.push("");
+    lines.push(`(${data.truncated} more not shown)`);
+  }
+  return lines.join("\n");
+}

package/src/report/text/layout.ts

@@ -0,0 +1,125 @@
+// text 面的排版工具:显示宽度(CJK 记 2 列)、填充、折行、对齐列、字符条形。
+// 全部纯函数、零依赖;niceeval show 的终端输出与 Row 分栏都建立在这几样上。
+
+/** 终端显示宽度:CJK / 全角记 2 列,其余记 1。启发式覆盖常用区段,够对齐表格用。 */
+export function charDisplayWidth(codePoint: number): number {
+  if (
+    (codePoint >= 0x1100 && codePoint <= 0x115f) ||
+    (codePoint >= 0x2e80 && codePoint <= 0x303e) ||
+    (codePoint >= 0x3041 && codePoint <= 0x33ff) ||
+    (codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+    (codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+    (codePoint >= 0xa000 && codePoint <= 0xa4cf) ||
+    (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+    (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+    (codePoint >= 0xfe30 && codePoint <= 0xfe4f) ||
+    (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+    (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+    (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+export function stringWidth(text: string): number {
+  let width = 0;
+  for (const ch of text) width += charDisplayWidth(ch.codePointAt(0)!);
+  return width;
+}
+
+/** 右侧补空格到目标显示宽度(超宽不截断,如实溢出)。 */
+export function padDisplay(text: string, width: number): string {
+  const gap = width - stringWidth(text);
+  return gap > 0 ? text + " ".repeat(gap) : text;
+}
+
+/** 左侧补空格(数字右对齐用)。 */
+export function padStartDisplay(text: string, width: number): string {
+  const gap = width - stringWidth(text);
+  return gap > 0 ? " ".repeat(gap) + text : text;
+}
+
+/**
+ * 按显示宽度折行:优先在空格处断,连续超宽(如中文)按列宽硬断。
+ * 返回至少一行(空串输入 → [""])。
+ */
+export function wrapDisplay(text: string, width: number): string[] {
+  const max = Math.max(4, width);
+  const lines: string[] = [];
+  for (const paragraph of text.split("\n")) {
+    let line = "";
+    let lineWidth = 0;
+    const flush = () => {
+      lines.push(line);
+      line = "";
+      lineWidth = 0;
+    };
+    for (const word of paragraph.split(" ")) {
+      const wordWidth = stringWidth(word);
+      if (lineWidth > 0 && lineWidth + 1 + wordWidth > max) flush();
+      if (wordWidth > max) {
+        // 单词本身超宽(URL / 中文长句):逐字符硬断
+        for (const ch of word) {
+          const w = charDisplayWidth(ch.codePointAt(0)!);
+          if (lineWidth + w > max) flush();
+          line += ch;
+          lineWidth += w;
+        }
+        continue;
+      }
+      if (lineWidth > 0) {
+        line += " ";
+        lineWidth += 1;
+      }
+      line += word;
+      lineWidth += wordWidth;
+    }
+    flush();
+  }
+  return lines.length > 0 ? lines : [""];
+}
+
+/** 每行前加缩进。 */
+export function indentBlock(block: string, indent: string): string {
+  return block
+    .split("\n")
+    .map((line) => (line.length > 0 ? indent + line : line))
+    .join("\n");
+}
+
+/** 对齐列渲染:每列宽 = 该列最宽格,列间 3 空格。首行是表头。 */
+export function renderAlignedRows(rows: string[][]): string {
+  const columnCount = Math.max(...rows.map((r) => r.length), 0);
+  const widths: number[] = [];
+  for (let c = 0; c < columnCount; c++) {
+    widths.push(Math.max(...rows.map((r) => stringWidth(r[c] ?? ""))));
+  }
+  return rows
+    .map((row) =>
+      row
+        .map((cell, c) => (c === row.length - 1 ? cell : padDisplay(cell, widths[c])))
+        .join("   ")
+        .replace(/\s+$/, ""),
+    )
+    .join("\n");
+}
+
+/** 字符条形:filled 比例 → █ 填充、░ 补齐到 barWidth。 */
+export function textBar(ratio: number, barWidth: number): string {
+  const clamped = Math.max(0, Math.min(1, ratio));
+  const filled = Math.round(clamped * barWidth);
+  return "█".repeat(filled) + "░".repeat(barWidth - filled);
+}
+
+/** 多块并排(Row 的 text 面):逐行拼接,各栏折到自己的宽度,短栏补齐。 */
+export function joinColumns(blocks: string[], columnWidths: number[], separator = " │ "): string {
+  const columns = blocks.map((block) => block.split("\n"));
+  const height = Math.max(...columns.map((lines) => lines.length), 0);
+  const out: string[] = [];
+  for (let i = 0; i < height; i++) {
+    const parts = columns.map((lines, c) => padDisplay(lines[i] ?? "", columnWidths[c]));
+    out.push(parts.join(separator).replace(/\s+$/, ""));
+  }
+  return out.join("\n");
+}

package/src/report/text/plot.ts

@@ -0,0 +1,127 @@
+// text 面的字符坐标图:MetricScatter / MetricLine 共用。
+// 形态照 docs-site/zh/guides/report-components.mdx 的示例块:y 轴刻度 + │ 边框,
+// 点用字母标注、图例列在图下;lower-better 的轴反向,「好」的角落恒在右上。
+
+import { padDisplay, padStartDisplay, stringWidth } from "./layout.ts";
+
+export interface PlotPoint {
+  /** 图上的标记字符(点或系列的字母)。 */
+  mark: string;
+  x: number;
+  y: number;
+}
+
+export interface CharPlotOptions {
+  /** 总列宽(含 y 轴刻度区)。 */
+  width: number;
+  /** 网格行数;默认 9。 */
+  height?: number;
+  points: PlotPoint[];
+  /** 值空间的折线(同系列点按 x 排序连线),用 · 描画,字母覆盖其上。 */
+  lines?: { x: number; y: number }[][];
+  xLabel: string;
+  yLabel: string;
+  /** 值 → 刻度文案(已格式化的 display)。 */
+  formatX: (value: number) => string;
+  formatY: (value: number) => string;
+  /** better: "lower" 的轴反向 —— 好的一端在右 / 上。 */
+  invertX?: boolean;
+  invertY?: boolean;
+}
+
+interface Scale {
+  lo: number;
+  hi: number;
+  /** 值 → [0, cells-1] 的下标。 */
+  at(value: number): number;
+}
+
+function makeScale(values: number[], cells: number, invert: boolean): Scale {
+  const lo = Math.min(...values);
+  const hi = Math.max(...values);
+  const span = hi - lo;
+  return {
+    lo,
+    hi,
+    at(value: number): number {
+      // 单值域:唯一的点落正中
+      let t = span === 0 ? 0.5 : (value - lo) / span;
+      if (invert) t = 1 - t;
+      return Math.max(0, Math.min(cells - 1, Math.round(t * (cells - 1))));
+    },
+  };
+}
+
+/** 值空间折线 → 网格 · 描画:相邻点之间按列逐格线性插值。 */
+function drawLine(grid: string[][], a: { col: number; row: number }, b: { col: number; row: number }): void {
+  const steps = Math.max(Math.abs(b.col - a.col), Math.abs(b.row - a.row));
+  for (let i = 1; i < steps; i++) {
+    const col = Math.round(a.col + ((b.col - a.col) * i) / steps);
+    const row = Math.round(a.row + ((b.row - a.row) * i) / steps);
+    if (grid[row][col] === " ") grid[row][col] = "·";
+  }
+}
+
+export function renderCharPlot(opts: CharPlotOptions): string {
+  const height = Math.max(4, opts.height ?? 9);
+  const yTickTexts = [opts.formatY(Math.min(...opts.points.map((p) => p.y))), opts.formatY(Math.max(...opts.points.map((p) => p.y)))];
+  const gutter = Math.max(...yTickTexts.map(stringWidth)) + 1;
+  const plotWidth = Math.max(16, opts.width - gutter - 1);
+
+  const xScale = makeScale(opts.points.map((p) => p.x), plotWidth, opts.invertX ?? false);
+  // y:大下标 = 「好」的一端;网格第 0 行是顶端,行下标 = height-1 - at,
+  // 所以 invertY=false(higher 好)时 hi 折到 at=height-1 → 顶行,lower 好时反之
+  const yScale = makeScale(opts.points.map((p) => p.y), height, opts.invertY ?? false);
+  const rowOf = (y: number) => height - 1 - yScale.at(y);
+
+  const grid: string[][] = Array.from({ length: height }, () => Array.from({ length: plotWidth }, () => " "));
+  for (const line of opts.lines ?? []) {
+    for (let i = 1; i < line.length; i++) {
+      drawLine(
+        grid,
+        { col: xScale.at(line[i - 1].x), row: rowOf(line[i - 1].y) },
+        { col: xScale.at(line[i].x), row: rowOf(line[i].y) },
+      );
+    }
+  }
+  for (const point of opts.points) {
+    grid[rowOf(point.y)][xScale.at(point.x)] = point.mark;
+  }
+
+  // y 轴刻度:极值行标注 display,其余空
+  const tickByRow = new Map<number, string>();
+  tickByRow.set(rowOf(yScale.lo), opts.formatY(yScale.lo));
+  tickByRow.set(rowOf(yScale.hi), opts.formatY(yScale.hi));
+
+  const out: string[] = [];
+  out.push(`${" ".repeat(gutter)}${opts.yLabel} ↑`);
+  for (let row = 0; row < height; row++) {
+    const tick = tickByRow.get(row) ?? "";
+    out.push(`${padStartDisplay(tick, gutter)}│${grid[row].join("")}`.replace(/\s+$/, ""));
+  }
+  out.push(`${" ".repeat(gutter)}└${"─".repeat(plotWidth)}→ ${opts.xLabel}`);
+
+  // x 轴刻度:两端极值(反向轴时右端是 lo),标在真实位置上
+  const ticksRow = Array.from({ length: plotWidth }, () => " ");
+  for (const value of xScale.lo === xScale.hi ? [xScale.lo] : [xScale.lo, xScale.hi]) {
+    const label = opts.formatX(value);
+    let col = xScale.at(value);
+    col = Math.min(col, plotWidth - stringWidth(label));
+    for (let i = 0; i < label.length && col + i < plotWidth; i++) ticksRow[col + i] = label[i];
+  }
+  out.push(`${" ".repeat(gutter + 1)}${ticksRow.join("")}`.replace(/\s+$/, ""));
+  return out.join("\n");
+}
+
+/** 点太密排不下时的降级:坐标表,不硬挤(每行 key、x、y 的 display)。 */
+export function renderCoordinateTable(
+  rows: { key: string; x: string; y: string }[],
+  header: { key: string; x: string; y: string },
+): string {
+  const all = [header, ...rows];
+  const w1 = Math.max(...all.map((r) => stringWidth(r.key)));
+  const w2 = Math.max(...all.map((r) => stringWidth(r.x)));
+  return all
+    .map((r) => `${padDisplay(r.key, w1)}   ${padDisplay(r.x, w2)}   ${r.y}`.replace(/\s+$/, ""))
+    .join("\n");
+}