niceeval 0.6.2 → 0.7.1

package/src/show/report-host.ts

@@ -0,0 +1,375 @@
+// 报告装载的宿主联系面:show 与 view 共用(view 从这里 import;两个宿主对同一份
+// defineReport 产物必须得到同一个规范化结果,见 docs/feature/reports/library/shell.md)。
+//
+// 契约(docs/feature/reports/library/shell.md「行为约束」/ architecture.md「外壳与页:装载规范化」):
+// - `--report` 文件默认导出恒为 defineReport 产物;裸宿主装载 `niceeval/report/built-in` 的默认导出,
+//   走同一条「装载 → resolve → validate → render」管线。
+// - 装载规范化唯一产物是「外壳 + 非空页列表」:`defineReport(树)` ≡ `{ content: 树 }` ≡
+//   `pages: [{ id: "report", title: 内置页名, content: 树 }]`。
+// - 标题回退单点:def.title → Scope 中唯一且相同(LocalizedText 深相等)的非空快照 name →
+//   内置文案「Eval 运行结果 / Eval Results」。落点是首页 hero、浏览器标题与 show 页索引标题行;
+//   页头品牌位恒为 NiceEval 字标,不归 title。
+// - LocalizedText 回退:当前 locale → en → 按 locale 键字典序的第一个非空值。
+//
+// ⚠ 集成状态:src/report/** 正被并行重写(plan/reports-redesign-implementation.md)。这里把宿主
+// 需要的新报告 runtime API 收敛成唯一联系面,并对「新 dist 尚未产出」提供旧 API 桥接
+// (旧 ReportDefinition 是 build 函数形态,恒为单页)。集成阶段的对接点(搜索 INTEGRATION):
+//   1. `dist/report/built-in/index.js` 默认导出(内建报告入口;恒为新格式,无桥接——
+//      它随本包源码一起构建,不存在旧产物)。
+//   2. `normalizeReport(definition)`:装载规范化(外壳 + 非空页列表);旧桥接对 build 形态自行包单页。
+//   3. `renderReportTreeToText(tree, ctx, options)` / `renderReportTreeToStaticHtml(tree, ctx, options)`:
+//      逐页渲染入口(ctx = { scope, results, report });旧桥接调 renderReportToText /
+//      renderReportToStaticHtml(definition 整体)。
+
+import type { Results } from "../results/index.ts";
+import type { LocalizedText } from "../types.ts";
+
+/** 页:宿主寻址单位(`--page <id>` / `#/page/<id>`)。content 是报告树(旧桥接下是整个旧 definition)。 */
+export interface HostReportPage {
+  id: string;
+  title: LocalizedText;
+  content: unknown;
+}
+
+export interface HostReportLink {
+  label: LocalizedText;
+  href: string;
+  /**
+   * 可选内联 SVG 字标(shell.md「字段穷尽」):web 面渲染在 label 前,静态导出原样内联;
+   * 不收组件(外壳声明经 viewData 序列化边界);show 不消费。
+   */
+  icon?: { svg: string };
+}
+
+/** `{src}` 与 `{inline}` 两种形态不可同时出现(shell.md「字段穷尽」)。 */
+export type HostReportAsset = { src: string; inline?: never } | { inline: string; src?: never };
+
+/** 装载规范化产物:外壳 + 非空页列表。show 只消费 title / pages;其余是 web 面属性。 */
+export interface HostReport {
+  title?: LocalizedText;
+  links: HostReportLink[];
+  footer?: LocalizedText;
+  scripts: HostReportAsset[];
+  styles: HostReportAsset[];
+  pages: HostReportPage[];
+}
+
+/** 单页缩写展开出的唯一页使用内置页名(shell.md:「报告 / Report」)。 */
+export const BUILT_IN_PAGE_TITLE: LocalizedText = { en: "Report", "zh-CN": "报告" };
+export const SINGLE_PAGE_ID = "report";
+
+/** 标题回退链的终点:内置文案「Eval 运行结果 / Eval Results」(shell.md「行为约束」)。 */
+export const BUILT_IN_REPORT_TITLE: LocalizedText = { en: "Eval Results", "zh-CN": "Eval 运行结果" };
+
+/** 规范化报告声明的只读注入(组合组件 ctx.report;ReportMeta,见 library/layout.md)。 */
+export interface HostReportMeta {
+  title: LocalizedText;
+  links: HostReportLink[];
+  footer?: LocalizedText;
+  pages: { id: string; title: LocalizedText }[];
+  pageId: string;
+}
+
+/** 可预期的装载用户错误(与 ReportLoadError 同待遇:打一句直说问题与下一步,不抛堆栈)。 */
+export class HostReportError extends Error {}
+
+// ───────────────────────── LocalizedText ─────────────────────────
+
+/**
+ * LocalizedText 的确定回退(shell.md「行为约束」):当前 locale → en → 按 locale 键字典序的
+ * 第一个非空值。对象没有任何非空值时返回 undefined(装载期应当已报错,渲染兜底不再抛)。
+ */
+export function localizeText(text: LocalizedText | undefined, locale: string): string | undefined {
+  if (text === undefined) return undefined;
+  if (typeof text === "string") return text || undefined;
+  const exact = text[locale];
+  if (exact) return exact;
+  if (text.en) return text.en;
+  for (const key of Object.keys(text).sort()) {
+    if (text[key]) return text[key];
+  }
+  return undefined;
+}
+
+/** LocalizedText 深相等:按字段值比较,对象键顺序不影响结果(shell.md「标题回退必须确定」)。 */
+export function localizedTextEquals(a: LocalizedText, b: LocalizedText): boolean {
+  if (typeof a === "string" || typeof b === "string") return a === b;
+  const keysA = Object.keys(a).sort();
+  const keysB = Object.keys(b).sort();
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((key, i) => key === keysB[i] && a[key] === b[key]);
+}
+
+/** LocalizedText 是否有任何非空值(空串 / 全空对象都算空)。 */
+function hasText(text: LocalizedText | undefined): text is LocalizedText {
+  if (text === undefined) return false;
+  if (typeof text === "string") return text.length > 0;
+  return Object.values(text).some((v) => typeof v === "string" && v.length > 0);
+}
+
+/**
+ * 标题回退单点(show 页索引标题与 view hero / 浏览器标题共用):def.title → Scope 中唯一且相同
+ * (深相等)的非空快照 name → 内置文案「Eval 运行结果 / Eval Results」。多个不同 name 时
+ * 不随机挑一个,直接落到内置文案。
+ */
+export function resolveReportTitle(
+  defTitle: LocalizedText | undefined,
+  snapshots: readonly { name?: LocalizedText }[],
+): LocalizedText {
+  if (hasText(defTitle)) return defTitle;
+  let unique: LocalizedText | undefined;
+  for (const snapshot of snapshots) {
+    if (!hasText(snapshot.name)) continue;
+    if (unique === undefined) {
+      unique = snapshot.name;
+    } else if (!localizedTextEquals(unique, snapshot.name)) {
+      return BUILT_IN_REPORT_TITLE;
+    }
+  }
+  return unique ?? BUILT_IN_REPORT_TITLE;
+}
+
+/** 组合组件 ctx.report 的形状(走完回退链的 title;scripts / styles 不进)。 */
+export function reportMetaFor(
+  report: HostReport,
+  pageId: string,
+  snapshots: readonly { name?: LocalizedText }[],
+): HostReportMeta {
+  return {
+    title: resolveReportTitle(report.title, snapshots),
+    links: report.links,
+    ...(report.footer !== undefined ? { footer: report.footer } : {}),
+    pages: report.pages.map((p) => ({ id: p.id, title: p.title })),
+    pageId,
+  };
+}
+
+// ───────────────────────── 装载与规范化 ─────────────────────────
+
+/** 旧(集成前)ReportDefinition:build 函数形态,恒为单页。集成阶段删除。 */
+interface LegacyReportDefinition {
+  build: (ctx: unknown) => unknown;
+}
+
+function isLegacyDefinition(value: unknown): value is LegacyReportDefinition {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    typeof (value as Partial<LegacyReportDefinition>).build === "function"
+  );
+}
+
+const PAGE_ID_PATTERN = /^[a-z0-9-]+$/;
+
+/**
+ * 装载期校验 `ReportLink.icon`(shell.md「字段穷尽」):唯一合法形状是 `{ svg: string }`。
+ * 无类型 JS 传组件 / ReactNode / 裸字符串都在这里被完整用户反馈拒绝——外壳声明要过
+ * viewData 的序列化边界,ReactNode 过不去,可序列化是外壳契约的一部分。
+ */
+function assertLinkIcon(link: unknown, sourceLabel: string): void {
+  const icon = (link as { icon?: unknown })?.icon;
+  if (icon === undefined) return;
+  const svg = (icon as { svg?: unknown })?.svg;
+  if (typeof icon !== "object" || icon === null || typeof svg !== "string" || svg.length === 0) {
+    throw new HostReportError(
+      `${sourceLabel}: a 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>" }.',
+    );
+  }
+}
+
+/**
+ * 装载规范化:把 defineReport 产物折成「外壳 + 非空页列表」。三种入参写法
+ * (树 / `content:` / `pages:`)展开成同一形状;page id 的唯一性与字符纪律在这里校验
+ * (shell.md「校验分两期」的装载期部分)。
+ */
+export function normalizeHostReport(definition: unknown, sourceLabel: string): HostReport {
+  // INTEGRATION(2):新 defineReport 产物(kind === "report")。规范化后的外壳与页列表
+  // 若由新报告 runtime 导出的 normalizeReport 承担,这里改为直接调它;当前按 docs 的
+  // 字段穷尽读取产物自带的声明。
+  if (typeof definition === "object" && definition !== null && (definition as { kind?: unknown }).kind === "report") {
+    const def = definition as {
+      title?: LocalizedText;
+      links?: HostReportLink[];
+      footer?: LocalizedText;
+      scripts?: HostReportAsset[];
+      styles?: HostReportAsset[];
+      content?: unknown;
+      pages?: { id: string; title: LocalizedText; content: unknown }[];
+    };
+    const hasContent = def.content !== undefined;
+    const hasPages = def.pages !== undefined;
+    if (hasContent === hasPages) {
+      // content / pages 同缺或同给:装载期完整用户反馈,下一步是 content: <ExperimentComparison />。
+      throw new HostReportError(
+        `${sourceLabel}: a report declares exactly one of "content" or "pages" — ` +
+          (hasContent ? "it declares both. " : "it declares neither. ") +
+          `To render the built-in report content, write: content: <ExperimentComparison />.`,
+      );
+    }
+    const pages: HostReportPage[] = hasPages
+      ? def.pages!.map((p) => ({ id: p.id, title: p.title, content: p.content }))
+      : [{ id: SINGLE_PAGE_ID, title: BUILT_IN_PAGE_TITLE, content: def.content }];
+    if (pages.length === 0) {
+      throw new HostReportError(`${sourceLabel}: "pages" must be a non-empty list of report pages.`);
+    }
+    const seen = new Set<string>();
+    for (const page of pages) {
+      if (!PAGE_ID_PATTERN.test(page.id)) {
+        throw new HostReportError(
+          `${sourceLabel}: page id "${page.id}" is invalid. Page ids use lowercase letters, digits and hyphens.`,
+        );
+      }
+      if (seen.has(page.id)) {
+        throw new HostReportError(`${sourceLabel}: duplicate page id "${page.id}". Page ids must be unique per file.`);
+      }
+      seen.add(page.id);
+    }
+    for (const link of def.links ?? []) assertLinkIcon(link, sourceLabel);
+    return {
+      ...(def.title !== undefined ? { title: def.title } : {}),
+      links: def.links ?? [],
+      ...(def.footer !== undefined ? { footer: def.footer } : {}),
+      scripts: def.scripts ?? [],
+      styles: def.styles ?? [],
+      pages,
+    };
+  }
+
+  // INTEGRATION(2) 桥接:旧 build 函数形态(集成前的 dist);恒为单页,无外壳字段。
+  if (isLegacyDefinition(definition)) {
+    return {
+      links: [],
+      scripts: [],
+      styles: [],
+      pages: [{ id: SINGLE_PAGE_ID, title: BUILT_IN_PAGE_TITLE, content: definition }],
+    };
+  }
+
+  throw new HostReportError(
+    `${sourceLabel} does not default-export a report. Export default defineReport(<ExperimentComparison />) (or defineReport({ title, content })) from "niceeval/report".`,
+  );
+}
+
+/**
+ * 装载宿主报告:`--report <file>` 走 loadReportFile;缺省(裸 show / 裸 view)装载内建报告的
+ * 默认导出。两条路都进 normalizeHostReport,同一条装载管线。
+ */
+export async function loadHostReport(
+  cwd: string,
+  reportPath: string | undefined,
+  options?: { freshImport?: boolean },
+): Promise<HostReport> {
+  if (reportPath !== undefined) {
+    const { loadReportFile } = await import("../../dist/report/load.js");
+    const definition = await loadReportFile(cwd, reportPath, options);
+    return normalizeHostReport(definition, reportPath);
+  }
+  return normalizeHostReport(await loadBuiltInDefinition(), "the built-in report");
+}
+
+/** 内建报告即 `niceeval/report/built-in` 的默认导出(dist 预编译产物,`prepare` 时构建)。 */
+async function loadBuiltInDefinition(): Promise<unknown> {
+  const mod = await import("../../dist/report/built-in/index.js");
+  return mod.default;
+}
+
+// ───────────────────────── 逐页渲染 ─────────────────────────
+
+export interface HostRenderContext {
+  /** 宿主按官方现刻水位挑好的 Scope(集成前类型名仍是 Selection;两者同物)。 */
+  scope: unknown;
+  results: Results;
+  report: HostReportMeta;
+}
+
+export interface HostTextRenderOptions {
+  width?: number;
+  locale?: string;
+  /**
+   * 索引命令的完整上下文(docs/feature/reports/show/reports.md:「索引命令携带完整上下文」):
+   * 组索引 / 页索引输出的每一条可复制命令都保留当前 --results / --report / --page 与位置参数。
+   * INTEGRATION(3):由新 text 面消费;旧桥接的 renderReportToText 不认识该字段,原样忽略。
+   */
+  commandContext?: HostCommandContext;
+}
+
+export interface HostCommandContext {
+  patterns: string[];
+  results?: string;
+  experiment?: string;
+  report?: string;
+  page?: string;
+}
+
+/** 按上下文拼一条可复制的 show 命令(页索引 / 组索引共用的携带规则)。 */
+export function showCommand(ctx: HostCommandContext, extra: string[] = []): string {
+  const parts = ["niceeval show", ...ctx.patterns];
+  if (ctx.experiment !== undefined) parts.push(`--experiment ${ctx.experiment}`);
+  if (ctx.results !== undefined) parts.push(`--results ${ctx.results}`);
+  if (ctx.report !== undefined) parts.push(`--report ${ctx.report}`);
+  if (ctx.page !== undefined) parts.push(`--page ${ctx.page}`);
+  parts.push(...extra);
+  return parts.join(" ");
+}
+
+/**
+ * 渲染一页的 text 面。INTEGRATION(3):新 runtime 的入口是
+ * `renderReportTreeToText(tree, { scope, results, report }, options)`;旧桥接下 content 是
+ * 整个旧 definition,调 renderReportToText(definition, { selection, results }, options)。
+ */
+export async function renderHostPageText(
+  page: HostReportPage,
+  ctx: HostRenderContext,
+  options: HostTextRenderOptions,
+): Promise<string> {
+  const mod = (await import("../../dist/report/report.js")) as Record<string, unknown>;
+  const renderTree = mod.renderReportTreeToText as
+    | ((tree: unknown, ctx: HostRenderContext, options: HostTextRenderOptions) => Promise<string>)
+    | undefined;
+  if (typeof renderTree === "function" && !isLegacyDefinition(page.content)) {
+    return renderTree(page.content, ctx, options);
+  }
+  if (isLegacyDefinition(page.content)) {
+    const renderLegacy = mod.renderReportToText as (
+      definition: unknown,
+      ctx: { selection: unknown; results: Results },
+      options: { width?: number; locale?: string },
+    ) => Promise<string>;
+    return renderLegacy(
+      page.content,
+      { selection: ctx.scope, results: ctx.results },
+      { ...(options.width !== undefined ? { width: options.width } : {}), ...(options.locale !== undefined ? { locale: options.locale } : {}) },
+    );
+  }
+  throw new HostReportError(
+    "The installed report runtime cannot render this report page yet (renderReportTreeToText is missing). Rebuild dist/report with `pnpm run build:report`.",
+  );
+}
+
+/** 渲染一页的 web 面(静态 HTML)。INTEGRATION(3) 同上,web 侧入口在 dist/report/web.js。 */
+export async function renderHostPageHtml(
+  page: HostReportPage,
+  ctx: HostRenderContext,
+  options: { locale: string },
+): Promise<string> {
+  const mod = (await import("../../dist/report/web.js")) as Record<string, unknown>;
+  const renderTree = mod.renderReportTreeToStaticHtml as
+    | ((tree: unknown, ctx: HostRenderContext, options: { locale: string }) => Promise<string>)
+    | undefined;
+  if (typeof renderTree === "function" && !isLegacyDefinition(page.content)) {
+    return renderTree(page.content, ctx, options);
+  }
+  if (isLegacyDefinition(page.content)) {
+    const renderLegacy = mod.renderReportToStaticHtml as (
+      definition: unknown,
+      ctx: { selection: unknown; results: Results },
+      options: { locale: string },
+    ) => Promise<string>;
+    return renderLegacy(page.content, { selection: ctx.scope, results: ctx.results }, options);
+  }
+  throw new HostReportError(
+    "The installed report runtime cannot render this report page yet (renderReportTreeToStaticHtml is missing). Rebuild dist/report with `pnpm run build:report`.",
+  );
+}

package/src/show/show.test.ts

@@ -1,12 +1,12 @@
 // cases: docs/engineering/unit-tests/reports/cases.md
-// niceeval show 终端宿主的测试(行为规范:docs-site/zh/guides/viewing-results.mdx;
+// niceeval show 终端宿主的测试(行为规范:docs-site/zh/how-to/viewing-results.mdx;
 // 组合语义:docs/feature/reports/architecture.md「Selection 是计算入口」)。覆盖:
 // - 榜单合成口径:每 experiment × eval 取最新判定,局部重跑从更早快照补齐,头部标注合成自几个快照;
 // - 前缀过滤收窄 Selection,覆盖警告分母 = 已知并集 ∩ 范围;
 // - --history 时间轴只列真实执行,resume 携带的复印件不占行;
 // - --report 装载(合法 / 非法默认导出 / 文件缺失)、位置前缀收窄注入 Selection、attemptCommand 下钻;
 // - 互斥:--history 与 --report;
-// - 单 eval 详情、`@<locator>` 精确定位与 --eval / --execution / --diff 证据切面的输出形态。
+// - 单 eval 详情、`@<locator>` 精确定位与 --source / --execution / --diff 证据切面的输出形态。
 //
 // fixture 直接写新布局(<expDir>/<snapDir>/snapshot.json + <evalId>/a<n>/result.json),
 // 依据是 docs/feature/results/architecture.md 的稳定磁盘契约,不经 writer 运行时 API(避免与并行重写的
@@ -20,7 +20,7 @@ import { createHash } from "node:crypto";
 import { openResults } from "../results/index.ts";
 import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type TimingNode, type TraceSpan, type Verdict } from "../types.ts";
 import { selectCurrentResults } from "../results/select.ts";
-import { evalHistory } from "./compose.ts";
+import { attemptHistory } from "./compose.ts";
 import { runShow, type ShowFlags } from "./index.ts";
 import { stringWidth } from "../report/text/layout.ts";
 
@@ -113,7 +113,7 @@ interface Captured {
 async function show(root: string, patterns: string[], flags: ShowFlags = {}, width = 100): Promise<Captured> {
   let out = "";
   let err = "";
-  const code = await runShow(root, patterns, { run: root, ...flags }, {
+  const code = await runShow(root, patterns, { results: root, ...flags }, {
     out: (s) => (out += s),
     err: (s) => (err += s),
     width,
@@ -169,7 +169,7 @@ describe("默认报告:跨快照合成的现刻水位(ExperimentComparison text
     try {
       const { out, code } = await show(root, []);
       expect(code).toBe(0);
-      expect(out).toContain("预估成本 × 端到端成功率 没有可绘制的数据");
+      expect(out).toContain("成本 × 端到端成功率 没有可绘制的数据");
       expect(out).toContain("1 通过 / 1 失败");
       expect(out).toMatch(/\bbub\s+默认\s+bub\s+1s\s+50%/);
     } finally {
@@ -199,6 +199,7 @@ describe("默认报告:跨快照合成的现刻水位(ExperimentComparison text
     ]);
     const { out, code } = await show(root, []);
     expect(code).toBe(0);
+    // 成本轴(better: lower)反向,「更好」恒指向右上;两轴都声明 better → 提示在场
     expect(out).toContain("better → upper right");
     expect(out).toContain("A compare/a   B compare/b");
     expect(out).toMatch(/\bb\s+large\s+claude\s+1s\s+100%/);
@@ -312,7 +313,7 @@ describe("单 eval 详情", () => {
     // 每 experiment 一行都带紧凑索引(locator + 失败原因),详情块再补一条精确的 attempt locator
     expect(out).toMatch(/✗ failed\s+2 attempts.*@1[0-9a-z]{7}.*gate calledTool/);
     expect(out).toMatch(/attempt locator: @1[0-9a-z]{7}/);
-    expect(out).toMatch(/next: niceeval show @1[0-9a-z]{7} \[--eval\|--execution\|--diff\]/);
+    expect(out).toMatch(/next: niceeval show @1[0-9a-z]{7} \[--source\|--execution\|--diff\]/);
   });
 });
 
@@ -349,61 +350,87 @@ describe("--history 时间轴", () => {
     return root;
   }
 
-  it("时间轴只列真实执行:复印件不占行,新失败带断言", async () => {
+  it("逐 attempt 分节:复印件按身份键去重不占行,startedAt 升序,行带摘要 / 成本 / locator", async () => {
     const root = await seedHistoryRoot();
     const results = await openResults(root);
     const exp = results.experiments.find((e) => e.id === "compare/bub")!;
-    const rows = evalHistory(exp, "weather/brooklyn");
-    // 快照2 里复印件被识别,真实执行只有:快照1 的 passed + 快照2 的 failed(新 attempt)
+    const rows = attemptHistory(exp, "weather/brooklyn");
+    // 快照2 里复印件被识别(与快照1 的真实执行同身份键),历次 attempt = 快照1 的 passed +
+    // 快照2 的 failed(新 attempt);startedAt 升序,旧的在前。
     expect(rows).toHaveLength(2);
-    expect(rows[0]).toMatchObject({ verdict: "failed", attempts: 1, costUSD: 0.04 });
-    expect(rows[0].failedAssertion).toBe('gate calledTool("get_weather")');
-    expect(rows[1]).toMatchObject({ verdict: "passed", attempts: 1, costUSD: 0.03 });
+    expect(rows[0]).toMatchObject({ verdict: "passed", costUSD: 0.03 });
+    expect(rows[0].summary).toBeUndefined();
+    expect(rows[1]).toMatchObject({ verdict: "failed", costUSD: 0.04 });
+    expect(rows[1].summary).toContain('calledTool("get_weather")');
+    expect(rows[1].locator).toMatch(/^@/);
 
     const { out, code } = await show(root, ["weather/brooklyn"], { history: true });
     expect(code).toBe(0);
-    expect(out).toContain("compare/bub · 2 runs · passed 1/2");
-    expect(out).toContain("2026-07-09T10-00");
-    expect(out).toContain("2026-07-07T09-00");
-    // 复印件那份 passed 判定只出现一行(快照1),不在快照2 再占一行
+    // 分节头:experimentId + evalId 一起出现,计数按 attempt。
+    expect(out).toContain("weather/brooklyn · compare/bub · 2 attempts · passed 1/2");
+    // 复印件那份 passed 判定只出现一行,不在快照2 再占一行;升序:passed 行在 failed 行之前。
     expect(out.match(/✓ passed/g)).toHaveLength(1);
+    expect(out.indexOf("✓ passed")).toBeLessThan(out.indexOf("✗ failed"));
+    // 每行携带可复制的 locator。
+    expect(out).toMatch(/@\w+/);
   });
 
-  it("裸 --history:每个 experiment 的 per-run 通过率序列", async () => {
+  it("裸 --history:对 Scope 中每个 experimentId + evalId 分节,不再输出快照级序列", async () => {
     const root = await seedHistoryRoot();
     const { out, code } = await show(root, [], { history: true });
     expect(code).toBe(0);
-    expect(out).toContain("compare/bub · 2 runs");
-    // 每个快照一行(快照2 折叠含携带的 passed 复印件,任一轮通过 → passed)
-    expect(out.match(/1\/1 passed/g)).toHaveLength(2);
+    expect(out).toContain("weather/brooklyn · compare/bub · 2 attempts · passed 1/2");
+    // 不是「每个快照一行」的通过率序列。
+    expect(out).not.toContain("1/1 passed");
+  });
+
+  it("--history 与 --page 组合是用法矛盾:直说", async () => {
+    const root = await seedHistoryRoot();
+    const { err, code } = await show(root, [], { history: true, page: "report" });
+    expect(code).toBe(1);
+    expect(err).toContain("--page");
   });
 });
 
 // ───────────────────────── --report 装载与组合语义 ─────────────────────────
 
 describe("--report 装载", () => {
-  /** 不经 niceeval 包也能造出合法报告:判别与双面组件都锚在 Symbol.for 上。 */
+  /**
+   * 不经 niceeval 包也能造出合法报告:判别、组合组件与双面组件都锚在 Symbol.for 上
+   * (docs/feature/reports/library/shell.md「defineReport 产物」、layout.md「自定义组件」)。
+   * Custom 是双面组件,读 props 直接渲染;Wrapper 是组合组件,用 ComposeContext 的 scope
+   * 算出 evals / locator 再装配进 Custom —— 对应 defineReport(<Wrapper />) 的展开形态。
+   */
   async function writeReportFile(dir: string): Promise<string> {
     const path = join(dir, "report.mjs");
     await writeFile(
       path,
       [
         'const FACES = Symbol.for("niceeval.report.faces");',
+        'const COMPOSE = Symbol.for("niceeval.report.compose");',
+        'const DEFINITION = Symbol.for("niceeval.report.definition");',
         "const Custom = () => null;",
         "Custom[FACES] = {",
         "  web: () => null,",
         "  text: (props, ctx) => `CUSTOM ${props.evals} · drill ${ctx.attemptCommand(props.locator)}`,",
         "};",
-        "export default {",
-        '  [Symbol.for("niceeval.report.definition")]: true,',
-        "  build: (ctx) => ({",
-        "    type: Custom,",
-        "    props: {",
-        "      evals: ctx.selection.snapshots.flatMap((s) => s.evals.map((e) => e.id)).sort().join(\",\"),",
-        "      locator: ctx.selection.snapshots[0].evals[0].attempts[0].locator,",
-        "    },",
-        "  }),",
+        "const Wrapper = () => null;",
+        "Wrapper[COMPOSE] = (props, ctx) => ({",
+        "  type: Custom,",
+        "  props: {",
+        "    evals: ctx.scope.snapshots.flatMap((s) => s.evals.map((e) => e.id)).sort().join(\",\"),",
+        "    locator: ctx.scope.snapshots[0].evals[0].attempts[0].locator,",
+        "  },",
+        "});",
+        "const definition = {",
+        '  kind: "report",',
+        "  links: [],",
+        "  scripts: [],",
+        "  styles: [],",
+        '  pages: [{ id: "report", title: "Report", content: { type: Wrapper, props: {} } }],',
         "};",
+        "Object.defineProperty(definition, DEFINITION, { value: true });",
+        "export default definition;",
         "",
       ].join("\n"),
       "utf-8",
@@ -473,6 +500,29 @@ describe("--report 装载", () => {
     expect(out).not.toContain("CUSTOM");
     expect(out).toContain("no diff recorded"); // fixture 没有 diff artifact:如实说缺
   });
+
+  it("--page 命中单页定义的唯一页 id `report`:与直接渲染等价", async () => {
+    const root = await seedComposedRoot();
+    const report = await writeReportFile(root);
+    const bare = await show(root, [], { report });
+    const paged = await show(root, [], { report, page: "report" });
+    expect(paged.code).toBe(0);
+    expect(paged.out).toBe(bare.out);
+  });
+
+  it("--page 未命中:按用法错误非零退出并列出可用页 id(内建报告同样成立)", async () => {
+    const root = await seedComposedRoot();
+    const report = await writeReportFile(root);
+    const miss = await show(root, [], { report, page: "typo" });
+    expect(miss.code).toBe(1);
+    expect(miss.err).toContain(`page "typo" not found in ${report}`);
+    expect(miss.err).toContain("Available pages: report");
+
+    const builtin = await show(root, [], { page: "typo" });
+    expect(builtin.code).toBe(1);
+    expect(builtin.err).toContain('page "typo" not found in the built-in report');
+    expect(builtin.err).toContain("Available pages: report");
+  });
 });
 
 // ───────────────────────── 证据切面:--execution ─────────────────────────
@@ -541,9 +591,9 @@ describe("--execution", () => {
   });
 });
 
-// ───────────────────────── 证据切面:--eval ─────────────────────────
+// ───────────────────────── 证据切面:--source ─────────────────────────
 
-describe("--eval", () => {
+describe("--source", () => {
   it("evalSource === null 时如实说源码未捕获", async () => {
     const root = await makeRoot();
     await writeSnapshot(
@@ -552,7 +602,7 @@ describe("--eval", () => {
       { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" },
       [res("weather/brooklyn", "failed", { assertions: [{ name: "succeeded()", severity: "gate", score: 0, outcome: "failed" as const }] })],
     );
-    const { out, code } = await show(root, ["weather/brooklyn"], { eval: true });
+    const { out, code } = await show(root, ["weather/brooklyn"], { source: true });
     expect(code).toBe(0);
     expect(out).toContain("eval source unavailable for this attempt");
   });
@@ -586,7 +636,7 @@ describe("--eval", () => {
     await mkdir(join(dir, "sources"), { recursive: true });
     await writeFile(join(dir, "sources", `${sha}.json`), JSON.stringify({ content }), "utf-8");
 
-    const { out, code } = await show(root, ["weather/brooklyn"], { eval: true });
+    const { out, code } = await show(root, ["weather/brooklyn"], { source: true });
     expect(code).toBe(0);
     expect(out).toContain(`eval source: evals/weather/brooklyn.eval.ts · sha256:${sha.slice(0, 8)}`);
     // 源码行的缩进是语义的一部分,渲染必须原样保留(不按词重排折叠掉这两个空格)。
@@ -608,7 +658,7 @@ describe("--eval", () => {
     await writeFile(join(attemptDir, "sources.json"), JSON.stringify([{ path: "evals/manager.eval.ts", sha256: sha }]), "utf-8");
     await mkdir(join(dir, "sources"), { recursive: true });
     await writeFile(join(dir, "sources", `${sha}.json`), JSON.stringify({ content }), "utf-8");
-    const { out } = await show(root, ["manager"], { eval: true });
+    const { out } = await show(root, ["manager"], { source: true });
     expect(out).toContain("gate · Issue 15193 · equals(4) · expected 4 · received 1");
   });
 });
@@ -702,7 +752,7 @@ describe("show @<locator>", () => {
 
     const { out, code } = await show(root, [locator]);
     expect(code).toBe(0);
-    expect(out).toContain(`available:\n  niceeval show ${locator} --eval\n  niceeval show ${locator} --execution`);
+    expect(out).toContain(`available:\n  niceeval show ${locator} --source\n  niceeval show ${locator} --execution`);
     expect(out).not.toContain(`niceeval show ${locator} --diff`);
     expect(out).not.toContain("evidence:");
     expect(out).not.toContain("next:");