niceeval 0.9.0 → 0.10.0

package/src/report/{primitives.tsx → definition/primitives.tsx}

@@ -1,15 +1,19 @@
-// 排版原语 Row / Col / Section / Text / Style / Tabs / Tab / Table:八个内置双面组件,
-// 没有特殊机制(docs/feature/reports/library/layout.md)。web 面是普通 React 渲染;
+// 排版原语 Row / Col / Grid / Section / Stat / Text / Style / Tabs / Tab / Table:十个内置
+// 双面组件,没有特殊机制(docs/feature/reports/library/layout.md)。web 面是普通 React 渲染;
 // text 面用 ctx.render(child, 子宽) 显式传宽。Style 注入页级全局 CSS(树位置只决定声明
 // 顺序),text 面渲染为空。Table 是自定义表的标准件,官方表状组件的 text 面也建在它上面。
+// Grid / Stat 的语义层(normalizeGrid 展平校验、text 面的 TextGridPlan 排版)在
+// ./grid-layout.ts(docs/feature/reports/architecture.md「排版原语的语义层与面内布局」);
+// 本文件只声明两面适配,不重复那份算术。
 
-import type { ReactNode } from "react";
-import type { AttemptLocator } from "../results/locator.ts";
+import type { CSSProperties, ReactNode } from "react";
+import type { AttemptLocator } from "../../results/locator.ts";
 import { COMPONENT_RAW_CHILDREN, COMPONENT_ROLE, defineComponent, type ReportNode } from "./tree.ts";
-import { localeText, resolveLocalizedText, type LocalizedText, type ReportLocale } from "./locale.ts";
-import { indentBlock, joinColumns, stringWidth, wrapDisplay } from "./text/layout.ts";
-import type { ColumnAlign } from "./text/layout.ts";
-import { renderTableText } from "./text/table.ts";
+import { localeText, resolveLocalizedText, type LocalizedText, type ReportLocale } from "../model/locale.ts";
+import { indentBlock, joinColumns, padDisplay, stringWidth, wrapDisplay } from "../model/text-layout.ts";
+import type { ColumnAlign } from "../model/text-layout.ts";
+import { renderTableText } from "./table-text.ts";
+import { normalizeGrid, planTextGrid, type GridDensity, type GridVariant } from "./grid-layout.ts";
 
 function childArray(children: ReportNode): ReportNode[] {
   if (children === null || children === undefined || typeof children === "boolean") return [];
@@ -20,6 +24,9 @@ function cx(...parts: (string | undefined)[]): string {
   return parts.filter(Boolean).join(" ");
 }
 
+/** `null`/缺数据的统一显示符:Table 与 Stat 共用,不补成 0。 */
+const MISSING_MARK = "—";
+
 export interface LayoutProps {
   children?: ReportNode;
   className?: string;
@@ -76,27 +83,168 @@ export const Row = defineComponent<RowProps>({
 });
 Row.displayName = "Row";
 
+// ───────────────────────── Grid / Stat ─────────────────────────
+
+export interface GridProps extends LayoutProps {
+  /** 宽面最多摆几列;必须是有限正整数,运行时校验(docs/feature/reports/library/layout.md「Grid 与 Stat」)。 */
+  columns: number;
+  /** plain 无框;boxed 给每个 cell 完整四边框。默认 plain。 */
+  variant?: GridVariant;
+  /** 改变格内留白,并调整内置 Stat 的主值字号;不改变内容和分组。默认 regular。 */
+  density?: GridDensity;
+}
+
+/** boxed 单个 cell 的完整边框:同一份 TextGridPlan 决定内容宽度,四边不因换行残缺。 */
+function boxCellBlock(content: string, contentWidth: number): string {
+  const lines = content.length > 0 ? content.split("\n") : [""];
+  const top = `┌${"─".repeat(contentWidth + 2)}┐`;
+  const bottom = `└${"─".repeat(contentWidth + 2)}┘`;
+  const body = lines.map((line) => `│ ${padDisplay(line, contentWidth)} │`);
+  return [top, ...body, bottom].join("\n");
+}
+
+/** 一个物理行内的 cell 并排:顶对齐、短 block 补空行到同高(joinColumns 已有语义)。 */
+function renderGridRow(blocks: string[], contentWidths: number[], gutter: number, variant: GridVariant): string {
+  const separator = " ".repeat(gutter);
+  if (variant === "boxed") {
+    const boxed = blocks.map((block, i) => boxCellBlock(block, contentWidths[i]));
+    const boxWidths = contentWidths.map((w) => w + 4);
+    return joinColumns(boxed, boxWidths, separator);
+  }
+  return joinColumns(blocks, contentWidths, separator);
+}
+
+/**
+ * 自由摘要面板的格子容器:只负责呈现,不读取 Scope、不聚合 Metric。每个直接子节点
+ * (数组 / Fragment 先按 ReportNode 规则展平,空分支不占格)是一格;`Col` 把多个区块
+ * 归成一格。展平与 text 面排版的算术在 ./grid-layout.ts,这里只做两面结构适配。
+ */
+export const Grid = defineComponent<GridProps>({
+  web({ children, columns, variant, density, className }) {
+    const normalized = normalizeGrid({ children, columns, variant, density });
+    const style: CSSProperties = { "--nre-grid-max-columns": normalized.columns } as CSSProperties;
+    return (
+      <div
+        className={cx("nre", "nre-grid", `nre-grid--${normalized.variant}`, `nre-grid--${normalized.density}`, className)}
+        style={style}
+      >
+        {normalized.cells.map((cell) => (
+          <div className="nre-grid-cell" key={cell.key}>
+            {cell.node as ReactNode}
+          </div>
+        ))}
+      </div>
+    );
+  },
+  text({ children, columns, variant, density }, ctx) {
+    const normalized = normalizeGrid({ children, columns, variant, density });
+    if (normalized.cells.length === 0) return "";
+    const plan = planTextGrid({
+      availableWidth: ctx.width,
+      cellCount: normalized.cells.length,
+      columns: normalized.columns,
+      density: normalized.density,
+    });
+    // 确定计划后才对每个 cell 调用一次 ctx.render——不为试探列数重复渲染。
+    const blocks = normalized.cells.map((cell, i) => ctx.render(cell.node, plan.contentWidths[i % plan.columns]));
+    const rows: string[] = [];
+    for (let start = 0; start < blocks.length; start += plan.columns) {
+      const rowBlocks = blocks.slice(start, start + plan.columns);
+      const rowWidths = plan.contentWidths.slice(0, rowBlocks.length);
+      rows.push(renderGridRow(rowBlocks, rowWidths, plan.gutter, normalized.variant));
+    }
+    return rows.join("\n\n");
+  },
+});
+Grid.displayName = "Grid";
+
+export type StatTone = "neutral" | "positive" | "negative" | "warning";
+
+export interface StatProps {
+  label: LocalizedText;
+  /** 已格式化的主值;null 明确渲染为 —,不补成 0。 */
+  value: LocalizedText | number | null;
+  /** 主值下面的短解释;省略时不留空行。 */
+  detail?: LocalizedText;
+  /** 主值的语义色;不从正负号、单位或 Metric.better 猜。默认 neutral。 */
+  tone?: StatTone;
+  className?: string;
+}
+
+/**
+ * Grid / Stat 共享的显示值规范化:LocalizedText 走 resolveLocalizedText,number 走当前
+ * locale 的 Intl.NumberFormat,null 变 —;两个面调同一份,不各写一套。
+ */
+function resolveStatDisplay(value: LocalizedText | number | null, locale: ReportLocale): string {
+  if (value === null) return MISSING_MARK;
+  if (typeof value === "number") return new Intl.NumberFormat(locale).format(value);
+  return resolveLocalizedText(value, locale);
+}
+
+/** label / 主值 / 辅助信息的最小内容单元;可以脱离 Grid 单独使用。 */
+export const Stat = defineComponent<StatProps>({
+  web({ label, value, detail, tone = "neutral", className }, ctx) {
+    return (
+      <div className={cx("nre", "nre-stat", `nre-stat--${tone}`, className)}>
+        <div className="nre-stat-label">{resolveLocalizedText(label, ctx.locale)}</div>
+        <div className="nre-stat-value">{resolveStatDisplay(value, ctx.locale)}</div>
+        {detail !== undefined ? <div className="nre-stat-detail">{resolveLocalizedText(detail, ctx.locale)}</div> : null}
+      </div>
+    );
+  },
+  text({ label, value, detail }, ctx) {
+    const lines = [resolveLocalizedText(label, ctx.locale), resolveStatDisplay(value, ctx.locale)];
+    if (detail !== undefined) lines.push(resolveLocalizedText(detail, ctx.locale));
+    return lines.flatMap((line) => wrapDisplay(line, ctx.width)).join("\n");
+  },
+});
+Stat.displayName = "Stat";
+
+// ───────────────────────── Section ─────────────────────────
+
 export interface SectionProps extends LayoutProps {
   title: LocalizedText;
+  /** 标题行右侧的短元信息;text 面与标题同一行,空间不足时换到下一行。 */
+  meta?: LocalizedText;
+}
+
+/** 标题行右侧同一行放不下 meta 时,退化成标题后两格缩进折行。 */
+function sectionHeadingLine(heading: string, metaText: string | undefined, width: number): string {
+  if (metaText === undefined) return heading;
+  const gap = width - stringWidth(heading) - stringWidth(metaText);
+  if (gap >= 1) return heading + " ".repeat(gap) + metaText;
+  const wrapped = wrapDisplay(metaText, Math.max(1, width - 2)).join("\n");
+  return `${heading}\n${indentBlock(wrapped, "  ")}`;
 }
 
-/** 带标题的块:网页是标题层级,终端是标题行加缩进。 */
+/** 带标题的块:网页是标题层级(可选 meta 同行右对齐),终端是标题行加缩进。 */
 export const Section = defineComponent<SectionProps>({
-  web({ title, children, className }, ctx) {
+  web({ title, meta, children, className }, ctx) {
+    const titleText = resolveLocalizedText(title, ctx.locale);
+    const metaText = meta !== undefined ? resolveLocalizedText(meta, ctx.locale) : undefined;
     return (
       <section className={cx("nre", "nre-section", className)}>
-        <h2 className="nre-section-title">{resolveLocalizedText(title, ctx.locale)}</h2>
+        {metaText !== undefined ? (
+          <header className="nre-section-header">
+            <h2 className="nre-section-title">{titleText}</h2>
+            <p className="nre-section-meta">{metaText}</p>
+          </header>
+        ) : (
+          <h2 className="nre-section-title">{titleText}</h2>
+        )}
         {children as ReactNode}
       </section>
     );
   },
-  text({ title, children }, ctx) {
+  text({ title, meta, children }, ctx) {
     const heading = resolveLocalizedText(title, ctx.locale);
+    const metaText = meta !== undefined ? resolveLocalizedText(meta, ctx.locale) : undefined;
+    const headingLine = sectionHeadingLine(heading, metaText, ctx.width);
     const body = childArray(children)
       .map((child) => ctx.render(child, ctx.width - 2))
       .filter((block) => block.length > 0)
       .join("\n\n");
-    return body.length > 0 ? `${heading}\n${indentBlock(body, "  ")}` : heading;
+    return body.length > 0 ? `${headingLine}\n${indentBlock(body, "  ")}` : headingLine;
   },
 });
 Section.displayName = "Section";
@@ -269,8 +417,6 @@ export interface TableProps {
   className?: string;
 }
 
-const MISSING_MARK = "—";
-
 /** 列 key 唯一、行 cells 不携带未声明 key、空列拒绝——无类型 JS 输入在渲染前同样校验。 */
 function validateTableProps(props: TableProps): void {
   if (!Array.isArray(props.columns) || props.columns.length === 0) {
@@ -344,9 +490,13 @@ export const Table = defineComponent<TableProps>({
               {hasLocator ? (
                 <td>
                   {row.locator ? (
-                    <a className="nre-locator" href={ctx.attemptHref(row.locator)}>
-                      {row.locator}
-                    </a>
+                    ctx.attemptHref ? (
+                      <a className="nre-locator" href={ctx.attemptHref(row.locator)}>
+                        {row.locator}
+                      </a>
+                    ) : (
+                      <span className="nre-locator">{row.locator}</span>
+                    )
                   ) : (
                     <span className="nre-missing">{MISSING_MARK}</span>
                   )}

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> --experiment <id> [--results/--report/--page]`。 */
-function experimentCommandFor(ctx: HostCommandContext): (experimentIdPrefix: string) => string {
-  return (prefix) => {
-    const parts = ["niceeval show", ...ctx.patterns.map(quoteArg), `--experiment ${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("   ") 一致。 */