niceeval 0.5.3 → 0.6.0

package/dist/report/text/layout.js

@@ -0,0 +1,173 @@
+// text 面的排版工具:显示宽度(CJK 记 2 列)、填充、折行、对齐列、字符条形。
+// 全部纯函数、零依赖;niceeval show 的终端输出与 Row 分栏都建立在这几样上。
+//
+// 其中七个是公开面(`niceeval/report` 以 stringWidth / padEnd / padStart / wrapText /
+// indent / bar / columns 的名字导出,见 ../index.ts):自定义组件的 text 面必须拿到与
+// 官方组件同一把尺子,否则「用户组件与官方组件对等」是假的。它们的 TSDoc 就是公开文档,
+// 改签名即破坏公开面。renderAlignedRows 不导出 —— 表格的能力由 <Table> 原语承担。
+/** 终端显示宽度:CJK / 全角记 2 列,其余记 1。启发式覆盖常用区段,够对齐表格用。 */
+export function charDisplayWidth(codePoint) {
+    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;
+}
+/**
+ * 一段文本在终端里占几列:CJK / 全角字符记 2 列,其余记 1 列。
+ *
+ * 对齐终端输出用它,不要用 `String.prototype.length`——`length` 数的是 UTF-16 码元,
+ * 一个汉字占 2 个显示列却只算 1 个码元,中文一进来列就错位。
+ *
+ * @param text 任意文本。
+ * @returns 显示列数。
+ */
+export function stringWidth(text) {
+    let width = 0;
+    for (const ch of text)
+        width += charDisplayWidth(ch.codePointAt(0));
+    return width;
+}
+/**
+ * 按显示宽度在右侧补空格(左对齐)。超宽不截断,如实溢出。
+ *
+ * `String.prototype.padEnd` 的显示宽度版:内容含中文时才对得齐。
+ *
+ * @param text 要补齐的文本。
+ * @param width 目标显示宽度。
+ * @returns 补齐后的文本。
+ */
+export function padDisplay(text, width) {
+    const gap = width - stringWidth(text);
+    return gap > 0 ? text + " ".repeat(gap) : text;
+}
+/**
+ * 按显示宽度在左侧补空格(右对齐)。超宽不截断,如实溢出。
+ *
+ * 数字列靠它对齐小数点。
+ *
+ * @param text 要补齐的文本。
+ * @param width 目标显示宽度。
+ * @returns 补齐后的文本。
+ */
+export function padStartDisplay(text, width) {
+    const gap = width - stringWidth(text);
+    return gap > 0 ? " ".repeat(gap) + text : text;
+}
+/**
+ * 按显示宽度折行:优先在空格处断,单个词超宽(URL / 中文长句)按列宽硬断。
+ *
+ * @param text 要折行的文本(`\n` 分段)。
+ * @param width 每行的最大显示宽度。
+ * @returns 折好的行;至少一行(空串输入 → `[""]`)。
+ */
+export function wrapDisplay(text, width) {
+    const max = Math.max(4, width);
+    const lines = [];
+    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 : [""];
+}
+/**
+ * 给一整块文本的每行加同一段前缀(嵌套块缩进)。空行不加,不留尾随空格。
+ *
+ * @param block 多行文本。
+ * @param indent 每行的前缀,通常是若干空格。
+ * @returns 缩进后的文本块。
+ */
+export function indentBlock(block, indent) {
+    return block
+        .split("\n")
+        .map((line) => (line.length > 0 ? indent + line : line))
+        .join("\n");
+}
+/**
+ * 对齐列渲染:每列宽 = 该列最宽格的显示宽度,列间 3 空格,行尾不留空白。首行是表头。
+ * `align[c]` 给第 c 列的对齐方向,缺省 `"left"`。
+ *
+ * 内部件:公开面是 <Table> 原语(见 ./table.ts 的 renderTableText,它先按 ctx.width
+ * 定好列宽再调这里)。不导出到 `niceeval/report` —— 两条并行的建表路径只会让作者选错。
+ */
+export function renderAlignedRows(rows, align = [], separator = "   ") {
+    const columnCount = Math.max(...rows.map((r) => r.length), 0);
+    const widths = [];
+    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) => (align[c] === "right" ? padStartDisplay(cell, widths[c]) : padDisplay(cell, widths[c])))
+        .join(separator)
+        .replace(/\s+$/, ""))
+        .join("\n");
+}
+/**
+ * 字符条形:比例 → `█` 填充、`░` 补齐到 `barWidth` 显示列。比例超出 [0, 1] 时钳住。
+ *
+ * @param ratio 填充比例,0 到 1。
+ * @param barWidth 整条的显示宽度。
+ * @returns 定宽的字符条。
+ */
+export function textBar(ratio, barWidth) {
+    const clamped = Math.max(0, Math.min(1, ratio));
+    const filled = Math.round(clamped * barWidth);
+    return "█".repeat(filled) + "░".repeat(barWidth - filled);
+}
+/**
+ * 多块文本并排成栏(`Row` 的 text 面):逐行拼接,各栏按显示宽度补齐,短栏补空行。
+ *
+ * @param blocks 每栏一块多行文本。
+ * @param columnWidths 每栏的显示宽度,与 `blocks` 一一对应。
+ * @param separator 栏间分隔符,默认 `" │ "`。
+ * @returns 并排后的文本块。
+ */
+export function joinColumns(blocks, columnWidths, separator = " │ ") {
+    const columns = blocks.map((block) => block.split("\n"));
+    const height = Math.max(...columns.map((lines) => lines.length), 0);
+    const out = [];
+    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/dist/report/text/plot.d.ts

@@ -0,0 +1,37 @@
+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;
+}
+export declare function renderCharPlot(opts: CharPlotOptions): string;
+/** 点太密排不下时的降级:坐标表,不硬挤(每行 key、x、y 的 display)。 */
+export declare function renderCoordinateTable(rows: {
+    key: string;
+    x: string;
+    y: string;
+}[], header: {
+    key: string;
+    x: string;
+    y: string;
+}): string;

package/dist/report/text/plot.js

@@ -0,0 +1,81 @@
+// text 面的字符坐标图:MetricScatter / MetricLine 共用。
+// 形态照 docs-site/zh/guides/report-components.mdx 的示例块:y 轴刻度 + │ 边框,
+// 点用字母标注、图例列在图下;lower-better 的轴反向,「好」的角落恒在右上。
+import { padDisplay, padStartDisplay, stringWidth } from "./layout.js";
+function makeScale(values, cells, invert) {
+    const lo = Math.min(...values);
+    const hi = Math.max(...values);
+    const span = hi - lo;
+    return {
+        lo,
+        hi,
+        at(value) {
+            // 单值域:唯一的点落正中
+            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, a, b) {
+    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) {
+    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) => height - 1 - yScale.at(y);
+    const grid = 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();
+    tickByRow.set(rowOf(yScale.lo), opts.formatY(yScale.lo));
+    tickByRow.set(rowOf(yScale.hi), opts.formatY(yScale.hi));
+    const out = [];
+    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, header) {
+    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");
+}

package/dist/report/text/table.d.ts

@@ -0,0 +1,8 @@
+import type { TableProps } from "../primitives.tsx";
+import type { TextContext } from "../tree.ts";
+/**
+ * <Table> 的 text 面:columns × rows → 对齐的字符表。
+ * 有任一行带 locator 时追加一列 attempt(locator 本身就是 `niceeval show <locator>`
+ * 的位置参数;逐行重复整条命令会把表撑宽,与三个实体列表 text 面的既有取舍一致)。
+ */
+export declare function renderTableText(props: TableProps, ctx: TextContext): string;

package/dist/report/text/table.js

@@ -0,0 +1,86 @@
+// <Table> 原语的 text 面(../primitives.tsx 的 Table.text 就是它)。
+// 官方的表状组件(MetricTable / MetricMatrix / Scoreboard / DeltaTable)的 text 面也直接
+// 调它 —— 官方与自定义表共用同一个渲染器,是「用户组件与官方组件对等」的构造证明:
+// 官方用不上的能力用户就拿不到,官方绕过它手搓它就一定会长歪。
+//
+// 列宽按显示宽度算(CJK 记 2 列);null 渲染 —,不补 0;超宽先折最宽的左对齐列,
+// 压到下限仍放不下就从右侧丢列并如实报数(「截断报剩余」是既有契约,不在这里破例)。
+import { countText, localeText } from "../locale.js";
+import { renderAlignedRows, stringWidth, wrapDisplay } from "./layout.js";
+const MISSING_MARK = "—";
+/** 列间距,与 renderAlignedRows 的 join("   ") 一致。 */
+const COLUMN_GAP = 3;
+/** 左对齐列的压缩下限:再窄就读不成句,宁可丢列。 */
+const MIN_TEXT_COLUMN = 8;
+/** 格子的文本形态:缺这个键、或值是 null,都渲染 —(与 web 面同源)。 */
+function cellText(row, key) {
+    const value = row.cells[key];
+    return value === null || value === undefined ? MISSING_MARK : value;
+}
+function totalWidth(widths) {
+    return widths.reduce((sum, w) => sum + w, 0) + COLUMN_GAP * Math.max(0, widths.length - 1);
+}
+/**
+ * 自然列宽 → 放得进 available 的列宽。两步,顺序即优先级:
+ * 1. 压最宽的左对齐列(文本列)到下限 —— 右对齐列是数字,折行读不了,不压;
+ * 2. 仍放不下就从右侧丢列(至少留一列),丢了几列如实返回。
+ */
+function fitWidths(natural, align, available) {
+    const widths = [...natural];
+    while (totalWidth(widths) > available) {
+        let widest = -1;
+        for (let c = 0; c < widths.length; c++) {
+            if (align[c] === "right" || widths[c] <= MIN_TEXT_COLUMN)
+                continue;
+            if (widest === -1 || widths[c] > widths[widest])
+                widest = c;
+        }
+        if (widest === -1)
+            break;
+        const over = totalWidth(widths) - available;
+        widths[widest] = Math.max(MIN_TEXT_COLUMN, widths[widest] - over);
+    }
+    let hidden = 0;
+    while (widths.length > 1 && totalWidth(widths) > available) {
+        widths.pop();
+        hidden += 1;
+    }
+    return { widths, hidden };
+}
+/** 逻辑行 → 物理行:每格折到自己的列宽,行高取最高的那格,矮格补空串。 */
+function toPhysicalRows(cells, widths) {
+    const wrapped = cells.map((cell, c) => 
+    // 放得下就原样保留:wrapDisplay 会把连续空格折成一个,而 DeltaTable 的
+    // "50% → 62%   +12pp" 这类格子内含固定间距 —— 不折行时一个字节都不能动。
+    !cell.includes("\n") && stringWidth(cell) <= widths[c] ? [cell] : wrapDisplay(cell, widths[c]));
+    const height = Math.max(...wrapped.map((lines) => lines.length), 1);
+    const out = [];
+    for (let i = 0; i < height; i++)
+        out.push(wrapped.map((lines) => lines[i] ?? ""));
+    return out;
+}
+/**
+ * <Table> 的 text 面:columns × rows → 对齐的字符表。
+ * 有任一行带 locator 时追加一列 attempt(locator 本身就是 `niceeval show <locator>`
+ * 的位置参数;逐行重复整条命令会把表撑宽,与三个实体列表 text 面的既有取舍一致)。
+ */
+export function renderTableText(props, ctx) {
+    const locale = props.locale ?? ctx.locale;
+    const hasLocator = props.rows.some((row) => row.locator !== undefined);
+    if (props.columns.length === 0 && !hasLocator)
+        return "";
+    const header = props.columns.map((column) => column.header);
+    const align = props.columns.map((column) => column.align ?? "left");
+    const body = props.rows.map((row) => props.columns.map((column) => cellText(row, column.key)));
+    if (hasLocator) {
+        header.push(localeText(locale, "table.attempt"));
+        align.push("left");
+        props.rows.forEach((row, i) => body[i].push(row.locator ?? MISSING_MARK));
+    }
+    const matrix = [header, ...body];
+    const natural = header.map((_, c) => Math.max(...matrix.map((row) => stringWidth(row[c] ?? ""))));
+    const { widths, hidden } = fitWidths(natural, align, ctx.width);
+    const physical = matrix.flatMap((row) => toPhysicalRows(row.slice(0, widths.length), widths));
+    const table = renderAlignedRows(physical, align);
+    return hidden > 0 ? `${table}\n${countText(locale, "table.columnsHidden", hidden)}` : table;
+}

package/dist/report/tree.d.ts

@@ -0,0 +1,99 @@
+import type { ReactNode } from "react";
+import type { AttemptLocator } from "../results/locator.ts";
+import { type ReportLocale } from "./locale.ts";
+/** 标准 jsx-runtime 元素形状;text 宿主只认 type / props,不管 $$typeof。 */
+export interface ReportElement {
+    type: unknown;
+    props: Record<string, unknown>;
+    key?: unknown;
+}
+/** 报告树节点:元素、文本、数组 / Fragment 的儿子们,或渲染为空的空值。 */
+export type ReportNode = ReportElement | string | number | boolean | null | undefined | ReportNode[];
+/** 挂 faces 的私有键:text 宿主与树校验靠它识别双面组件。 */
+export declare const COMPONENT_FACES: unique symbol;
+export interface TextContext {
+    /** 可用列宽;Row 分栏后变窄。 */
+    width: number;
+    /** chrome 文案的 locale(verdict 词、注脚、占位符);默认 "en",show 输出不变。 */
+    locale: ReportLocale;
+    /** 容器组件渲染 children 用,宽度显式传递。 */
+    render(node: ReportNode, width?: number): string;
+    /** 下钻命令,通证据室:`niceeval show @<locator>`。 */
+    attemptCommand(locator: AttemptLocator): string;
+}
+export interface WebContext {
+    /** 证据室深链,同 view 的 attempt 路由(`#/attempt/@<locator>`,单段、不透明)。 */
+    attemptHref(locator: AttemptLocator): string;
+    /** chrome 文案的 locale;官方组件渲染面经上下文读取,宿主外默认 "en"。 */
+    locale: ReportLocale;
+}
+export interface ComponentFaces<P, R = P> {
+    /**
+     * 可选的数据解析面:把声明式 props(selection + 计算选项)在渲染前解析成纯数据 props(R)。
+     * 宿主的 {@link resolveReportTree} 在 build 之后、validate / render 之前调用它——这是整条
+     * 管线里唯一允许 await / IO 的组件级步骤;渲染面(web / text)只看已解析的 R,保持同步、零 IO。
+     * 不实现 resolve 时 R = P,组件被当作纯数据组件直接渲染。
+     */
+    resolve?(props: P): Promise<R>;
+    /** 真 React JSX 在这个面里;返回静态可渲染的 ReactNode。只看已解析的 R。 */
+    web(props: R, ctx: WebContext): ReactNode;
+    text(props: R, ctx: TextContext): string;
+}
+/**
+ * 双面组件的产物:可直接用于 JSX(React 把它当函数组件调用,走 web 面),
+ * text 宿主经 COMPONENT_FACES 调 text 面。R(解析后 props 形态)在存储边界抹成 any——
+ * 树遍历只按 ComponentFaces 的结构调用 resolve / web / text,不需要在类型层追踪 R。
+ */
+export type ReportComponent<P> = ((props: P) => ReactNode) & {
+    [COMPONENT_FACES]: ComponentFaces<P, any>;
+    displayName?: string;
+};
+/** web 宿主用:在给定 WebContext 下同步渲染(React 静态渲染本身是同步的)。 */
+export declare function runWithWebContext<T>(ctx: WebContext, fn: () => T): T;
+/** 官方组件的装配用:宿主上下文激活时才把 ctx.attemptHref 当默认下钻。 */
+export declare function isHostWebContextActive(): boolean;
+/**
+ * 定义一个双面组件:faces 两键必填 —— 少实现一个面编译不过,配对是结构义务。
+ * 基础实现不 import react;产物以可调用组件的形状兼容 React 渲染。
+ */
+export declare function defineComponent<P, R = P>(faces: ComponentFaces<P, R>): ReportComponent<P>;
+export declare function facesOf(type: unknown): ComponentFaces<unknown> | undefined;
+/**
+ * 报告 build 之后、树校验与 text/web 渲染之前的解析遍历:把声明式数据组件(实现了
+ * `faces.resolve` 的双面组件,如 selection 形态的 MetricScatter)的 props
+ * 就地换成算好的数据形态 props(三个实体列表没有 `resolve` 面,不经这一步——它们的 `items`
+ * 由报告作者在 `build()` 里直接 `await .data(selection)` 备好)。计算发生在这里(唯一允许
+ * await 的组件级步骤,连同报告函数体自己的 `build()`),两个渲染面
+ * 之后都只看已解析的树、保持同步零 IO。遍历形状与 {@link validateReportTree} /
+ * {@link renderNodeToText} 一致:
+ *
+ * - 同层数组兄弟并行解析(`Promise.all`),保持原始顺序 / keys;
+ * - 双面组件带 resolve 的:调 `faces.resolve(props)` 换 props(有 children 再递归解析);
+ * - 双面组件无 resolve 的(Row / Col / Section / RunOverview…):只递归 children,自身 props
+ *   原样保留(title / className 等不能动);
+ * - 普通函数组件:同步调用展开,展开结果继续解析(与 validate / render 对函数组件的处理一致);
+ * - 字符串 intrinsic(<div>):原样返回,交给随后的 validateReportTree 报同一条错误。
+ *
+ * resolver 跑完后,树里已没有函数组件 / 未解析 props;validate / render 里对这两者的分支在
+ * 正常管线下是 no-op,但保留着——手搭树直接调 validate / render(不过 resolver)的低层用法仍需要。
+ */
+export declare function resolveReportTree(node: ReportNode): Promise<ReportNode>;
+/**
+ * 渲染前树校验:页面树里只放双面组件、排版原语与普通组合函数,字符串 intrinsic
+ * (<div>)报错、指名组件路径。这是运行时校验而非编译期(标准 JSX 下 TS 把一切
+ * JSX 表达式统一成 JSX.Element);两个宿主渲染前跑同一遍 —— 不做单侧宽容,否则
+ * 对着 view 写的页面到 show 才炸。校验只下钻 children(children 就是报告树);
+ * 普通函数组件调用展开(渲染面纯同步,重复调用无副作用)。
+ */
+export declare function validateReportTree(node: ReportNode, path?: string[]): void;
+export interface TextRenderOptions {
+    /** 终端可用列宽;默认 80。 */
+    width?: number;
+    /** 下钻命令的生成;宿主注入,默认 `niceeval show @<locator>`(真实可跑的 CLI 语法)。 */
+    attemptCommand?: (locator: AttemptLocator) => string;
+    /** chrome 文案的 locale;默认 "en"(`niceeval show` 现有输出不变)。 */
+    locale?: ReportLocale;
+}
+export declare function createTextContext(options?: TextRenderOptions): TextContext;
+/** text 宿主的遍历渲染:双面组件走 text 面,普通函数调用展开,块之间以换行相接。 */
+export declare function renderNodeToText(node: ReportNode, ctx: TextContext): string;