niceeval 0.8.1 → 0.9.0

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;

package/dist/report/scope-warnings.js

@@ -0,0 +1,101 @@
+// ScopeWarnings 的聚合层:把 Scope 警告按「下一步动作」组织成组,web / text 两面共用
+// (docs/feature/reports/library/site-components.md「聚合轴是动作,不是发生顺序」)。
+// message 是完整叙述的单源,这里只组织、不改写;徽标 / 组头文案按 kind 表登记的模板
+// (docs/feature/results/library.md「警告 kind 全集」)经 locale 词典渲染,未登记的 kind
+// 回退为单独成组、逐条 message 原样。
+import { gapParts } from "../results/select.js";
+import { localeText } from "./locale.js";
+const CATEGORY = {
+    "partial-coverage": "integrity",
+    "unfinished-snapshot": "integrity",
+    "unreadable-snapshot": "integrity",
+    "stale-snapshot": "freshness",
+};
+/** 实验作用域且登记了徽标模板的 kind 才进实验组;其余(含未登记 kind)按 kind 聚合。 */
+const EXPERIMENT_KINDS = new Set(["partial-coverage", "stale-snapshot", "unfinished-snapshot"]);
+function pluralText(locale, base, n) {
+    return localeText(locale, `${base}.${n === 1 ? "one" : "other"}`, { n });
+}
+/** 明细折叠块的标签(「N 条原始警告」)。 */
+export function warningDetailsLabel(locale, n) {
+    return pluralText(locale, "warnings.details", n);
+}
+function gapText(locale, fromIso, toIso) {
+    const { n, unit } = gapParts(fromIso, toIso);
+    return localeText(locale, `warnings.gap.${unit}.${n === 1 ? "one" : "other"}`, { n });
+}
+function badgeText(w, locale) {
+    switch (w.kind) {
+        case "partial-coverage":
+            return localeText(locale, "warnings.badge.partialCoverage", {
+                covered: String(w.covered),
+                total: String(w.total),
+            });
+        case "stale-snapshot":
+            return localeText(locale, "warnings.badge.staleSnapshot", {
+                gap: gapText(locale, String(w.startedAt), String(w.latestStartedAt)),
+            });
+        case "unfinished-snapshot":
+            return localeText(locale, "warnings.badge.unfinishedSnapshot");
+        default:
+            return null;
+    }
+}
+/** 组内命令去重:恰一条时它就是「复制即推进整组」的组头命令。 */
+function dedupeCommand(members) {
+    const commands = new Set(members.map((w) => w.command).filter((c) => typeof c === "string" && c !== ""));
+    return commands.size === 1 ? [...commands][0] : null;
+}
+function groupCategory(members) {
+    return members.some((w) => (CATEGORY[w.kind] ?? "integrity") === "integrity") ? "integrity" : "freshness";
+}
+export function groupScopeWarnings(input, locale) {
+    const warnings = input;
+    const byExperiment = new Map();
+    const byKind = new Map();
+    for (const w of warnings) {
+        if (EXPERIMENT_KINDS.has(w.kind) && typeof w.experimentId === "string") {
+            const members = byExperiment.get(w.experimentId) ?? [];
+            members.push(w);
+            byExperiment.set(w.experimentId, members);
+        }
+        else {
+            const members = byKind.get(w.kind) ?? [];
+            members.push(w);
+            byKind.set(w.kind, members);
+        }
+    }
+    const groups = [];
+    for (const [experimentId, members] of byExperiment) {
+        groups.push({
+            category: groupCategory(members),
+            title: experimentId,
+            badges: members
+                .map((w) => ({ kind: w.kind, text: badgeText(w, locale) }))
+                .filter((b) => b.text !== null),
+            headCommand: dedupeCommand(members),
+            warnings: members,
+        });
+    }
+    for (const [kind, members] of byKind) {
+        groups.push({
+            category: CATEGORY[kind] ?? "integrity",
+            title: kind === "unreadable-snapshot" ? pluralText(locale, "warnings.group.unreadableSnapshot", members.length) : kind,
+            badges: [],
+            headCommand: dedupeCommand(members),
+            warnings: members,
+        });
+    }
+    // 稳定排序:integrity 在前,同类别保持首次出现顺序。
+    const rank = (c) => (c === "integrity" ? 0 : 1);
+    groups.sort((a, b) => rank(a.category) - rank(b.category));
+    const parts = [];
+    if (byExperiment.size > 0)
+        parts.push(pluralText(locale, "warnings.summary.experiments", byExperiment.size));
+    for (const [kind, members] of byKind) {
+        parts.push(kind === "unreadable-snapshot"
+            ? pluralText(locale, "warnings.group.unreadableSnapshot", members.length)
+            : `${kind} ×${members.length}`);
+    }
+    return { summary: parts.join(" · "), groups, detailsOpen: warnings.length <= 3 };
+}

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

@@ -1,4 +1,5 @@
-import type { AttemptListItem, DeltaData, EvalListItem, ExperimentComparisonData, ExperimentListItem, LineData, MatrixData, MetricCell, ScatterData, ScopeSummaryData, ScoreboardData, TableData, VerdictTally } from "../types.ts";
+import type { AttemptListItem, DeltaData, EvalListItem, ExperimentComparisonData, ExperimentListItem, HeroData, LineData, MatrixData, MetricCell, ScatterData, ScopeSummaryData, ScopeWarning, ScoreboardData, TableData, TraceWaterfallRow, VerdictTally } from "../types.ts";
+import type { LocalizedText } from "../locale.ts";
 import type { TextContext } from "../tree.ts";
 import { type ReportLocale } from "../locale.ts";
 /** 格子的文本形态:缺数据 —,覆盖不全带 samples/total 角标;display 按 locale 解析。 */
@@ -25,3 +26,20 @@ export declare function deltaText(data: DeltaData, ctx: TextContext): string;
 export declare function experimentListText(items: readonly ExperimentListItem[], ctx: TextContext, relativeTo?: string): string;
 export declare function evalListText(items: readonly EvalListItem[], ctx: TextContext): string;
 export declare function attemptListText(items: readonly AttemptListItem[], total: number | undefined, ctx: TextContext): string;
+/**
+ * HeroCard 的 text 面:标题行 + meta 行(最后运行时间;空范围为内置「暂无运行」文案;
+ * 多快照时标注合成来源),不含品牌行(品牌行是纯 web 件,text 面零输出)。
+ */
+export declare function heroCardText(title: LocalizedText, data: HeroData, ctx: TextContext): string;
+/**
+ * ScopeWarnings 的 text 面:按动作聚合(../scope-warnings.ts,与 web 面共用),同构但不折叠——
+ * 多组时首行 "! <分类计数汇总>";每组一行组头 "! <标题> — <徽标> → <组头命令>",其下缩进
+ * 逐条原样打印 message(已以下一步收尾,不截断掉尾段)。空警告集零输出。
+ */
+export declare function scopeWarningsText(warnings: readonly ScopeWarning[], ctx: TextContext): string;
+/**
+ * TraceWaterfall 的 text 面:每 attempt 一行——locator、总耗时(缺 trace 如实显示缺失)、
+ * 顶层 span 计数与失败标记,行尾是可复制的 `--timing` 下钻命令(经宿主注入的
+ * attemptCommand 通道拼出,携带宿主上下文)。attempt 有选择器,索引终结于可执行命令。
+ */
+export declare function traceWaterfallText(rows: readonly TraceWaterfallRow[], ctx: TextContext): string;

package/dist/report/text/faces.js

@@ -3,6 +3,7 @@
 // 零 react、零 IO、纯同步 —— 这是 text 宿主不需要 react-dom 的那一半。
 // chrome 文案(注脚、verdict 词、截断提示)经 ctx.locale 查 locale 字典;
 // 数据 display 是 LocalizedText,按 LocalizedText 回退规则取值。
+import { groupScopeWarnings } from "../scope-warnings.js";
 import { experimentDisplayName, fitFailureSummary, formatDurationMs, formatMetricValue, formatPlainNumber, formatUSD, verdictMark, } from "../format.js";
 import { countText, localeText, resolveLocalizedText, resolveMetricLabel, } from "../locale.js";
 import { indentBlock, padDisplay, stringWidth, textBar, wrapDisplay } from "./layout.js";
@@ -608,3 +609,63 @@ export function attemptListText(items, total, ctx) {
         blocks.push(localeText(locale, "attemptList.truncatedText", { n: remaining }));
     return blocks.join("\n\n");
 }
+// ───────────────────────── 站点组件(HeroCard / ScopeWarnings / TraceWaterfall)─────────────────────────
+/**
+ * HeroCard 的 text 面:标题行 + meta 行(最后运行时间;空范围为内置「暂无运行」文案;
+ * 多快照时标注合成来源),不含品牌行(品牌行是纯 web 件,text 面零输出)。
+ */
+export function heroCardText(title, data, ctx) {
+    const locale = ctx.locale;
+    const meta = data.latestStartedAt === null
+        ? localeText(locale, "hero.noRuns")
+        : [
+            localeText(locale, "hero.lastRun", { time: formatDateTimeMinute(data.latestStartedAt) }),
+            ...(data.snapshots > 1 ? [localeText(locale, "hero.composedSnapshots", { n: data.snapshots })] : []),
+        ].join(" · ");
+    return `${resolveLocalizedText(title, locale)}\n${meta}`;
+}
+/**
+ * ScopeWarnings 的 text 面:按动作聚合(../scope-warnings.ts,与 web 面共用),同构但不折叠——
+ * 多组时首行 "! <分类计数汇总>";每组一行组头 "! <标题> — <徽标> → <组头命令>",其下缩进
+ * 逐条原样打印 message(已以下一步收尾,不截断掉尾段)。空警告集零输出。
+ */
+export function scopeWarningsText(warnings, ctx) {
+    if (warnings.length === 0)
+        return "";
+    const { summary, groups } = groupScopeWarnings(warnings, ctx.locale);
+    const lines = [];
+    // 汇总行只在多组时打印;单组时组头即汇总,不另起一行(web 面则恒以汇总行作外层 <summary>)。
+    if (groups.length > 1)
+        lines.push(`! ${summary}`);
+    for (const group of groups) {
+        const badges = group.badges.length > 0 ? ` — ${group.badges.map((b) => b.text).join(" · ")}` : "";
+        const command = group.headCommand !== null ? ` → ${group.headCommand}` : "";
+        lines.push(`! ${group.title}${badges}${command}`);
+        for (const w of group.warnings)
+            lines.push(`!   ${w.message}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * TraceWaterfall 的 text 面:每 attempt 一行——locator、总耗时(缺 trace 如实显示缺失)、
+ * 顶层 span 计数与失败标记,行尾是可复制的 `--timing` 下钻命令(经宿主注入的
+ * attemptCommand 通道拼出,携带宿主上下文)。attempt 有选择器,索引终结于可执行命令。
+ */
+export function traceWaterfallText(rows, ctx) {
+    const locale = ctx.locale;
+    if (rows.length === 0)
+        return localeText(locale, "traceWaterfall.empty");
+    return rows
+        .map((row) => {
+        const failedSpans = row.spans.filter((span) => span.failed).length;
+        const parts = [
+            row.locator,
+            row.evalId,
+            row.durationMs === null ? localeText(locale, "traceWaterfall.noTrace") : formatDurationMs(row.durationMs),
+            countText(locale, "traceWaterfall.spans", row.spans.length),
+            ...(failedSpans > 0 ? [`✗ ${countText(locale, "traceWaterfall.failedSpans", failedSpans)}`] : []),
+        ];
+        return `${parts.join(" · ")}   ${ctx.attemptCommand(row.locator)} --timing`;
+    })
+        .join("\n");
+}

package/dist/report/tree.js

@@ -187,7 +187,12 @@ async function resolveNode(node, state, path) {
         return node;
     }
     if (Array.isArray(node)) {
-        return Promise.all(node.map((child) => resolveNode(child, state, path)));
+        const resolved = await Promise.all(node.map((child) => resolveNode(child, state, path)));
+        // resolve 重建的 children 数组对 React 是动态列表(JSX 静态 children 的免 key 待遇随重建
+        // 丢失);声明序即身份,给缺 key 的元素补声明位 key,免得 web 面渲染刷 key 警告。
+        return resolved.map((child, i) => isReportElement(child) && (child.key === undefined || child.key === null)
+            ? { ...child, key: `.nre-${i}` }
+            : child);
     }
     if (!isReportElement(node))
         return node;

package/dist/report/types.d.ts

@@ -275,6 +275,51 @@ export interface ScopeSummaryData {
     /** costUSD 按 attempt 求和;缺失成本不伪造为 0。 */
     totalCostUSD: MetricCell;
 }
+/**
+ * `HeroCard` 的数据(docs/feature/reports/library/site-components.md):站点标题区的
+ * 运行 meta——最后运行时间与快照合成来源。标题不在 data 里,它是站点声明与 Scope 的合成物,
+ * 经 `HeroCardProps.title` 传入。
+ */
+export interface HeroData {
+    /** Scope 中最新快照的开始时间;空 Scope 为 null,不编造当前时间。 */
+    latestStartedAt: string | null;
+    /** 贡献当前水位的快照数;大于 1 时 web 面标注「由 N 次运行合成」。 */
+    snapshots: number;
+}
+/**
+ * `CopyFixPrompt` 的数据:resolve 期算好的修复 prompt 全文与参与的失败数
+ * (docs/feature/reports/library/site-components.md)。
+ */
+export interface CopyFixPromptData {
+    /** 修复 prompt 全文;失败逐条含 eval id、主失败摘要与 attempt 下钻命令。 */
+    prompt: string;
+    /** 参与 prompt 的失败 attempt 数(verdict 为 failed / errored)。 */
+    failures: number;
+}
+/** `TraceWaterfall` 一行里的一个顶层 span 摘要(canonical OTel 字段归一后的形态)。 */
+export interface TraceSpanSummary {
+    name: string;
+    /** 归一后的语义角色;turn 归入 agent,未识别落 other。 */
+    kind: "agent" | "model" | "tool" | "other";
+    /** 相对该 attempt trace 起点的偏移(毫秒)。 */
+    startOffsetMs: number;
+    durationMs: number;
+    /** span status 为 error 时 true(web 面失败标记的来源)。 */
+    failed: boolean;
+}
+/**
+ * `TraceWaterfall` 一行 = 一次 attempt 的执行时间瀑布摘要。只画被测 agent 的原始 span
+ * (trace.json);runner 生命周期节点(`result.phases`)不进瀑布,组合视图归 attempt 详情。
+ */
+export interface TraceWaterfallRow {
+    experimentId: string;
+    evalId: string;
+    locator: AttemptLocator;
+    /** trace.json 缺失或为空时 null;行照常出现,证据位置如实显示缺失,不猜值。 */
+    durationMs: number | null;
+    /** 顶层 span 摘要,按 startOffsetMs 升序。 */
+    spans: readonly TraceSpanSummary[];
+}
 /** 一个可比组的数据;三个子块都只消费本组快照,不能含其它父目录的引用。 */
 export interface ExperimentComparisonGroupData {
     /** experiment id 的完整父路径;根目录 experiment 使用完整 id。 */

package/dist/report/web.d.ts

@@ -12,14 +12,15 @@ export interface StaticHtmlOptions {
 }
 /**
  * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
- * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面;Scope 有挑选警告时在报告顶部前置
- * 一块警告 HTML(宿主是 warning 的唯一呈现者,组件数据不复制 warning)。
+ * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外另设警告通道——
+ * 挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是
+ * 作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
  */
 export declare function renderReportToStaticHtml(definition: ReportDefinition, ctx: ReportHostContext, options?: StaticHtmlOptions): Promise<string>;
 /**
  * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
- * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
- * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
+ * ctx.report 是宿主规范化后的声明。
  */
 export declare function renderReportTreeToStaticHtml(tree: import("./tree.ts").ReportNode, ctx: {
     scope: Scope;

package/dist/report/web.js

@@ -1,26 +1,15 @@
 // web 宿主(view --report)的装载入口:同一棵树走 web 面,renderToStaticMarkup 吐静态
 // HTML 烘进查看器的报告槽。只有这一侧真正 import react-dom(import 边界即运行时边界),
 // 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
-import * as React from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { resolveReportTree, runWithWebContext, validateReportTree, ResolveMemo, } from "./tree.js";
 import { DEFAULT_REPORT_LOCALE } from "./locale.js";
 import { buildReportMeta, pickReportPage } from "./report.js";
-/**
- * 挑选警告的 HTML 形态:宿主级前置块(`.nre nre-report-warnings` 外壳内一个
- * `ul.nre-warnings` + `li.nre-warning[data-kind]`,复用 styles.css 已有样式)。
- * 带 `command` 的警告把命令渲染为可复制块(`.nre-warning-command`);无 command 的
- * 只显示 message,不硬造动作。经 renderToStaticMarkup 走 React,文本自动转义。
- */
-function renderScopeWarningsHtml(scope) {
-    return renderToStaticMarkup(React.createElement("div", { className: "nre nre-report-warnings" }, React.createElement("ul", { className: "nre-warnings" }, scope.warnings.map((w, i) => React.createElement("li", { key: i, className: "nre-warning", "data-kind": w.kind }, w.message, "command" in w && w.command
-        ? React.createElement("code", { className: "nre-warning-command", "data-nre-copy": w.command }, w.command)
-        : null)))));
-}
 /**
  * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
- * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面;Scope 有挑选警告时在报告顶部前置
- * 一块警告 HTML(宿主是 warning 的唯一呈现者,组件数据不复制 warning)。
+ * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外另设警告通道——
+ * 挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是
+ * 作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
  */
 export async function renderReportToStaticHtml(definition, ctx, options) {
     const page = pickReportPage(definition, options?.pageId);
@@ -36,14 +25,12 @@ export async function renderReportToStaticHtml(definition, ctx, options) {
         attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
         locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
     };
-    const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
-    const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
-    return warnings + body;
+    return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
 }
 /**
  * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
- * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
- * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
+ * ctx.report 是宿主规范化后的声明。
  */
 export async function renderReportTreeToStaticHtml(tree, ctx, options) {
     const resolved = await resolveReportTree(tree, {
@@ -57,7 +44,5 @@ export async function renderReportTreeToStaticHtml(tree, ctx, options) {
         attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
         locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
     };
-    const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
-    const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
-    return warnings + body;
+    return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
 }

package/dist/results/select.d.ts

@@ -1,7 +1,12 @@
 import type { AttemptHandle, DedupeWarning, Experiment, Results, Scope, ScopeWarning, Snapshot } from "./types.ts";
 import type { ExperimentRunInfo, JsonValue } from "../types.ts";
-/** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
-export declare function selectLatest(experiments: Experiment[], opts?: {
+/**
+ * Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。
+ * 收整个 `Results` 而不是裸 `Experiment[]`,是为了同时取 `skipped` / `root` 生成
+ * `unreadable-snapshot` 警告(非实验作用域,不受 `opts.experiments` 过滤 —— 那些落盘
+ * 本来就没能解析出 experimentId,没有前缀可过滤)。
+ */
+export declare function selectLatest(results: Pick<Results, "experiments" | "skipped" | "root">, opts?: {
     experiments?: string | string[];
 }): Scope;
 /** selectCurrentResults 的范围输入:experiment id 前缀与 eval id 前缀,都可缺省。 */
@@ -65,3 +70,11 @@ export declare function dedupeAttempts(attempts: AttemptHandle[]): {
 export declare function isNewerSnapshot(a: Snapshot, b: Snapshot): boolean;
 /** experiment id 分段前缀过滤(--experiment / latest({ experiments }) 同一语义);包内使用,不进公共 barrel。 */
 export declare function filterExperiments(experiments: Experiment[], filter?: string | string[]): Experiment[];
+/**
+ * stale 警告的人话时距:选粒度最大的单位,四舍五入。结构化形态是单源——message 的英文时距
+ * 与 ScopeWarnings 徽标的本地化时距都从这里出,阈值不写两份。
+ */
+export declare function gapParts(fromIso: string, toIso: string): {
+    n: number;
+    unit: "second" | "minute" | "hour" | "day";
+};