niceeval 0.9.1 → 0.10.2

package/src/report/{report.ts → definition/report.ts}

@@ -5,26 +5,13 @@
 // `extends` 在另一份报告上叠外壳——页归 base、外壳逐字段覆盖,合并在调用时折叠完成,
 // 宿主装载看到的永远是已折叠的普通产物。
 //
-// renderReportToText 是 text 宿主(show)的装载入口;web 宿主(view)的
-// renderReportToStaticHtml 在 ./web.ts(那一侧才 import react-dom)。管线以页为单位执行:
-// 装载(规范化 + 静态校验)→ resolve → validate → render。
-
-import type { Results, Scope } from "../results/types.ts";
-import {
-  createTextContext,
-  renderNodeToText,
-  resolveReportTree,
-  validateReportTree,
-  ResolveMemo,
-  type ReportNode,
-  type TextRenderOptions,
-} from "./tree.ts";
-import {
-  localizedTextEquals,
-  resolveLocalizedText,
-  type LocalizedText,
-  type ReportLocale,
-} from "./locale.ts";
+// text/web 两个宿主的渲染入口(renderReportToText / renderReportToStaticHtml)在 ../runtime/
+// (text.ts / web.ts);这里只有 ReportDefinition 的类型体系、装载规范化与元数据折叠
+// (buildReportMeta / resolveReportTitle),不做任何渲染。
+
+import type { Scope } from "../../results/types.ts";
+import type { ReportNode } from "./tree.ts";
+import { localizedTextEquals, type LocalizedText } from "../model/locale.ts";
 
 // ───────────────────────── 公开形状 ─────────────────────────
 
@@ -73,7 +60,7 @@ export interface ReportShell {
 
 export type NonEmptyArray<T> = readonly [T, ...T[]];
 
-export interface ReportPage {
+export interface ReportPageBase {
   /** 页面身份:`--page <id>` 的取值、web 路由 `#/page/<id>` 与导航锚。小写字母、数字与连字符。 */
   id: string;
   /** 导航中的页名。 */
@@ -82,6 +69,18 @@ export interface ReportPage {
   content: ReportNode;
 }
 
+/**
+ * 页按输入分两种形态,仍是同一个类型族,走同一条 resolve → validate → render 管线
+ * (docs/feature/reports/architecture.md「Attempt 详情是一张参数化 page」):
+ * - `input` 省略或为 `"scope"`:消费宿主选择的 Scope;省略时规范化为 `navigation: true`。
+ * - `input: "attempt"`:以 locator 为参数,消费一份 AttemptEvidence;没有 locator 时不能打开,
+ *   必须显式 `navigation: false`,不进导航。
+ * 一份报告至多声明一张 attempt-input page。
+ */
+export type ReportPage =
+  | (ReportPageBase & { input?: "scope"; navigation?: boolean })
+  | (ReportPageBase & { input: "attempt"; navigation: false });
+
 /** content / pages / extends 三选一由类型表达,不把非法状态留到运行期。 */
 export type ReportDef = ReportShell &
   (
@@ -92,7 +91,7 @@ export type ReportDef = ReportShell &
         extends?: never;
       }
     | {
-        /** 非空页列表;导航按数组顺序显示。 */
+        /** 非空页列表;`navigation !== false` 的项按数组顺序显示。 */
         pages: NonEmptyArray<ReportPage>;
         content?: never;
         extends?: never;
@@ -128,17 +127,27 @@ export interface ReportDefinition {
   readonly pages: NonEmptyArray<ReportPage>;
 }
 
-/** 规范化后的报告声明,经组合组件 ctx.report 只读可见(scripts / styles 是注入资产,不进)。 */
+/** 规范化后页列表在 ctx.report 上的元数据形态(id / 导航页名 / 输入声明 / 导航资格)。 */
+export interface ReportMetaPage {
+  id: string;
+  title: LocalizedText;
+  input: "scope" | "attempt";
+  navigation: boolean;
+}
+
+/**
+ * 规范化后的报告声明,经组合组件 ctx.report 只读可见(scripts / styles 是注入资产,不进)。
+ * 不携带"当前是哪一页"——那由 ctx.page(PageContext)表达,两者不是同一份状态
+ * (docs/feature/reports/library/shell.md「行为约束」)。
+ */
 export interface ReportMeta {
   /** 走完回退链(声明 title → 唯一快照 name → 内置文案「Eval 运行结果 / Eval Results」)后的标题。 */
   title: LocalizedText;
   /** 页头外链;声明省略时为空数组。 */
   links: readonly ReportLink[];
   footer?: LocalizedText;
-  /** 规范化后的页列表(id 与导航页名),恒非空。 */
-  pages: NonEmptyArray<{ id: string; title: LocalizedText }>;
-  /** 当前渲染中的页 id。 */
-  pageId: string;
+  /** 规范化后的页列表,恒非空。 */
+  pages: NonEmptyArray<ReportMetaPage>;
 }
 
 /** 单页缩写展开出的唯一页 id 与内置页名。 */
@@ -332,6 +341,53 @@ function assertHeadTags(tags: unknown): HeadTag[] {
   return tags as HeadTag[];
 }
 
+/**
+ * page 的 input / navigation 规范化(shell.md「page 显式声明输入」):省略或 "scope" 时补
+ * `input: "scope"`,`navigation` 缺省为 true;"attempt" 必须显式 `navigation: false`——
+ * 没有 locator 时不可打开,不能悄悄挤进导航,省略或传 true 都在装载期报错。
+ */
+function normalizePageInputAndNavigation(page: Record<string, unknown>): ReportPage {
+  const input = page.input;
+  if (input === undefined || input === "scope") {
+    return {
+      id: page.id as string,
+      title: page.title as LocalizedText,
+      content: page.content as ReportNode,
+      input: "scope",
+      navigation: page.navigation !== false,
+    };
+  }
+  if (input === "attempt") {
+    if (page.navigation !== false) {
+      throw new Error(
+        `Report page "${page.id}" declares input: "attempt" but not navigation: false — an attempt-input page has no content without a locator, so it must not appear in navigation. Add navigation: false.`,
+      );
+    }
+    return {
+      id: page.id as string,
+      title: page.title as LocalizedText,
+      content: page.content as ReportNode,
+      input: "attempt",
+      navigation: false,
+    };
+  }
+  throw new Error(
+    `Report page "${page.id}" input ${JSON.stringify(input)} is not valid — input is omitted, "scope", or "attempt".`,
+  );
+}
+
+/** 一份报告至多一张 attempt-input page,避免 show @<locator> 与 locator 链接出现多个目标。 */
+function assertAtMostOneAttemptPage(pages: readonly ReportPage[]): void {
+  const attemptPages = pages.filter((p) => p.input === "attempt");
+  if (attemptPages.length > 1) {
+    throw new Error(
+      `A report can declare at most one input: "attempt" page — got ${attemptPages.length} (${attemptPages
+        .map((p) => `"${p.id}"`)
+        .join(", ")}). Keep one and remove the others, or fold their content into a single attempt-input page.`,
+    );
+  }
+}
+
 export function defineReport(content: ReportNode): ReportDefinition;
 export function defineReport(def: ReportDef): ReportDefinition;
 export function defineReport(input: ReportNode | ReportDef): ReportDefinition {
@@ -379,7 +435,9 @@ export function defineReport(input: ReportNode | ReportDef): ReportDefinition {
     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 }];
+    pages = [
+      { id: DEFAULT_PAGE_ID, title: DEFAULT_PAGE_TITLE, input: "scope", navigation: true, content: def.content as ReportNode },
+    ];
   } else {
     const raw = def.pages as unknown;
     if (!Array.isArray(raw) || raw.length === 0) {
@@ -388,6 +446,7 @@ export function defineReport(input: ReportNode | ReportDef): ReportDefinition {
       );
     }
     const seen = new Set<string>();
+    const normalized: ReportPage[] = [];
     for (const page of raw as Array<Record<string, unknown>>) {
       if (typeof page?.id !== "string" || !PAGE_ID_PATTERN.test(page.id)) {
         throw new Error(
@@ -402,9 +461,11 @@ export function defineReport(input: ReportNode | ReportDef): ReportDefinition {
       seen.add(page.id);
       assertLocalizedText(page.title, `Report page "${page.id}" title`);
       assertNotDefinition(page.content, `Report page "${page.id}" content`);
+      normalized.push(normalizePageInputAndNavigation(page));
     }
-    pages = raw as ReportPage[];
+    pages = normalized;
   }
+  assertAtMostOneAttemptPage(pages);
 
   if (def.title !== undefined) assertLocalizedText(def.title, "defineReport title");
   if (def.footer !== undefined) assertLocalizedText(def.footer, "defineReport footer");
@@ -482,145 +543,17 @@ export function resolveReportTitle(definition: ReportDefinition, scope: Scope):
   return names.every((name) => localizedTextEquals(name, first)) ? first : FALLBACK_REPORT_TITLE;
 }
 
-/** 规范化声明 → 组合组件可见的 ReportMeta(scripts / styles 是注入资产,不进)。 */
-export function buildReportMeta(definition: ReportDefinition, scope: Scope, pageId: string): ReportMeta {
+/** 规范化声明 → 组合组件可见的 ReportMeta(scripts / styles 是注入资产,不进;不携带当前页)。 */
+export function buildReportMeta(definition: ReportDefinition, scope: Scope): ReportMeta {
   return {
     title: resolveReportTitle(definition, scope),
     links: definition.links,
     ...(definition.footer !== undefined ? { footer: definition.footer } : {}),
-    pages: definition.pages.map((page) => ({ id: page.id, title: page.title })) as unknown as NonEmptyArray<{
-      id: string;
-      title: LocalizedText;
-    }>,
-    pageId,
-  };
-}
-
-// ───────────────────────── 页选择与 text 宿主入口 ─────────────────────────
-
-/** `--page` 未命中:宿主据此按用法错误退出并列出可用页 id。 */
-export class ReportPageNotFoundError extends Error {
-  readonly pageId: string;
-  readonly available: string[];
-  constructor(pageId: string, available: string[]) {
-    super(`page "${pageId}" not found. Available pages: ${available.join(", ")}`);
-    this.pageId = pageId;
-    this.available = available;
-  }
-}
-
-export function pickReportPage(definition: ReportDefinition, pageId?: string): ReportPage {
-  if (pageId === undefined) return definition.pages[0];
-  const page = definition.pages.find((p) => p.id === pageId);
-  if (!page) {
-    throw new ReportPageNotFoundError(
-      pageId,
-      definition.pages.map((p) => p.id),
-    );
-  }
-  return page;
-}
-
-/** 宿主注入的渲染上下文:官方口径挑好的 Scope 与结果根完整读取面。 */
-export interface ReportHostContext {
-  scope: Scope;
-  /** 组合组件 ctx.results 的来源;历史视图从这里自行挑 Snapshot[]。 */
-  results: Results;
-}
-
-export interface RenderReportTextOptions extends TextRenderOptions {
-  /** 渲染哪一页;缺省第一页。未命中抛 ReportPageNotFoundError。 */
-  pageId?: string;
-}
-
-/**
- * text 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→ 树校验 →
- * 遍历渲染 text 面。不需要 react-dom。宿主不在报告树外另设警告通道——挑选警告的呈现件是
- * `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是作者义务
- * (docs/feature/reports/architecture.md「Scope 是计算入口」)。
- */
-export async function renderReportToText(
-  definition: ReportDefinition,
-  ctx: ReportHostContext,
-  options?: RenderReportTextOptions,
-): Promise<string> {
-  const page = pickReportPage(definition, options?.pageId);
-  const meta = buildReportMeta(definition, ctx.scope, page.id);
-  const resolved = await resolveReportTree(page.content, {
-    scope: ctx.scope,
-    results: ctx.results,
-    report: meta,
-    memo: new ResolveMemo(),
-  });
-  validateReportTree(resolved);
-  return renderNodeToText(resolved, createTextContext(options));
-}
-
-/** 页索引标题行(show 多页索引 / view 导航共用的解析结果):按 locale 解析的标题字符串。 */
-export function reportTitleText(definition: ReportDefinition, scope: Scope, locale: ReportLocale): string {
-  return resolveLocalizedText(resolveReportTitle(definition, scope), locale);
-}
-
-// ───────────────────────── 逐页(树)渲染入口:宿主联系面 ─────────────────────────
-
-/** 宿主索引命令的完整上下文(docs/feature/reports/show/reports.md「索引命令携带完整上下文」)。 */
-export interface HostCommandContext {
-  patterns: string[];
-  results?: string;
-  experiment?: string;
-  report?: string;
-  page?: string;
-}
-
-function quoteArg(value: string): string {
-  return /^[A-Za-z0-9._/@-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-/** 按上下文拼组索引的可复制命令:`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), `--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)}`);
-    return parts.join(" ");
+    pages: definition.pages.map((page) => ({
+      id: page.id,
+      title: page.title,
+      input: page.input ?? "scope",
+      navigation: page.navigation ?? true,
+    })) as unknown as NonEmptyArray<ReportMetaPage>,
   };
 }
-
-/** 逐页渲染的宿主上下文:官方口径的 Scope、结果根读取面与规范化声明(ctx.report)。 */
-export interface ReportTreeHostContext {
-  scope: Scope;
-  results: Results;
-  report: ReportMeta;
-}
-
-export interface RenderTreeTextOptions extends TextRenderOptions {
-  /** 组索引命令的完整上下文;给了就按它拼命令,experimentCommand 显式注入时以后者为准。 */
-  commandContext?: HostCommandContext;
-}
-
-/**
- * 渲染一页报告树的 text 面(宿主逐页调用;页选择归宿主):
- * resolve(组合展开 + spec 取数)→ validate → render。宿主不在报告树外另设警告通道,
- * 挑选警告由页内的 `ScopeWarnings` 组件呈现(内建报告每页都放它)。
- */
-export async function renderReportTreeToText(
-  tree: ReportNode,
-  ctx: ReportTreeHostContext,
-  options?: RenderTreeTextOptions,
-): Promise<string> {
-  const resolved = await resolveReportTree(tree, {
-    scope: ctx.scope,
-    results: ctx.results,
-    report: ctx.report,
-    memo: new ResolveMemo(),
-  });
-  validateReportTree(resolved);
-  const textCtx = createTextContext({
-    ...options,
-    ...(options?.experimentCommand === undefined && options?.commandContext !== undefined
-      ? { experimentCommand: experimentCommandFor(options.commandContext) }
-      : {}),
-  });
-  return renderNodeToText(resolved, textCtx);
-}

package/src/report/{shell-head.test.ts → definition/shell-head.test.ts}

@@ -5,7 +5,7 @@
 
 import { describe, expect, it } from "vitest";
 
-import type { Scope } from "../results/index.ts";
+import type { Scope } from "../../results/index.ts";
 import { buildReportMeta, defineReport } from "./report.ts";
 
 const emptyScope = { snapshots: [] } as unknown as Scope;
@@ -97,6 +97,6 @@ describe("defineReport head 通道(装载校验)", () => {
     ];
     const definition = defineReport({ content: null, head });
     expect(definition.head).toEqual(head);
-    expect(buildReportMeta(definition, emptyScope, "report")).not.toHaveProperty("head");
+    expect(buildReportMeta(definition, emptyScope)).not.toHaveProperty("head");
   });
 });

package/src/report/{text/table.ts → definition/table-text.ts}

@@ -6,10 +6,10 @@
 // 列宽按显示宽度算(CJK 记 2 列);null 渲染 —,不补 0;超宽先折最宽的左对齐列,
 // 压到下限仍放不下就从右侧丢列并如实报数(「截断报剩余」是既有契约,不在这里破例)。
 
-import type { TableProps, TableRow } from "../primitives.tsx";
-import type { TextContext } from "../tree.ts";
-import { countText, localeText, resolveLocalizedText } from "../locale.ts";
-import { charDisplayWidth, renderAlignedRows, stringWidth, wrapDisplay, type ColumnAlign } from "./layout.ts";
+import type { TableProps, TableRow } from "./primitives.tsx";
+import type { TextContext } from "./tree.ts";
+import { countText, localeText, resolveLocalizedText } from "../model/locale.ts";
+import { charDisplayWidth, renderAlignedRows, stringWidth, wrapDisplay, type ColumnAlign } from "../model/text-layout.ts";
 
 const MISSING_MARK = "—";
 /** 列间距,与 renderAlignedRows 的 join("   ") 一致。 */

package/src/report/{tree.ts → definition/tree.ts}

@@ -10,12 +10,37 @@
 // 只在 resolve 阶段被懒加载,永远不进渲染路径。
 
 import type { ReactNode } from "react";
-import type { AttemptLocator } from "../results/locator.ts";
-import type { Results, Scope } from "../results/types.ts";
-import { DEFAULT_REPORT_LOCALE, type ReportLocale } from "./locale.ts";
-import type { ReportInput } from "./types.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
+import type { AttemptEvidence } from "../../results/attempt-evidence.ts";
+import type { Results, Scope } from "../../results/types.ts";
+import { DEFAULT_REPORT_LOCALE, type ReportLocale } from "../model/locale.ts";
+import type { ReportInput } from "../model/types.ts";
 import type { ReportMeta } from "./report.ts";
 
+// ───────────────────────── 当前页判别(PageContext) ─────────────────────────
+
+/** scope-input page 的当前页上下文:消费宿主选择的 Scope,没有 locator/evidence。 */
+export interface ScopePageContext {
+  id: string;
+  input: "scope";
+}
+
+/** attempt-input page 的当前页上下文:按 locator 消费一份 AttemptEvidence。 */
+export interface AttemptPageContext {
+  id: string;
+  input: "attempt";
+  locator: AttemptLocator;
+  evidence: AttemptEvidence;
+}
+
+/**
+ * 当前渲染中的页判别联合(docs/feature/reports/library/shell.md「行为约束」、
+ * library/attempt-detail.md「page 输入与 spec / data 形态」)。经 ComposeContext.page 与
+ * ResolveContext.page 双双可见:组合组件靠它读当前页 id 与输入分支;attempt 叶子组件靠它
+ * 取省略 input 时的缺省 evidence。
+ */
+export type PageContext = ScopePageContext | AttemptPageContext;
+
 // ───────────────────────── 节点形状 ─────────────────────────
 
 /** 标准 jsx-runtime 元素形状;text 宿主只认 type / props,不管 $$typeof。 */
@@ -67,8 +92,12 @@ export interface TextContext {
   locale: ReportLocale;
   /** 容器组件渲染 children 用,宽度显式传递。 */
   render(node: ReportNode, width?: number): string;
-  /** 下钻命令,通证据室:`niceeval show @<locator>`。 */
-  attemptCommand(locator: AttemptLocator): string;
+  /**
+   * 下钻命令,通 attempt-input page:`niceeval show @<locator>`。当前报告没有声明
+   * attempt-input page 时不存在——宿主不生成假命令,locator 只是文本(architecture.md
+   * 「Attempt 详情是一张参数化 page」)。
+   */
+  attemptCommand?(locator: AttemptLocator): string;
   /**
    * 组索引一类「按实验收窄」命令的生成;宿主注入以携带完整上下文(--results / --report /
    * --page 与位置参数),默认 `niceeval show --exp <id>`。非契约字段,官方组件内部用。
@@ -77,8 +106,12 @@ export interface TextContext {
 }
 
 export interface WebContext {
-  /** 证据室深链,同 view 的 attempt 路由(`#/attempt/@<locator>`,单段、不透明)。 */
-  attemptHref(locator: AttemptLocator): string;
+  /**
+   * attempt-input page 深链,同 view 的 attempt 路由(`#/attempt/@<locator>`,单段、不透明)。
+   * 当前报告没有声明 attempt-input page 时不存在——宿主不生成空 href 或假链接,locator 只是
+   * 文本(architecture.md「Attempt 详情是一张参数化 page」)。
+   */
+  attemptHref?(locator: AttemptLocator): string;
   /** chrome 文案的 locale;官方组件渲染面经上下文读取,宿主外默认 "en"。 */
   locale: ReportLocale;
 }
@@ -86,6 +119,8 @@ export interface WebContext {
 /** 双面组件解析面的上下文:宿主注入的数据来源;props 显式给出 input 时以 props 为准。 */
 export interface ResolveContext {
   input: ReportInput;
+  /** 当前页判别;attempt 叶子组件省略 input 时从这里的 attempt 分支取缺省 evidence。 */
+  page: PageContext;
 }
 
 /** 组合组件的上下文:宿主 Scope、结果根完整读取面与规范化后的报告声明。 */
@@ -96,6 +131,8 @@ export interface ComposeContext {
   results: Results;
   /** 规范化后的报告声明,只读(docs/feature/reports/library/layout.md「自定义组件」)。 */
   report: ReportMeta;
+  /** 当前页判别:scope 分支只有 id;attempt 分支带 locator + evidence。 */
+  page: PageContext;
 }
 
 export interface ComponentFaces<P, R = P> {
@@ -125,9 +162,9 @@ export type ReportComponent<P> = ((props: P) => ReactNode) & {
 };
 
 // web 面的环境上下文:web 宿主渲染前设好;宿主之外(组件直接嵌进用户 React 应用)
-// 用默认值 —— attemptHref 默认 view 的 attempt 路由格式。
+// 用默认值——没有 attemptHref,组件显式传 prop 才产生外部链接(architecture.md
+// 「Attempt 详情是一张参数化 page」:没有 target 时 locator 只是文本,不生成假 href)。
 const DEFAULT_WEB_CONTEXT: WebContext = {
-  attemptHref: (locator) => `#/attempt/${locator}`,
   locale: DEFAULT_REPORT_LOCALE,
 };
 let activeWebContext: WebContext | null = null;
@@ -143,11 +180,6 @@ export function runWithWebContext<T>(ctx: WebContext, fn: () => T): T {
   }
 }
 
-/** 官方组件的装配用:宿主上下文激活时才把 ctx.attemptHref 当默认下钻。 */
-export function isHostWebContextActive(): boolean {
-  return activeWebContext !== null;
-}
-
 /** 函数形态:组合组件,只装配已有组件,可以异步;ctx 携带 scope / results / report。 */
 export function defineComponent<P>(
   compose: (props: P, context: ComposeContext) => ReportNode | Promise<ReportNode>,
@@ -269,11 +301,13 @@ export class ResolveMemo {
   }
 }
 
-/** resolveReportTree 的环境:宿主注入的 Scope / 读取面 / 规范化声明。 */
+/** resolveReportTree 的环境:宿主注入的 Scope / 读取面 / 规范化声明 / 当前页判别。 */
 export interface ResolveEnv {
   scope: Scope;
   results: Results;
   report: ReportMeta;
+  /** 当前渲染的页:scope 分支只有 id;attempt 分支带 locator + evidence。 */
+  page: PageContext;
   /** 一次页渲染一份;跨页共享缓存时由宿主显式传同一实例。 */
   memo?: ResolveMemo;
 }
@@ -323,7 +357,7 @@ function bareTextError(value: string | number, path: string[]): Error {
  */
 export async function resolveReportTree(node: ReportNode, env: ResolveEnv): Promise<ReportNode> {
   const memo = env.memo ?? new ResolveMemo();
-  const composeCtx: ComposeContext = { scope: env.scope, results: env.results, report: env.report };
+  const composeCtx: ComposeContext = { scope: env.scope, results: env.results, report: env.report, page: env.page };
   return resolveNode(node, { memo, composeCtx }, []);
 }
 
@@ -367,6 +401,7 @@ async function resolveNode(node: ReportNode | string | number, state: ResolveSta
       const input = ((props as { input?: unknown }).input as ReportInput | undefined) ?? state.composeCtx.scope;
       const ctx: InternalResolveContext = {
         input,
+        page: state.composeCtx.page,
         memoFetch: <T,>(dataFn: unknown, dataInput: unknown, options: unknown, compute: () => Promise<T>) =>
           state.memo.fetch(dataFn, dataInput, options, compute) as Promise<T>,
       };
@@ -528,9 +563,10 @@ function shellQuote(value: string): string {
 export function createTextContext(options?: TextRenderOptions): TextContext {
   const width = Math.max(20, options?.width ?? 80);
   const locale = options?.locale ?? DEFAULT_REPORT_LOCALE;
-  // 默认下钻命令:AttemptLocator 是 `@` 前缀的不透明短串,`niceeval show @<locator>` 是
-  // show 已实现的真实 CLI 语法,不需要反查 eval id 再拼一条近似命令。
-  const attemptCommand = options?.attemptCommand ?? ((locator: AttemptLocator) => `niceeval show ${locator}`);
+  // 没有默认值:当前报告没有声明 attempt-input page 时不存在下钻命令——宿主(report.ts /
+  // web.ts 的渲染入口)据规范化 definition 是否有 attempt page 决定要不要注入生成器,
+  // 这里只透传调用方给的值(architecture.md「Attempt 详情是一张参数化 page」)。
+  const attemptCommand = options?.attemptCommand;
   const experimentCommand =
     options?.experimentCommand ?? ((prefix: string) => `niceeval show --exp ${shellQuote(prefix)}`);
   const make = (w: number): TextContext => ({