niceeval 0.9.0 → 0.10.0

package/dist/report/{react → components/summaries}/ScopeSummary.js

@@ -1,17 +1,26 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { DEFAULT_REPORT_LOCALE, localeText } from "../locale.js";
-import { MetricCellView } from "./cell.js";
-import { cx } from "./format.js";
+import { DEFAULT_REPORT_LOCALE, localeText } from "../../model/locale.js";
+import { formatReportDateTime, formatReportDateTimeRange } from "../../model/format.js";
+import { MetricCellView } from "../cell.js";
+import { cx } from "../shared.js";
 function VerdictTallyView({ tally, locale }) {
     const kinds = ["passed", "failed", "errored", "skipped"].filter((k) => tally[k] > 0);
     return (_jsxs("span", { className: "nre-verdict-tally", children: [kinds.map((kind) => (_jsxs("span", { className: cx("nre-verdict-pill", `nre-verdict-${kind}`), children: [tally[kind], " ", localeText(locale, `verdict.${kind}`)] }, kind))), kinds.length === 0 && _jsx("span", { className: "nre-missing", children: "\u2014" })] }));
 }
 export function ScopeSummary({ data, votes = "eval", className, locale = DEFAULT_REPORT_LOCALE, }) {
     const tally = votes === "attempt" ? data.attemptVerdicts : data.evalVerdicts;
-    return (_jsxs("div", { className: cx("nre", "nre-scope-summary", className), "data-votes": votes, children: [_jsxs("dl", { className: "nre-scope-kpis", children: [_jsxs("div", { className: "nre-scope-kpi nre-scope-kpi-rate", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.passRate") }), _jsx("dd", { children: _jsx(MetricCellView, { cell: data.endToEndPassRate, locale: locale }) })] }), _jsxs("div", { className: "nre-scope-kpi", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.experiments") }), _jsx("dd", { children: data.experiments })] }), _jsxs("div", { className: "nre-scope-kpi", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.evals") }), _jsx("dd", { children: data.evals })] }), _jsxs("div", { className: "nre-scope-kpi", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.attempts") }), _jsx("dd", { children: data.attempts })] }), _jsxs("div", { className: "nre-scope-kpi nre-scope-kpi-verdicts", children: [_jsx("dt", { children: localeText(locale, votes === "attempt" ? "scopeSummary.votesAttempt" : "scopeSummary.votesEval") }), _jsx("dd", { children: _jsx(VerdictTallyView, { tally: tally, locale: locale }) })] }), _jsxs("div", { className: "nre-scope-kpi", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.totalCost") }), _jsx("dd", { children: _jsx(MetricCellView, { cell: data.totalCostUSD, locale: locale }) })] })] }), data.range.latestStartedAt !== null && (_jsx("p", { className: "nre-scope-summary-range", children: data.range.earliestStartedAt !== null && data.range.earliestStartedAt !== data.range.latestStartedAt
-                    ? localeText(locale, "scopeSummary.range", {
-                        from: data.range.earliestStartedAt,
-                        to: data.range.latestStartedAt,
+    const formattedRange = data.range.earliestStartedAt !== null && data.range.latestStartedAt !== null
+        ? formatReportDateTimeRange(data.range.earliestStartedAt, data.range.latestStartedAt, locale)
+        : null;
+    return (_jsxs("div", { className: cx("nre", "nre-scope-summary", className), "data-votes": votes, children: [_jsxs("dl", { className: "nre-scope-kpis", children: [_jsxs("div", { className: "nre-scope-kpi nre-scope-kpi-rate", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.passRate") }), _jsx("dd", { children: _jsx(MetricCellView, { cell: data.endToEndPassRate, locale: locale }) })] }), _jsxs("div", { className: "nre-scope-kpi", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.experiments") }), _jsx("dd", { children: data.experiments })] }), _jsxs("div", { className: "nre-scope-kpi", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.evals") }), _jsx("dd", { children: data.evals })] }), _jsxs("div", { className: "nre-scope-kpi", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.attempts") }), _jsx("dd", { children: data.attempts })] }), _jsxs("div", { className: "nre-scope-kpi nre-scope-kpi-verdicts", children: [_jsx("dt", { children: localeText(locale, votes === "attempt" ? "scopeSummary.votesAttempt" : "scopeSummary.votesEval") }), _jsx("dd", { children: _jsx(VerdictTallyView, { tally: tally, locale: locale }) })] }), _jsxs("div", { className: "nre-scope-kpi", children: [_jsx("dt", { children: localeText(locale, "scopeSummary.totalCost") }), _jsxs("dd", { children: [_jsx(MetricCellView, { cell: data.totalCostUSD, locale: locale, showCoverage: false }), data.totalCostUSD.samples < data.totalCostUSD.total && (_jsx("small", { className: "nre-scope-kpi-note", children: localeText(locale, "scopeSummary.costCoverage", {
+                                            samples: data.totalCostUSD.samples,
+                                            total: data.totalCostUSD.total,
+                                        }) }))] })] })] }), data.range.latestStartedAt !== null && (_jsx("p", { className: "nre-scope-summary-range", children: data.range.earliestStartedAt !== null && data.range.earliestStartedAt !== data.range.latestStartedAt
+                    ? localeText(locale, "scopeSummary.runRange", {
+                        from: formattedRange.from,
+                        to: formattedRange.to,
                     })
-                    : data.range.latestStartedAt }))] }));
+                    : localeText(locale, "scopeSummary.lastRun", {
+                        time: formatReportDateTime(data.range.latestStartedAt, locale),
+                    }) }))] }));
 }

package/dist/report/components/summaries/compute.d.ts

@@ -0,0 +1,7 @@
+import type { ReportInput, ScopeSummaryData } from "../../model/types.ts";
+/**
+ * `scopeSummaryData(input)`:范围摘要——快照时间窗、experiment / eval / attempt 数、
+ * 两级判定计票、端到端通过率与总成本(docs/feature/reports/library/summaries.md)。
+ * data 恒携带两级计票;通过率来自官方两级指标引擎,不从任一计票重算。
+ */
+export declare function scopeSummaryData(input: ReportInput): Promise<ScopeSummaryData>;

package/dist/report/components/summaries/compute.js

@@ -0,0 +1,51 @@
+// 计算函数(*Data):ReportInput → 一份组件数据。ScopeSummary 的 scopeSummaryData 住在这里
+// (docs/feature/reports/library/summaries.md)。ExperimentComparison 是纯组合组件,不产生
+// 独立的 data,没有对应的计算函数。
+//
+// 共同约定(docs/feature/reports/architecture.md「指标聚合不变量」):
+// - 第一参收 ReportInput = Scope | readonly Snapshot[];warnings 不进组件数据(宿主统一显示);
+// - 聚合前按身份键去重(dedupeAttempts;missing-startedAt 不去重、如实保留、不透出警告);
+// - null ≠ 0:缺数据不编数,覆盖率经 samples/total 如实暴露。
+import { collectItems, computeCell, resolveInput } from "../../model/aggregate.js";
+import { costUSD, defineMetric, endToEndPassRate } from "../../model/metrics.js";
+import { selectedEvalsOnly, summarizeItems, tallyOf } from "../shared-compute.js";
+// ───────────────────────── scopeSummaryData ─────────────────────────
+/** costUSD 的求和投影:两级都 sum(题内多轮求和 + 跨题求和 = 全量求和),display 走 $。 */
+const totalCostMetric = defineMetric({
+    name: "total-cost",
+    label: costUSD.label,
+    unit: "$",
+    value: costUSD.value,
+    aggregate: { perEval: "sum", acrossEvals: "sum" },
+});
+/**
+ * `scopeSummaryData(input)`:范围摘要——快照时间窗、experiment / eval / attempt 数、
+ * 两级判定计票、端到端通过率与总成本(docs/feature/reports/library/summaries.md)。
+ * data 恒携带两级计票;通过率来自官方两级指标引擎,不从任一计票重算。
+ */
+export async function scopeSummaryData(input) {
+    const snapshots = selectedEvalsOnly(resolveInput(input).snapshots);
+    const items = collectItems(snapshots);
+    let earliest = null;
+    let latest = null;
+    for (const snapshot of snapshots) {
+        if (earliest === null || snapshot.startedAt < earliest)
+            earliest = snapshot.startedAt;
+        if (latest === null || snapshot.startedAt > latest)
+            latest = snapshot.startedAt;
+    }
+    const stats = summarizeItems(items);
+    const attemptVerdicts = tallyOf();
+    for (const item of items)
+        attemptVerdicts[item.attempt.result.verdict] += 1;
+    return {
+        range: { earliestStartedAt: earliest, latestStartedAt: latest },
+        experiments: stats.experiments,
+        evals: stats.evals,
+        attempts: stats.attempts,
+        evalVerdicts: stats.verdicts,
+        attemptVerdicts,
+        endToEndPassRate: await computeCell(endToEndPassRate, items),
+        totalCostUSD: await computeCell(totalCostMetric, items),
+    };
+}

package/dist/report/components/summaries/faces.d.ts

@@ -0,0 +1,7 @@
+import type { ScopeSummaryData } from "../../model/types.ts";
+import type { TextContext } from "../../definition/tree.ts";
+/**
+ * 一至两行:头行是端到端通过率(官方 MetricCell,不重算)+ experiment/eval/attempt 数 +
+ * `votes` 选中的那级计票 + 总成本;第二行(有则加)是快照时间窗。
+ */
+export declare function scopeSummaryText(data: ScopeSummaryData, votes: "eval" | "attempt", ctx: TextContext): string;

package/dist/report/components/summaries/faces.js

@@ -0,0 +1,38 @@
+// ScopeSummary 的 text 面:同一份算好的数据,渲染成终端字符(niceeval show 的形态)。
+// 与 web 面共守诚实契约:排序随 better、samples < total 角标、缺数据 — 不补 0。
+// 零 react、零 IO、纯同步。
+import { countText, localeText, resolveLocalizedText } from "../../model/locale.js";
+import { formatReportDateTime, formatReportDateTimeRange } from "../../model/format.js";
+import { wrapDisplay } from "../../model/text-layout.js";
+import { cellText, verdictTallyText, MISSING_MARK } from "../shared-faces.js";
+/**
+ * 一至两行:头行是端到端通过率(官方 MetricCell,不重算)+ experiment/eval/attempt 数 +
+ * `votes` 选中的那级计票 + 总成本;第二行(有则加)是快照时间窗。
+ */
+export function scopeSummaryText(data, votes, ctx) {
+    const locale = ctx.locale;
+    const tally = votes === "attempt" ? data.attemptVerdicts : data.evalVerdicts;
+    const head = [
+        `${localeText(locale, "scopeSummary.passRate")} ${cellText(data.endToEndPassRate, locale)}`,
+        countText(locale, "overview.experiments", data.experiments),
+        localeText(locale, "overview.evalsCount", { n: data.evals }),
+        localeText(locale, "overview.attemptsCount", { n: data.attempts }),
+        verdictTallyText(tally, locale),
+        `${localeText(locale, "scopeSummary.totalCost")} ${data.totalCostUSD.value === null ? MISSING_MARK : resolveLocalizedText(data.totalCostUSD.display, locale)}${data.totalCostUSD.samples < data.totalCostUSD.total
+            ? ` (${localeText(locale, "scopeSummary.costCoverage", {
+                samples: data.totalCostUSD.samples,
+                total: data.totalCostUSD.total,
+            })})`
+            : ""}`,
+    ].join(" · ");
+    // 头行拼接的字段较多,窄终端下按显示宽度折行(不截断内容)。
+    const lines = wrapDisplay(head, ctx.width);
+    if (data.range.latestStartedAt !== null) {
+        const from = data.range.earliestStartedAt;
+        const to = data.range.latestStartedAt;
+        lines.push(from !== null && from !== to
+            ? localeText(locale, "scopeSummary.runRange", formatReportDateTimeRange(from, to, locale))
+            : localeText(locale, "scopeSummary.lastRun", { time: formatReportDateTime(to, locale) }));
+    }
+    return lines.join("\n");
+}

package/dist/report/components/summaries/index.d.ts

@@ -0,0 +1,27 @@
+import { type ReportComponent } from "../../definition/tree.ts";
+import type { ReportInput, ScopeSummaryData, SeriesInput } from "../../model/types.ts";
+import { type ChromeProps, type DataProps, type Validator } from "../shared.ts";
+export declare const validateScopeSummaryData: Validator;
+export type ScopeSummaryProps = DataProps<ScopeSummaryData, Record<never, never>, ChromeProps & {
+    /** 显示哪一级计票;默认 "eval"。data 恒携带两级,votes 只选择呈现。 */
+    votes?: "eval" | "attempt";
+}>;
+/** 范围摘要卡:时间窗、数量、两级计票、端到端通过率与总成本。 */
+export declare const ScopeSummary: ReportComponent<ScopeSummaryProps>;
+type ComparisonChrome = ChromeProps & {
+    /** 透传给散点;缺省跟随缺省 series 解析——按 line 归类时连线(声明了线就画线)。 */
+    connect?: boolean;
+};
+export type ExperimentComparisonProps = ComparisonChrome & {
+    input?: ReportInput;
+    /** 散点的 series 维度。缺省解析:Scope 内任一实验声明了 label `line` → `label("line")` 并连线;否则 `"agent"`、不连线。 */
+    series?: SeriesInput;
+};
+/**
+ * 内建报告的默认组合件:把同一个 input(缺省 ctx.scope)原样透传给 ScopeSummary、
+ * 成本 × 端到端通过率的 MetricScatter 与 ExperimentList——组合本身不二次计算或过滤,
+ * 也不导出自己的 data 形态;每个叶子组件按自己的公开契约取数,共享计算由 resolve 的
+ * 「同引用 input + 深相等 spec」记忆化保证。
+ */
+export declare const ExperimentComparison: ReportComponent<ExperimentComparisonProps>;
+export {};

package/dist/report/components/summaries/index.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// 官方双面组件的装配点:web 面(./ScopeSummary.tsx 的纯 React 组件)+ text 面(./faces.ts)
+// + resolve 解析面(spec 形态由管线代调配套 ./compute.ts)。ScopeSummary 与 ExperimentComparison
+// 同属汇总族——前者是范围摘要卡,后者是内建报告默认使用的组合件(装配 ScopeSummary +
+// MetricScatter + ExperimentList,不产生自己的 data)。
+import { defineComponent } from "../../definition/tree.js";
+import { Col } from "../../definition/primitives.js";
+import { resolveInput, seriesName } from "../../model/aggregate.js";
+import { label } from "../../model/flag.js";
+import { costUSD, endToEndPassRate } from "../../model/metrics.js";
+import { cellProblem, isObject, makeDataComponent, tallyProblem, } from "../shared.js";
+import { scopeSummaryData } from "./compute.js";
+import { scopeSummaryText } from "./faces.js";
+import { ScopeSummary as ScopeSummaryWeb } from "./ScopeSummary.js";
+import { MetricScatter } from "../metric-views/index.js";
+import { ExperimentList } from "../entity-lists/index.js";
+export const validateScopeSummaryData = (data) => {
+    if (!isObject(data))
+        return "expected an object";
+    if (!isObject(data.range))
+        return 'missing "range" ({ earliestStartedAt, latestStartedAt })';
+    if (!(data.range.earliestStartedAt === null || typeof data.range.earliestStartedAt === "string")) {
+        return '"range.earliestStartedAt" must be a string or null';
+    }
+    if (!(data.range.latestStartedAt === null || typeof data.range.latestStartedAt === "string")) {
+        return '"range.latestStartedAt" must be a string or null';
+    }
+    if (typeof data.experiments !== "number")
+        return '"experiments" must be a number';
+    if (typeof data.evals !== "number")
+        return '"evals" must be a number';
+    if (typeof data.attempts !== "number")
+        return '"attempts" must be a number';
+    const evalVerdictsProblem = tallyProblem(data.evalVerdicts, "evalVerdicts");
+    if (evalVerdictsProblem !== null)
+        return evalVerdictsProblem;
+    const attemptVerdictsProblem = tallyProblem(data.attemptVerdicts, "attemptVerdicts");
+    if (attemptVerdictsProblem !== null)
+        return attemptVerdictsProblem;
+    const passRateProblem = cellProblem(data.endToEndPassRate, "endToEndPassRate");
+    if (passRateProblem !== null)
+        return passRateProblem;
+    return cellProblem(data.totalCostUSD, "totalCostUSD");
+};
+/** 范围摘要卡:时间窗、数量、两级计票、端到端通过率与总成本。 */
+export const ScopeSummary = makeDataComponent({
+    name: "ScopeSummary",
+    dataFnName: "scopeSummaryData",
+    shapeName: "ScopeSummaryData",
+    dataFn: (input) => scopeSummaryData(input),
+    specKeys: [],
+    validate: validateScopeSummaryData,
+    web: (props, ctx) => _jsx(ScopeSummaryWeb, { ...props, locale: props.locale ?? ctx.locale }),
+    text: (props, ctx) => scopeSummaryText(props.data, props.votes ?? "eval", ctx),
+});
+/** 默认报告识别的归类键:声明了它的实验按线归类并连线(docs/feature/experiments/library.md「labels」)。 */
+const LINE_LABEL_KEY = "line";
+/**
+ * 缺省 series:Scope 内任一快照声明了 labels.line 用 line 维度,否则 agent;显式传入覆盖。
+ * connect 缺省跟随最终 series 是否解析为 line(即便是显式传入的)。
+ */
+function resolveComparisonSeries(input, props) {
+    const hasLine = resolveInput(input).snapshots.some((s) => s.experiment?.labels?.[LINE_LABEL_KEY] !== undefined);
+    const series = props.series ?? (hasLine ? label(LINE_LABEL_KEY) : "agent");
+    return { series, connect: props.connect ?? seriesName(series) === LINE_LABEL_KEY };
+}
+/**
+ * 内建报告的默认组合件:把同一个 input(缺省 ctx.scope)原样透传给 ScopeSummary、
+ * 成本 × 端到端通过率的 MetricScatter 与 ExperimentList——组合本身不二次计算或过滤,
+ * 也不导出自己的 data 形态;每个叶子组件按自己的公开契约取数,共享计算由 resolve 的
+ * 「同引用 input + 深相等 spec」记忆化保证。
+ */
+export const ExperimentComparison = defineComponent((props, ctx) => {
+    const input = props.input ?? ctx.scope;
+    const { series, connect } = resolveComparisonSeries(input, props);
+    return (_jsxs(Col, { className: props.className, children: [_jsx(ScopeSummary, { input: input, locale: props.locale }), _jsx(MetricScatter, { input: input, points: "experiment", series: series, connect: connect, x: costUSD, y: endToEndPassRate, locale: props.locale }), _jsx(ExperimentList, { input: input, filter: true, locale: props.locale })] }));
+});
+ExperimentComparison.displayName = "ExperimentComparison";

package/dist/report/definition/grid-layout.d.ts

@@ -0,0 +1,50 @@
+import type { ReportNode } from "./tree.ts";
+export type GridVariant = "plain" | "boxed";
+export type GridDensity = "regular" | "compact";
+/** 校验 `columns`:必须是有限正整数——TypeScript 的 `number` 排除不了 0/负数/小数/NaN/Infinity。 */
+export declare function validateGridColumns(columns: number): number;
+export interface NormalizedGridCell {
+    readonly node: ReportNode;
+    /** React key:复用元素自带 key,缺失时按展平后的声明序生成稳定回退。 */
+    readonly key: string;
+}
+/**
+ * `normalizeGrid` 的产物:有序、不可拆的 cell 列表 + columns / variant / density。
+ * 不是公开 data shape,也不进结果或 artifact——只是两个渲染面共享的同步排版中间值。
+ */
+export interface NormalizedGrid {
+    readonly cells: readonly NormalizedGridCell[];
+    readonly columns: number;
+    readonly variant: GridVariant;
+    readonly density: GridDensity;
+}
+/** `Grid` 组件创建时的一次性规范化:校验 props、展平 children 成有序 cell 列表。 */
+export declare function normalizeGrid(input: {
+    children: ReportNode;
+    columns: number;
+    variant?: GridVariant;
+    density?: GridDensity;
+}): NormalizedGrid;
+/** text 面规划的输入:只有可用宽度、cell 数与规范化 Grid props 里跟宽度有关的两项。 */
+export interface TextGridPlanInput {
+    readonly availableWidth: number;
+    readonly cellCount: number;
+    readonly columns: number;
+    readonly density: GridDensity;
+}
+/**
+ * text 面的一次性排版计划:实际列数、每列内容显示宽度、格间 gutter。
+ * `boxed` 与 `plain` 复用同一份计划(规划总是先扣 boxed 的四边框与内 padding),
+ * `plain` 渲染时只是不打印这部分字符——两个 variant 因此列数一致,不会各挑各的列数。
+ */
+export interface TextGridPlan {
+    readonly columns: number;
+    readonly contentWidths: readonly number[];
+    readonly gutter: number;
+}
+/**
+ * 从 `min(columns, cellCount)` 向一列尝试,选出满足每格最小可读内容宽度的最大列数;
+ * 一列是无条件 fallback(即使内容宽度因此小于 24)。选定列数后,余下的显示列从左向右
+ * 逐列多补一列,因此任意一行的显示宽度都不会超过 `availableWidth`(见调用方组装)。
+ */
+export declare function planTextGrid(input: TextGridPlanInput): TextGridPlan;

package/dist/report/definition/grid-layout.js

@@ -0,0 +1,89 @@
+// Grid 的语义层与面内布局(docs/feature/reports/architecture.md「排版原语的语义层与面内布局」、
+// docs/feature/reports/library/layout.md「Grid 与 Stat」)。只放同步纯函数与中间类型:
+// normalizeGrid 把 resolved ReportNode children 校验并展平成有序 cell 列表;planTextGrid
+// 只依赖 availableWidth / cell 数 / 规范化 Grid props,规划 text 面的列数与每列宽度。
+// 不 import show / view、Results IO 或 stylesheet;primitives.tsx 消费本文件产出两面适配。
+// react/jsx-runtime 的 Fragment 注册符号,跨 react 版本稳定(tree.ts 同一常量的独立取用,
+// Symbol.for 全局注册表保证同一符号,不产生耦合)。
+const REACT_FRAGMENT = Symbol.for("react.fragment");
+function isElementNode(node) {
+    return typeof node === "object" && node !== null && !Array.isArray(node) && "type" in node && "props" in node;
+}
+function keyOf(node, fallback) {
+    if (isElementNode(node)) {
+        const key = node.key;
+        if (typeof key === "string" || typeof key === "number")
+            return String(key);
+    }
+    return fallback;
+}
+/** 校验 `columns`:必须是有限正整数——TypeScript 的 `number` 排除不了 0/负数/小数/NaN/Infinity。 */
+export function validateGridColumns(columns) {
+    if (!(Number.isFinite(columns) && Number.isInteger(columns) && columns > 0)) {
+        throw new Error(`Grid columns must be a finite positive integer, received ${JSON.stringify(columns)}. ` +
+            "Pass columns={N} with a whole number greater than 0 (e.g. columns={3}).");
+    }
+    return columns;
+}
+/**
+ * 递归展开数组与 Fragment、跳过空分支(null/undefined/boolean),其余节点各占一格
+ * ——`Col` 归拢的多个子节点、任意自定义组件的渲染结果都是不透明的一格,不下钻其内部结构。
+ */
+function flattenGridChildren(children) {
+    const cells = [];
+    const visit = (node) => {
+        if (node === null || node === undefined || typeof node === "boolean")
+            return;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                visit(child);
+            return;
+        }
+        if (isElementNode(node) && node.type === REACT_FRAGMENT) {
+            visit(node.props.children);
+            return;
+        }
+        cells.push({ node, key: keyOf(node, `nre-grid-cell-${cells.length}`) });
+    };
+    visit(children);
+    return cells;
+}
+/** `Grid` 组件创建时的一次性规范化:校验 props、展平 children 成有序 cell 列表。 */
+export function normalizeGrid(input) {
+    return {
+        cells: flattenGridChildren(input.children),
+        columns: validateGridColumns(input.columns),
+        variant: input.variant ?? "plain",
+        density: input.density ?? "regular",
+    };
+}
+/** text 面每 cell 的最小可读内容宽度;density 不以挤坏字段换取更多列。 */
+const MIN_CONTENT_WIDTH = 24;
+/** boxed 单 cell 的固定开销:左右各一根边框 + 左右各一格 padding。 */
+const BOXED_OVERHEAD_PER_CELL = 4;
+function gridGutter(density) {
+    return density === "compact" ? 1 : 2;
+}
+/**
+ * 从 `min(columns, cellCount)` 向一列尝试,选出满足每格最小可读内容宽度的最大列数;
+ * 一列是无条件 fallback(即使内容宽度因此小于 24)。选定列数后,余下的显示列从左向右
+ * 逐列多补一列,因此任意一行的显示宽度都不会超过 `availableWidth`(见调用方组装)。
+ */
+export function planTextGrid(input) {
+    const { availableWidth, cellCount, columns, density } = input;
+    const gutter = gridGutter(density);
+    const maxColumns = Math.max(1, Math.min(columns, Math.max(cellCount, 1)));
+    let chosen = 1;
+    for (let n = maxColumns; n >= 2; n--) {
+        const budget = availableWidth - BOXED_OVERHEAD_PER_CELL * n - gutter * (n - 1);
+        if (budget >= 0 && Math.floor(budget / n) >= MIN_CONTENT_WIDTH) {
+            chosen = n;
+            break;
+        }
+    }
+    const budget = Math.max(0, availableWidth - BOXED_OVERHEAD_PER_CELL * chosen - gutter * (chosen - 1));
+    const base = Math.floor(budget / chosen);
+    const remainder = budget - base * chosen;
+    const contentWidths = Array.from({ length: chosen }, (_, i) => Math.max(1, base + (i < remainder ? 1 : 0)));
+    return { columns: chosen, contentWidths, gutter };
+}

package/dist/report/{primitives.d.ts → definition/primitives.d.ts}

@@ -1,7 +1,8 @@
-import type { AttemptLocator } from "../results/locator.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
 import { type ReportNode } from "./tree.ts";
-import { type LocalizedText, type ReportLocale } from "./locale.ts";
-import type { ColumnAlign } from "./text/layout.ts";
+import { type LocalizedText, type ReportLocale } from "../model/locale.ts";
+import type { ColumnAlign } from "../model/text-layout.ts";
+import { type GridDensity, type GridVariant } from "./grid-layout.ts";
 export interface LayoutProps {
     children?: ReportNode;
     className?: string;
@@ -15,10 +16,39 @@ export declare const Col: import("./tree.ts").ReportComponent<LayoutProps>;
  * 同一把尺),装不下时整块退化为纵向堆叠——不截断、不隐藏任何子块。
  */
 export declare const Row: import("./tree.ts").ReportComponent<LayoutProps>;
+export interface GridProps extends LayoutProps {
+    /** 宽面最多摆几列;必须是有限正整数,运行时校验(docs/feature/reports/library/layout.md「Grid 与 Stat」)。 */
+    columns: number;
+    /** plain 无框;boxed 给每个 cell 完整四边框。默认 plain。 */
+    variant?: GridVariant;
+    /** 改变格内留白,并调整内置 Stat 的主值字号;不改变内容和分组。默认 regular。 */
+    density?: GridDensity;
+}
+/**
+ * 自由摘要面板的格子容器:只负责呈现,不读取 Scope、不聚合 Metric。每个直接子节点
+ * (数组 / Fragment 先按 ReportNode 规则展平,空分支不占格)是一格;`Col` 把多个区块
+ * 归成一格。展平与 text 面排版的算术在 ./grid-layout.ts,这里只做两面结构适配。
+ */
+export declare const Grid: import("./tree.ts").ReportComponent<GridProps>;
+export type StatTone = "neutral" | "positive" | "negative" | "warning";
+export interface StatProps {
+    label: LocalizedText;
+    /** 已格式化的主值;null 明确渲染为 —,不补成 0。 */
+    value: LocalizedText | number | null;
+    /** 主值下面的短解释;省略时不留空行。 */
+    detail?: LocalizedText;
+    /** 主值的语义色;不从正负号、单位或 Metric.better 猜。默认 neutral。 */
+    tone?: StatTone;
+    className?: string;
+}
+/** label / 主值 / 辅助信息的最小内容单元;可以脱离 Grid 单独使用。 */
+export declare const Stat: import("./tree.ts").ReportComponent<StatProps>;
 export interface SectionProps extends LayoutProps {
     title: LocalizedText;
+    /** 标题行右侧的短元信息;text 面与标题同一行,空间不足时换到下一行。 */
+    meta?: LocalizedText;
 }
-/** 带标题的块:网页是标题层级,终端是标题行加缩进。 */
+/** 带标题的块:网页是标题层级(可选 meta 同行右对齐),终端是标题行加缩进。 */
 export declare const Section: import("./tree.ts").ReportComponent<SectionProps>;
 export interface TextProps {
     /** 自由正文原样渲染,不随 locale 自动翻译。 */

package/dist/report/{primitives.js → definition/primitives.js}

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { COMPONENT_RAW_CHILDREN, COMPONENT_ROLE, defineComponent } from "./tree.js";
-import { localeText, resolveLocalizedText } from "./locale.js";
-import { indentBlock, joinColumns, stringWidth, wrapDisplay } from "./text/layout.js";
-import { renderTableText } from "./text/table.js";
+import { localeText, resolveLocalizedText } from "../model/locale.js";
+import { indentBlock, joinColumns, padDisplay, stringWidth, wrapDisplay } from "../model/text-layout.js";
+import { renderTableText } from "./table-text.js";
+import { normalizeGrid, planTextGrid } from "./grid-layout.js";
 function childArray(children) {
     if (children === null || children === undefined || typeof children === "boolean")
         return [];
@@ -11,6 +12,8 @@ function childArray(children) {
 function cx(...parts) {
     return parts.filter(Boolean).join(" ");
 }
+/** `null`/缺数据的统一显示符:Table 与 Stat 共用,不补成 0。 */
+const MISSING_MARK = "—";
 /** 纵向依次排列:网页是块级堆叠,终端是逐块输出(块间空一行)。两面都按声明序。 */
 export const Col = defineComponent({
     web({ children, className }) {
@@ -56,18 +59,107 @@ export const Row = defineComponent({
     },
 });
 Row.displayName = "Row";
-/** 带标题的块:网页是标题层级,终端是标题行加缩进。 */
+/** boxed 单个 cell 的完整边框:同一份 TextGridPlan 决定内容宽度,四边不因换行残缺。 */
+function boxCellBlock(content, contentWidth) {
+    const lines = content.length > 0 ? content.split("\n") : [""];
+    const top = `┌${"─".repeat(contentWidth + 2)}┐`;
+    const bottom = `└${"─".repeat(contentWidth + 2)}┘`;
+    const body = lines.map((line) => `│ ${padDisplay(line, contentWidth)} │`);
+    return [top, ...body, bottom].join("\n");
+}
+/** 一个物理行内的 cell 并排:顶对齐、短 block 补空行到同高(joinColumns 已有语义)。 */
+function renderGridRow(blocks, contentWidths, gutter, variant) {
+    const separator = " ".repeat(gutter);
+    if (variant === "boxed") {
+        const boxed = blocks.map((block, i) => boxCellBlock(block, contentWidths[i]));
+        const boxWidths = contentWidths.map((w) => w + 4);
+        return joinColumns(boxed, boxWidths, separator);
+    }
+    return joinColumns(blocks, contentWidths, separator);
+}
+/**
+ * 自由摘要面板的格子容器:只负责呈现,不读取 Scope、不聚合 Metric。每个直接子节点
+ * (数组 / Fragment 先按 ReportNode 规则展平,空分支不占格)是一格;`Col` 把多个区块
+ * 归成一格。展平与 text 面排版的算术在 ./grid-layout.ts,这里只做两面结构适配。
+ */
+export const Grid = defineComponent({
+    web({ children, columns, variant, density, className }) {
+        const normalized = normalizeGrid({ children, columns, variant, density });
+        const style = { "--nre-grid-max-columns": normalized.columns };
+        return (_jsx("div", { className: cx("nre", "nre-grid", `nre-grid--${normalized.variant}`, `nre-grid--${normalized.density}`, className), style: style, children: normalized.cells.map((cell) => (_jsx("div", { className: "nre-grid-cell", children: cell.node }, cell.key))) }));
+    },
+    text({ children, columns, variant, density }, ctx) {
+        const normalized = normalizeGrid({ children, columns, variant, density });
+        if (normalized.cells.length === 0)
+            return "";
+        const plan = planTextGrid({
+            availableWidth: ctx.width,
+            cellCount: normalized.cells.length,
+            columns: normalized.columns,
+            density: normalized.density,
+        });
+        // 确定计划后才对每个 cell 调用一次 ctx.render——不为试探列数重复渲染。
+        const blocks = normalized.cells.map((cell, i) => ctx.render(cell.node, plan.contentWidths[i % plan.columns]));
+        const rows = [];
+        for (let start = 0; start < blocks.length; start += plan.columns) {
+            const rowBlocks = blocks.slice(start, start + plan.columns);
+            const rowWidths = plan.contentWidths.slice(0, rowBlocks.length);
+            rows.push(renderGridRow(rowBlocks, rowWidths, plan.gutter, normalized.variant));
+        }
+        return rows.join("\n\n");
+    },
+});
+Grid.displayName = "Grid";
+/**
+ * Grid / Stat 共享的显示值规范化:LocalizedText 走 resolveLocalizedText,number 走当前
+ * locale 的 Intl.NumberFormat,null 变 —;两个面调同一份,不各写一套。
+ */
+function resolveStatDisplay(value, locale) {
+    if (value === null)
+        return MISSING_MARK;
+    if (typeof value === "number")
+        return new Intl.NumberFormat(locale).format(value);
+    return resolveLocalizedText(value, locale);
+}
+/** label / 主值 / 辅助信息的最小内容单元;可以脱离 Grid 单独使用。 */
+export const Stat = defineComponent({
+    web({ label, value, detail, tone = "neutral", className }, ctx) {
+        return (_jsxs("div", { className: cx("nre", "nre-stat", `nre-stat--${tone}`, className), children: [_jsx("div", { className: "nre-stat-label", children: resolveLocalizedText(label, ctx.locale) }), _jsx("div", { className: "nre-stat-value", children: resolveStatDisplay(value, ctx.locale) }), detail !== undefined ? _jsx("div", { className: "nre-stat-detail", children: resolveLocalizedText(detail, ctx.locale) }) : null] }));
+    },
+    text({ label, value, detail }, ctx) {
+        const lines = [resolveLocalizedText(label, ctx.locale), resolveStatDisplay(value, ctx.locale)];
+        if (detail !== undefined)
+            lines.push(resolveLocalizedText(detail, ctx.locale));
+        return lines.flatMap((line) => wrapDisplay(line, ctx.width)).join("\n");
+    },
+});
+Stat.displayName = "Stat";
+/** 标题行右侧同一行放不下 meta 时,退化成标题后两格缩进折行。 */
+function sectionHeadingLine(heading, metaText, width) {
+    if (metaText === undefined)
+        return heading;
+    const gap = width - stringWidth(heading) - stringWidth(metaText);
+    if (gap >= 1)
+        return heading + " ".repeat(gap) + metaText;
+    const wrapped = wrapDisplay(metaText, Math.max(1, width - 2)).join("\n");
+    return `${heading}\n${indentBlock(wrapped, "  ")}`;
+}
+/** 带标题的块:网页是标题层级(可选 meta 同行右对齐),终端是标题行加缩进。 */
 export const Section = defineComponent({
-    web({ title, children, className }, ctx) {
-        return (_jsxs("section", { className: cx("nre", "nre-section", className), children: [_jsx("h2", { className: "nre-section-title", children: resolveLocalizedText(title, ctx.locale) }), children] }));
+    web({ title, meta, children, className }, ctx) {
+        const titleText = resolveLocalizedText(title, ctx.locale);
+        const metaText = meta !== undefined ? resolveLocalizedText(meta, ctx.locale) : undefined;
+        return (_jsxs("section", { className: cx("nre", "nre-section", className), children: [metaText !== undefined ? (_jsxs("header", { className: "nre-section-header", children: [_jsx("h2", { className: "nre-section-title", children: titleText }), _jsx("p", { className: "nre-section-meta", children: metaText })] })) : (_jsx("h2", { className: "nre-section-title", children: titleText })), children] }));
     },
-    text({ title, children }, ctx) {
+    text({ title, meta, children }, ctx) {
         const heading = resolveLocalizedText(title, ctx.locale);
+        const metaText = meta !== undefined ? resolveLocalizedText(meta, ctx.locale) : undefined;
+        const headingLine = sectionHeadingLine(heading, metaText, ctx.width);
         const body = childArray(children)
             .map((child) => ctx.render(child, ctx.width - 2))
             .filter((block) => block.length > 0)
             .join("\n\n");
-        return body.length > 0 ? `${heading}\n${indentBlock(body, "  ")}` : heading;
+        return body.length > 0 ? `${headingLine}\n${indentBlock(body, "  ")}` : headingLine;
     },
 });
 Section.displayName = "Section";
@@ -164,7 +256,6 @@ export const Tab = defineComponent({
 });
 Tab.displayName = "Tab";
 Tab[COMPONENT_ROLE] = "tab";
-const MISSING_MARK = "—";
 /** 列 key 唯一、行 cells 不携带未声明 key、空列拒绝——无类型 JS 输入在渲染前同样校验。 */
 function validateTableProps(props) {
     if (!Array.isArray(props.columns) || props.columns.length === 0) {
@@ -212,7 +303,7 @@ export const Table = defineComponent({
                                 const value = row.cells[column.key];
                                 const missing = value === null || value === undefined;
                                 return (_jsx("td", { className: alignClass(column.align), children: missing ? _jsx("span", { className: "nre-missing", children: MISSING_MARK }) : value }, column.key));
-                            }), hasLocator ? (_jsx("td", { children: row.locator ? (_jsx("a", { className: "nre-locator", href: ctx.attemptHref(row.locator), children: row.locator })) : (_jsx("span", { className: "nre-missing", children: MISSING_MARK })) })) : null] }, row.key))) })] }));
+                            }), hasLocator ? (_jsx("td", { children: row.locator ? (ctx.attemptHref ? (_jsx("a", { className: "nre-locator", href: ctx.attemptHref(row.locator), children: row.locator })) : (_jsx("span", { className: "nre-locator", children: row.locator }))) : (_jsx("span", { className: "nre-missing", children: MISSING_MARK })) })) : null] }, row.key))) })] }));
     },
     text(props, ctx) {
         validateTableProps(props);