niceeval 0.9.1 → 0.10.2

package/dist/report/{types.d.ts → model/types.d.ts}

@@ -1,6 +1,8 @@
-import type { AttemptHandle, Scope, ScopeWarning, Snapshot } from "../results/types.ts";
-import type { AttemptLocator } from "../results/locator.ts";
-import type { ExperimentRunInfo, JsonValue, Verdict } from "../types.ts";
+import type { AttemptHandle, Scope, ScopeWarning, Snapshot } from "../../results/types.ts";
+import type { AttemptIdentity, AttemptLocator } from "../../results/locator.ts";
+import type { AttemptEvidenceCapabilities } from "../../results/attempt-evidence.ts";
+import type { AnnotatedEvalSourceSummary, AnnotatedSourceLine } from "../../results/annotated-source.ts";
+import type { AssertionResult, AttemptError, DiagnosticRecord, ExperimentRunInfo, InputRequest, JsonValue, PhaseTiming, SourceLoc, ToolName, TraceSpan, Usage, Verdict } from "../../types.ts";
 import type { LocalizedText, ReportLocale } from "./locale.ts";
 export type { ScopeWarning };
 export type { AttemptLocator };
@@ -57,18 +59,24 @@ export interface CustomDimension {
     of(attempt: AttemptHandle): string;
 }
 /**
- * flag() / runConfig() 的产物:把 experiment 声明的 flag 或顶层运行配置当分组维度。
- * 读取的 JSON 值可能是任意形状,分组显示键按稳定 JSON 规则生成;缺失值显示内置文案
- * `(missing)`,不同原始值撞出同一显示键时计算报错并要求改用 CustomDimension。
+ * flag() / label() / runConfig() 的产物:把 experiment 声明的 flag、报告标注 label 或
+ * 顶层运行配置当分组维度。读取的落盘值可能是任意形状,分组显示键按稳定 JSON 规则生成;
+ * 缺失值显示内置文案 `(missing)`,不同原始值撞出同一显示键时计算报错并要求改用 CustomDimension。
  */
 export interface DimensionRef {
-    readonly kind: "flag" | "runConfig";
+    readonly kind: "flag" | "runConfig" | "label";
     readonly name: string;
     readonly label?: LocalizedText;
     readonly unit?: string;
 }
-/** 维度槽的输入:内置维度、自定义维度,或 flag() / runConfig() 的产物。 */
+/** 维度槽的输入:内置维度、自定义维度,或 flag() / label() / runConfig() 的产物。 */
 export type DimensionInput = BuiltInDimension | CustomDimension | DimensionRef;
+/**
+ * series 类选项(MetricScatter / MetricLine / ExperimentComparison)的输入:单维度,或
+ * 非空数组解析为复合维度——name 依声明顺序以 ` × ` 连接,每个 attempt 的值为各成员显示键
+ * 以 ` · ` 连接,任一成员缺失沿用 `(missing)` 显示键参与连接(docs/feature/reports/library/metrics.md)。
+ */
+export type SeriesInput = DimensionInput | readonly [DimensionInput, ...DimensionInput[]];
 /** MetricLine 的 x 轴:必须是数值;字符串配置显式映射,组件不猜 low < medium < high。 */
 export interface NumericAxis {
     name: string;
@@ -252,7 +260,7 @@ export interface VerdictTally {
     skipped: number;
 }
 /**
- * 一个范围的摘要:快照时间窗、experiment / eval / attempt 数、两级判定计票、端到端成功率
+ * 一个范围的摘要:快照时间窗、experiment / eval / attempt 数、两级判定计票、端到端通过率
  * 和总成本。eval 的身份键是 experimentId + evalId;data 恒携带两级计票,渲染面显示哪一级
  * 由呈现 prop `votes` 决定,不改变 data(docs/feature/reports/library/summaries.md)。
  */
@@ -320,17 +328,6 @@ export interface TraceWaterfallRow {
     /** 顶层 span 摘要,按 startOffsetMs 升序。 */
     spans: readonly TraceSpanSummary[];
 }
-/** 一个可比组的数据;三个子块都只消费本组快照,不能含其它父目录的引用。 */
-export interface ExperimentComparisonGroupData {
-    /** experiment id 的完整父路径;根目录 experiment 使用完整 id。 */
-    key: string;
-    summary: ScopeSummaryData;
-    scatter: ScatterData;
-    experiments: ExperimentListItem[];
-}
-export interface ExperimentComparisonData {
-    groups: ExperimentComparisonGroupData[];
-}
 /**
  * `AttemptList` 一项 = 一次 attempt:身份、判定、算好的单行结果摘要与证据引用。
  * 完整 assertions、Judge evidence、diagnostics、cause 与 stack 不进列表 data;
@@ -404,3 +401,140 @@ export interface ExperimentListItem {
     lastRunAt: string;
     evalRows: ExperimentListEvalRow[];
 }
+/** `AttemptSummary` 的 data:身份、verdict、时间与成本——恒非空。 */
+export interface AttemptSummaryData {
+    locator: AttemptLocator;
+    identity: AttemptIdentity;
+    verdict: Verdict;
+    startedAt?: string;
+    durationMs: number;
+    costUSD: number | null;
+    capabilities: AttemptEvidenceCapabilities;
+}
+/** `AttemptError` 的 data:结构化 error 一层原因 + cause + stack;没有 error 时 null。 */
+export type AttemptErrorData = AttemptError;
+/** `AttemptAssertions` 的 data:非 passed 条目默认展开,passed 按 group 折叠计数;没有 assertion 时 null。 */
+export interface AttemptAssertionsData {
+    /** failed / unavailable / soft 全部非 passed 条目,按原始声明顺序。 */
+    attention: AssertionResult[];
+    /** passed 条目按 groupPath.join(" > ") 分组(无分组键为 ""),组内保持原始顺序。 */
+    passedGroups: {
+        group: string;
+        items: AssertionResult[];
+    }[];
+}
+/** `AttemptSource` 源码行内的一轮执行：send 头事实 + 标准事件流归并出的完整回复。 */
+export interface AttemptSourceTurn {
+    label: string;
+    status: "completed" | "failed" | "waiting";
+    durationMs?: number;
+    sentText: string;
+    replies: AttemptConversationReply[];
+}
+/** AnnotatedSourceLine 加上 web 源码视图需要的行内执行轮。 */
+export interface AttemptSourceLineData extends AnnotatedSourceLine {
+    turns: AttemptSourceTurn[];
+}
+/** `AttemptSource` 的 data:AnnotatedEvalSource + 按 loc 投影的标准事件流;没有 source 时 null。 */
+export interface AttemptSourceData {
+    /** text 面拼 `niceeval show <locator> --source` 下钻命令用;web 面不需要。 */
+    locator: AttemptLocator;
+    sourcePath: string;
+    lines: AttemptSourceLineData[];
+    unmapped: AssertionResult[];
+    /** 没有 loc、指向其它文件或越界的轮次；不能静默丢弃，放在源码块末尾。 */
+    unlocatedTurns: AttemptSourceTurn[];
+    summary: AnnotatedEvalSourceSummary;
+}
+/** `AttemptFixPrompt` 的 data:单条 attempt 的复制修复 prompt;passed/skipped 或无可操作失败时 null。 */
+export interface AttemptFixPromptData {
+    prompt: string;
+}
+/** `AttemptTimeline` 的 data:runner 阶段主链 + 收尾段,以及可选的 trace(供 turn 节点按 traceId 关联 span);没有 phase 时 null。 */
+export interface AttemptTimelineData {
+    /** text 面拼 `niceeval show <locator> --timing` 下钻命令用;web 面不需要。 */
+    locator: AttemptLocator;
+    phases: PhaseTiming[];
+    trace: TraceSpan[] | null;
+}
+/** `AttemptConversation` 一轮:由带 `loc` 的 user 消息开启;`loc` 缺省表示流首无位置信息的兜底轮(旧 artifact)。 */
+export interface AttemptConversationRound {
+    loc?: SourceLoc;
+    sentText: string;
+    replies: AttemptConversationReply[];
+}
+/** 一轮内的回复条目;`raw` 是未识别事件类型的原样兜底,不吞没其余事件。 */
+export type AttemptConversationReply = {
+    kind: "assistant" | "user" | "thinking" | "error";
+    text: string;
+} | {
+    kind: "tool";
+    callId: string;
+    name: string;
+    tool?: ToolName;
+    input: JsonValue;
+    output?: JsonValue;
+    status?: "completed" | "failed" | "rejected";
+} | {
+    kind: "skill";
+    skill: string;
+} | {
+    kind: "subagent";
+    callId: string;
+    name: string;
+    remoteUrl?: string;
+    output?: JsonValue;
+    status?: "completed" | "failed";
+} | {
+    kind: "input";
+    request: InputRequest;
+} | {
+    kind: "compaction";
+    reason?: string;
+} | {
+    kind: "raw";
+    raw: JsonValue;
+};
+/** `AttemptConversation` 的 data:标准事件流按 loc 分轮;没有 events 时 null。 */
+export interface AttemptConversationData {
+    /** text 面拼 `niceeval show <locator> --execution` 下钻命令用;web 面不需要。 */
+    locator: AttemptLocator;
+    rounds: AttemptConversationRound[];
+}
+/** `AttemptDiagnostics` 的 data:按 lifecycle phase 分组;没有 diagnostics 时 null。 */
+export interface AttemptDiagnosticsData {
+    groups: {
+        phase: string;
+        items: DiagnosticRecord[];
+    }[];
+}
+/** `AttemptUsage` 的 data:token / cache token / provider usage 明细;没有 usage 时 null。 */
+export interface AttemptUsageData {
+    usage: Usage;
+    costUSD: number | null;
+}
+/** `AttemptTrace` 的 data:不与 runner 节点合并的原始 OTel span 列表;没有 trace 时 null。 */
+export interface AttemptTraceData {
+    /** text 面拼 `niceeval show <locator> --timing` 下钻命令用;web 面不需要。 */
+    locator: AttemptLocator;
+    spans: TraceSpan[];
+}
+/** `AttemptDiff` 一个文件的摘要:`net` 恒 !== "none"(净无变化的触碰不进这份列表)。 */
+export interface AttemptDiffFileEntry {
+    path: string;
+    net: "added" | "modified" | "deleted";
+    /** 净行数变化(公共前后缀修剪后的近似上界,与 `niceeval show --diff` 同一算法)。 */
+    lines: {
+        added: number;
+        deleted: number;
+    };
+    binary?: true;
+    /** 触碰过该文件的窗口标签,按时序;供 text 面引用 `--diff` 深挖同一批窗口。 */
+    windows: string[];
+}
+/** `AttemptDiff` 的 data:generated / modified / deleted 的文件级摘要;没有变更时 null。 */
+export interface AttemptDiffData {
+    /** text 面拼 `niceeval show <locator> --diff` 下钻命令用;web 面不需要。 */
+    locator: AttemptLocator;
+    files: AttemptDiffFileEntry[];
+}

package/dist/report/react/index.d.ts

@@ -1,21 +1,32 @@
-export { AttemptList } from "./AttemptList.tsx";
-export { EvalList } from "./EvalList.tsx";
-export { ExperimentList } from "./ExperimentList.tsx";
-export { ScopeSummary } from "./ScopeSummary.tsx";
-export { ExperimentComparisonView as ExperimentComparison } from "./ExperimentComparison.tsx";
-export { MetricTable } from "./MetricTable.tsx";
-export { MetricMatrix } from "./MetricMatrix.tsx";
-export { MetricBars } from "./MetricBars.tsx";
-export { MetricScatter } from "./MetricScatter.tsx";
-export { MetricLine } from "./MetricLine.tsx";
-export { DeltaTable } from "./DeltaTable.tsx";
-export { Scoreboard } from "./Scoreboard.tsx";
-export { HeroCard } from "./HeroCard.tsx";
-export { PoweredBy } from "./PoweredBy.tsx";
-export { ScopeWarnings } from "./ScopeWarnings.tsx";
-export { CopyFixPrompt } from "./CopyFixPrompt.tsx";
-export { TraceWaterfall } from "./TraceWaterfall.tsx";
-export type { AttemptListItem, AttemptLocator, CopyFixPromptData, DeltaData, EvalListItem, ExperimentComparisonData, ExperimentComparisonGroupData, ExperimentListEvalRow, ExperimentListItem, HeroData, LineData, MatrixData, MetricCell, MetricColumn, ScatterData, ScopeSummaryData, ScopeWarning, ScoreboardData, TableData, TraceSpanSummary, TraceWaterfallRow, VerdictTally, } from "../types.ts";
-export { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel } from "../locale.ts";
-export type { LocalizedText, ReportLocale } from "../locale.ts";
-export { NRE_PALETTE, colorClassForKey, colorHexForKey, colorIndexForKey, seriesClassForKey } from "./colors.ts";
+export { AttemptList } from "../components/entity-lists/AttemptList.tsx";
+export { EvalList } from "../components/entity-lists/EvalList.tsx";
+export { ExperimentList } from "../components/entity-lists/ExperimentList.tsx";
+export { ScopeSummary } from "../components/summaries/ScopeSummary.tsx";
+export { MetricTable } from "../components/metric-views/MetricTable.tsx";
+export { MetricMatrix } from "../components/metric-views/MetricMatrix.tsx";
+export { MetricBars } from "../components/metric-views/MetricBars.tsx";
+export { MetricScatter } from "../components/metric-views/MetricScatter.tsx";
+export { MetricLine } from "../components/metric-views/MetricLine.tsx";
+export { DeltaTable } from "../components/metric-views/DeltaTable.tsx";
+export { Scoreboard } from "../components/metric-views/Scoreboard.tsx";
+export { HeroCard } from "../components/site-components/HeroCard.tsx";
+export { PoweredBy } from "../components/site-components/PoweredBy.tsx";
+export { ScopeWarnings } from "../components/site-components/ScopeWarnings.tsx";
+export { CopyFixPrompt } from "../components/site-components/CopyFixPrompt.tsx";
+export { TraceWaterfall } from "../components/site-components/TraceWaterfall.tsx";
+export { AttemptSummary } from "../components/attempt-detail/AttemptSummary.tsx";
+export { AttemptError } from "../components/attempt-detail/AttemptError.tsx";
+export { AttemptAssertions } from "../components/attempt-detail/AttemptAssertions.tsx";
+export { AttemptSource } from "../components/attempt-detail/AttemptSource.tsx";
+export { AttemptFixPrompt } from "../components/attempt-detail/AttemptFixPrompt.tsx";
+export { AttemptTimeline } from "../components/attempt-detail/AttemptTimeline.tsx";
+export { AttemptConversation } from "../components/attempt-detail/AttemptConversation.tsx";
+export { AttemptDiagnostics } from "../components/attempt-detail/AttemptDiagnostics.tsx";
+export { AttemptUsage } from "../components/attempt-detail/AttemptUsage.tsx";
+export { AttemptTrace } from "../components/attempt-detail/AttemptTrace.tsx";
+export { AttemptDiff } from "../components/attempt-detail/AttemptDiff.tsx";
+export type { AttemptAssertionsData, AttemptConversationData, AttemptConversationReply, AttemptConversationRound, AttemptDiagnosticsData, AttemptDiffData, AttemptDiffFileEntry, AttemptErrorData, AttemptFixPromptData, AttemptListItem, AttemptLocator, AttemptSourceData, AttemptSourceLineData, AttemptSourceTurn, AttemptSummaryData, AttemptTimelineData, AttemptTraceData, AttemptUsageData, CopyFixPromptData, DeltaData, EvalListItem, ExperimentListEvalRow, ExperimentListItem, HeroData, LineData, MatrixData, MetricCell, MetricColumn, ScatterData, ScopeSummaryData, ScopeWarning, ScoreboardData, TableData, TraceSpanSummary, TraceWaterfallRow, VerdictTally, } from "../model/types.ts";
+export type { AttemptEvidence, AttemptEvidenceCapabilities } from "../../results/attempt-evidence.ts";
+export { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel } from "../model/locale.ts";
+export type { LocalizedText, ReportLocale } from "../model/locale.ts";
+export { NRE_PALETTE, colorClassForKey, colorHexForKey, colorIndexForKey, seriesClassForKey } from "../assets/colors.ts";

package/dist/report/react/index.js

@@ -6,26 +6,38 @@
 //   - 组件只认「算好的可序列化数据」:零 hooks、零数据操作;
 //   - 样式随包发布:配套 ./styles.css(nre-* 稳定类名),使用者在其后加载覆盖即可;
 //   - 渐进增强脚本 ./enhance.js 可选加载,初始静态 HTML 无 JS 完整可读;
-//   - 跨块配色一致:维度键 → 稳定散列 → 固定调色板下标(colors.ts)。
-export { AttemptList } from "./AttemptList.js";
-export { EvalList } from "./EvalList.js";
-export { ExperimentList } from "./ExperimentList.js";
-export { ScopeSummary } from "./ScopeSummary.js";
-export { ExperimentComparisonView as ExperimentComparison } from "./ExperimentComparison.js";
-export { MetricTable } from "./MetricTable.js";
-export { MetricMatrix } from "./MetricMatrix.js";
-export { MetricBars } from "./MetricBars.js";
-export { MetricScatter } from "./MetricScatter.js";
-export { MetricLine } from "./MetricLine.js";
-export { DeltaTable } from "./DeltaTable.js";
-export { Scoreboard } from "./Scoreboard.js";
+//   - 跨块配色一致:维度键 → 稳定散列 → 固定调色板下标(../assets/colors.ts)。
+export { AttemptList } from "../components/entity-lists/AttemptList.js";
+export { EvalList } from "../components/entity-lists/EvalList.js";
+export { ExperimentList } from "../components/entity-lists/ExperimentList.js";
+export { ScopeSummary } from "../components/summaries/ScopeSummary.js";
+export { MetricTable } from "../components/metric-views/MetricTable.js";
+export { MetricMatrix } from "../components/metric-views/MetricMatrix.js";
+export { MetricBars } from "../components/metric-views/MetricBars.js";
+export { MetricScatter } from "../components/metric-views/MetricScatter.js";
+export { MetricLine } from "../components/metric-views/MetricLine.js";
+export { DeltaTable } from "../components/metric-views/DeltaTable.js";
+export { Scoreboard } from "../components/metric-views/Scoreboard.js";
 // 站点组件的纯 web 面(data 形态;Hero 是组合组件,只住 niceeval/report)
-export { HeroCard } from "./HeroCard.js";
-export { PoweredBy } from "./PoweredBy.js";
-export { ScopeWarnings } from "./ScopeWarnings.js";
-export { CopyFixPrompt } from "./CopyFixPrompt.js";
-export { TraceWaterfall } from "./TraceWaterfall.js";
-// locale(官方组件 chrome 文案;LocalizedText 的按 locale 解析也用它)
-export { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel } from "../locale.js";
+export { HeroCard } from "../components/site-components/HeroCard.js";
+export { PoweredBy } from "../components/site-components/PoweredBy.js";
+export { ScopeWarnings } from "../components/site-components/ScopeWarnings.js";
+export { CopyFixPrompt } from "../components/site-components/CopyFixPrompt.js";
+export { TraceWaterfall } from "../components/site-components/TraceWaterfall.js";
+// Attempt 详情组件族的纯 web 面(data 形态;AttemptAssessment / AttemptDetail 是组合组件,
+// 不产生新渲染面,只住 niceeval/report)
+export { AttemptSummary } from "../components/attempt-detail/AttemptSummary.js";
+export { AttemptError } from "../components/attempt-detail/AttemptError.js";
+export { AttemptAssertions } from "../components/attempt-detail/AttemptAssertions.js";
+export { AttemptSource } from "../components/attempt-detail/AttemptSource.js";
+export { AttemptFixPrompt } from "../components/attempt-detail/AttemptFixPrompt.js";
+export { AttemptTimeline } from "../components/attempt-detail/AttemptTimeline.js";
+export { AttemptConversation } from "../components/attempt-detail/AttemptConversation.js";
+export { AttemptDiagnostics } from "../components/attempt-detail/AttemptDiagnostics.js";
+export { AttemptUsage } from "../components/attempt-detail/AttemptUsage.js";
+export { AttemptTrace } from "../components/attempt-detail/AttemptTrace.js";
+export { AttemptDiff } from "../components/attempt-detail/AttemptDiff.js";
+// locale(官方组件 chrome 文案的语言;LocalizedText 的按 locale 解析也用它)
+export { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel } from "../model/locale.js";
 // 稳定配色(自定义组件想与官方组件同键同色时用;seriesClassForKey 配 CSS 的 --nre-series)
-export { NRE_PALETTE, colorClassForKey, colorHexForKey, colorIndexForKey, seriesClassForKey } from "./colors.js";
+export { NRE_PALETTE, colorClassForKey, colorHexForKey, colorIndexForKey, seriesClassForKey } from "../assets/colors.js";

package/dist/report/{load.d.ts → runtime/load.d.ts}

@@ -1,4 +1,4 @@
-import { type ReportDefinition } from "./report.ts";
+import { type ReportDefinition } from "../definition/report.ts";
 /** 可预期的装载错误:宿主打一句英文直说问题与下一步,不抛堆栈。 */
 export declare class ReportLoadError extends Error {
 }

package/dist/report/{load.js → runtime/load.js}

@@ -14,7 +14,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { isReportDefinition } from "./report.js";
+import { isReportDefinition } from "../definition/report.js";
 /** 可预期的装载错误:宿主打一句英文直说问题与下一步,不抛堆栈。 */
 export class ReportLoadError extends Error {
 }

package/dist/report/runtime/text.d.ts

@@ -0,0 +1,67 @@
+import type { Results, Scope } from "../../results/types.ts";
+import { type PageContext, type ReportNode, type TextRenderOptions } from "../definition/tree.ts";
+import { type ReportDefinition, type ReportMeta, type ReportPage } from "../definition/report.ts";
+import { type ReportLocale } from "../model/locale.ts";
+/** `--page` 未命中:宿主据此按用法错误退出并列出可用页 id(只列 navigation !== false 的)。 */
+export declare class ReportPageNotFoundError extends Error {
+    readonly pageId: string;
+    readonly available: string[];
+    constructor(pageId: string, available: string[]);
+}
+/** 显式请求了 attempt-input page,但当前入口没有 locator 可注入 evidence。 */
+export declare class ReportPageNeedsLocatorError extends Error {
+    readonly pageId: string;
+    constructor(pageId: string);
+}
+/**
+ * 挑选要渲染的 page:省略 pageId 时挑第一张 `navigation !== false` 的页(跳过参数化详情页,
+ * 它没有 locator 就不可打开);显式 pageId 命中 attempt-input page 时报
+ * ReportPageNeedsLocatorError——这个入口没有 locator,不能拿 Scope 强行 resolve。
+ */
+export declare function pickReportPage(definition: ReportDefinition, pageId?: string): ReportPage;
+/** 宿主注入的渲染上下文:官方口径挑好的 Scope 与结果根完整读取面。 */
+export interface ReportHostContext {
+    scope: Scope;
+    /** 组合组件 ctx.results 的来源;历史视图从这里自行挑 Snapshot[]。 */
+    results: Results;
+}
+export interface RenderReportTextOptions extends TextRenderOptions {
+    /** 渲染哪一页;缺省第一张可导航页。命中 attempt-input page 抛 ReportPageNeedsLocatorError,未命中抛 ReportPageNotFoundError。 */
+    pageId?: string;
+}
+/**
+ * text 宿主的装载语义:选页(只能是 scope-input page,见 pickReportPage)→ resolve(组合展开 +
+ * spec 取数,唯一的 await 边界)→ 树校验 → 遍历渲染 text 面。不需要 react-dom。宿主不在报告树外
+ * 另设警告通道——挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放
+ * 是作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
+ */
+export declare function renderReportToText(definition: ReportDefinition, ctx: ReportHostContext, options?: RenderReportTextOptions): Promise<string>;
+/** 页索引标题行(show 多页索引 / view 导航共用的解析结果):按 locale 解析的标题字符串。 */
+export declare function reportTitleText(definition: ReportDefinition, scope: Scope, locale: ReportLocale): string;
+/** 宿主索引命令的完整上下文(docs/feature/reports/show/reports.md「索引命令携带完整上下文」)。 */
+export interface HostCommandContext {
+    patterns: string[];
+    results?: string;
+    experiment?: string;
+    report?: string;
+    page?: string;
+}
+/** 逐页渲染的宿主上下文:官方口径的 Scope、结果根读取面、规范化声明(ctx.report)与当前页判别。 */
+export interface ReportTreeHostContext {
+    scope: Scope;
+    results: Results;
+    report: ReportMeta;
+    /** 当前渲染的页:scope 分支只有 id;attempt 分支带 locator + evidence(宿主已完成寻址与装配)。 */
+    page: PageContext;
+}
+export interface RenderTreeTextOptions extends TextRenderOptions {
+    /** 组索引命令的完整上下文;给了就按它拼命令,experimentCommand 显式注入时以后者为准。 */
+    commandContext?: HostCommandContext;
+}
+/**
+ * 渲染一页报告树的 text 面(宿主逐页调用;页选择归宿主):
+ * resolve(组合展开 + spec 取数)→ validate → render。宿主不在报告树外另设警告通道,
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现(内建报告每页都放它)。当前 definition 没有
+ * attempt-input page 时不注入默认下钻命令,调用方也没显式给,`ctx.attemptCommand` 就不存在。
+ */
+export declare function renderReportTreeToText(tree: ReportNode, ctx: ReportTreeHostContext, options?: RenderTreeTextOptions): Promise<string>;

package/dist/report/runtime/text.js

@@ -0,0 +1,114 @@
+// text 宿主(show)的渲染入口:装载好的 ReportDefinition/page → resolve(组合展开 + spec 取数)
+// → validate(两面资格)→ render(纯同步字符输出)。web 宿主的对应入口在 ./web.ts(那一侧才
+// import react-dom)。管线以页为单位执行;defineReport 本身与 ReportDefinition 的类型体系在
+// ../definition/report.ts,这里只做渲染编排与宿主联系面(页选择、索引命令拼装)。
+import { createTextContext, renderNodeToText, resolveReportTree, validateReportTree, ResolveMemo, } from "../definition/tree.js";
+import { buildReportMeta, resolveReportTitle, } from "../definition/report.js";
+import { resolveLocalizedText } from "../model/locale.js";
+/** 默认下钻命令:`niceeval show <locator>` 是 show 已实现的真实 CLI 语法,不需要反查 eval id 再拼近似命令。 */
+const DEFAULT_ATTEMPT_COMMAND = (locator) => `niceeval show ${locator}`;
+// ───────────────────────── 页选择与 text 宿主入口 ─────────────────────────
+/** `--page` 未命中:宿主据此按用法错误退出并列出可用页 id(只列 navigation !== false 的)。 */
+export class ReportPageNotFoundError extends Error {
+    pageId;
+    available;
+    constructor(pageId, available) {
+        super(`page "${pageId}" not found. Available pages: ${available.join(", ")}`);
+        this.pageId = pageId;
+        this.available = available;
+    }
+}
+/** 显式请求了 attempt-input page,但当前入口没有 locator 可注入 evidence。 */
+export class ReportPageNeedsLocatorError extends Error {
+    pageId;
+    constructor(pageId) {
+        super(`Page "${pageId}" is an attempt-input page and needs a locator — it cannot be opened with --page or #/page/<id> directly. ` +
+            "Use the host's locator addressing instead (niceeval show @<locator>, or the view attempt route), which resolves this page with the matching AttemptEvidence.");
+        this.pageId = pageId;
+    }
+}
+/**
+ * 挑选要渲染的 page:省略 pageId 时挑第一张 `navigation !== false` 的页(跳过参数化详情页,
+ * 它没有 locator 就不可打开);显式 pageId 命中 attempt-input page 时报
+ * ReportPageNeedsLocatorError——这个入口没有 locator,不能拿 Scope 强行 resolve。
+ */
+export function pickReportPage(definition, pageId) {
+    if (pageId === undefined) {
+        return definition.pages.find((p) => p.navigation !== false) ?? definition.pages[0];
+    }
+    const page = definition.pages.find((p) => p.id === pageId);
+    if (!page) {
+        throw new ReportPageNotFoundError(pageId, definition.pages.filter((p) => p.navigation !== false).map((p) => p.id));
+    }
+    if (page.input === "attempt")
+        throw new ReportPageNeedsLocatorError(page.id);
+    return page;
+}
+/**
+ * text 宿主的装载语义:选页(只能是 scope-input page,见 pickReportPage)→ resolve(组合展开 +
+ * spec 取数,唯一的 await 边界)→ 树校验 → 遍历渲染 text 面。不需要 react-dom。宿主不在报告树外
+ * 另设警告通道——挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放
+ * 是作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
+ */
+export async function renderReportToText(definition, ctx, options) {
+    const page = pickReportPage(definition, options?.pageId);
+    const meta = buildReportMeta(definition, ctx.scope);
+    const hasAttemptPage = definition.pages.some((p) => p.input === "attempt");
+    const resolved = await resolveReportTree(page.content, {
+        scope: ctx.scope,
+        results: ctx.results,
+        report: meta,
+        page: { id: page.id, input: "scope" },
+        memo: new ResolveMemo(),
+    });
+    validateReportTree(resolved);
+    return renderNodeToText(resolved, createTextContext({
+        ...options,
+        attemptCommand: options?.attemptCommand ?? (hasAttemptPage ? DEFAULT_ATTEMPT_COMMAND : undefined),
+    }));
+}
+/** 页索引标题行(show 多页索引 / view 导航共用的解析结果):按 locale 解析的标题字符串。 */
+export function reportTitleText(definition, scope, locale) {
+    return resolveLocalizedText(resolveReportTitle(definition, scope), locale);
+}
+function quoteArg(value) {
+    return /^[A-Za-z0-9._/@-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+/** 按上下文拼组索引的可复制命令:`niceeval show <patterns> --exp <id> [--results/--report/--page]`。 */
+function experimentCommandFor(ctx) {
+    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(" ");
+    };
+}
+/**
+ * 渲染一页报告树的 text 面(宿主逐页调用;页选择归宿主):
+ * resolve(组合展开 + spec 取数)→ validate → render。宿主不在报告树外另设警告通道,
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现(内建报告每页都放它)。当前 definition 没有
+ * attempt-input page 时不注入默认下钻命令,调用方也没显式给,`ctx.attemptCommand` 就不存在。
+ */
+export async function renderReportTreeToText(tree, ctx, options) {
+    const resolved = await resolveReportTree(tree, {
+        scope: ctx.scope,
+        results: ctx.results,
+        report: ctx.report,
+        page: ctx.page,
+        memo: new ResolveMemo(),
+    });
+    validateReportTree(resolved);
+    const hasAttemptPage = ctx.report.pages.some((p) => p.input === "attempt");
+    const textCtx = createTextContext({
+        ...options,
+        attemptCommand: options?.attemptCommand ?? (hasAttemptPage ? DEFAULT_ATTEMPT_COMMAND : undefined),
+        ...(options?.experimentCommand === undefined && options?.commandContext !== undefined
+            ? { experimentCommand: experimentCommandFor(options.commandContext) }
+            : {}),
+    });
+    return renderNodeToText(resolved, textCtx);
+}

package/dist/report/runtime/web.d.ts

@@ -0,0 +1,35 @@
+import type { AttemptLocator } from "../../results/locator.ts";
+import type { Scope } from "../../results/types.ts";
+import { type PageContext } from "../definition/tree.ts";
+import { type ReportLocale } from "../model/locale.ts";
+import { type ReportDefinition } from "../definition/report.ts";
+import { type ReportHostContext } from "./text.ts";
+export interface StaticHtmlOptions {
+    /** 渲染哪一页;缺省第一张可导航页。命中 attempt-input page 抛 ReportPageNeedsLocatorError。 */
+    pageId?: string;
+    /** 证据室深链;当前 definition 没有 attempt-input page 时不注入默认值,除非显式传入。 */
+    attemptHref?: (locator: AttemptLocator) => string;
+    /** 官方组件 chrome 文案的 locale;默认 "en"。 */
+    locale?: ReportLocale;
+}
+/**
+ * web 宿主的装载语义:选页(只能是 scope-input page)→ resolve(组合展开 + spec 取数,
+ * 唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外
+ * 另设警告通道——挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告
+ * 放不放是作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
+ */
+export declare function renderReportToStaticHtml(definition: ReportDefinition, ctx: ReportHostContext, options?: StaticHtmlOptions): Promise<string>;
+/**
+ * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
+ * ctx.report 是宿主规范化后的声明,ctx.page 是当前页判别(scope 或 attempt 分支)。
+ */
+export declare function renderReportTreeToStaticHtml(tree: import("../definition/tree.ts").ReportNode, ctx: {
+    scope: Scope;
+    results: import("../../results/types.ts").Results;
+    report: import("../definition/report.ts").ReportMeta;
+    page: PageContext;
+}, options?: {
+    attemptHref?: (locator: AttemptLocator) => string;
+    locale?: ReportLocale;
+}): Promise<string>;

package/dist/report/runtime/web.js

@@ -0,0 +1,70 @@
+// web 宿主(view --report)的装载入口:同一棵树走 web 面,renderToStaticMarkup 吐静态
+// HTML 烘进查看器的报告槽。只有这一侧真正 import react-dom(import 边界即运行时边界),
+// 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
+import { renderToStaticMarkup } from "react-dom/server";
+import { resolveReportTree, runWithWebContext, validateReportTree, ResolveMemo, } from "../definition/tree.js";
+import { DEFAULT_REPORT_LOCALE } from "../model/locale.js";
+import { buildReportMeta } from "../definition/report.js";
+import { pickReportPage } from "./text.js";
+/**
+ * 默认证据室深链:view 静态站的 attempt 文档路径,根相对(与 index.html 同级 —— scope-input
+ * page 恒在文档树的根)。文件名是 URL 编码后的 locator(architecture.md「Attempt 详情是一张
+ * 参数化 page」);磁盘/清单键用未编码的原始 locator,两者的对应关系与拆分只住在 view 的站点
+ * 管线(site.ts),这里只产出 href 字符串。从 attempt 页面自身内容渲染时(极少见:自定义
+ * attempt-input page 里嵌了别的证据引用组件)view 显式传入同级相对版本覆盖这个默认值,
+ * 不依赖这里的根相对形态。
+ */
+const DEFAULT_ATTEMPT_HREF = (locator) => `attempt/${encodeURIComponent(locator)}.html`;
+/**
+ * web 宿主的装载语义:选页(只能是 scope-input page)→ resolve(组合展开 + spec 取数,
+ * 唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外
+ * 另设警告通道——挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告
+ * 放不放是作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
+ */
+export async function renderReportToStaticHtml(definition, ctx, options) {
+    const page = pickReportPage(definition, options?.pageId);
+    const meta = buildReportMeta(definition, ctx.scope);
+    const hasAttemptPage = definition.pages.some((p) => p.input === "attempt");
+    const resolved = await resolveReportTree(page.content, {
+        scope: ctx.scope,
+        results: ctx.results,
+        report: meta,
+        page: { id: page.id, input: "scope" },
+        memo: new ResolveMemo(),
+    });
+    validateReportTree(resolved);
+    const webCtx = {
+        ...(options?.attemptHref !== undefined
+            ? { attemptHref: options.attemptHref }
+            : hasAttemptPage
+                ? { attemptHref: DEFAULT_ATTEMPT_HREF }
+                : {}),
+        locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
+    };
+    return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
+}
+/**
+ * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
+ * ctx.report 是宿主规范化后的声明,ctx.page 是当前页判别(scope 或 attempt 分支)。
+ */
+export async function renderReportTreeToStaticHtml(tree, ctx, options) {
+    const resolved = await resolveReportTree(tree, {
+        scope: ctx.scope,
+        results: ctx.results,
+        report: ctx.report,
+        page: ctx.page,
+        memo: new ResolveMemo(),
+    });
+    validateReportTree(resolved);
+    const hasAttemptPage = ctx.report.pages.some((p) => p.input === "attempt");
+    const webCtx = {
+        ...(options?.attemptHref !== undefined
+            ? { attemptHref: options.attemptHref }
+            : hasAttemptPage
+                ? { attemptHref: DEFAULT_ATTEMPT_HREF }
+                : {}),
+        locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
+    };
+    return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
+}