niceeval 0.9.1 → 0.10.0

package/src/show/show.test.ts

@@ -1,5 +1,5 @@
 // cases: docs/engineering/unit-tests/reports/cases.md
-// niceeval show 终端宿主的测试(行为规范:docs-site/zh/how-to/viewing-results.mdx;
+// niceeval show 终端宿主的测试(行为规范:docs-site/zh/tutorials/viewing-results.mdx;
 // 组合语义:docs/feature/reports/architecture.md「Selection 是计算入口」)。覆盖:
 // - 榜单合成口径:每 experiment × eval 取最新判定,局部重跑从更早快照补齐,头部标注合成自几个快照;
 // - 前缀过滤收窄 Selection,覆盖警告分母 = 已知并集 ∩ 范围;
@@ -22,7 +22,7 @@ import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type TimingNod
 import { selectCurrentResults } from "../results/select.ts";
 import { attemptHistory } from "./compose.ts";
 import { runShow, type ShowFlags } from "./index.ts";
-import { stringWidth } from "../report/text/layout.ts";
+import { stringWidth } from "../report/model/text-layout.ts";
 
 // ───────────────────────── fixture 工具 ─────────────────────────
 
@@ -152,12 +152,12 @@ describe("默认报告:跨快照合成的现刻水位(ExperimentComparison text
     const root = await seedComposedRoot();
     const { out, code } = await show(root, []);
     expect(code).toBe(0);
-    expect(out).toContain("No data to plot Cost × End-to-end pass rate");
+    expect(out).toContain("No data to plot Cost × Pass rate");
     expect(out).toContain("1 point missing data");
     expect(out).not.toContain("needed to compare");
     expect(out).not.toContain("COMPARISON");
     expect(out).toMatch(/\bbub\s+default\s+bub\s+1s\s+50%/);
-    expect(out).toMatch(/1 passed[\s\S]*?\/ 1\s+failed/);
+    expect(out).toMatch(/1 passed[\s\S]*?· 1\s+failed/);
     expect(out).toMatch(/✗ failed\s+fixtures\/button[\s\S]*└─ @1[0-9a-z]{7}[\s\S]*fileChanged/);
     expect(out).toMatch(/✓ passed\s+weather\/brooklyn[\s\S]*└─ @1[0-9a-z]{7}/);
     expect(out).not.toMatch(/\[[EXD⏱,]+\]/);
@@ -220,8 +220,8 @@ describe("默认报告:跨快照合成的现刻水位(ExperimentComparison text
     try {
       const { out, code } = await show(root, []);
       expect(code).toBe(0);
-      expect(out).toContain("成本 × 端到端成功率 没有可绘制的数据");
-      expect(out).toContain("1 通过 / 1 失败");
+      expect(out).toContain("成本 × 通过率 没有可绘制的数据");
+      expect(out).toContain("1 通过 · 1 失败");
       expect(out).toMatch(/\bbub\s+默认\s+bub\s+1s\s+50%/);
       // 页首 Hero 与尾部页索引同样跟随 locale(内置文案与页名)。
       expect(out.split("\n")[0]).toBe("Eval 运行结果");
@@ -259,7 +259,10 @@ describe("默认报告:跨快照合成的现刻水位(ExperimentComparison text
     expect(code).toBe(0);
     // 成本轴(better: lower)反向,「更好」恒指向右上;两轴都声明 better → 提示在场
     expect(out).toContain("better → upper right");
-    expect(out).toContain("A compare/a   B compare/b");
+    // 无 line 声明:按 agent 归类、不连线;图例一行一个 series(显示键字典序),标记按图例顺序分配
+    expect(out).toContain("grouped by agent");
+    expect(out).toContain("claude  A compare/b");
+    expect(out).toContain("codex   B compare/a");
     expect(out).toMatch(/\bb\s+large\s+claude\s+1s\s+100%/);
     expect(out).toMatch(/\ba\s+mini\s+codex\s+1s\s+50%/);
     expect(out).toMatch(/✓ passed\s+q1[\s\S]*└─ @1[0-9a-z]{7}/);
@@ -480,12 +483,23 @@ describe("--report 装载", () => {
         "    locator: ctx.scope.snapshots[0].evals[0].attempts[0].locator,",
         "  },",
         "});",
+        "const AttemptPage = () => null;",
+        "AttemptPage[FACES] = {",
+        "  resolve: (props, ctx) => ({ locator: ctx.page.locator, verdict: ctx.page.evidence.result.verdict }),",
+        "  web: () => null,",
+        "  text: (props) => `CUSTOM ATTEMPT PAGE · ${props.locator} · ${props.verdict}`,",
+        "};",
         "const definition = {",
         '  kind: "report",',
         "  links: [],",
         "  scripts: [],",
         "  styles: [],",
-        '  pages: [{ id: "report", title: "Report", content: { type: Wrapper, props: {} } }],',
+        "  pages: [",
+        '    { id: "report", title: "Report", input: "scope", navigation: true, content: { type: Wrapper, props: {} } },',
+        // 报告需要声明一张 attempt-input page,attemptCommand 生成器才存在(architecture.md
+        // 「Attempt 详情是一张参数化 page」);navigation:false 不进「其余页」索引,单页断言不受影响。
+        '    { id: "attempt", title: "Attempt", input: "attempt", navigation: false, content: { type: AttemptPage, props: {} } },',
+        "  ],",
         "};",
         "Object.defineProperty(definition, DEFINITION, { value: true });",
         "export default definition;",
@@ -660,6 +674,75 @@ describe("--report 装载", () => {
     expect(builtin.err).toContain('page "typo" not found in the built-in report');
     expect(builtin.err).toContain("Available pages: report, attempts, traces");
   });
+
+  /** 只有一张 scope-input page,没有声明 attempt-input page。 */
+  async function writeReportFileNoAttemptPage(dir: string): Promise<string> {
+    const path = join(dir, "no-attempt-page.mjs");
+    await writeFile(
+      path,
+      [
+        'const FACES = Symbol.for("niceeval.report.faces");',
+        'const DEFINITION = Symbol.for("niceeval.report.definition");',
+        "const Overview = () => null;",
+        "Overview[FACES] = { web: () => null, text: () => \"OVERVIEW\" };",
+        "const definition = {",
+        '  kind: "report",',
+        "  links: [],",
+        "  scripts: [],",
+        "  styles: [],",
+        '  pages: [{ id: "report", title: "Report", input: "scope", navigation: true, content: { type: Overview, props: {} } }],',
+        "};",
+        "Object.defineProperty(definition, DEFINITION, { value: true });",
+        "export default definition;",
+        "",
+      ].join("\n"),
+      "utf-8",
+    );
+    return path;
+  }
+
+  it("show @<locator> --report <file>:选中该定义自己声明的 attempt-input page,不是内建固定首页(docs/engineering/unit-tests/reports/cases.md 第 202 行)", async () => {
+    const root = await seedComposedRoot();
+    const report = await writeReportFile(root);
+    const results = await openResults(root);
+    const evals = results.experiments[0]!.snapshots.flatMap((s) => s.evals);
+    const locator = evals.find((e) => e.id === "weather/brooklyn")!.attempts[0]!.locator!;
+
+    const { out, code } = await show(root, [locator], { report });
+    expect(code).toBe(0);
+    expect(out).toBe(`CUSTOM ATTEMPT PAGE · ${locator} · passed\n`);
+    // 不是内建 standard 的固定首页文案(AttemptSummary/AttemptAssessment 等)
+    expect(out).not.toContain("niceeval show");
+  });
+
+  it("自定义报告没有 attempt-input page 时,裸 show @<locator> --report <file> 报完整用户反馈,指引三种解决路径,不回退到内建详情(第 204 行)", async () => {
+    const root = await seedComposedRoot();
+    const report = await writeReportFileNoAttemptPage(root);
+    const results = await openResults(root);
+    const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
+
+    const { err, code } = await show(root, [locator], { report });
+    expect(code).toBe(1);
+    expect(err).toContain(report);
+    expect(err).toContain("has no attempt-input page");
+    expect(err).toContain("extends: standard");
+    expect(err).toContain("standardAttemptPage");
+    expect(err).toContain('input: "attempt"');
+    // 不静默回退渲染内建 standard 的详情页(那会让用户以为自定义报告本来就有这页)
+    expect(err).not.toContain("Eval Results");
+  });
+
+  it("--source/--execution/--diff 直接读 AttemptEvidence,不经 page content:没有 attempt page 的自定义报告下仍正常工作(第 203 行)", async () => {
+    const root = await seedComposedRoot();
+    const report = await writeReportFileNoAttemptPage(root);
+    const results = await openResults(root);
+    const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
+
+    const { out, code } = await show(root, [locator], { report, diff: true });
+    expect(code).toBe(0);
+    expect(out).toContain(locator);
+    expect(out).not.toContain("has no attempt-input page");
+  });
 });
 
 // ───────────────────────── 证据切面:--execution ─────────────────────────
@@ -812,7 +895,7 @@ describe("show @<locator>", () => {
     const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
     const { out } = await show(root, [locator]);
     expect(out).toContain("gate · Issue 15193");
-    expect(out).toContain("assertion: equals(4)");
+    expect(out).toContain("equals(4)");
     expect(out).toContain("expected: 4");
     expect(out).toContain("received: 1");
     expect(out).toContain("source: evals/manager.eval.ts:40:11");
@@ -829,10 +912,13 @@ describe("show @<locator>", () => {
 
     const { out, code } = await show(root, [locator]);
     expect(code).toBe(0);
-    expect(out).toContain(`${locator} · weather/brooklyn · compare/bub · passed`);
-    expect(out).toContain("attempt 1 · ");
-    expect(out).toContain("execution: unavailable (no events recorded for this attempt)");
-    expect(out).toContain("changes: diff unavailable");
+    // 首行不做整段精确匹配:startedAt 按本机时区格式化,时间部分跨时区不稳定,只断言与时区无关的片段。
+    expect(out).toContain(`${locator} · weather/brooklyn · compare/bub · attempt 1 · ✓ passed`);
+    expect(out).toContain("· 1.0s");
+    // 没有 events/diff 的组件零输出(不是"execution: unavailable"这类占位文案)——
+    // 与「Attempt 详情组件族:非空/空证据矩阵」的单元测试同一条契约,这里是集成层确认。
+    expect(out).not.toContain("execution:");
+    expect(out).not.toContain("changes:");
     expect(out).not.toContain("evidence:");
     expect(out).not.toContain("available:");
   });
@@ -857,22 +943,22 @@ describe("show @<locator>", () => {
 
     const { out, code } = await show(root, [locator]);
     expect(code).toBe(0);
-    expect(out).toContain(`${locator} · agent-029 · compare/claude-e2b · errored`);
-    // 结构化 error 块:phase 直接展示闭集点分名,code/message/cause 各一行(见 docs/feature/reports/show.md)
-    expect(out).toContain("error:");
+    // 同上:跳过 startedAt 的时区敏感部分,只断言与时区无关的片段。
+    expect(out).toContain(`${locator} · agent-029 · compare/claude-e2b · attempt 1 · ! errored`);
+    expect(out).toContain("· 1.0s");
+    // 结构化 error 块:code 折进 error: 首行,phase/message/cause 各一行(AttemptError)
+    expect(out).toContain("error: sandbox-rate-limit");
     expect(out).toContain("phase: sandbox.create");
-    expect(out).toContain("code: sandbox-rate-limit");
     expect(out).toContain("message: E2B sandbox allocation failed after 5 attempts");
     expect(out).toContain("cause: RateLimitError · too many concurrent sandboxes");
-    // attempt 级 diagnostics 块(与 verdict 独立)
-    expect(out).toContain("diagnostics:");
-    expect(out).toContain("warning · sandbox.teardown · teardown-failed");
-    expect(out).toContain("container stop timed out");
-    // errored 且无断言:不打印空的 assertions 汇总行
+    // attempt 级 diagnostics 按 lifecycle phase 分组(AttemptDiagnostics),标题即 phase 名
+    expect(out).toContain("sandbox.teardown:");
+    expect(out).toContain("warning · teardown-failed — container stop timed out");
+    // errored 且无断言:AttemptAssertions 零输出,不打印空的 assertions 汇总行
     expect(out).not.toContain("assertions:");
   });
 
-  it("available 只逐行列出实际存在的证据命令,不打印能力字母或合并式 next", async () => {
+  it("证据下钻命令散落在各自区块行尾(带 locator),不存在的能力不生成假命令,也没有合并式 available/next 尾块", async () => {
     const root = await makeRoot();
     const dir = await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
       res("weather/brooklyn", "failed", { hasEvents: true }),
@@ -889,9 +975,14 @@ describe("show @<locator>", () => {
 
     const { out, code } = await show(root, [locator]);
     expect(code).toBe(0);
-    expect(out).toContain(`available:\n  niceeval show ${locator} --source\n  niceeval show ${locator} --execution`);
+    // AttemptSource / AttemptConversation 各自行尾带命令(不是集中列在一个 available: 块里)
+    expect(out).toContain(`niceeval show ${locator} --source`);
+    expect(out).toContain(`niceeval show ${locator} --execution`);
+    // 没有 diff/timing 能力(fixture 没写 diff.json,也没有 phases)时不生成假命令
     expect(out).not.toContain(`niceeval show ${locator} --diff`);
+    expect(out).not.toContain(`niceeval show ${locator} --timing`);
     expect(out).not.toContain("evidence:");
+    expect(out).not.toContain("available:");
     expect(out).not.toContain("next:");
   });
 
@@ -1054,7 +1145,7 @@ describe("show @<locator>", () => {
     expect(out).not.toContain("git show ×");
   });
 
-  it("attempt 首页 timing 只列大头,但保留变慢的 telemetry 阶段", async () => {
+  it("attempt 首页 timing 逐阶段一行,收尾段单独归拢(AttemptTimeline 不做单行宽度收窄,--timing 才是完整分解)", async () => {
     const root = await makeRoot();
     const dir = await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
       res("weather/brooklyn", "passed", {
@@ -1080,15 +1171,17 @@ describe("show @<locator>", () => {
     const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
 
     const { out } = await show(root, [locator]);
-    const timingLine = out.split("\n").find((line) => line.startsWith("timing:"));
-    expect(out).toContain("1 AI message");
-    expect(timingLine).toContain("sandbox.queue 0ms");
-    expect(timingLine).toContain("sandbox.create 3.0s");
-    expect(timingLine).toContain("eval.run 45.0s");
-    expect(timingLine).toContain("telemetry.collect 35.3s");
-    expect(timingLine).toContain("teardown +8.5s");
-    expect(timingLine).not.toContain("workspace.baseline");
-    expect(timingLine).not.toContain("telemetry.configure");
+    // 每个主链阶段各占一行(不再是旧格式的单行拼接,那条规则本身是为单行可读服务的,
+    // 多行块没有这个约束了),收尾段(sandbox.stop)单独归拢在 teardown: 之下。
+    expect(out).toContain("timing: 1m 24s");
+    expect(out).toContain("sandbox.queue 0ms");
+    expect(out).toContain("sandbox.create 3.0s");
+    expect(out).toContain("workspace.baseline 310ms");
+    expect(out).toContain("telemetry.configure 358ms");
+    expect(out).toContain("eval.run 45.0s");
+    expect(out).toContain("telemetry.collect 35.3s");
+    expect(out).toContain("teardown:");
+    expect(out).toContain("sandbox.stop 8.5s");
   });
 
   it("语法不对的 locator 报「not a valid attempt locator」,退出码 1,不崩", async () => {

package/src/view/app/App.test.tsx

@@ -22,7 +22,7 @@ const reportPages = {
 };
 
 function dataWithShell(report: ViewData["report"]): ViewData {
-  return { composedRuns: 1, snapshots: [], ...(report !== undefined ? { report } : {}) };
+  return { composedRuns: 1, ...(report !== undefined ? { report } : {}) };
 }
 
 describe("外壳:宿主恒有 NiceEval 品牌位、无 hero,导航只有报告页", () => {

package/src/view/app/App.tsx

@@ -1,9 +1,15 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties } from "react";
 import { detectLocale, makeTranslator, persistLocale, setDocumentLocale } from "./i18n.ts";
-import type { Locale, LocalizedText, ReportSlotHtml, Tab, ViewData, ViewReportPageMeta, ViewResult } from "./types.ts";
-import { resultFromUrl } from "./lib/rows.ts";
-import { parseAttemptHash, resolveAttemptLocator, unresolvedAttemptWarning } from "./lib/attempt-route.ts";
-import { AttemptModal } from "./components/AttemptModal.tsx";
+import type { Locale, LocalizedText, ReportSlotHtml, Tab, ViewData, ViewReportPageMeta } from "./types.ts";
+import {
+  attemptHrefFor,
+  attemptLocatorFromHref,
+  hashForAttempt,
+  locatorFromHash,
+  parseAttemptDocument,
+  type AttemptDocumentContent,
+} from "./lib/attempt-dialog.ts";
+import { Dialog, DialogClose, DialogContent, DialogTitle } from "./components/ui/dialog.tsx";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "./components/ui/tabs.tsx";
 
 // 导航组成只有一条规则(docs/feature/reports/view.md「页面构成」):导航项 = 报告定义声明的页,
@@ -17,6 +23,20 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "./components/ui/tabs.t
 // utm_medium 区分点击来自哪个品牌位(shell.md「行为约束」)。
 const BRAND_HREF = "https://niceeval.com/?utm_source=report&utm_medium=brand";
 
+/** 屏幕阅读器可用、视觉上不占位:Radix Dialog 需要一个可访问标题,内容本身(身份 / verdict)
+ *  已经在 dialog 里可见,不需要再视觉重复一遍。 */
+const VISUALLY_HIDDEN: CSSProperties = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: "hidden",
+  clip: "rect(0, 0, 0, 0)",
+  whiteSpace: "nowrap",
+  border: 0,
+};
+
 /**
  * LocalizedText 的确定回退(docs/feature/reports/library/shell.md):当前 locale → en →
  * 按 locale 键字典序的第一个非空值。字符串原样返回。
@@ -32,19 +52,6 @@ export function localizedText(text: LocalizedText | undefined, locale: Locale):
   return undefined;
 }
 
-/** 初始 URL → 直接打开的 attempt:先认 #/attempt/@<locator> 深链,回退旧版 ?modal= 参数。 */
-function modalResultFromLocation(snapshots: ViewData["snapshots"]): ViewResult | null {
-  const locator = parseAttemptHash(location.hash);
-  if (locator) {
-    const found = resolveAttemptLocator(snapshots, locator);
-    if (found) return found;
-    // 定位不到(locator 不在、快照未加载、旧格式数据):不开空 modal,页面照常渲染。
-    console.warn(unresolvedAttemptWarning(location.hash));
-    return null;
-  }
-  return resultFromUrl(snapshots);
-}
-
 /**
  * 报告槽:React 19 对 dangerouslySetInnerHTML 只比较对象身份,身份一变就无条件重设
  * innerHTML(不再比对 __html 字符串值)。{__html} 必须 memo 住,否则 App 任意一次重渲染
@@ -68,7 +75,6 @@ function hashForTab(tab: Tab): string {
 }
 
 export function App({ data, reportPages }: { data: ViewData; reportPages: Record<string, ReportSlotHtml> }) {
-  const snapshots = data.snapshots ?? [];
   const [locale, setLocale] = useState<Locale>(() => detectLocale());
   const t = useMemo(() => makeTranslator(locale), [locale]);
 
@@ -79,11 +85,16 @@ export function App({ data, reportPages }: { data: ViewData; reportPages: Record
   const initialPageId = data.report?.initialPageId ?? pages[0]!.id;
 
   const [tab, setTab] = useState<Tab>(() => tabFromHash(location.hash, pages) ?? `page:${initialPageId}`);
-  const [modalResult, setModalResult] = useState<ViewResult | null>(() => modalResultFromLocation(snapshots));
-  // 当前 modal 的 hash 历史条目前面是否还有本页条目(本页 push 的 / 前进键回到的):
+
+  // attempt 详情弹窗:内容是独立文档(attempt/<locator>.html)fetch 回来的同一份 server-rendered
+  // 片段,不维护第二份客户端渲染(docs/feature/reports/view.md「静态导出」)。dialogLocator 为
+  // null 即关闭。
+  const [dialogLocator, setDialogLocator] = useState<string | null>(null);
+  const [dialogContent, setDialogContent] = useState<AttemptDocumentContent | null>(null);
+  // 当前 dialog 的 hash 历史条目前面是否还有本页条目(点击链接 push 的 / 前进键回到的):
   // true → UI 关闭走 history.back(),前进键还能重新打开;false(深链直接落地)→ 原地抹 hash,
   // 免得 back 把用户弹出站外。
-  const modalOwnsHistory = useRef(false);
+  const dialogOwnsHistory = useRef(false);
 
   useEffect(() => {
     setDocumentLocale(locale);
@@ -98,48 +109,88 @@ export function App({ data, reportPages }: { data: ViewData; reportPages: Record
     document.title = shellTitle;
   }, [shellTitle]);
 
-  const closeModal = useCallback(() => {
-    setModalResult(null);
-    if (modalOwnsHistory.current) {
-      modalOwnsHistory.current = false;
+  /** fetch 一个 locator 的独立文档、抠出两种语言内容并打开 dialog;定位不到就直说,不开空 dialog。 */
+  const openAttempt = useCallback(async (locator: string, ownsHistory: boolean) => {
+    try {
+      const res = await fetch(attemptHrefFor(locator));
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const content = parseAttemptDocument(await res.text());
+      if (!content) throw new Error("response is not a recognized attempt document");
+      dialogOwnsHistory.current = ownsHistory;
+      setDialogLocator(locator);
+      setDialogContent(content);
+    } catch (e) {
+      console.warn(
+        `[niceeval view] failed to open attempt "${locator}": ${e instanceof Error ? e.message : String(e)}`,
+      );
+    }
+  }, []);
+
+  const closeDialog = useCallback(() => {
+    setDialogLocator(null);
+    setDialogContent(null);
+    if (dialogOwnsHistory.current) {
+      dialogOwnsHistory.current = false;
       history.back();
       return;
     }
     try {
-      // 深链直接落地 / 旧版 ?modal= 链接:没有可回退的本页条目,原地还原成无 modal 的 URL。
-      history.replaceState(null, "", location.pathname);
+      // 深链直接落地:没有可回退的本页条目,原地还原成无 hash 的 URL。
+      history.replaceState(null, "", location.pathname + location.search);
     } catch {
       // 还原 URL 失败不影响关闭。
     }
   }, []);
 
-  // 浏览器前进/后退、手改 hash、页内链接(attempt 深链与 `#/page/<id>` 页路由)统一从
-  // hashchange 分发:attempt hash 开证据室弹窗,页 hash 切当前 tab。
-  // attempt 详情路由对有效根解析(viewData.snapshots 即有效根):收窄之内、不在页面统计
-  // 口径(现刻水位)里的历史 attempt 仍能经深链打开,报告里的证据引用不因统计口径失效。
+  // 初始 URL 已经是 #/attempt/@<locator> 深链:直接打开(不经 hashchange——那只在后续变化时触发)。
+  // 有效根即收窄后的结果(view.md「打开与收窄」):这份路由对完整结果根解析,不受当前统计口径
+  // (现刻水位)限制,深链因此对历史 attempt 同样可达;收窄之外的 locator 由这份文档自身
+  // 的宿主寻址语义处理(本地越过收窄解析,导出站按证据缺失呈现,不是这里的关注点)。
+  // 空依赖数组是有意的:只在挂载时检查一次初始 hash,openAttempt 本身是 useCallback(deps: [])
+  // 的稳定引用,不会随后续渲染变化。
+  useEffect(() => {
+    const locator = locatorFromHash(location.hash);
+    if (locator) void openAttempt(locator, false);
+  }, [openAttempt]);
+
+  // 浏览器前进/后退、手改 hash、页内链接点击(经下面的点击拦截转成 hash 变化)统一从
+  // hashchange 分发:attempt hash 开证据室 dialog,页 hash 切当前 tab。
   useEffect(() => {
     const onHashChange = () => {
-      const locator = parseAttemptHash(location.hash);
+      const locator = locatorFromHash(location.hash);
       if (locator) {
-        const found = resolveAttemptLocator(snapshots, locator);
-        if (!found) {
-          console.warn(unresolvedAttemptWarning(location.hash));
-          setModalResult(null);
-          return;
-        }
-        // 经浏览器导航打开:前一条历史仍是本页,UI 关闭可以安全 back()。
-        modalOwnsHistory.current = true;
-        setModalResult(found);
+        // 经浏览器导航打开:前一条历史仍是本页,dialog 关闭可以安全 back()。
+        void openAttempt(locator, true);
         return;
       }
-      modalOwnsHistory.current = false;
-      setModalResult(null);
+      setDialogLocator(null);
+      setDialogContent(null);
       const routed = tabFromHash(location.hash, pages);
       if (routed) setTab(routed);
     };
     window.addEventListener("hashchange", onHashChange);
     return () => window.removeEventListener("hashchange", onHashChange);
-  }, [snapshots, pages]);
+  }, [pages, openAttempt]);
+
+  // 拦截 attempt 文档链接(报告页里的 locator 引用,attemptHref 缺省产出的
+  // `attempt/<encodeURIComponent(locator)>.html`):点击时改写成 hash 路由,交给上面的
+  // hashchange 统一打开——无 JavaScript 时这些链接原样导航到独立文档,同样完整可读。
+  // 修饰键 / 非左键点击放行,让「新标签页打开」这类浏览器原生行为不受影响。
+  useEffect(() => {
+    const onClick = (e: MouseEvent) => {
+      if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      const target = e.target;
+      if (!(target instanceof Element)) return;
+      const anchor = target.closest("a[href]");
+      if (!anchor) return;
+      const locator = attemptLocatorFromHref(anchor.getAttribute("href") ?? "");
+      if (!locator) return;
+      e.preventDefault();
+      location.hash = hashForAttempt(locator);
+    };
+    document.addEventListener("click", onClick);
+    return () => document.removeEventListener("click", onClick);
+  }, []);
 
   const selectTab = useCallback((value: Tab) => {
     setTab(value);
@@ -202,7 +253,7 @@ export function App({ data, reportPages }: { data: ViewData; reportPages: Record
           <TabsContent key={`page:${page.id}`} value={`page:${page.id}`} id={`tab-page-${page.id}`}>
             {/* 报告槽:server 侧逐页渲染好的静态 HTML(含 <Style> 产物),按当前页与界面语言
                 摆放对应块;hero、品牌行、Scope 警告、批量修复 prompt 都是页内组件,壳不再渲染。
-                attempt 深链是普通 <a href="#/attempt/…">,经 hashchange 打开证据室弹窗。 */}
+                attempt 深链是普通 <a href="attempt/…html">,经上面的点击拦截打开 dialog。 */}
             <ReportSlot html={reportPages[page.id]?.[locale] || reportPages[page.id]?.en || ""} />
           </TabsContent>
         ))}
@@ -212,7 +263,28 @@ export function App({ data, reportPages }: { data: ViewData; reportPages: Record
           <span className="site-footer-text">{footerText}</span>
         </footer>
       ) : null}
-      {modalResult && <AttemptModal result={modalResult} onClose={closeModal} t={t} />}
+      {dialogLocator && dialogContent ? (
+        <Dialog open onOpenChange={(o) => { if (!o) closeDialog(); }}>
+          <DialogContent aria-describedby={undefined}>
+            {/* 屏幕阅读器用的可访问标题:视觉上隐藏,身份 / verdict 等实际内容已经在下面
+                fetch 回来的片段里可见,这里不重复渲染。 */}
+            <DialogTitle style={VISUALLY_HIDDEN}>{t("dialog.attemptTitle")}</DialogTitle>
+            <div className="flex min-w-0 shrink-0 items-center justify-end border-b border-line px-7 pb-3 pt-4">
+              <DialogClose
+                aria-label={t("action.close")}
+                className="grid h-7 w-7 shrink-0 place-items-center rounded-md border border-transparent text-sm text-muted transition-colors hover:border-line hover:bg-panel-2 hover:text-text"
+              >
+                x
+              </DialogClose>
+            </div>
+            {/* 与直接打开 attempt/<locator>.html 看到的是同一份 server-rendered 片段
+                (docs/engineering/unit-tests/reports/cases.md 第 207 行),不是客户端重新渲染。 */}
+            <div className="flex-1 overflow-y-auto px-7 pb-7 pt-2">
+              <ReportSlot html={dialogContent[locale] || dialogContent.en} />
+            </div>
+          </DialogContent>
+        </Dialog>
+      ) : null}
     </Tabs>
   );
 }