niceeval 0.9.0 → 0.10.0

package/dist/report/{react → components/site-components}/TraceWaterfall.d.ts

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

package/dist/report/{react → components/site-components}/TraceWaterfall.js

@@ -1,7 +1,7 @@
 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}`;
+import { DEFAULT_REPORT_LOCALE, countText, localeText } from "../../model/locale.js";
+import { formatDurationMs } from "../../model/format.js";
+import { cx } from "../shared.js";
 function pct(part, total) {
     if (total <= 0)
         return "0%";
@@ -11,10 +11,10 @@ function pct(part, total) {
  * 执行时间瀑布(纯 web 渲染面):嵌入自有 React 页面时配合 `traceWaterfallData()` 使用。
  * 只画被测 agent 的原始 span;runner 生命周期节点不在 data 里,组合视图归 attempt 详情。
  */
-export function TraceWaterfall({ data, attemptHref = DEFAULT_ATTEMPT_HREF, className, locale = DEFAULT_REPORT_LOCALE, }) {
+export function TraceWaterfall({ data, attemptHref, 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: {
+                    return (_jsxs("li", { className: "nre-waterfall-row", children: [_jsxs("div", { className: "nre-waterfall-head", children: [attemptHref ? (_jsx("a", { className: "nre-locator", href: attemptHref(row.locator), children: row.locator })) : (_jsx("span", { className: "nre-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/components/site-components/compute.d.ts

@@ -0,0 +1,28 @@
+import type { CopyFixPromptData, HeroData, ReportInput, ScopeWarning, TraceWaterfallRow } from "../../model/types.ts";
+/**
+ * `heroData(input)`:站点标题区的运行 meta——`latestStartedAt` 取范围内最新快照的开始时间
+ * (空范围为 null,不编造当前时间),`snapshots` 计贡献当前水位的快照数
+ * (docs/feature/reports/library/site-components.md「HeroCard」)。
+ */
+export declare function heroData(input: ReportInput): Promise<HeroData>;
+/**
+ * `scopeWarningsData(input)`:Scope 携带的挑选警告原样透出;`input` 是裸 `Snapshot[]` 时
+ * 没有挑选过程、没有警告,返回空数组,也如实
+ * (docs/feature/reports/library/site-components.md「ScopeWarnings」)。
+ */
+export declare function scopeWarningsData(input: ReportInput): Promise<readonly ScopeWarning[]>;
+/**
+ * `copyFixPromptData(input)`:把范围内全部失败(verdict 为 failed / errored 的 attempt)
+ * 整理成一段可交给 coding agent 的修复 prompt——逐失败含 eval id、主失败摘要与 attempt
+ * 下钻命令(`niceeval show @<locator>`)。prompt 面向 agent,固定英文
+ * (docs/feature/reports/library/site-components.md「CopyFixPrompt」)。
+ */
+export declare function copyFixPromptData(input: ReportInput): Promise<CopyFixPromptData>;
+/**
+ * `traceWaterfallData(input)`:每个 attempt 一行的执行时间瀑布摘要。span 事实只来自
+ * trace artifact(经 AttemptHandle 懒加载的 canonical OTel span);runner 生命周期节点
+ * (`result.phases`)不进瀑布。行内只汇总顶层 span(parentSpanId 缺失或不在本 trace 内),
+ * 按 startOffsetMs 升序;trace 缺失或为空时 `durationMs` 为 null、行照常出现
+ * (docs/feature/reports/library/site-components.md「TraceWaterfall」)。
+ */
+export declare function traceWaterfallData(input: ReportInput): Promise<readonly TraceWaterfallRow[]>;

package/dist/report/components/site-components/compute.js

@@ -0,0 +1,132 @@
+// 计算函数(*Data):ReportInput → 一份组件数据。站点组件族(Hero / ScopeWarnings /
+// CopyFixPrompt / TraceWaterfall)的 *Data 都住在这里
+// (docs/feature/reports/library/site-components.md)。
+//
+// 共同约定(docs/feature/reports/architecture.md「指标聚合不变量」):
+// - 第一参收 ReportInput = Scope | readonly Snapshot[];warnings 不进组件数据(宿主统一显示);
+// - null ≠ 0:缺数据不编数。
+import { collectItems, evalIdOf, experimentIdOf, locatorOf, resolveInput } from "../../model/aggregate.js";
+import { attemptListData } from "../entity-lists/compute.js";
+// ───────────────────────── 站点组件的计算函数(hero / warnings / fix prompt / trace)─────────────────────────
+/**
+ * `heroData(input)`:站点标题区的运行 meta——`latestStartedAt` 取范围内最新快照的开始时间
+ * (空范围为 null,不编造当前时间),`snapshots` 计贡献当前水位的快照数
+ * (docs/feature/reports/library/site-components.md「HeroCard」)。
+ */
+export async function heroData(input) {
+    const { snapshots } = resolveInput(input);
+    let latest = null;
+    for (const snapshot of snapshots) {
+        if (latest === null || snapshot.startedAt > latest)
+            latest = snapshot.startedAt;
+    }
+    return { latestStartedAt: latest, snapshots: snapshots.length };
+}
+/**
+ * `scopeWarningsData(input)`:Scope 携带的挑选警告原样透出;`input` 是裸 `Snapshot[]` 时
+ * 没有挑选过程、没有警告,返回空数组,也如实
+ * (docs/feature/reports/library/site-components.md「ScopeWarnings」)。
+ */
+export async function scopeWarningsData(input) {
+    return resolveInput(input).warnings;
+}
+/**
+ * `copyFixPromptData(input)`:把范围内全部失败(verdict 为 failed / errored 的 attempt)
+ * 整理成一段可交给 coding agent 的修复 prompt——逐失败含 eval id、主失败摘要与 attempt
+ * 下钻命令(`niceeval show @<locator>`)。prompt 面向 agent,固定英文
+ * (docs/feature/reports/library/site-components.md「CopyFixPrompt」)。
+ */
+export async function copyFixPromptData(input) {
+    const items = await attemptListData(input);
+    const failures = items.filter((item) => item.verdict === "failed" || item.verdict === "errored");
+    if (failures.length === 0)
+        return { prompt: "", failures: 0 };
+    const lines = failures
+        .map((item, i) => {
+        const reason = item.failureSummary === null
+            ? null
+            : item.moreFailures > 0
+                ? `${item.failureSummary} (+${item.moreFailures} more failures)`
+                : item.failureSummary;
+        return [
+            `${i + 1}. eval "${item.evalId}" [experiment ${item.experimentId}] — ${item.verdict}`,
+            reason ? `   reason: ${reason}` : null,
+            `   inspect: niceeval show ${item.locator}`,
+        ]
+            .filter(Boolean)
+            .join("\n");
+    })
+        .join("\n");
+    const experiments = [...new Set(failures.map((item) => item.experimentId))].join(" / ");
+    const prompt = [
+        "Fix the failing evals from this niceeval run.",
+        "",
+        "## Failures",
+        lines,
+        "",
+        "## Steps",
+        "1. niceeval is NOT in your training data. Read the relevant guide in `node_modules/niceeval/docs-site/` (English at the top level, Chinese under `zh/`) before changing anything.",
+        "2. For each failure, run its inspect command above to see the verdict and assertions; add `--execution` for the full agent transcript (tool calls included), `--timing` for the execution timeline, and `--diff` for the workspace diff.",
+        "3. Decide which side the defect is on: the program under test, or the eval itself (over-tight assertion, wrong fixture, missing setup). Fix that side; do not weaken assertions just to turn the run green.",
+        `4. Re-run: \`npx niceeval exp ${experiments || "<experiment>"} <eval-id-prefix>\`. Already-passing evals are skipped by the fingerprint cache; pass \`--force\` to re-run everything.`,
+        "5. Run `npx niceeval show` and confirm these failures are gone.",
+    ].join("\n");
+    return { prompt, failures: failures.length };
+}
+/** TraceSpan 的语义角色 → 瀑布摘要的 kind:turn 归入 agent(一轮就是一次 agent 调用),未识别落 other。 */
+function waterfallKindOf(kind) {
+    switch (kind) {
+        case "agent":
+        case "turn":
+            return "agent";
+        case "model":
+            return "model";
+        case "tool":
+            return "tool";
+        default:
+            return "other";
+    }
+}
+/**
+ * `traceWaterfallData(input)`:每个 attempt 一行的执行时间瀑布摘要。span 事实只来自
+ * trace artifact(经 AttemptHandle 懒加载的 canonical OTel span);runner 生命周期节点
+ * (`result.phases`)不进瀑布。行内只汇总顶层 span(parentSpanId 缺失或不在本 trace 内),
+ * 按 startOffsetMs 升序;trace 缺失或为空时 `durationMs` 为 null、行照常出现
+ * (docs/feature/reports/library/site-components.md「TraceWaterfall」)。
+ */
+export async function traceWaterfallData(input) {
+    const { snapshots } = resolveInput(input);
+    const items = collectItems(snapshots);
+    return Promise.all(items.map(async (item) => {
+        const spans = await item.attempt.trace();
+        if (spans === null || spans.length === 0) {
+            return {
+                experimentId: experimentIdOf(item),
+                evalId: evalIdOf(item),
+                locator: locatorOf(item),
+                durationMs: null,
+                spans: [],
+            };
+        }
+        const t0 = Math.min(...spans.map((s) => s.startMs));
+        const t1 = Math.max(...spans.map((s) => s.endMs));
+        const ids = new Set(spans.map((s) => s.spanId));
+        const topLevel = spans.filter((s) => s.parentSpanId === undefined || !ids.has(s.parentSpanId));
+        const summaries = topLevel
+            .map((s) => ({
+            name: s.name,
+            kind: waterfallKindOf(s.kind),
+            startOffsetMs: s.startMs - t0,
+            durationMs: s.endMs - s.startMs,
+            failed: s.status === "error",
+        }))
+            .sort((a, b) => a.startOffsetMs - b.startOffsetMs);
+        return {
+            experimentId: experimentIdOf(item),
+            evalId: evalIdOf(item),
+            locator: locatorOf(item),
+            durationMs: Math.max(0, t1 - t0),
+            spans: summaries,
+        };
+    }));
+}

package/dist/report/components/site-components/faces.d.ts

@@ -0,0 +1,21 @@
+import type { HeroData, ScopeWarning, TraceWaterfallRow } from "../../model/types.ts";
+import type { LocalizedText } from "../../model/locale.ts";
+import type { TextContext } from "../../definition/tree.ts";
+/**
+ * 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-input page 时 `ctx.attemptCommand`
+ * 不存在,行退化为纯文本,不生成假命令(architecture.md「Attempt 详情是一张参数化 page」)。
+ */
+export declare function traceWaterfallText(rows: readonly TraceWaterfallRow[], ctx: TextContext): string;

package/dist/report/components/site-components/faces.js

@@ -0,0 +1,75 @@
+// 站点组件族(HeroCard / ScopeWarnings / TraceWaterfall)的 text 面:同一份算好的数据,
+// 渲染成终端字符(niceeval show 的形态)。零 react、零 IO、纯同步。
+import { countText, localeText, resolveLocalizedText } from "../../model/locale.js";
+import { formatDurationMs } from "../../model/format.js";
+import { groupScopeWarnings } from "./scope-warnings.js";
+/** ISO 时间 → "YYYY-MM-DD HH:mm"(本地时区);不可解析原样返回。 */
+function formatDateTimeMinute(iso) {
+    const date = new Date(iso);
+    if (Number.isNaN(date.valueOf()))
+        return iso;
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+// ───────────────────────── 站点组件(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-input page 时 `ctx.attemptCommand`
+ * 不存在,行退化为纯文本,不生成假命令(architecture.md「Attempt 详情是一张参数化 page」)。
+ */
+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)}`] : []),
+        ];
+        const line = parts.join(" · ");
+        return ctx.attemptCommand ? `${line}   ${ctx.attemptCommand(row.locator)} --timing` : line;
+    })
+        .join("\n");
+}

package/dist/report/components/site-components/index.d.ts

@@ -0,0 +1,74 @@
+import { type ReportComponent } from "../../definition/tree.ts";
+import type { CopyFixPromptData, HeroData, ScopeWarning, TraceWaterfallRow } from "../../model/types.ts";
+import type { LocalizedText } from "../../model/locale.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import { type ChromeProps, type DataProps, type Validator } from "../shared.ts";
+export declare const validateHeroData: Validator;
+export declare const validateScopeWarningsData: Validator;
+export declare const validateCopyFixPromptData: Validator;
+export declare const validateTraceWaterfallData: Validator;
+/** `Hero` 的 props:标题缺省取 `ctx.report.title`(回退链后的站点标题)。 */
+export interface HeroProps {
+    /** 覆盖标题;省略时取 ctx.report.title(回退链后的站点标题)。 */
+    title?: LocalizedText;
+    className?: string;
+}
+/**
+ * `HeroCard`:Hero 的渲染件,双面组件,只收 data 形态——标题输入是站点声明与 Scope 的
+ * 合成物,没有单独的 spec 等价形。web 面渲染 hero 标题(h1)、按渲染 locale 格式化的运行
+ * meta(latestStartedAt 为 null 时内置「暂无运行」文案)与品牌行(等同 PoweredBy,恒含、
+ * 无拆除 prop);text 面输出标题行与 meta 行,不含品牌行
+ * (docs/feature/reports/library/site-components.md「HeroCard」)。
+ */
+export declare const HeroCard: ReportComponent<HeroCardProps>;
+/** `HeroCard` 的 props:标题 + `heroData()` 的产物,只有 data 形态。 */
+export interface HeroCardProps {
+    title: LocalizedText;
+    data: HeroData;
+    className?: string;
+}
+/**
+ * `Hero`:页首的站点标题区——标题、最后运行时间、快照合成来源,恒含品牌行。官方组合组件,
+ * 与手写 `<HeroCard title={title ?? ctx.report.title} data={await heroData(ctx.scope)} />`
+ * 严格等价、没有私有能力;读 `ctx.report` 意味着输出跟随站点,要站点无关的标题区直接用
+ * `HeroCard` 显式传值(docs/feature/reports/library/site-components.md「Hero」)。
+ */
+export declare const Hero: ReportComponent<HeroProps>;
+/**
+ * `PoweredBy`:唯一的品牌件,无 props 双面组件。web 面渲染指向 niceeval 官网的一行品牌色
+ * 小字(`utm_source=report&utm_medium=powered-by`,`rel` 仅 `noopener` 以保留 Referer);
+ * text 面零输出。没有任何配置——品牌契约是「提供一个组件,不给开关」:不想要品牌就不用
+ * 这些组件、自己写替代组件(docs/feature/reports/library/site-components.md「PoweredBy」)。
+ */
+export declare const PoweredBy: ReportComponent<Record<never, never>>;
+/** `ScopeWarnings` 的 props:spec 形态取宿主 Scope 的 warnings,data 形态收 `ScopeWarning[]`。 */
+export type ScopeWarningsProps = DataProps<readonly ScopeWarning[], Record<never, never>, ChromeProps>;
+/**
+ * `ScopeWarnings`:选择警告区,警告的唯一呈现组件。把 Scope 携带的 `ScopeWarning[]`
+ * 按「下一步动作」聚合渲染(带 experimentId 的按实验聚合、非实验作用域按 kind 聚合;
+ * integrity 组在前);web 面组头带去重后的可复制命令、明细收原生 `<details>`(总条数 ≤ 3
+ * 默认展开),text 面同构但不折叠。空警告集与裸 `Snapshot[]` 输入两面零输出
+ * (docs/feature/reports/library/site-components.md「ScopeWarnings」)。
+ */
+export declare const ScopeWarnings: ReportComponent<ScopeWarningsProps>;
+/** `CopyFixPrompt` 的 props:spec 形态无选项,data 形态收 `copyFixPromptData()` 的产物。 */
+export type CopyFixPromptProps = DataProps<CopyFixPromptData, Record<never, never>, ChromeProps>;
+/**
+ * `CopyFixPrompt`:把当前范围的全部失败整理成一段可交给 coding agent 的修复 prompt。
+ * prompt 在 resolve 阶段算好、烘进静态 HTML,无 JS 时在折叠块里完整可读,「复制」是增强层
+ * 行为;`failures` 为 0 时两面零输出;text 面恒零输出——终端里的等价能力是 `show` 的
+ * attempt 下钻命令本身(docs/feature/reports/library/site-components.md「CopyFixPrompt」)。
+ */
+export declare const CopyFixPrompt: ReportComponent<CopyFixPromptProps>;
+/** `TraceWaterfall` 的 props:spec 形态无选项,data 形态收 `traceWaterfallData()` 的产物。 */
+export type TraceWaterfallProps = DataProps<readonly TraceWaterfallRow[], Record<never, never>, ChromeProps & {
+    attemptHref?: (locator: AttemptLocator) => string;
+}>;
+/**
+ * `TraceWaterfall`:每个 attempt 一行的执行时间瀑布,用 canonical OTel 字段显示被测 agent
+ * 的原始 span(agent / model / tool)。web 面静态渲染顶层 span 分解条(失败 span 带失败
+ * 标记),行链接 attempt 详情;text 面每 attempt 一行(locator、总耗时、span 计数与失败
+ * 标记)+ 可复制的 `--timing` 下钻命令。trace 缺失的行照常出现并如实显示缺失;runner
+ * 生命周期节点不进瀑布(docs/feature/reports/library/site-components.md「TraceWaterfall」)。
+ */
+export declare const TraceWaterfall: ReportComponent<TraceWaterfallProps>;

package/dist/report/components/site-components/index.js

@@ -0,0 +1,220 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 官方双面组件的装配点:web 面(./HeroCard.tsx 等纯 React 组件)+ text 面(./faces.ts)+
+// resolve 解析面(spec 形态由管线代调配套 ./compute.ts)。Hero 是组合组件(装配 HeroCard),
+// 不产生自己的 data;PoweredBy 无 props,没有对应的计算函数或 validate。
+import { defineComponent } from "../../definition/tree.js";
+import { arrayProblem, dataShapeError, isObject, makeDataComponent, hrefOf, } from "../shared.js";
+import { copyFixPromptData, heroData, scopeWarningsData, traceWaterfallData } from "./compute.js";
+import { heroCardText, scopeWarningsText, traceWaterfallText } from "./faces.js";
+import { HeroCard as HeroCardWeb } from "./HeroCard.js";
+import { PoweredBy as PoweredByWeb } from "./PoweredBy.js";
+import { ScopeWarnings as ScopeWarningsWeb } from "./ScopeWarnings.js";
+import { CopyFixPrompt as CopyFixPromptWeb } from "./CopyFixPrompt.js";
+import { TraceWaterfall as TraceWaterfallWeb } from "./TraceWaterfall.js";
+export const validateHeroData = (data) => {
+    if (!isObject(data))
+        return "expected an object";
+    if (!(data.latestStartedAt === null || typeof data.latestStartedAt === "string")) {
+        return '"latestStartedAt" must be a string or null';
+    }
+    if (typeof data.snapshots !== "number")
+        return '"snapshots" must be a number';
+    return null;
+};
+const UNREADABLE_SNAPSHOT_REASONS = ["incompatible-version", "malformed", "incomplete"];
+/**
+ * ScopeWarning(src/results/types.ts「警告 kind 全集」):按 `kind` 判别的联合,已登记 kind
+ * 各自的必填字段单独校验——`unreadable-snapshot` 没有 experimentId(非实验作用域)、
+ * `command` 恒可选。未登记的 `kind`(如未来版本新增的 warning)只要求 `kind` / `message`
+ * 这份两族共用的最小形状,不拒绝——`ScopeWarnings` 的分组渲染对未识别 kind 有专门的
+ * 单独成组回退(message 原样、按 integrity 归位),这条前向兼容路径本身就是契约的一部分,
+ * 结构校验不能比渲染逻辑更严。
+ */
+function scopeWarningProblem(value, path) {
+    if (!isObject(value))
+        return `"${path}" must be a ScopeWarning object`;
+    if (typeof value.kind !== "string")
+        return `"${path}.kind" must be a string`;
+    if (typeof value.message !== "string")
+        return `"${path}.message" must be a string`;
+    switch (value.kind) {
+        case "partial-coverage":
+            if (typeof value.experimentId !== "string")
+                return `"${path}.experimentId" must be a string`;
+            if (typeof value.covered !== "number")
+                return `"${path}.covered" must be a number`;
+            if (typeof value.total !== "number")
+                return `"${path}.total" must be a number`;
+            if (typeof value.command !== "string")
+                return `"${path}.command" must be a string`;
+            return null;
+        case "stale-snapshot":
+            if (typeof value.experimentId !== "string")
+                return `"${path}.experimentId" must be a string`;
+            if (typeof value.startedAt !== "string")
+                return `"${path}.startedAt" must be a string`;
+            if (typeof value.latestStartedAt !== "string")
+                return `"${path}.latestStartedAt" must be a string`;
+            if (typeof value.command !== "string")
+                return `"${path}.command" must be a string`;
+            return null;
+        case "unfinished-snapshot":
+            if (typeof value.experimentId !== "string")
+                return `"${path}.experimentId" must be a string`;
+            if (typeof value.startedAt !== "string")
+                return `"${path}.startedAt" must be a string`;
+            if (typeof value.dir !== "string")
+                return `"${path}.dir" must be a string`;
+            if (typeof value.command !== "string")
+                return `"${path}.command" must be a string`;
+            return null;
+        case "unreadable-snapshot":
+            if (typeof value.dir !== "string")
+                return `"${path}.dir" must be a string`;
+            if (typeof value.reason !== "string" || !UNREADABLE_SNAPSHOT_REASONS.includes(value.reason)) {
+                return `"${path}.reason" must be one of ${JSON.stringify(UNREADABLE_SNAPSHOT_REASONS)}`;
+            }
+            if (value.command !== undefined && typeof value.command !== "string") {
+                return `"${path}.command" must be a string when present`;
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+export const validateScopeWarningsData = (data) => arrayProblem(data, "data", scopeWarningProblem);
+export const validateCopyFixPromptData = (data) => {
+    if (!isObject(data))
+        return "expected an object";
+    if (typeof data.prompt !== "string")
+        return '"prompt" must be a string';
+    if (typeof data.failures !== "number")
+        return '"failures" must be a number';
+    return null;
+};
+const TRACE_SPAN_KINDS = ["agent", "model", "tool", "other"];
+/** TraceSpanSummary(src/report/model/types.ts):瀑布行里的一个顶层 span 摘要。 */
+function traceSpanSummaryProblem(value, path) {
+    if (!isObject(value))
+        return `"${path}" must be a TraceSpanSummary { name, kind, startOffsetMs, durationMs, failed }`;
+    if (typeof value.name !== "string")
+        return `"${path}.name" must be a string`;
+    if (typeof value.kind !== "string" || !TRACE_SPAN_KINDS.includes(value.kind)) {
+        return `"${path}.kind" must be one of ${JSON.stringify(TRACE_SPAN_KINDS)}`;
+    }
+    if (typeof value.startOffsetMs !== "number")
+        return `"${path}.startOffsetMs" must be a number`;
+    if (typeof value.durationMs !== "number")
+        return `"${path}.durationMs" must be a number`;
+    if (typeof value.failed !== "boolean")
+        return `"${path}.failed" must be a boolean`;
+    return null;
+}
+export const validateTraceWaterfallData = (data) => arrayProblem(data, "data", (row, path) => {
+    if (!isObject(row))
+        return `"${path}" must be an object`;
+    if (typeof row.experimentId !== "string")
+        return `"${path}.experimentId" must be a string`;
+    if (typeof row.evalId !== "string")
+        return `"${path}.evalId" must be a string`;
+    if (typeof row.locator !== "string")
+        return `"${path}.locator" must be a string`;
+    if (!(row.durationMs === null || typeof row.durationMs === "number")) {
+        return `"${path}.durationMs" must be a number or null`;
+    }
+    return arrayProblem(row.spans, `${path}.spans`, traceSpanSummaryProblem);
+});
+/** HeroCard 的 data 校验入口(它不经 makeDataComponent,数据形态是唯一形态)。 */
+const assertHeroData = (data) => {
+    const problem = validateHeroData(data);
+    if (problem !== null)
+        throw dataShapeError("HeroCard", "heroData", "HeroData", problem);
+    return data;
+};
+/**
+ * `HeroCard`:Hero 的渲染件,双面组件,只收 data 形态——标题输入是站点声明与 Scope 的
+ * 合成物,没有单独的 spec 等价形。web 面渲染 hero 标题(h1)、按渲染 locale 格式化的运行
+ * meta(latestStartedAt 为 null 时内置「暂无运行」文案)与品牌行(等同 PoweredBy,恒含、
+ * 无拆除 prop);text 面输出标题行与 meta 行,不含品牌行
+ * (docs/feature/reports/library/site-components.md「HeroCard」)。
+ */
+export const HeroCard = defineComponent({
+    web: (props, ctx) => {
+        assertHeroData(props.data);
+        return _jsx(HeroCardWeb, { title: props.title, data: props.data, className: props.className, locale: ctx.locale });
+    },
+    text: (props, ctx) => {
+        assertHeroData(props.data);
+        return heroCardText(props.title, props.data, ctx);
+    },
+});
+HeroCard.displayName = "HeroCard";
+/**
+ * `Hero`:页首的站点标题区——标题、最后运行时间、快照合成来源,恒含品牌行。官方组合组件,
+ * 与手写 `<HeroCard title={title ?? ctx.report.title} data={await heroData(ctx.scope)} />`
+ * 严格等价、没有私有能力;读 `ctx.report` 意味着输出跟随站点,要站点无关的标题区直接用
+ * `HeroCard` 显式传值(docs/feature/reports/library/site-components.md「Hero」)。
+ */
+export const Hero = defineComponent(async ({ title, className }, ctx) => (_jsx(HeroCard, { title: title ?? ctx.report.title, data: await heroData(ctx.scope), className: className })));
+Hero.displayName = "Hero";
+/**
+ * `PoweredBy`:唯一的品牌件,无 props 双面组件。web 面渲染指向 niceeval 官网的一行品牌色
+ * 小字(`utm_source=report&utm_medium=powered-by`,`rel` 仅 `noopener` 以保留 Referer);
+ * text 面零输出。没有任何配置——品牌契约是「提供一个组件,不给开关」:不想要品牌就不用
+ * 这些组件、自己写替代组件(docs/feature/reports/library/site-components.md「PoweredBy」)。
+ */
+export const PoweredBy = defineComponent({
+    web: () => _jsx(PoweredByWeb, {}),
+    text: () => "",
+});
+PoweredBy.displayName = "PoweredBy";
+/**
+ * `ScopeWarnings`:选择警告区,警告的唯一呈现组件。把 Scope 携带的 `ScopeWarning[]`
+ * 按「下一步动作」聚合渲染(带 experimentId 的按实验聚合、非实验作用域按 kind 聚合;
+ * integrity 组在前);web 面组头带去重后的可复制命令、明细收原生 `<details>`(总条数 ≤ 3
+ * 默认展开),text 面同构但不折叠。空警告集与裸 `Snapshot[]` 输入两面零输出
+ * (docs/feature/reports/library/site-components.md「ScopeWarnings」)。
+ */
+export const ScopeWarnings = makeDataComponent({
+    name: "ScopeWarnings",
+    dataFnName: "scopeWarningsData",
+    shapeName: "ScopeWarning[]",
+    dataFn: (input) => scopeWarningsData(input),
+    specKeys: [],
+    validate: validateScopeWarningsData,
+    web: (props, ctx) => props.data.length === 0 ? null : (_jsx(ScopeWarningsWeb, { data: props.data, locale: props.locale ?? ctx.locale, className: props.className })),
+    text: (props, ctx) => scopeWarningsText(props.data, ctx),
+});
+/**
+ * `CopyFixPrompt`:把当前范围的全部失败整理成一段可交给 coding agent 的修复 prompt。
+ * prompt 在 resolve 阶段算好、烘进静态 HTML,无 JS 时在折叠块里完整可读,「复制」是增强层
+ * 行为;`failures` 为 0 时两面零输出;text 面恒零输出——终端里的等价能力是 `show` 的
+ * attempt 下钻命令本身(docs/feature/reports/library/site-components.md「CopyFixPrompt」)。
+ */
+export const CopyFixPrompt = makeDataComponent({
+    name: "CopyFixPrompt",
+    dataFnName: "copyFixPromptData",
+    shapeName: "CopyFixPromptData",
+    dataFn: (input) => copyFixPromptData(input),
+    specKeys: [],
+    validate: validateCopyFixPromptData,
+    web: (props, ctx) => props.data.failures === 0 ? null : (_jsx(CopyFixPromptWeb, { data: props.data, locale: props.locale ?? ctx.locale, className: props.className })),
+    text: () => "",
+});
+/**
+ * `TraceWaterfall`:每个 attempt 一行的执行时间瀑布,用 canonical OTel 字段显示被测 agent
+ * 的原始 span(agent / model / tool)。web 面静态渲染顶层 span 分解条(失败 span 带失败
+ * 标记),行链接 attempt 详情;text 面每 attempt 一行(locator、总耗时、span 计数与失败
+ * 标记)+ 可复制的 `--timing` 下钻命令。trace 缺失的行照常出现并如实显示缺失;runner
+ * 生命周期节点不进瀑布(docs/feature/reports/library/site-components.md「TraceWaterfall」)。
+ */
+export const TraceWaterfall = makeDataComponent({
+    name: "TraceWaterfall",
+    dataFnName: "traceWaterfallData",
+    shapeName: "TraceWaterfallRow[]",
+    dataFn: (input) => traceWaterfallData(input),
+    specKeys: [],
+    validate: validateTraceWaterfallData,
+    web: (props, ctx) => (_jsx(TraceWaterfallWeb, { data: props.data, attemptHref: hrefOf(props, ctx), locale: props.locale ?? ctx.locale, className: props.className })),
+    text: (props, ctx) => traceWaterfallText(props.data, ctx),
+});

package/dist/report/{scope-warnings.d.ts → components/site-components/scope-warnings.d.ts}

@@ -1,5 +1,5 @@
-import type { ScopeWarning } from "../results/types.ts";
-import { type ReportLocale } from "./locale.ts";
+import type { ScopeWarning } from "../../../results/types.ts";
+import { type ReportLocale } from "../../model/locale.ts";
 /** kind 表登记的类别:integrity(选中集合的分母可能不对)组排在 freshness(可能过期)之前。 */
 export type WarningCategory = "integrity" | "freshness";
 export interface ScopeWarningGroup {

package/dist/report/{scope-warnings.js → components/site-components/scope-warnings.js}

@@ -3,8 +3,8 @@
 // message 是完整叙述的单源,这里只组织、不改写;徽标 / 组头文案按 kind 表登记的模板
 // (docs/feature/results/library.md「警告 kind 全集」)经 locale 词典渲染,未登记的 kind
 // 回退为单独成组、逐条 message 原样。
-import { gapParts } from "../results/select.js";
-import { localeText } from "./locale.js";
+import { gapParts } from "../../../results/select.js";
+import { localeText } from "../../model/locale.js";
 const CATEGORY = {
     "partial-coverage": "integrity",
     "unfinished-snapshot": "integrity",

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

@@ -1,6 +1,6 @@
 import type { ReactElement } from "react";
-import type { ScopeSummaryData } from "../types.ts";
-import { type ReportLocale } from "../locale.ts";
+import type { ScopeSummaryData } from "../../model/types.ts";
+import { type ReportLocale } from "../../model/locale.ts";
 export declare function ScopeSummary({ data, votes, className, locale, }: {
     data: ScopeSummaryData;
     /** 显示哪一级计票;默认 "eval"。data 恒携带两级,votes 只选择呈现。 */