niceeval 0.6.1 → 0.7.0

package/src/view/data.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
 // view 数据层(data.ts)的单测:loader 收编到 openResults、统计整体住进报告槽之后,
 // 守护三件事——skipped 三种原因如实进 viewData(producer 感知的 npx 提示)、报告槽是
 // 现刻水位口径(裸跑经 selectCurrentResults 跨快照合成每 experiment × eval 的最新判定,
@@ -110,7 +111,9 @@ describe("loadViewScan · skipped 三种原因进 viewData", () => {
     await mkdir(join(incompleteDir, "q1", "a0"), { recursive: true });
     await writeFile(join(incompleteDir, "q1", "a0", "events.json"), "[]", "utf-8");
 
-    const { viewData, reportHtml } = await loadViewScan(root);
+    const scan = await loadViewScan(root);
+    const { viewData } = scan;
+    const reportHtml = scan.reportPages[0]!.html;
     const byReason = new Map(viewData.skippedRuns!.map((s) => [s.dir, s]));
     expect(viewData.skippedRuns).toHaveLength(4);
 
@@ -160,7 +163,9 @@ describe("loadViewScan · 报告槽是现刻水位口径,裸跑与局部收窄
       res("q1", "passed"),
     ]);
 
-    const { viewData, reportHtml } = await loadViewScan(root);
+    const scan = await loadViewScan(root);
+    const { viewData } = scan;
+    const reportHtml = scan.reportPages[0]!.html;
     // 现刻水位:q1 取周二(更新,通过),q2 取周一(仅此一次,通过)—— 两题全过(2/2 = 100%),
     // 不是「只看周二快照的 1/1」。深链分别指向各自的贡献快照(AttemptLocator 由身份元组——
     // 含快照 startedAt——确定性派生,两个不同快照的 q1/q2 编出两个不同的 locator)。
@@ -250,7 +255,9 @@ describe("loadViewScan · 新布局落盘直接可读(写入面 / 读取面同
       ],
     );
 
-    const { viewData, reportHtml } = await loadViewScan(root);
+    const scan = await loadViewScan(root);
+    const { viewData } = scan;
+    const reportHtml = scan.reportPages[0]!.html;
     // 报告槽(ExperimentComparison 的 web 面):Experiment 工作台行 + 官方通过率格子(1 过 1 败 = 50%)。
     expect(reportHtml.en).toContain("compare/bub");
     expect(reportHtml.en).toContain("50%");

package/src/view/data.ts

@@ -1,25 +1,37 @@
 // view 的数据层:读取经 niceeval/results 的 openResults(布局/版本知识只住在那)。
-// 这里只做编排:报告槽 Selection 恒经 selectCurrentResults(现刻水位;与 show 调同一个函数,
-// 两扇门判定不分叉)、快照明细注入(locator / artifactBase)、skipped 透传、报告槽渲染
-// (renderReportSlot:裸跑填充 ExperimentComparison,--report 整槽替换,en / zh-CN 双语各渲染一遍)。
-// --report 只换报告定义,注入的 Selection 与裸跑同一份。统计口径整体住在报告槽里
+// 这里只做编排:报告槽 Scope 恒经 selectCurrentResults(现刻水位;与 show 调同一个函数,
+// 两扇门判定不分叉)、快照明细注入(locator / artifactBase)、skipped 透传、报告装载与逐页渲染
+// (裸跑填充 niceeval/report/built-in 的默认导出,--report 整槽替换,en / zh-CN 双语各渲染一遍)。
+// --report 只换报告定义,注入的 Scope 与裸跑同一份。统计口径整体住在报告页里
 // (报告组件的官方计算函数),viewData 不再携带 overview / 榜单这类统计产物,
 // 见 docs/feature/reports/view.md「打开与收窄」。
 
-import { statSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { dedupeAttempts, openResults } from "../results/index.ts";
-import type { AttemptHandle, Results, Selection, Snapshot, SkippedDir } from "../results/index.ts";
-// dist-sourced: ReportDefinition/ReportLoadError identity must match the built-ins/web.ts
-// module instance renderReportSlot() dynamically imports below (see its comment).
-import { loadReportFile } from "../../dist/report/load.js";
+import type { AttemptHandle, Results, Scope, Snapshot, SkippedDir } from "../results/index.ts";
+import {
+  loadHostReport,
+  renderHostPageHtml,
+  reportMetaFor,
+  resolveReportTitle,
+  type HostReport,
+  type HostReportAsset,
+} from "../show/report-host.ts";
 import { selectCurrentResults, filterExperiments } from "../results/select.ts";
 import type { EvalResult } from "../types.ts";
-import type { ReportSlotHtml, SkippedRunNotice, ViewData, ViewEvalResult, ViewSnapshot } from "./shared/types.ts";
+import type {
+  SkippedRunNotice,
+  ViewData,
+  ViewEvalResult,
+  ViewReportMeta,
+  ViewReportPageHtml,
+  ViewSnapshot,
+} from "./shared/types.ts";
 import { t } from "../i18n/index.ts";
 import { RESULTS_SCHEMA_VERSION } from "../types.ts";
 
-export type { ReportSlotHtml } from "./shared/types.ts";
+export type { ViewReportMeta, ViewReportPageHtml } from "./shared/types.ts";
 
 export interface ViewScan {
   viewData: ViewData;
@@ -36,22 +48,38 @@ export interface ViewScan {
    */
   attemptsByBase: Map<string, AttemptHandle>;
   /**
-   * 报告槽:报告树经 renderReportToStaticHtml 渲染出的静态 HTML(en / zh-CN 各一份),
-   * 裸跑填充内置默认报告 ExperimentComparison,--report 整槽替换。作为两个 <template> 静态块
-   * 烘进页面(与 __NICEEVAL_VIEW_DATA__ 相邻),不进 viewData —— 前端只负责把当前
-   * 界面语言对应的那块 HTML 摆进报告槽位置,不解析。
+   * 报告页:每页渲染成静态 HTML(en / zh-CN 各一份),裸跑填充内建报告(单页 id `report`),
+   * --report 整槽替换(树 / 配置对象形态都规范化成页列表)。作为 <template
+   * id="niceeval-report-<pageId>-<locale>"> 静态块烘进页面(与 __NICEEVAL_VIEW_DATA__ 相邻),
+   * HTML 本体不进 viewData —— 前端只负责把当前页 / 当前界面语言对应的块摆进报告槽位置,不解析。
    */
-  reportHtml: ReportSlotHtml;
+  reportPages: ViewReportPageHtml[];
+  /** 外壳注入资产(styles / scripts;{src} 已按路径纪律解析成 inline 内容),只进 web 面。 */
+  shellAssets: { styles: string[]; scripts: string[] };
+  /**
+   * --out 的数据等级(见 docs/feature/reports/view.md「静态导出」):全部选中快照带
+   * publish:{redaction:"applied"} 才是 "applied",否则 "sensitive"(含本地事实根与
+   * redaction:"none"——上游声明过原文发布也不豁免导出时的确认)。
+   */
+  publishState: "applied" | "sensitive";
 }
 
-/** view 宿主输入的组合语义(与 show 对齐,docs/feature/reports/architecture.md「Selection 是计算入口」)。 */
+/** view 宿主输入的组合语义(与 show 对齐,docs/feature/reports/architecture.md「Scope 是计算入口」)。 */
 export interface ViewScanOptions {
-  /** eval id 前缀(位置参数):收窄报告槽 Selection;证据室(快照明细)不收窄,深链恒可达。 */
+  /** eval id 前缀(位置参数):收窄报告槽 Scope;证据室(快照明细)不收窄,深链恒可达。 */
   patterns?: string[];
-  /** experiment id 前缀(--experiment):Selection 只留该实验。 */
+  /** experiment id 前缀(--experiment):Scope 只留该实验。 */
   experiment?: string;
   /** --report 报告文件:相对 cwd 的路径。装载失败抛 ReportLoadError(CLI 打印后退出)。 */
   report?: { path: string; cwd: string };
+  /** --page:多页报告的初始页 id;未命中任何页按用法错误退出并列出可用页 id。 */
+  page?: string;
+  /**
+   * 单页渲染失败的处置(docs/feature/reports/architecture.md「管线以页为单位执行」):
+   * 本地 server 传 "embed"(该页显示完整错误反馈,其它页照常可读);静态导出与启动前预检
+   * 缺省 "throw"(任一页失败整体失败,不产出半套站点)。
+   */
+  pageFailure?: "throw" | "embed";
 }
 
 /** 可预期的用户输入错误:CLI 打一句英文直说问题与下一步,退出码 1,不抛堆栈。 */
@@ -68,7 +96,7 @@ export interface IncompatibleRun {
 /** 用能读这份报告的 niceeval 版本查看的命令;第三方 harness 的落盘拼不出 npx,返回 undefined。 */
 export function incompatibleViewCommand(run: IncompatibleRun): string | undefined {
   if (run.producer && run.producer.name !== "niceeval") return undefined;
-  return `npx niceeval@${run.producer?.version ?? "<version>"} view ${run.dir}`;
+  return `npx niceeval@${run.producer?.version ?? "<version>"} view --snapshot ${run.dir}/snapshot.json`;
 }
 
 /** 版本不匹配的完整提示文案;CLI 单文件模式和目录扫描占位共用。 */
@@ -200,9 +228,10 @@ export async function loadViewScan(input?: string, opts: ViewScanOptions = {}):
     );
   }
 
-  // 报告槽:裸跑填充 ExperimentComparison,--report 整槽替换。报告吃同一份注入 Selection,
-  // web 面在计算侧静态渲染成 HTML(en / zh-CN 各一遍,切界面语言不重算数据)。
-  const reportHtml = await renderReportSlot(opts.report, results, selection);
+  // 报告槽:裸跑装载内建报告默认导出,--report 整槽替换——同一条「装载 → 规范化 → 逐页渲染」
+  // 管线(docs/feature/reports/library/shell.md)。报告吃同一份注入 Scope,web 面在计算侧
+  // 静态渲染成 HTML(en / zh-CN 各一遍,切界面语言不重算数据)。
+  const slot = await renderReportSlot(opts.report, opts.page, results, selection, opts.pageFailure ?? "throw");
 
   // 跨快照按身份键去重:--resume 携带的条目在多份落盘里重复,只保留最新快照里的那份
   // (与官方计算函数的聚合口径一致,Runs / Traces 的计数因此不被复印件灌票)。
@@ -243,7 +272,8 @@ export async function loadViewScan(input?: string, opts: ViewScanOptions = {}):
     }
   }
 
-  // 全局最新快照(跨全部实验):hero 的项目名 / 最近一次运行时刻从这里取。
+  // 全局最新快照(跨全部实验):hero 的「最近一次运行」时刻从这里取。
+  // hero 标题不从这里取——它走标题回退链(resolveReportTitle,进 viewData.report.title)。
   let latestSnapshot: Snapshot | undefined;
   for (const exp of results.experiments) {
     const candidate = exp.snapshots[0];
@@ -252,16 +282,27 @@ export async function loadViewScan(input?: string, opts: ViewScanOptions = {}):
   }
 
   const viewData: ViewData = {
-    ...(latestSnapshot?.name !== undefined ? { name: latestSnapshot.name } : {}),
     ...(latestSnapshot ? { lastRunAt: latestSnapshot.startedAt } : {}),
-    // 合成 Selection 的快照是跨快照拼出来的,来源物理 run 数从 attempt 自己的 snapshot
-    // 反向引用取——每个 attempt 的 .snapshot 恒指向它真实所在的贡献快照(无论 Selection
+    // 合成 Scope 的快照是跨快照拼出来的,来源物理 run 数从 attempt 自己的 snapshot
+    // 反向引用取——每个 attempt 的 .snapshot 恒指向它真实所在的贡献快照(无论 Scope
     // 是否合成),所以这条对裸跑与收窄一律成立,不需要分支。
     composedRuns: new Set(selection.snapshots.flatMap((s) => s.attempts.map((a) => a.snapshot.dir))).size,
     snapshots,
     skippedRuns: results.skipped.map(toSkippedNotice),
+    report: slot.meta,
+  };
+  const publishState =
+    selection.snapshots.length > 0 && selection.snapshots.every((snap) => snap.publish?.redaction === "applied")
+      ? ("applied" as const)
+      : ("sensitive" as const);
+  return {
+    viewData,
+    artifactDirs,
+    attemptsByBase,
+    reportPages: slot.pages,
+    shellAssets: slot.shellAssets,
+    publishState,
   };
-  return { viewData, artifactDirs, attemptsByBase, reportHtml };
 }
 
 /**
@@ -286,34 +327,99 @@ export async function loadAttemptIndex(input?: string): Promise<Map<string, Atte
   return index;
 }
 
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** 外壳 `{src}` 资产的路径纪律(shell.md「行为约束」):相对报告文件解析;拒绝 `..` 路径段、绝对路径与 `~`。 */
+function resolveShellAssets(assets: HostReportAsset[], baseDir: string | undefined, kind: "styles" | "scripts"): string[] {
+  const out: string[] = [];
+  for (const asset of assets) {
+    if (asset.inline !== undefined) {
+      out.push(asset.inline);
+      continue;
+    }
+    const src = asset.src;
+    if (src.startsWith("/") || src.startsWith("~") || src.split("/").includes("..")) {
+      throw new ViewInputError(
+        `Report ${kind} asset "${src}" is not a plain relative path. Assets resolve relative to the report file; ".." segments, absolute paths and "~" are not allowed.`,
+      );
+    }
+    const abs = resolve(baseDir ?? process.cwd(), src);
+    try {
+      out.push(readFileSync(abs, "utf-8"));
+    } catch {
+      throw new ViewInputError(`Report ${kind} asset not found: ${abs} (declared as "${src}").`);
+    }
+  }
+  return out;
+}
+
 /**
- * 报告槽渲染:装载报告文件(--report;dev server 语义 —— 文件变更下次请求整页重算,
- * 经 mtime cache-busting),缺省用内置默认报告 ExperimentComparison → 注入 Selection →
- * web 面 renderToStaticMarkup 成静态 HTML,en / zh-CN 各渲染一遍(chrome 文案按 locale)。
+ * 报告装载与逐页渲染:装载报告文件(--report;dev server 语义 —— 文件变更下次请求整页重算,
+ * 经 mtime cache-busting),缺省装载内建报告默认导出 → 规范化成「外壳 + 非空页列表」→
+ * 注入 Scope → 每页 web 面渲染成静态 HTML,en / zh-CN 各渲染一遍(chrome 文案按 locale)。
+ * 本地 server 下单页渲染失败折成该页的完整错误反馈块,其它页照常可读(静态导出的
+ * 「任一页失败整体失败」由 buildView 侧的 failFast 保证)。
  * react / react-dom 动态加载:data.ts 还被 runner 的续跑携带(loadLatestResultsPerEval)
- * 消费,渲染依赖不进那条路径。attemptHref 缺省即 `#/attempt/@<locator>` 深链路由(web.ts 的默认值),
- * 单段、不透明——证据室(`src/view/app/`)的 attempt 路由消费同一个格式(attempt-route.ts),
- * 报告槽深链与证据室深链是同一条路由的两个来源。
+ * 消费,渲染依赖不进那条路径。attemptHref 缺省即 `#/attempt/@<locator>` 深链路由,
+ * 报告页深链与证据室深链是同一条路由的两个来源。
  */
 async function renderReportSlot(
   report: { path: string; cwd: string } | undefined,
+  page: string | undefined,
   results: Results,
-  selection: Selection,
-): Promise<ReportSlotHtml> {
-  // built-ins/index.ts 和 web.ts 都碰 JSX(.tsx / import react-dom);package-owned 的报告
-  // runtime 走预编译产物(dist/report/**,`pnpm run build:report` 产出),不受 view 消费方
-  // cwd/tsconfig 影响 —— 见 tsconfig.report-build.json。两个动态 import 必须落在同一份编译
-  // 产物图里(dist/report/tree.js 的 WebContext 模块级状态不能跨实例),不能一个走 dist
-  // 一个走 src。
-  const definition = report
-    ? await loadReportFile(report.cwd, report.path, { freshImport: true })
-    : (await import("../../dist/report/built-ins/index.js")).ExperimentComparison;
-  const { renderReportToStaticHtml } = await import("../../dist/report/web.js");
-  const ctx = { selection, results };
-  return {
-    en: await renderReportToStaticHtml(definition, ctx, { locale: "en" }),
-    "zh-CN": await renderReportToStaticHtml(definition, ctx, { locale: "zh-CN" }),
+  selection: Scope,
+  pageFailure: "throw" | "embed" = "throw",
+): Promise<{ meta: ViewReportMeta; pages: ViewReportPageHtml[]; shellAssets: { styles: string[]; scripts: string[] } }> {
+  // 报告 runtime 走预编译产物(dist/report/**,`pnpm run build:report` 产出),不受 view
+  // 消费方 cwd/tsconfig 影响;装载与渲染统一经 ../show/report-host.ts(两个宿主共用的联系面)。
+  const hostReport: HostReport = await loadHostReport(report?.cwd ?? process.cwd(), report?.path, {
+    freshImport: true,
+  });
+
+  const initialPageId = page ?? hostReport.pages[0]!.id;
+  if (!hostReport.pages.some((p) => p.id === initialPageId)) {
+    throw new ViewInputError(
+      `error: page "${page}" not found in ${report?.path ?? "the built-in report"}. Available pages: ${hostReport.pages.map((p) => p.id).join(", ")}`,
+    );
+  }
+
+  const reportDir = report ? dirname(resolve(report.cwd, report.path)) : undefined;
+  const shellAssets = {
+    styles: resolveShellAssets(hostReport.styles, reportDir, "styles"),
+    scripts: resolveShellAssets(hostReport.scripts, reportDir, "scripts"),
+  };
+
+  const pages: ViewReportPageHtml[] = [];
+  for (const hostPage of hostReport.pages) {
+    const meta = reportMetaFor(hostReport, hostPage.id, selection.snapshots);
+    const ctx = { scope: selection, results, report: meta };
+    try {
+      pages.push({
+        id: hostPage.id,
+        html: {
+          en: await renderHostPageHtml(hostPage, ctx, { locale: "en" }),
+          "zh-CN": await renderHostPageHtml(hostPage, ctx, { locale: "zh-CN" }),
+        },
+      });
+    } catch (e) {
+      if (pageFailure !== "embed") throw e;
+      // 本地 server:该页显示完整错误反馈,其它页照常可读(不让一页的树错误拖垮整站)。
+      const message = e instanceof Error ? e.message : String(e);
+      const block = `<div class="nre nre-page-error"><pre>${escapeHtml(message)}</pre></div>`;
+      pages.push({ id: hostPage.id, html: { en: block, "zh-CN": block } });
+    }
+  }
+
+  const meta: ViewReportMeta = {
+    title: resolveReportTitle(hostReport.title, selection.snapshots),
+    links: hostReport.links,
+    ...(hostReport.footer !== undefined ? { footer: hostReport.footer } : {}),
+    pages: hostReport.pages.map((p) => ({ id: p.id, title: p.title })),
+    initialPageId,
   };
+  return { meta, pages, shellAssets };
 }
 
 /**

package/src/view/index.ts

@@ -22,64 +22,54 @@ export {
 } from "./data.ts";
 
 /**
- * view 的位置参数语义(与 CLI 模型一致:位置参数选「看哪些 eval」):
- * - 恰好一个位置参数且指向存在的文件 → 单文件模式(`niceeval view <summary.json>`),
- *   不与 --run 或其它位置参数混用;
- * - 指向存在的目录 → 报错直说:目录经 `--run <dir>` 递入,位置参数留给 eval id 前缀;
- * - 其余 → eval id 前缀,收窄报告槽 Selection(经 show 同一套 Selection 合成)。
+ * view 的输入语义(docs/feature/reports/view.md「打开与收窄」):位置参数只有一种含义——
+ * eval id 前缀,与 show 一致,含义不随文件系统状态改变(路径样子的位置参数只会按前缀报无匹配)。
+ * 结果根经 `--results <dir>` 递入;单开一份快照经 `--snapshot <file>` 递入,文件不可读时
+ * 命令失败(扫描模式对坏快照只跳过)。两个来源互斥。
  */
 export function resolveViewInput(
   cwd: string,
   positionals: string[],
-  run?: string,
+  opts: { results?: string; snapshot?: string } = {},
 ): { input?: string; patterns: string[] } {
-  if (run !== undefined) {
-    const dir = resolve(cwd, run);
+  const { results, snapshot } = opts;
+  if (results !== undefined && snapshot !== undefined) {
+    throw new ViewInputError(
+      "--results and --snapshot are mutually exclusive: --results scans a results root, --snapshot opens exactly one snapshot file.",
+    );
+  }
+  if (results !== undefined) {
+    const dir = resolve(cwd, results);
     if (!existsSync(dir)) {
       throw new ViewInputError(`Results directory not found: ${dir}`);
     }
+    return { input: dir, patterns: positionals };
   }
-  const kindOf = (p: string): "file" | "dir" | "pattern" => {
+  if (snapshot !== undefined) {
+    const file = resolve(cwd, snapshot);
+    let isFile = false;
     try {
-      const stat = statSync(resolve(cwd, p));
-      return stat.isFile() ? "file" : stat.isDirectory() ? "dir" : "pattern";
+      isFile = statSync(file).isFile();
     } catch {
-      return "pattern";
-    }
-  };
-  for (const p of positionals) {
-    const kind = kindOf(p);
-    if (kind === "dir") {
-      throw new ViewInputError(
-        `"${p}" is a directory. Pass results directories with --run (niceeval view --run ${p}); positional arguments select evals by id prefix.`,
-      );
-    }
-    if (kind !== "file") continue;
-    if (positionals.length > 1) {
-      throw new ViewInputError(
-        `"${p}" is a summary file, but more positional arguments were given. Single-file mode takes exactly one path: niceeval view ${p}`,
-      );
+      isFile = false;
     }
-    if (run !== undefined) {
+    if (!isFile) {
       throw new ViewInputError(
-        `"${p}" is a summary file and cannot be combined with --run. Pass either the file (niceeval view ${p}) or the results dir (niceeval view --run <dir>).`,
+        `--snapshot expects a readable snapshot file, got: ${file}. Pass the snapshot.json of one run, or scan a results root with --results <dir>.`,
       );
     }
-    return { input: resolve(cwd, p), patterns: [] };
+    return { input: file, patterns: positionals };
   }
-  return {
-    ...(run !== undefined ? { input: resolve(cwd, run) } : {}),
-    patterns: positionals,
-  };
+  return { patterns: positionals };
 }
 
 /**
  * 导出静态报告(--out):只有目录式一种形态。写 <dir>/index.html,并把前端会 fetch 的 artifact
- * (sources.json / events.json / trace.json)复制到 <dir>/artifact/<base>/——与本地
+ * (sources.json / events.json / trace.json / diff.json)复制到 <dir>/artifact/<base>/——与本地
  * server 的 /artifact/<rel> 路由同一布局,整个目录扔给任何静态托管即是完整体验。
- * 首页即报告槽(裸跑填充 ExperimentComparison,--report 整槽替换),证据室同站。
- * 单文件(*.html)导出已移除:代码/transcript/trace 视图依赖 artifact 文件,单文件注定残缺,
- * 存在本身就在诱导用户导出一份看不了证据的报告(docs/feature/reports/view.md「静态导出」)。
+ * 首页即报告槽(裸跑填充内建报告,--report 整槽替换),证据室同站;多页报告仍是单个
+ * index.html(页面走 `#/page/<id>` 路由)。单文件(*.html)导出已移除:代码/transcript/trace
+ * 视图依赖 artifact 文件,单文件注定残缺(docs/feature/reports/view.md「静态导出」)。
  */
 export async function buildView(opts: ViewOptions = {}): Promise<string> {
   const out = resolve(opts.out ?? ".niceeval/site");
@@ -88,19 +78,44 @@ export async function buildView(opts: ViewOptions = {}): Promise<string> {
       `--out expects a directory, got "${opts.out}". Single-file HTML export was removed: code, transcript and trace views need artifact files next to the page. Export a directory instead (e.g. --out site) and serve it with any static host.`,
     );
   }
+  // --out 与位置参数 / --experiment 互斥(docs/feature/reports/view.md「静态导出」):报告槽收窄
+  // 只影响报告,证据室恒随根完整——允许同用会让发布者误以为站点只含该实验,实际根里全部
+  // attempt 的证据都已出站。按实验收窄发布 = 用 copySnapshots 构建只含它的发布根,再对新根导出。
+  if ((opts.scan?.patterns?.length ?? 0) > 0 || opts.scan?.experiment !== undefined) {
+    throw new ViewInputError(
+      "--out exports the whole results root and cannot be combined with eval prefixes or --experiment.\n" +
+        "To publish a site for one experiment, build a narrower results root and export that:\n" +
+        '  const results = await openResults(".niceeval");\n' +
+        '  await copySnapshots(results.latest().filter((s) => s.experimentId.startsWith("<prefix>/")), "<publish-root>", { redact });\n' +
+        "Then: niceeval view --results <publish-root> --out <site>",
+    );
+  }
   const scan = await loadViewScan(opts.input, opts.scan);
+  // --out 按发布防呆二分(见 docs/feature/reports/view.md「静态导出」):目标结果根的全部快照
+  // 带 publish:{redaction:"applied"}(copySnapshots 补记)时直接导出;redaction:"none"、
+  // 无标记结果或本地事实根,都必须显式传 --allow-sensitive-artifacts——静态站原样携带证据文件,
+  // 上游声明过原文发布也不豁免这里的确认。
+  if (!opts.allowSensitiveArtifacts && scan.publishState !== "applied") {
+    throw new ViewInputError(
+      `--out refuses to export unredacted results: not every selected snapshot carries publish: { redaction: "applied" }. ` +
+        `Produce a publish root first with copySnapshots({ redact }) and export that (niceeval view --results <publish-root> --out <site>), ` +
+        `or pass --allow-sensitive-artifacts to explicitly export raw evidence (prompts, tool args, full outputs, sources).`,
+    );
+  }
   await mkdir(out, { recursive: true });
   await writeFile(join(out, "index.html"), await renderHtml(scan), "utf-8");
   await copyFetchedArtifacts(scan, join(out, "artifact"));
   return out;
 }
 
-// 只导出前端会 fetch 的三类 artifact。diff.json / o11y.json 是运行侧产物,查看器从不读取,
-// 且 diff 可达上百 MB,带进静态导出只会拖垮部署体积。events.json / trace.json 原字节复制;
-// sources.json 是例外——盘上是去重后的引用(`{path, sha256}[]`),必须先经
+// 导出没有档位(docs/feature/reports/view.md「静态导出」):结果根里存在且前端会读取的证据
+// 文件全部复制——events.json / trace.json / diff.json 原字节复制(diff 有就带,缺时前端在
+// 证据位置如实显示缺失;体积取舍在构建发布根时用 copySnapshots({ artifacts }) 做,不在导出层);
+// 唯一永不复制的是 o11y.json——报告数字在导出时已烘进 HTML,浏览器不读它。
+// sources.json 是格式例外——盘上是去重后的引用(`{path, sha256}[]`),必须先经
 // AttemptHandle.sources() 解引用出完整内容(`{path, content}[]`)再写出,否则浏览器端的
 // isCodeSource 守卫因缺 content 字段判空,代码视图会误判「源码未捕获」(即便源码明明捕获了)。
-const RAW_COPY_ARTIFACTS = ["events.json", "trace.json"];
+const RAW_COPY_ARTIFACTS = ["events.json", "trace.json", "diff.json"];
 
 async function copyFetchedArtifacts(scan: ViewScan, artifactRoot: string): Promise<void> {
   for (const [base, srcDir] of scan.artifactDirs) {

package/src/view/server.ts

@@ -6,12 +6,15 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { loadAttemptIndex, loadViewScan, viewRoot, type ViewScan, type ViewScanOptions } from "./data.ts";
 import type { AttemptHandle } from "../results/index.ts";
+import { localizeText } from "../show/report-host.ts";
 import { formatThrown } from "../util.ts";
 
 export interface ViewOptions {
   input?: string;
   out?: string;
   port?: number;
+  /** `--out` 对非发布根(无 publish:applied 标记)导出时的显式确认;静态站原样携带证据文件。 */
+  allowSensitiveArtifacts?: boolean;
   /** 报告槽的组合语义(位置前缀 / --experiment / --report),透传给 loadViewScan。 */
   scan?: ViewScanOptions;
 }
@@ -31,9 +34,11 @@ const TEMPLATE_PLACEHOLDERS = {
 export async function startViewServer(opts: ViewOptions = {}): Promise<ViewServer> {
   const input = opts.input;
   const root = viewRoot(input);
-  // 数据装载先跑一遍:单文件模式指向读不了的报告、--report 装载失败、
+  // 本地 server 的单页失败折成该页的错误块,其它页照常可读(静态导出仍整体失败)。
+  const scanOptions = { ...opts.scan, pageFailure: "embed" as const };
+  // 数据装载先跑一遍:--snapshot 指向读不了的快照、--report 装载失败、
   // 前缀匹配不到,都要在起 server 前就失败并给出提示。
-  await loadViewScan(input, opts.scan);
+  await loadViewScan(input, scanOptions);
   const server = createServer(async (req, res) => {
     try {
       const url = new URL(req.url ?? "/", "http://127.0.0.1");
@@ -65,7 +70,7 @@ export async function startViewServer(opts: ViewOptions = {}): Promise<ViewServe
       });
       // 每次请求现读现算,永远是盘上最新数据;--report 的报告文件变更同样在
       // 下次请求整页重算(装载走 mtime cache-busting,见 report/load.ts)。
-      res.end(await renderHtml(await loadViewScan(input, opts.scan)));
+      res.end(await renderHtml(await loadViewScan(input, scanOptions)));
     } catch (e) {
       res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
       res.end(formatThrown(e));
@@ -84,12 +89,13 @@ export async function startViewServer(opts: ViewOptions = {}): Promise<ViewServe
 
 /**
  * 把 viewData(只含原始值与相对路径,不含宿主机绝对路径)和前端产物烘焙进单个 HTML。
- * 报告槽恒在:报告 HTML 作为 <template id="niceeval-report-en"> / <template
- * id="niceeval-report-zh-CN"> 两个静态块烘在 __NICEEVAL_VIEW_DATA__ 旁(不 hydrate,
- * 自定义组件的 <Style> 产物已内联其中),并恒内联官方组件样式(report/react/styles.css)
- * 与渐进增强 runtime(report/react/enhance.js,内联 <script>:排序 / 过滤 / tooltip,
- * document 级事件委托,报告块被前端搬进槽位也无需重绑;无 JS 时报告内容依旧完整);
- * 前端只把当前界面语言对应的那块摆进报告槽位置,不解析。
+ * 报告槽恒在:每页报告 HTML 作为 <template id="niceeval-report-<pageId>-<locale>"> 静态块
+ * 烘在 __NICEEVAL_VIEW_DATA__ 旁(不 hydrate,自定义组件的 <Style> 产物已内联其中),
+ * 并恒内联官方组件样式(report/react/styles.css)与渐进增强 runtime(report/react/enhance.js,
+ * 内联 <script>:排序 / 过滤 / tooltip,document 级事件委托,报告块被前端搬进槽位也无需重绑;
+ * 无 JS 时报告内容依旧完整);外壳声明的 styles 注入在官方样式之后、scripts 注入在官方
+ * 增强脚本之后 </body> 前,均按声明顺序(docs/feature/reports/library/shell.md)。
+ * 前端只把当前页 / 当前界面语言对应的块摆进报告槽位置,不解析。
  */
 export async function renderHtml(scan: ViewScan): Promise<string> {
   const template = await readViewAsset("template.html");
@@ -100,19 +106,35 @@ export async function renderHtml(scan: ViewScan): Promise<string> {
     readFile(new URL("../report/react/enhance.js", import.meta.url), "utf-8"),
   ]);
 
+  const shellStyles = scan.shellAssets.styles.map((css) => `\n<style>\n${css}\n</style>`).join("");
+  const shellScripts = scan.shellAssets.scripts.map((js) => `<script>\n${js}\n</script>\n`).join("");
+
+  const pageTemplates = scan.reportPages
+    .flatMap((page) => [
+      `<template id="niceeval-report-${page.id}-en">${page.html.en}</template>`,
+      `<template id="niceeval-report-${page.id}-zh-CN">${page.html["zh-CN"]}</template>`,
+    ])
+    .join("\n");
+
+  // 初始 <title> 与 hero 同源:走完回退链的报告标题(viewData.report.title;终点是内置文案
+  // 「Eval 运行结果 / Eval Results」)。模板 lang="en",初始按 en 解析;前端按界面语言更新。
+  const title = localizeText(scan.viewData.report?.title, "en") ?? "Eval Results";
+
   return template
     .replace(
-      TEMPLATE_PLACEHOLDERS.styles,
-      () => `<style>\n${styles}\n</style>\n<style>\n${reportStyles}\n</style>\n<script>\n${reportEnhance}\n</script>`,
+      /<title>[^<]*<\/title>/,
+      () => `<title>${title.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}</title>`,
     )
     .replace(
-      TEMPLATE_PLACEHOLDERS.reportSlot,
+      TEMPLATE_PLACEHOLDERS.styles,
       () =>
-        `<template id="niceeval-report-en">${scan.reportHtml.en}</template>\n` +
-        `<template id="niceeval-report-zh-CN">${scan.reportHtml["zh-CN"]}</template>`,
+        `<style>\n${styles}\n</style>\n<style>\n${reportStyles}\n</style>\n<script>\n${reportEnhance}\n</script>` +
+        shellStyles,
     )
+    .replace(TEMPLATE_PLACEHOLDERS.reportSlot, () => pageTemplates)
     .replace(TEMPLATE_PLACEHOLDERS.viewData, () => JSON.stringify(scan.viewData).replace(/</g, "\\u003c"))
-    .replace(TEMPLATE_PLACEHOLDERS.appCode, () => JSON.stringify(app).replace(/</g, "\\u003c"));
+    .replace(TEMPLATE_PLACEHOLDERS.appCode, () => JSON.stringify(app).replace(/</g, "\\u003c"))
+    .replace("</body>", () => `${shellScripts}</body>`);
 }
 
 /** rel 的末段文件名;base = 去掉末段后剩下的部分(与 artifactUrl 的按段编码/拼接对称)。 */

package/src/view/shared/types.ts

@@ -12,11 +12,40 @@ import type { AttemptLocator } from "../../results/locator.ts";
 export type { AttemptLocator };
 
 /**
- * 报告槽的双语静态 HTML:同一棵报告树按 locale 渲染两遍(en / zh-CN),server 烘成
- * 两个 <template> 静态块,前端按当前界面语言摆放对应块,切语言不重算数据。
+ * 一页报告的双语静态 HTML:同一棵页树按 locale 渲染两遍(en / zh-CN),server 烘成
+ * <template id="niceeval-report-<pageId>-<locale>"> 静态块,前端按当前页与界面语言摆放
+ * 对应块,切语言 / 切页不重算数据。
  */
 export type ReportSlotHtml = Record<ReportLocale, string>;
 
+/** 服务端渲染好的一页报告(HTML 本体不进 viewData,烘成 <template> 静态块)。 */
+export interface ViewReportPageHtml {
+  id: string;
+  html: ReportSlotHtml;
+}
+
+/** 导航里的一页(id = `#/page/<id>` 路由与 `--page` 的取值)。 */
+export interface ViewReportPageMeta {
+  id: string;
+  title: LocalizedText;
+}
+
+/**
+ * 规范化后的报告外壳声明(docs/feature/reports/library/shell.md):壳(导航 / 页脚)由前端
+ * 渲染,页内容消费 <template> 静态块。title 已走完回退链(def.title → 唯一且相同的快照 name →
+ * 内置文案「Eval 运行结果 / Eval Results」),落点是首页 hero 与浏览器标题——页头品牌位恒为
+ * NiceEval 字标,不归 title;scripts / styles 是注入资产,不进 viewData。
+ * link 的 icon 是内联 SVG 字符串(原样透传、原样内联),不收组件——viewData 就是序列化边界。
+ */
+export interface ViewReportMeta {
+  title: LocalizedText;
+  links: { label: LocalizedText; href: string; icon?: { svg: string } }[];
+  footer?: LocalizedText;
+  pages: ViewReportPageMeta[];
+  /** 初始页(--page 或声明序第一页);`#/page/<id>` 路由覆盖它。 */
+  initialPageId: string;
+}
+
 /** view 侧的 attempt 结果 = 瘦身后的 EvalResult + loader 注入的深链身份(不透明 AttemptLocator,
  * `#/attempt/@<locator>` 路由的参数,与 Reports 的 MetricCell.refs / `ctx.attemptHref` 同一身份契约)
  * 与 artifact 基址。 */
@@ -61,14 +90,14 @@ export interface SkippedRunNotice {
  * 格式化统一由前端按当前界面 locale 做。
  */
 export interface ViewData {
-  /** 项目名(来自 config.name);hero 标题,可按 locale 多语言。 */
-  name?: LocalizedText;
   /** 最近一次 run 的 startedAt(ISO);没有历史 run 时缺省。 */
   lastRunAt?: string;
   /** 报告槽 Selection 合成自几个物理 run;hero「合成来源」标注。 */
   composedRuns: number;
-  /** 全部历史快照(跨快照按身份键去重后);修复 prompt 吃 latest,Runs / Traces 吃全部。 */
+  /** 全部历史快照(跨快照按身份键去重后);修复 prompt 吃 latest,Attempts / Traces 吃全部。 */
   snapshots: ViewSnapshot[];
   /** 读不了的落盘(三种原因);前端顶部横幅展示,不静默。 */
   skippedRuns?: SkippedRunNotice[];
+  /** 报告外壳与页导航的声明(规范化后);缺省时前端按单页 `report` 兜底。 */
+  report?: ViewReportMeta;
 }