niceeval 0.8.1 → 0.9.1

package/src/report/react/TraceWaterfall.tsx

@@ -0,0 +1,78 @@
+// TraceWaterfall:执行时间瀑布的 web 面——每个 attempt 一行,静态渲染顶层 span 分解条
+// (定位按 startOffsetMs / durationMs 百分比;失败 span 带失败标记),行链接 attempt 详情。
+// trace 缺失的行照常出现并如实显示缺失;排序、缩放是渐进增强,静态 HTML 无 JS 完整可读
+// (docs/feature/reports/library/site-components.md「TraceWaterfall」)。
+
+import type { ReactElement } from "react";
+import type { TraceWaterfallRow } from "../types.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
+import { DEFAULT_REPORT_LOCALE, countText, localeText, type ReportLocale } from "../locale.ts";
+import { cx, formatDurationMs } from "./format.ts";
+
+const DEFAULT_ATTEMPT_HREF = (locator: AttemptLocator): string => `#/attempt/${locator}`;
+
+function pct(part: number, total: number): string {
+  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,
+}: {
+  data: readonly TraceWaterfallRow[];
+  attemptHref?: (locator: AttemptLocator) => string;
+  className?: string;
+  locale?: ReportLocale;
+}): ReactElement {
+  return (
+    <section className={cx("nre", "nre-trace-waterfall", className)}>
+      {data.length === 0 && <p className="nre-waterfall-empty">{localeText(locale, "traceWaterfall.empty")}</p>}
+      <ul className="nre-waterfall">
+        {data.map((row) => {
+          const failedSpans = row.spans.filter((span) => span.failed).length;
+          return (
+            <li key={row.locator} className="nre-waterfall-row">
+              <div className="nre-waterfall-head">
+                <a className="nre-locator" href={attemptHref(row.locator)}>
+                  {row.locator}
+                </a>
+                <span className="nre-waterfall-eval">{row.evalId}</span>
+                <span className="nre-waterfall-experiment">{row.experimentId}</span>
+                {/* trace 缺失如实显示缺失,不猜值、不藏行 */}
+                <span className="nre-waterfall-duration">
+                  {row.durationMs === null ? localeText(locale, "traceWaterfall.noTrace") : formatDurationMs(row.durationMs)}
+                </span>
+                <span className="nre-waterfall-count">{countText(locale, "traceWaterfall.spans", row.spans.length)}</span>
+                {failedSpans > 0 && (
+                  <span className="nre-waterfall-failed">✗ {countText(locale, "traceWaterfall.failedSpans", failedSpans)}</span>
+                )}
+              </div>
+              {row.durationMs !== null && row.spans.length > 0 && (
+                <div className="nre-waterfall-track">
+                  {row.spans.map((span, i) => (
+                    <span
+                      key={i}
+                      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 ? " · ✗" : ""}`}
+                    />
+                  ))}
+                </div>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    </section>
+  );
+}

package/src/report/react/enhance.js

@@ -196,6 +196,20 @@
     }
   });
 
+  // AttemptList 的过滤(<AttemptList filter />):按条目全文 + data-nre-verdict(verdict 词
+  // 不在可见文本里,判定符是 ✓/✗)收窄 .nre-attempt 行。只改浏览状态,不改数据与初始 HTML。
+  document.addEventListener("input", function (e) {
+    var input = closest(e.target, "input[data-nre-attempt-filter]");
+    if (!input) return;
+    var scope = input.parentElement;
+    var rows = scope ? scope.querySelectorAll(".nre-attempt") : [];
+    var query = input.value.trim().toLowerCase();
+    for (var i = 0; i < rows.length; i++) {
+      var haystack = rows[i].textContent + " " + (rows[i].getAttribute("data-nre-verdict") || "");
+      rows[i].classList.toggle("nre-row-hidden", query !== "" && haystack.toLowerCase().indexOf(query) === -1);
+    }
+  });
+
   // ───────────────────────── tooltip:.nre-scatter-point / .nre-line-point ─────────────────────────
   // 首次 hover 时把点内 <title> 的内容搬进 data-nre-title(避免与原生 tooltip 重影),
   // 渲染样式化 tooltip div(定位在点上方,挂在所属 figure 里)。无 JS 时 <title> 原样生效。

package/src/report/react/index.tsx

@@ -21,16 +21,25 @@ export { MetricLine } from "./MetricLine.tsx";
 export { DeltaTable } from "./DeltaTable.tsx";
 export { Scoreboard } from "./Scoreboard.tsx";
 
+// 站点组件的纯 web 面(data 形态;Hero 是组合组件,只住 niceeval/report)
+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";
+
 // 数据契约类型(家在 ../types.ts,「算」与「画」两侧共用同一份)
 export type {
   AttemptListItem,
   AttemptLocator,
+  CopyFixPromptData,
   DeltaData,
   EvalListItem,
   ExperimentComparisonData,
   ExperimentComparisonGroupData,
   ExperimentListEvalRow,
   ExperimentListItem,
+  HeroData,
   LineData,
   MatrixData,
   MetricCell,
@@ -40,6 +49,8 @@ export type {
   ScopeWarning,
   ScoreboardData,
   TableData,
+  TraceSpanSummary,
+  TraceWaterfallRow,
   VerdictTally,
 } from "../types.ts";
 

package/src/report/react/styles.css

@@ -436,18 +436,63 @@ table.nre,
   margin: 0.25rem 0 0;
 }
 
-/* ---- 宿主警告块:.nre-report-warnings 外壳 + ul.nre-warnings + li.nre-warning[data-kind] ---- */
+/* ---- 宿主警告块:.nre-warnings 是默认折叠的 <details>,<summary> 汇总行恒可见。
+   不占框:无边框、无底色、不缩进,警示色只落在汇总行文字与徽标上。 ---- */
 .nre .nre-warnings {
-  list-style: none;
   margin: 0;
-  padding: 10px 14px;
-  border: 1px solid color-mix(in oklch, var(--warn), var(--line) 45%);
-  border-left: 3px solid var(--warn);
-  border-radius: 8px;
-  background: color-mix(in oklch, var(--warn), var(--panel) 92%);
   color: var(--text);
   font-size: 13px;
 }
+/* 外层 <details> 的 <summary>:分类计数汇总行,原生无 JS 可展开。 */
+.nre .nre-warnings > .nre-warnings-summary {
+  font-weight: 650;
+  color: var(--warn);
+  cursor: pointer;
+}
+.nre .nre-warning-groups {
+  list-style: none;
+  margin: 8px 0 0;
+  padding: 0;
+}
+.nre .nre-warning-group + .nre-warning-group {
+  margin-top: 10px;
+  padding-top: 10px;
+  border-top: 1px solid var(--line);
+}
+.nre .nre-warning-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: 4px 10px;
+}
+.nre .nre-warning-title { font-weight: 650; }
+.nre .nre-warning-badge {
+  padding: 1px 8px;
+  border: 1px solid color-mix(in oklch, var(--warn), var(--line) 35%);
+  border-radius: 999px;
+  background: color-mix(in oklch, var(--warn), var(--panel) 84%);
+  font-size: 0.9em;
+  white-space: nowrap;
+}
+/* freshness 组(数字对但可能过期)视觉降一档,integrity 保持警示底色。 */
+.nre .nre-warning-group[data-category="freshness"] .nre-warning-badge {
+  border-color: var(--line);
+  background: var(--panel);
+  color: var(--soft);
+}
+.nre .nre-warning-details { margin: 4px 0 0; }
+/* <details> 原生无 JS 可展开,cursor 不经 .nre-js 门控。 */
+.nre .nre-warning-details > summary {
+  color: var(--soft);
+  font-size: 0.9em;
+  cursor: pointer;
+}
+.nre .nre-warning-details > ul {
+  list-style: none;
+  margin: 4px 0 0;
+  padding: 0 0 0 12px;
+  border-left: 2px solid var(--line);
+}
 .nre .nre-warning + .nre-warning { margin-top: 8px; }
 /* 警告携带的下一步命令:等宽块,无 JS 时点击即全选;enhance.js 在场时点击复制 */
 .nre .nre-warning-command {
@@ -470,6 +515,147 @@ table.nre,
   color: var(--good);
 }
 
+/* ---- Hero / PoweredBy(站点标题区与品牌行) ---- */
+/* 居中大标题:hero 是页首的门面块,整块占满内容列宽、文本水平居中,标题随视口 clamp 放大,
+   meta 与品牌行居中跟随。不设 max-width——窄框居中在宽内容列里会读成左偏,占满列宽才真居中。 */
+.nre-hero {
+  text-align: center;
+  margin: 0 0 clamp(28px, 5vw, 44px);
+}
+.nre-hero .nre-hero-title {
+  margin: 0;
+  font-size: clamp(38px, 5vw, 60px);
+  line-height: 0.98;
+  font-weight: 760;
+  letter-spacing: -0.01em;
+}
+.nre-hero .nre-hero-meta {
+  margin: 14px 0 0;
+  color: var(--muted);
+  font-size: 14px;
+}
+.nre-powered-by {
+  margin: 10px 0 0;
+  font-size: 12px;
+}
+.nre-powered-by a {
+  color: var(--soft);
+  text-decoration: none;
+}
+.nre-powered-by a:hover { color: var(--text); text-decoration: underline; }
+
+/* ---- CopyFixPrompt(批量修复 prompt:折叠块 + 增强层复制) ---- */
+.nre-copy-fix-prompt {
+  margin: 0 0 16px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--panel);
+  padding: 8px 12px;
+}
+.nre-copy-fix-prompt > summary {
+  cursor: pointer;
+  font-weight: 620;
+  font-size: 13px;
+}
+.nre-copy-fix-prompt .nre-copy-fix-prompt-copy {
+  margin: 8px 0 0;
+  padding: 4px 10px;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: var(--panel);
+  color: var(--text);
+  font: inherit;
+  font-size: 12px;
+}
+:root.nre-js .nre-copy-fix-prompt .nre-copy-fix-prompt-copy { cursor: copy; }
+.nre-copy-fix-prompt .nre-copy-fix-prompt-copy[data-nre-copied]::after {
+  content: "✓";
+  margin-left: 0.6em;
+  color: var(--good);
+}
+.nre-copy-fix-prompt .nre-copy-fix-prompt-text {
+  margin: 8px 0 0;
+  padding: 8px 10px;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: var(--bg, transparent);
+  font-size: 12px;
+  line-height: 1.5;
+  overflow-x: auto;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+/* ---- TraceWaterfall(每 attempt 一行的静态时间瀑布) ---- */
+.nre-trace-waterfall .nre-waterfall {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.nre-trace-waterfall .nre-waterfall-row {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 10px 14px;
+  margin-bottom: 8px;
+  background: var(--panel);
+}
+.nre-trace-waterfall .nre-waterfall-head {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75em;
+  align-items: baseline;
+}
+.nre-trace-waterfall .nre-waterfall-eval { font-weight: 620; }
+.nre-trace-waterfall .nre-waterfall-experiment,
+.nre-trace-waterfall .nre-waterfall-duration,
+.nre-trace-waterfall .nre-waterfall-count {
+  color: var(--muted);
+  font-size: 0.9em;
+  font-variant-numeric: tabular-nums;
+}
+.nre-trace-waterfall .nre-waterfall-failed { color: var(--bad); font-size: 0.9em; }
+/* 分解条:span 按 startOffsetMs / durationMs 百分比静态定位,失败 span 换警示色 */
+.nre-trace-waterfall .nre-waterfall-track {
+  position: relative;
+  height: 14px;
+  margin-top: 8px;
+  border-radius: 4px;
+  background: color-mix(in oklch, var(--line), var(--panel) 60%);
+  overflow: hidden;
+}
+.nre-trace-waterfall .nre-waterfall-span {
+  position: absolute;
+  top: 2px;
+  bottom: 2px;
+  border-radius: 2px;
+  background: var(--line-strong);
+}
+.nre-trace-waterfall .nre-span-agent { background: color-mix(in oklch, var(--good), var(--line-strong) 40%); }
+.nre-trace-waterfall .nre-span-model { background: color-mix(in oklch, var(--warn), var(--line-strong) 40%); }
+.nre-trace-waterfall .nre-span-tool { background: color-mix(in oklch, var(--line-strong), var(--text) 25%); }
+.nre-trace-waterfall .nre-span-failed { background: var(--bad); }
+.nre-trace-waterfall .nre-waterfall-empty {
+  border: 1px dashed var(--line-strong);
+  border-radius: 8px;
+  padding: 18px;
+  color: var(--muted);
+  text-align: center;
+  background: var(--panel);
+}
+
+/* ---- AttemptList 的过滤框(<AttemptList filter />,渐进增强) ---- */
+.nre-attempt-list > .nre-filter {
+  height: 34px;
+  min-width: 260px;
+  margin-bottom: 12px;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  padding: 0 11px;
+  background: var(--panel);
+  color: var(--text);
+  font: inherit;
+}
+
 /* ---- MetricMatrix ---- */
 .nre-metric-matrix .nre-matrix-caption {
   caption-side: top;

package/src/report/report.ts

@@ -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)。管线以页为单位执行:
@@ -51,11 +53,11 @@ export type HeadTag =
   | { tag: "script" | "style"; attrs?: Record<string, string | true>; 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>` 的结构化标签,在官方与外壳样式之后按声明顺序渲染。
@@ -80,11 +82,32 @@ export interface ReportPage {
   content: ReportNode;
 }
 
-/** content / pages 互斥由类型表达,不把非法状态留到运行期。 */
+/** content / pages / extends 三选一由类型表达,不把非法状态留到运行期。 */
 export type ReportDef = ReportShell &
   (
-    | { content: ReportNode; pages?: never }
-    | { pages: NonEmptyArray<ReportPage>; content?: never }
+    | {
+        /** 单页缩写,等价于只含 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;
+      }
   );
 
 const REPORT_DEFINITION: unique symbol = Symbol.for("niceeval.report.definition");
@@ -124,8 +147,8 @@ const DEFAULT_PAGE_TITLE: LocalizedText = { 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: unknown): boolean {
   if (value === null || value === undefined || typeof value === "boolean") return true;
@@ -148,7 +171,8 @@ function assertNotDefinition(value: unknown, where: string): void {
   ) {
     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.",
     );
   }
 }
@@ -317,33 +341,50 @@ export function defineReport(input: ReportNode | ReportDef): ReportDefinition {
     : (input as ReportDef);
   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,
+      "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) {
+  const hasExtends = "extends" in def && (def as { extends?: unknown }).extends !== undefined;
+  const declared = [hasContent && '"content"', hasPages && '"pages"', hasExtends && '"extends"'].filter(
+    (name): name is string => typeof name === "string",
+  );
+  if (declared.length > 1) {
     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}`,
+      `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) {
+  if (declared.length === 0) {
     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}`,
+      `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}`,
     );
   }
 
-  let pages: ReportPage[];
-  if (hasContent) {
+  // extends:报告级复用的唯一位置。页归 base,本对象只贡献外壳;base 已经过 defineReport
+  // 校验,页不重验。
+  let base: ReportDefinition | undefined;
+  let pages: readonly ReportPage[];
+  if (hasExtends) {
+    const candidate = (def as { extends: unknown }).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 as ReportNode }];
   } else {
     const raw = def.pages as unknown;
     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}`,
+        `defineReport "pages" must be a non-empty array of { id, title, content }. ${EXTENDS_NEXT_STEP}`,
       );
     }
     const seen = new Set<string>();
@@ -367,36 +408,44 @@ export function defineReport(input: ReportNode | ReportDef): ReportDefinition {
 
   if (def.title !== undefined) 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 as ReportLink)?.label, "defineReport link label");
-    if (typeof (link as ReportLink)?.href !== "string" || (link as ReportLink).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 as { icon?: unknown }).icon;
-    if (icon !== undefined) {
-      const svg = (icon as { svg?: unknown })?.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: readonly ReportLink[];
+  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 as ReportLink)?.label, "defineReport link label");
+      if (typeof (link as ReportLink)?.href !== "string" || (link as ReportLink).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 as { icon?: unknown }).icon;
+      if (icon !== undefined) {
+        const svg = (icon as { svg?: unknown })?.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" as const,
-    ...(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 as unknown as NonEmptyArray<ReportPage>,
   };
   Object.defineProperty(definition, REPORT_DEFINITION, { value: true });
@@ -484,18 +533,11 @@ export interface RenderReportTextOptions extends TextRenderOptions {
   pageId?: string;
 }
 
-/**
- * 挑选警告的 text 形态:每条渲染好的 message 前缀 "! ",一行一条。宿主级前置块——
- * 宿主是 warning 的唯一呈现者,组件数据不复制 warning;裸跑 / --report 都在报告顶上
- * 如实报残缺,不静默(docs/feature/reports/architecture.md「Scope 是计算入口」)。
- */
-function renderScopeWarningsText(scope: Scope, _locale: ReportLocale): string {
-  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: ReportDefinition,
@@ -511,11 +553,7 @@ export async function renderReportToText(
     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 解析的标题字符串。 */
@@ -538,10 +576,10 @@ function quoteArg(value: string): string {
   return /^[A-Za-z0-9._/@-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 
-/** 按上下文拼组索引的可复制命令:`niceeval show <patterns> --experiment <id> [--results/--report/--page]`。 */
+/** 按上下文拼组索引的可复制命令:`niceeval show <patterns> --exp <id> [--results/--report/--page]`。 */
 function experimentCommandFor(ctx: HostCommandContext): (experimentIdPrefix: string) => string {
   return (prefix) => {
-    const parts = ["niceeval show", ...ctx.patterns.map(quoteArg), `--experiment ${quoteArg(prefix)}`];
+    const parts = ["niceeval show", ...ctx.patterns.map(quoteArg), `--exp ${quoteArg(prefix)}`];
     if (ctx.results !== undefined) parts.push(`--results ${quoteArg(ctx.results)}`);
     if (ctx.report !== undefined) parts.push(`--report ${quoteArg(ctx.report)}`);
     if (ctx.page !== undefined) parts.push(`--page ${quoteArg(ctx.page)}`);
@@ -563,8 +601,8 @@ export interface RenderTreeTextOptions extends TextRenderOptions {
 
 /**
  * 渲染一页报告树的 text 面(宿主逐页调用;页选择归宿主):
- * resolve(组合展开 + spec 取数)→ validate → render。Scope 有挑选警告时在页顶前置
- * "! <message>" 块——宿主是 warning 的唯一呈现者,组件数据不复制 warning。
+ * resolve(组合展开 + spec 取数)→ validate → render。宿主不在报告树外另设警告通道,
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现(内建报告每页都放它)。
  */
 export async function renderReportTreeToText(
   tree: ReportNode,
@@ -584,8 +622,5 @@ export async function renderReportTreeToText(
       ? { 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);
 }