niceeval 0.8.0 → 0.9.0

package/dist/report/locale.js

@@ -129,6 +129,44 @@ const en = {
     "scoreboard.subjectTitle": "{questions} evals, weighted {earned} of {possible}",
     "delta.pairHeader": "pair (A → B)",
     "delta.empty": "{experiments} experiments, 0 comparable pairs",
+    /** ScopeWarnings 聚合层的 chrome:汇总行、kind 徽标、组头与明细折叠标签;message 本体不经字典。 */
+    "warnings.summary.experiments.one": "{n} experiment flagged",
+    "warnings.summary.experiments.other": "{n} experiments flagged",
+    "warnings.group.unreadableSnapshot.one": "{n} snapshot skipped",
+    "warnings.group.unreadableSnapshot.other": "{n} snapshots skipped",
+    "warnings.details.one": "{n} warning",
+    "warnings.details.other": "{n} warnings",
+    "warnings.badge.partialCoverage": "coverage {covered}/{total}",
+    "warnings.badge.staleSnapshot": "{gap} behind",
+    "warnings.badge.unfinishedSnapshot": "unfinished",
+    "warnings.gap.second.one": "{n} second",
+    "warnings.gap.second.other": "{n} seconds",
+    "warnings.gap.minute.one": "{n} minute",
+    "warnings.gap.minute.other": "{n} minutes",
+    "warnings.gap.hour.one": "{n} hour",
+    "warnings.gap.hour.other": "{n} hours",
+    "warnings.gap.day.one": "{n} day",
+    "warnings.gap.day.other": "{n} days",
+    /** Hero / HeroCard 的运行 meta(hero.noRuns 是 latestStartedAt 为 null 时的内置文案)。 */
+    "hero.lastRun": "Last run {time}",
+    "hero.noRuns": "No runs yet",
+    /** web 面的合成来源标注(仅 snapshots > 1 时显示)。 */
+    "hero.composedRuns": "composed from {n} runs",
+    /** text 面的合成来源标注(show 页首 meta 行,仅 snapshots > 1 时显示)。 */
+    "hero.composedSnapshots": "composed from {n} snapshots",
+    /** CopyFixPrompt 的 web 面 chrome(prompt 本身面向 agent、固定英文,不经词典)。 */
+    "copyFixPrompt.summary.one": "Fix prompt · {n} failure",
+    "copyFixPrompt.summary.other": "Fix prompt · {n} failures",
+    "copyFixPrompt.copy": "Copy fix prompt",
+    /** TraceWaterfall 的 chrome。 */
+    "traceWaterfall.empty": "No attempts",
+    "traceWaterfall.noTrace": "no trace",
+    "traceWaterfall.spans.one": "{n} span",
+    "traceWaterfall.spans.other": "{n} spans",
+    "traceWaterfall.failedSpans.one": "{n} failed",
+    "traceWaterfall.failedSpans.other": "{n} failed",
+    /** AttemptList 的 web 面过滤框占位符(filter 渐进增强)。 */
+    "attemptList.filterPlaceholder": "Filter attempts…",
     "tabs.tab": "Tab",
 };
 const zhCN = {
@@ -216,6 +254,37 @@ const zhCN = {
     "scoreboard.subjectTitle": "{questions} 道题,加权得分 {earned}/{possible}",
     "delta.pairHeader": "对比 (A → B)",
     "delta.empty": "{experiments} 个实验、0 个可配对",
+    "warnings.summary.experiments.one": "{n} 个实验的数字带警告",
+    "warnings.summary.experiments.other": "{n} 个实验的数字带警告",
+    "warnings.group.unreadableSnapshot.one": "{n} 个快照被跳过",
+    "warnings.group.unreadableSnapshot.other": "{n} 个快照被跳过",
+    "warnings.details.one": "{n} 条原始警告",
+    "warnings.details.other": "{n} 条原始警告",
+    "warnings.badge.partialCoverage": "覆盖 {covered}/{total}",
+    "warnings.badge.staleSnapshot": "落后 {gap}",
+    "warnings.badge.unfinishedSnapshot": "未收尾",
+    "warnings.gap.second.one": "{n} 秒",
+    "warnings.gap.second.other": "{n} 秒",
+    "warnings.gap.minute.one": "{n} 分钟",
+    "warnings.gap.minute.other": "{n} 分钟",
+    "warnings.gap.hour.one": "{n} 小时",
+    "warnings.gap.hour.other": "{n} 小时",
+    "warnings.gap.day.one": "{n} 天",
+    "warnings.gap.day.other": "{n} 天",
+    "hero.lastRun": "最后运行 {time}",
+    "hero.noRuns": "暂无运行",
+    "hero.composedRuns": "由 {n} 次运行合成",
+    "hero.composedSnapshots": "由 {n} 份快照合成",
+    "copyFixPrompt.summary.one": "修复 prompt · {n} 个失败",
+    "copyFixPrompt.summary.other": "修复 prompt · {n} 个失败",
+    "copyFixPrompt.copy": "复制修复 prompt",
+    "traceWaterfall.empty": "没有 attempt",
+    "traceWaterfall.noTrace": "无 trace",
+    "traceWaterfall.spans.one": "{n} 个 span",
+    "traceWaterfall.spans.other": "{n} 个 span",
+    "traceWaterfall.failedSpans.one": "{n} 个失败",
+    "traceWaterfall.failedSpans.other": "{n} 个失败",
+    "attemptList.filterPlaceholder": "筛选 attempt…",
     "tabs.tab": "Tab",
 };
 const dictionaries = {

package/dist/report/react/AttemptList.d.ts

@@ -15,10 +15,12 @@ export declare function AttemptRow({ item, attemptHref, locale, }: {
     attemptHref?: (locator: AttemptLocator) => string;
     locale?: ReportLocale;
 }): ReactElement;
-export declare function AttemptList({ data, total, attemptHref, className, locale, }: {
+export declare function AttemptList({ data, total, filter, attemptHref, className, locale, }: {
     data: readonly AttemptListItem[];
     /** data 被 slice 时的原始数量;如实显示还剩多少条没展示。 */
     total?: number;
+    /** web 面加过滤输入框(按 experiment、eval、agent、verdict 或摘要文本收窄行);渐进增强,不改变数据。 */
+    filter?: boolean;
     attemptHref?: (locator: AttemptLocator) => string;
     className?: string;
     locale?: ReportLocale;

package/dist/report/react/AttemptList.js

@@ -18,9 +18,9 @@ export function failureSummaryText(item, locale) {
 /** 一条 Attempt 的比较卡片;完整 assertions 通过 locator 下钻,不在列表内展开。 */
 export function AttemptRow({ item, attemptHref = DEFAULT_ATTEMPT_HREF, locale = DEFAULT_REPORT_LOCALE, }) {
     const reason = failureSummaryText(item, locale);
-    return (_jsxs("li", { className: cx("nre-attempt", `nre-attempt-${item.verdict}`), children: [_jsxs("div", { className: "nre-attempt-head", children: [_jsx(AttemptLocatorBadge, { item: item, attemptHref: attemptHref }), _jsx("span", { className: "nre-attempt-eval", children: item.evalId }), _jsx("span", { className: "nre-attempt-experiment", children: item.experimentId }), _jsx("span", { className: cx("nre-attempt-agent", "nre-key", colorClassForKey(item.agent)), children: item.agent }), _jsx("span", { className: "nre-attempt-duration", children: formatDurationMs(item.durationMs) }), item.costUSD !== null && _jsx("span", { className: "nre-attempt-cost", children: formatUSD(item.costUSD) })] }), reason && _jsx("p", { className: "nre-attempt-result", children: reason })] }));
+    return (_jsxs("li", { className: cx("nre-attempt", `nre-attempt-${item.verdict}`), "data-nre-verdict": item.verdict, children: [_jsxs("div", { className: "nre-attempt-head", children: [_jsx(AttemptLocatorBadge, { item: item, attemptHref: attemptHref }), _jsx("span", { className: "nre-attempt-eval", children: item.evalId }), _jsx("span", { className: "nre-attempt-experiment", children: item.experimentId }), _jsx("span", { className: cx("nre-attempt-agent", "nre-key", colorClassForKey(item.agent)), children: item.agent }), _jsx("span", { className: "nre-attempt-duration", children: formatDurationMs(item.durationMs) }), item.costUSD !== null && _jsx("span", { className: "nre-attempt-cost", children: formatUSD(item.costUSD) })] }), reason && _jsx("p", { className: "nre-attempt-result", children: reason })] }));
 }
-export function AttemptList({ data, total, attemptHref = DEFAULT_ATTEMPT_HREF, className, locale = DEFAULT_REPORT_LOCALE, }) {
+export function AttemptList({ data, total, filter = false, attemptHref = DEFAULT_ATTEMPT_HREF, className, locale = DEFAULT_REPORT_LOCALE, }) {
     const remaining = (total ?? data.length) - data.length;
-    return (_jsxs("section", { className: cx("nre", "nre-attempt-list", className), children: [data.length === 0 && _jsx("p", { className: "nre-attempt-list-empty", children: localeText(locale, "attemptList.empty") }), _jsx("ul", { className: "nre-attempts", children: data.map((item) => (_jsx(AttemptRow, { item: item, attemptHref: attemptHref, locale: locale }, item.locator))) }), remaining > 0 && (_jsx("p", { className: "nre-truncated", children: localeText(locale, "attemptList.truncated", { n: remaining }) }))] }));
+    return (_jsxs("section", { className: cx("nre", "nre-attempt-list", className), children: [filter && (_jsx("input", { className: "nre-filter", "data-nre-attempt-filter": "", type: "search", placeholder: localeText(locale, "attemptList.filterPlaceholder") })), data.length === 0 && _jsx("p", { className: "nre-attempt-list-empty", children: localeText(locale, "attemptList.empty") }), _jsx("ul", { className: "nre-attempts", children: data.map((item) => (_jsx(AttemptRow, { item: item, attemptHref: attemptHref, locale: locale }, item.locator))) }), remaining > 0 && (_jsx("p", { className: "nre-truncated", children: localeText(locale, "attemptList.truncated", { n: remaining }) }))] }));
 }

package/dist/report/react/CopyFixPrompt.d.ts

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import type { CopyFixPromptData } from "../types.ts";
+import { type ReportLocale } from "../locale.ts";
+/**
+ * 批量修复 prompt(纯 web 渲染面):折叠块内完整 prompt 文本 + 复制按钮(增强层)。
+ * 嵌入自有 React 页面时配合 `copyFixPromptData()` 使用;failures 为 0 返回 null。
+ */
+export declare function CopyFixPrompt({ data, className, locale, }: {
+    data: CopyFixPromptData;
+    className?: string;
+    locale?: ReportLocale;
+}): ReactElement | null;

package/dist/report/react/CopyFixPrompt.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DEFAULT_REPORT_LOCALE, countText, localeText } from "../locale.js";
+import { cx } from "./format.js";
+/**
+ * 批量修复 prompt(纯 web 渲染面):折叠块内完整 prompt 文本 + 复制按钮(增强层)。
+ * 嵌入自有 React 页面时配合 `copyFixPromptData()` 使用;failures 为 0 返回 null。
+ */
+export function CopyFixPrompt({ data, className, locale = DEFAULT_REPORT_LOCALE, }) {
+    if (data.failures === 0)
+        return null;
+    return (_jsxs("details", { className: cx("nre", "nre-copy-fix-prompt", className), children: [_jsx("summary", { className: "nre-copy-fix-prompt-summary", children: countText(locale, "copyFixPrompt.summary", data.failures) }), _jsx("button", { type: "button", className: "nre-copy-fix-prompt-copy", "data-nre-copy": data.prompt, children: localeText(locale, "copyFixPrompt.copy") }), _jsx("pre", { className: "nre-copy-fix-prompt-text", children: data.prompt })] }));
+}

package/dist/report/react/HeroCard.d.ts

@@ -0,0 +1,13 @@
+import type { ReactElement } from "react";
+import type { HeroData } from "../types.ts";
+import { type LocalizedText, type ReportLocale } from "../locale.ts";
+/**
+ * 站点标题区(纯 web 渲染面):`<h1>` 标题 + meta 行 + 品牌行。
+ * 嵌入自有 React 页面时配合 `heroData()` 使用。
+ */
+export declare function HeroCard({ title, data, className, locale, }: {
+    title: LocalizedText;
+    data: HeroData;
+    className?: string;
+    locale?: ReportLocale;
+}): ReactElement;

package/dist/report/react/HeroCard.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DEFAULT_REPORT_LOCALE, localeText, resolveLocalizedText } from "../locale.js";
+import { cx } from "./format.js";
+import { PoweredBy } from "./PoweredBy.js";
+/** ISO 时间 → 按 locale 的「最后运行」显示(年月日 时:分);不可解析原样返回。 */
+function formatLastRun(iso, locale) {
+    const date = new Date(iso);
+    if (Number.isNaN(date.valueOf()))
+        return iso;
+    try {
+        return new Intl.DateTimeFormat(locale, {
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+            hour: "2-digit",
+            minute: "2-digit",
+        }).format(date);
+    }
+    catch {
+        return iso;
+    }
+}
+/**
+ * 站点标题区(纯 web 渲染面):`<h1>` 标题 + meta 行 + 品牌行。
+ * 嵌入自有 React 页面时配合 `heroData()` 使用。
+ */
+export function HeroCard({ title, data, className, locale = DEFAULT_REPORT_LOCALE, }) {
+    const meta = data.latestStartedAt === null
+        ? localeText(locale, "hero.noRuns")
+        : [
+            localeText(locale, "hero.lastRun", { time: formatLastRun(data.latestStartedAt, locale) }),
+            ...(data.snapshots > 1 ? [localeText(locale, "hero.composedRuns", { n: data.snapshots })] : []),
+        ].join(" · ");
+    return (_jsxs("header", { className: cx("nre", "nre-hero", className), children: [_jsx("h1", { className: "nre-hero-title", children: resolveLocalizedText(title, locale) }), _jsx("p", { className: "nre-hero-meta", children: meta }), _jsx(PoweredBy, {})] }));
+}

package/dist/report/react/PoweredBy.d.ts

@@ -0,0 +1,5 @@
+import type { ReactElement } from "react";
+/** 品牌行的固定去处:niceeval 官网,utm 标记「来自报告的品牌行」。 */
+export declare const POWERED_BY_HREF = "https://niceeval.com/?utm_source=report&utm_medium=powered-by";
+/** 一行品牌色小字 `Powered by NiceEval`,链接官网;HeroCard 的品牌行与它同一渲染。 */
+export declare function PoweredBy(): ReactElement;

package/dist/report/react/PoweredBy.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** 品牌行的固定去处:niceeval 官网,utm 标记「来自报告的品牌行」。 */
+export const POWERED_BY_HREF = "https://niceeval.com/?utm_source=report&utm_medium=powered-by";
+/** 一行品牌色小字 `Powered by NiceEval`,链接官网;HeroCard 的品牌行与它同一渲染。 */
+export function PoweredBy() {
+    return (_jsx("p", { className: "nre nre-powered-by", children: _jsx("a", { href: POWERED_BY_HREF, target: "_blank", rel: "noopener", children: "Powered by NiceEval" }) }));
+}

package/dist/report/react/ScopeWarnings.d.ts

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import type { ScopeWarning } from "../types.ts";
+import { type ReportLocale } from "../locale.ts";
+/**
+ * 选择警告区(纯 web 渲染面):按动作聚合的警告组。嵌入自有 React 页面时传
+ * `data={scope.warnings}`;空集返回 null,不渲染空容器。
+ */
+export declare function ScopeWarnings({ data, className, locale, }: {
+    data: readonly ScopeWarning[];
+    className?: string;
+    locale?: ReportLocale;
+}): ReactElement | null;

package/dist/report/react/ScopeWarnings.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DEFAULT_REPORT_LOCALE } from "../locale.js";
+import { groupScopeWarnings, warningDetailsLabel } from "../scope-warnings.js";
+import { cx } from "./format.js";
+/** 命令的可复制块:无 JS 时点击全选(user-select: all),enhance.js 在场时点击复制。 */
+function CommandBlock({ command }) {
+    return (_jsx("code", { className: "nre-warning-command", "data-nre-copy": command, children: command }));
+}
+/**
+ * 选择警告区(纯 web 渲染面):按动作聚合的警告组。嵌入自有 React 页面时传
+ * `data={scope.warnings}`;空集返回 null,不渲染空容器。
+ */
+export function ScopeWarnings({ data, className, locale = DEFAULT_REPORT_LOCALE, }) {
+    if (data.length === 0)
+        return null;
+    const { summary, groups, detailsOpen } = groupScopeWarnings(data, locale);
+    return (_jsx("div", { className: cx("nre", "nre-scope-warnings", className), children: _jsxs("details", { className: "nre-warnings", children: [_jsx("summary", { className: "nre-warnings-summary", children: summary }), _jsx("ul", { className: "nre-warning-groups", children: groups.map((group, i) => (_jsxs("li", { className: "nre-warning-group", "data-category": group.category, children: [_jsxs("div", { className: "nre-warning-head", children: [_jsx("span", { className: "nre-warning-title", children: group.title }), group.badges.map((badge, j) => (_jsx("span", { className: "nre-warning-badge", "data-kind": badge.kind, children: badge.text }, j))), group.headCommand !== null && _jsx(CommandBlock, { command: group.headCommand })] }), _jsxs("details", { className: "nre-warning-details", open: detailsOpen || undefined, children: [_jsx("summary", { children: warningDetailsLabel(locale, group.warnings.length) }), _jsx("ul", { children: group.warnings.map((w, j) => (_jsxs("li", { className: "nre-warning", "data-kind": w.kind, children: [w.message, group.headCommand === null && "command" in w && w.command !== undefined && (_jsx(CommandBlock, { command: w.command }))] }, j))) })] })] }, i))) })] }) }));
+}

package/dist/report/react/TraceWaterfall.d.ts

@@ -0,0 +1,14 @@
+import type { ReactElement } from "react";
+import type { TraceWaterfallRow } from "../types.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
+import { type ReportLocale } from "../locale.ts";
+/**
+ * 执行时间瀑布(纯 web 渲染面):嵌入自有 React 页面时配合 `traceWaterfallData()` 使用。
+ * 只画被测 agent 的原始 span;runner 生命周期节点不在 data 里,组合视图归 attempt 详情。
+ */
+export declare function TraceWaterfall({ data, attemptHref, className, locale, }: {
+    data: readonly TraceWaterfallRow[];
+    attemptHref?: (locator: AttemptLocator) => string;
+    className?: string;
+    locale?: ReportLocale;
+}): ReactElement;

package/dist/report/react/TraceWaterfall.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DEFAULT_REPORT_LOCALE, countText, localeText } from "../locale.js";
+import { cx, formatDurationMs } from "./format.js";
+const DEFAULT_ATTEMPT_HREF = (locator) => `#/attempt/${locator}`;
+function pct(part, total) {
+    if (total <= 0)
+        return "0%";
+    return `${Math.min(100, Math.max(0, (part / total) * 100)).toFixed(2)}%`;
+}
+/**
+ * 执行时间瀑布(纯 web 渲染面):嵌入自有 React 页面时配合 `traceWaterfallData()` 使用。
+ * 只画被测 agent 的原始 span;runner 生命周期节点不在 data 里,组合视图归 attempt 详情。
+ */
+export function TraceWaterfall({ data, attemptHref = DEFAULT_ATTEMPT_HREF, className, locale = DEFAULT_REPORT_LOCALE, }) {
+    return (_jsxs("section", { className: cx("nre", "nre-trace-waterfall", className), children: [data.length === 0 && _jsx("p", { className: "nre-waterfall-empty", children: localeText(locale, "traceWaterfall.empty") }), _jsx("ul", { className: "nre-waterfall", children: data.map((row) => {
+                    const failedSpans = row.spans.filter((span) => span.failed).length;
+                    return (_jsxs("li", { className: "nre-waterfall-row", children: [_jsxs("div", { className: "nre-waterfall-head", children: [_jsx("a", { className: "nre-locator", href: attemptHref(row.locator), children: row.locator }), _jsx("span", { className: "nre-waterfall-eval", children: row.evalId }), _jsx("span", { className: "nre-waterfall-experiment", children: row.experimentId }), _jsx("span", { className: "nre-waterfall-duration", children: row.durationMs === null ? localeText(locale, "traceWaterfall.noTrace") : formatDurationMs(row.durationMs) }), _jsx("span", { className: "nre-waterfall-count", children: countText(locale, "traceWaterfall.spans", row.spans.length) }), failedSpans > 0 && (_jsxs("span", { className: "nre-waterfall-failed", children: ["\u2717 ", countText(locale, "traceWaterfall.failedSpans", failedSpans)] }))] }), row.durationMs !== null && row.spans.length > 0 && (_jsx("div", { className: "nre-waterfall-track", children: row.spans.map((span, i) => (_jsx("span", { className: cx("nre-waterfall-span", `nre-span-${span.kind}`, span.failed && "nre-span-failed"), style: {
+                                        left: pct(span.startOffsetMs, row.durationMs),
+                                        width: `max(${pct(span.durationMs, row.durationMs)}, 0.5%)`,
+                                    }, title: `${span.name} · ${formatDurationMs(span.durationMs)}${span.failed ? " · ✗" : ""}` }, i))) }))] }, row.locator));
+                }) })] }));
+}

package/dist/report/react/index.d.ts

@@ -10,7 +10,12 @@ export { MetricScatter } from "./MetricScatter.tsx";
 export { MetricLine } from "./MetricLine.tsx";
 export { DeltaTable } from "./DeltaTable.tsx";
 export { Scoreboard } from "./Scoreboard.tsx";
-export type { AttemptListItem, AttemptLocator, DeltaData, EvalListItem, ExperimentComparisonData, ExperimentComparisonGroupData, ExperimentListEvalRow, ExperimentListItem, LineData, MatrixData, MetricCell, MetricColumn, ScatterData, ScopeSummaryData, ScopeWarning, ScoreboardData, TableData, VerdictTally, } from "../types.ts";
+export { HeroCard } from "./HeroCard.tsx";
+export { PoweredBy } from "./PoweredBy.tsx";
+export { ScopeWarnings } from "./ScopeWarnings.tsx";
+export { CopyFixPrompt } from "./CopyFixPrompt.tsx";
+export { TraceWaterfall } from "./TraceWaterfall.tsx";
+export type { AttemptListItem, AttemptLocator, CopyFixPromptData, DeltaData, EvalListItem, ExperimentComparisonData, ExperimentComparisonGroupData, ExperimentListEvalRow, ExperimentListItem, HeroData, LineData, MatrixData, MetricCell, MetricColumn, ScatterData, ScopeSummaryData, ScopeWarning, ScoreboardData, TableData, TraceSpanSummary, TraceWaterfallRow, VerdictTally, } from "../types.ts";
 export { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel } from "../locale.ts";
 export type { LocalizedText, ReportLocale } from "../locale.ts";
 export { NRE_PALETTE, colorClassForKey, colorHexForKey, colorIndexForKey, seriesClassForKey } from "./colors.ts";

package/dist/report/react/index.js

@@ -19,6 +19,12 @@ export { MetricScatter } from "./MetricScatter.js";
 export { MetricLine } from "./MetricLine.js";
 export { DeltaTable } from "./DeltaTable.js";
 export { Scoreboard } from "./Scoreboard.js";
+// 站点组件的纯 web 面(data 形态;Hero 是组合组件,只住 niceeval/report)
+export { HeroCard } from "./HeroCard.js";
+export { PoweredBy } from "./PoweredBy.js";
+export { ScopeWarnings } from "./ScopeWarnings.js";
+export { CopyFixPrompt } from "./CopyFixPrompt.js";
+export { TraceWaterfall } from "./TraceWaterfall.js";
 // locale(官方组件 chrome 文案;LocalizedText 的按 locale 解析也用它)
 export { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel } from "../locale.js";
 // 稳定配色(自定义组件想与官方组件同键同色时用;seriesClassForKey 配 CSS 的 --nre-series)

package/dist/report/report.d.ts

@@ -37,11 +37,11 @@ export type HeadTag = {
     children?: string;
 };
 export interface ReportShell {
-    /** 标题:首页 hero 与浏览器标题。页头左端是恒定的 NiceEval 品牌字标,不由 title 覆盖;回退链 def.title → 唯一快照 name → 内置文案「Eval 运行结果 / Eval Results」。 */
+    /** 站点标题:浏览器标题、show 页索引标题行与 `ctx.report.title` 的取值源;`Hero` 组件缺省消费它。回退链 def.title → 唯一快照 name → 内置文案「Eval 运行结果 / Eval Results」。 */
     title?: LocalizedText;
     /** 页头右侧的外部链接,如 GitHub、文档、CI。 */
     links?: ReportLink[];
-    /** 每页页脚的一段文字;省略时不渲染页脚(品牌行恒在 hero 下方,不占页脚)。 */
+    /** 每页页脚的一段文字;省略时不渲染页脚(品牌行归 PoweredBy 组件,不占页脚)。 */
     footer?: LocalizedText;
     /**
      * 注入每页 `<head>` 的结构化标签,在官方与外壳样式之后按声明顺序渲染。
@@ -63,13 +63,27 @@ export interface ReportPage {
     /** 这一页的报告树;ReportDefinition 不是 ReportNode,页装不进外壳。 */
     content: ReportNode;
 }
-/** content / pages 互斥由类型表达,不把非法状态留到运行期。 */
+/** content / pages / extends 三选一由类型表达,不把非法状态留到运行期。 */
 export type ReportDef = ReportShell & ({
+    /** 单页缩写,等价于只含 id `report` 的页列表。 */
     content: ReportNode;
     pages?: never;
+    extends?: never;
 } | {
+    /** 非空页列表;导航按数组顺序显示。 */
     pages: NonEmptyArray<ReportPage>;
     content?: never;
+    extends?: never;
+} | {
+    /**
+     * 在另一份报告上叠外壳:页列表取 base 的页列表;本对象声明的外壳字段整字段覆盖
+     * base 的同名字段,未声明的沿用 base——没有数组拼接、没有深合并。base 是任何
+     * `defineReport` 产物(内建视图或自己别的报告文件的具名导出);合并在
+     * `defineReport` 调用时折叠完成,产物仍是普通 ReportDefinition,可以再被 extends。
+     */
+    extends: ReportDefinition;
+    content?: never;
+    pages?: never;
 });
 /**
  * defineReport 的唯一产物:只作 --report 文件的默认导出,交给宿主装载。
@@ -136,7 +150,9 @@ export interface RenderReportTextOptions extends TextRenderOptions {
 }
 /**
  * text 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→ 树校验 →
- * 遍历渲染 text 面;Scope 有挑选警告时在报告顶部前置一块 "! <message>"。不需要 react-dom。
+ * 遍历渲染 text 面。不需要 react-dom。宿主不在报告树外另设警告通道——挑选警告的呈现件是
+ * `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是作者义务
+ * (docs/feature/reports/architecture.md「Scope 是计算入口」)。
  */
 export declare function renderReportToText(definition: ReportDefinition, ctx: ReportHostContext, options?: RenderReportTextOptions): Promise<string>;
 /** 页索引标题行(show 多页索引 / view 导航共用的解析结果):按 locale 解析的标题字符串。 */
@@ -161,7 +177,7 @@ export interface RenderTreeTextOptions extends TextRenderOptions {
 }
 /**
  * 渲染一页报告树的 text 面(宿主逐页调用;页选择归宿主):
- * resolve(组合展开 + spec 取数)→ validate → render。Scope 有挑选警告时在页顶前置
- * "! <message>" 块——宿主是 warning 的唯一呈现者,组件数据不复制 warning。
+ * resolve(组合展开 + spec 取数)→ validate → render。宿主不在报告树外另设警告通道,
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现(内建报告每页都放它)。
  */
 export declare function renderReportTreeToText(tree: ReportNode, ctx: ReportTreeHostContext, options?: RenderTreeTextOptions): Promise<string>;

package/dist/report/report.js

@@ -1,7 +1,9 @@
 // defineReport:唯一可被宿主装载的产物 —— 一层外壳(标题、外链、页脚、head 标签、脚本、样式)加
 // 非空页列表;单页与多页不是两种机制,页数只是列表长度(docs/feature/reports/library/shell.md)。
 // 入参有两级缩写,各有精确展开:树入参 ≡ { content: 树 } ≡ pages: [{ id: "report",
-// title: 内置页名, content: 树 }]。`content` 与 `pages` 恰好声明一个,没有隐式默认。
+// title: 内置页名, content: 树 }]。`content` / `pages` / `extends` 恰好声明一个,没有隐式默认;
+// `extends` 在另一份报告上叠外壳——页归 base、外壳逐字段覆盖,合并在调用时折叠完成,
+// 宿主装载看到的永远是已折叠的普通产物。
 //
 // renderReportToText 是 text 宿主(show)的装载入口;web 宿主(view)的
 // renderReportToStaticHtml 在 ./web.ts(那一侧才 import react-dom)。管线以页为单位执行:
@@ -13,7 +15,7 @@ const REPORT_DEFINITION = Symbol.for("niceeval.report.definition");
 export const DEFAULT_PAGE_ID = "report";
 const DEFAULT_PAGE_TITLE = { en: "Report", "zh-CN": "报告" };
 // ───────────────────────── 装载规范化与静态校验 ─────────────────────────
-const CONTENT_NEXT_STEP = 'To render the built-in report content, write content: <ExperimentComparison /> (imported from "niceeval/report").';
+const EXTENDS_NEXT_STEP = 'To render the built-in report, write extends: standard (import { standard } from "niceeval/report/built-in").';
 function isReportNodeInput(value) {
     if (value === null || value === undefined || typeof value === "boolean")
         return true;
@@ -31,7 +33,8 @@ function assertNotDefinition(value, where) {
         value.kind === "report" &&
         value[REPORT_DEFINITION] === true) {
         throw new Error(`${where} received a defineReport(...) product, but a report definition is not a report node — the shell cannot nest. ` +
-            "Pass the page's tree or component here, and export the defineReport product only as the file's default export.");
+            "Pass the page's tree or component here. To layer a shell over another report, write defineReport({ extends: base, … }); " +
+            "otherwise export the defineReport product as the file's default export.");
     }
 }
 function assertLocalizedText(value, where) {
@@ -155,26 +158,40 @@ export function defineReport(input) {
         ? { content: input }
         : input;
     if (typeof def !== "object" || def === null) {
-        throw new Error("defineReport expects a report tree or a config object ({ title?, links?, footer?, head?, scripts?, styles?, content | pages }). " +
-            CONTENT_NEXT_STEP);
+        throw new Error("defineReport expects a report tree or a config object ({ title?, links?, footer?, head?, scripts?, styles?, content | pages | extends }). " +
+            EXTENDS_NEXT_STEP);
     }
     const hasContent = "content" in def && def.content !== undefined;
     const hasPages = "pages" in def && def.pages !== undefined;
-    if (hasContent && hasPages) {
-        throw new Error(`defineReport got both "content" and "pages" — declare exactly one. Keep "pages" for a multi-page report, or keep a single tree in "content". ${CONTENT_NEXT_STEP}`);
+    const hasExtends = "extends" in def && def.extends !== undefined;
+    const declared = [hasContent && '"content"', hasPages && '"pages"', hasExtends && '"extends"'].filter((name) => typeof name === "string");
+    if (declared.length > 1) {
+        throw new Error(`defineReport got ${declared.join(" and ")} — declare exactly one of "content" (a single tree), "pages" (a multi-page report), or "extends" (another report plus this shell). ${EXTENDS_NEXT_STEP}`);
     }
-    if (!hasContent && !hasPages) {
-        throw new Error(`defineReport got neither "content" nor "pages" — declare exactly one; omission is not a meaningful value, the file must show what renders. ${CONTENT_NEXT_STEP}`);
+    if (declared.length === 0) {
+        throw new Error(`defineReport got none of "content", "pages" or "extends" — declare exactly one; omission is not a meaningful value, the file must show what renders. ${EXTENDS_NEXT_STEP}`);
     }
+    // extends:报告级复用的唯一位置。页归 base,本对象只贡献外壳;base 已经过 defineReport
+    // 校验,页不重验。
+    let base;
     let pages;
-    if (hasContent) {
+    if (hasExtends) {
+        const candidate = def.extends;
+        if (!isReportDefinition(candidate)) {
+            throw new Error('defineReport "extends" must be a defineReport(...) product — the base report whose pages this report inherits. ' +
+                EXTENDS_NEXT_STEP);
+        }
+        base = candidate;
+        pages = base.pages;
+    }
+    else if (hasContent) {
         assertNotDefinition(def.content, 'defineReport "content"');
         pages = [{ id: DEFAULT_PAGE_ID, title: DEFAULT_PAGE_TITLE, content: def.content }];
     }
     else {
         const raw = def.pages;
         if (!Array.isArray(raw) || raw.length === 0) {
-            throw new Error(`defineReport "pages" must be a non-empty array of { id, title, content }. ${CONTENT_NEXT_STEP}`);
+            throw new Error(`defineReport "pages" must be a non-empty array of { id, title, content }. ${EXTENDS_NEXT_STEP}`);
         }
         const seen = new Set();
         for (const page of raw) {
@@ -194,34 +211,43 @@ export function defineReport(input) {
         assertLocalizedText(def.title, "defineReport title");
     if (def.footer !== undefined)
         assertLocalizedText(def.footer, "defineReport footer");
-    const links = def.links ?? [];
-    if (!Array.isArray(links))
-        throw new Error("defineReport links must be an array of { label, href }.");
-    for (const link of links) {
-        assertLocalizedText(link?.label, "defineReport link label");
-        if (typeof link?.href !== "string" || link.href.length === 0) {
-            throw new Error("defineReport link href must be a non-empty string URL.");
-        }
-        // icon 唯一合法形状是 { svg: string }(无类型 JS 传组件 / ReactNode / 裸字符串都在装载期拒绝):
-        // 外壳声明经序列化边界进前端,ReactNode 过不去,可序列化是外壳契约的一部分。
-        const icon = link.icon;
-        if (icon !== undefined) {
-            const svg = icon?.svg;
-            if (typeof icon !== "object" || icon === null || typeof svg !== "string" || svg.length === 0) {
-                throw new Error('defineReport link "icon" must be { svg: string } — an inline SVG string rendered before the label. ' +
-                    "Components and React nodes are not accepted: the shell declaration crosses a serialization boundary. " +
-                    'Write e.g. icon: { svg: "<svg …>…</svg>" }.');
+    // 外壳合并:声明即整字段覆盖,未声明沿用 base(base 的字段已规范化,不重验)。
+    let links;
+    if (def.links !== undefined) {
+        if (!Array.isArray(def.links))
+            throw new Error("defineReport links must be an array of { label, href }.");
+        for (const link of def.links) {
+            assertLocalizedText(link?.label, "defineReport link label");
+            if (typeof link?.href !== "string" || link.href.length === 0) {
+                throw new Error("defineReport link href must be a non-empty string URL.");
+            }
+            // icon 唯一合法形状是 { svg: string }(无类型 JS 传组件 / ReactNode / 裸字符串都在装载期拒绝):
+            // 外壳声明经序列化边界进前端,ReactNode 过不去,可序列化是外壳契约的一部分。
+            const icon = link.icon;
+            if (icon !== undefined) {
+                const svg = icon?.svg;
+                if (typeof icon !== "object" || icon === null || typeof svg !== "string" || svg.length === 0) {
+                    throw new Error('defineReport link "icon" must be { svg: string } — an inline SVG string rendered before the label. ' +
+                        "Components and React nodes are not accepted: the shell declaration crosses a serialization boundary. " +
+                        'Write e.g. icon: { svg: "<svg …>…</svg>" }.');
+                }
             }
         }
+        links = def.links;
     }
+    else {
+        links = base?.links ?? [];
+    }
+    const title = def.title !== undefined ? def.title : base?.title;
+    const footer = def.footer !== undefined ? def.footer : base?.footer;
     const definition = {
         kind: "report",
-        ...(def.title !== undefined ? { title: def.title } : {}),
+        ...(title !== undefined ? { title } : {}),
         links: [...links],
-        ...(def.footer !== undefined ? { footer: def.footer } : {}),
-        head: assertHeadTags(def.head),
-        scripts: assertAssets(def.scripts, "scripts"),
-        styles: assertAssets(def.styles, "styles"),
+        ...(footer !== undefined ? { footer } : {}),
+        head: def.head !== undefined ? assertHeadTags(def.head) : [...(base?.head ?? [])],
+        scripts: def.scripts !== undefined ? assertAssets(def.scripts, "scripts") : [...(base?.scripts ?? [])],
+        styles: def.styles !== undefined ? assertAssets(def.styles, "styles") : [...(base?.styles ?? [])],
         pages: pages,
     };
     Object.defineProperty(definition, REPORT_DEFINITION, { value: true });
@@ -283,17 +309,11 @@ export function pickReportPage(definition, pageId) {
     }
     return page;
 }
-/**
- * 挑选警告的 text 形态:每条渲染好的 message 前缀 "! ",一行一条。宿主级前置块——
- * 宿主是 warning 的唯一呈现者,组件数据不复制 warning;裸跑 / --report 都在报告顶上
- * 如实报残缺,不静默(docs/feature/reports/architecture.md「Scope 是计算入口」)。
- */
-function renderScopeWarningsText(scope, _locale) {
-    return scope.warnings.map((w) => `! ${w.message}`).join("\n");
-}
 /**
  * text 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→ 树校验 →
- * 遍历渲染 text 面;Scope 有挑选警告时在报告顶部前置一块 "! <message>"。不需要 react-dom。
+ * 遍历渲染 text 面。不需要 react-dom。宿主不在报告树外另设警告通道——挑选警告的呈现件是
+ * `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是作者义务
+ * (docs/feature/reports/architecture.md「Scope 是计算入口」)。
  */
 export async function renderReportToText(definition, ctx, options) {
     const page = pickReportPage(definition, options?.pageId);
@@ -305,11 +325,7 @@ export async function renderReportToText(definition, ctx, options) {
         memo: new ResolveMemo(),
     });
     validateReportTree(resolved);
-    const textCtx = createTextContext(options);
-    const body = renderNodeToText(resolved, textCtx);
-    return ctx.scope.warnings.length > 0
-        ? [renderScopeWarningsText(ctx.scope, textCtx.locale), body].join("\n\n")
-        : body;
+    return renderNodeToText(resolved, createTextContext(options));
 }
 /** 页索引标题行(show 多页索引 / view 导航共用的解析结果):按 locale 解析的标题字符串。 */
 export function reportTitleText(definition, scope, locale) {
@@ -333,8 +349,8 @@ function experimentCommandFor(ctx) {
 }
 /**
  * 渲染一页报告树的 text 面(宿主逐页调用;页选择归宿主):
- * resolve(组合展开 + spec 取数)→ validate → render。Scope 有挑选警告时在页顶前置
- * "! <message>" 块——宿主是 warning 的唯一呈现者,组件数据不复制 warning。
+ * resolve(组合展开 + spec 取数)→ validate → render。宿主不在报告树外另设警告通道,
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现(内建报告每页都放它)。
  */
 export async function renderReportTreeToText(tree, ctx, options) {
     const resolved = await resolveReportTree(tree, {
@@ -350,8 +366,5 @@ export async function renderReportTreeToText(tree, ctx, options) {
             ? { experimentCommand: experimentCommandFor(options.commandContext) }
             : {}),
     });
-    const body = renderNodeToText(resolved, textCtx);
-    return ctx.scope.warnings.length > 0
-        ? [renderScopeWarningsText(ctx.scope, textCtx.locale), body].join("\n\n")
-        : body;
+    return renderNodeToText(resolved, textCtx);
 }

package/dist/report/scope-warnings.d.ts

@@ -0,0 +1,28 @@
+import type { ScopeWarning } from "../results/types.ts";
+import { type ReportLocale } from "./locale.ts";
+/** kind 表登记的类别:integrity(选中集合的分母可能不对)组排在 freshness(可能过期)之前。 */
+export type WarningCategory = "integrity" | "freshness";
+export interface ScopeWarningGroup {
+    category: WarningCategory;
+    /** 实验组为 experimentId;kind 组为登记的组头文案(含条数);未登记 kind 用 kind 原文。 */
+    title: string;
+    /** 每条警告一枚、与 warnings 同序;未登记徽标模板的成员不出徽标。 */
+    badges: readonly {
+        kind: string;
+        text: string;
+    }[];
+    /** 组内命令去重后恰一条时归组头(复制即推进整组);多条或零条为 null,命令随明细逐条走。 */
+    headCommand: string | null;
+    /** 原始条目(明细层,message 单源)。 */
+    warnings: readonly ScopeWarning[];
+}
+export interface GroupedScopeWarnings {
+    /** 分类计数汇总行,任何组数下都产出;web 面用作外层折叠块的 <summary>,text 面只在多组时打印。 */
+    summary: string;
+    groups: readonly ScopeWarningGroup[];
+    /** 警告总条数 ≤ 3 时组级明细默认展开(web 面第二层 <details> 的 open;阈值是行为契约,无开关)。 */
+    detailsOpen: boolean;
+}
+/** 明细折叠块的标签(「N 条原始警告」)。 */
+export declare function warningDetailsLabel(locale: ReportLocale, n: number): string;
+export declare function groupScopeWarnings(input: readonly ScopeWarning[], locale: ReportLocale): GroupedScopeWarnings;