niceeval 0.6.1 → 0.7.0

package/src/report/tree.ts

@@ -1,14 +1,20 @@
-// 报告的元素树与双面组件基座(docs/feature/reports/architecture.md「报告树与两个宿主」)。
+// 报告的元素树、组件模型与 resolve 管线(docs/feature/reports/architecture.md「组件模型」
+// 「报告树与两个宿主」、docs/feature/reports/library/layout.md)。
 //
 // 报告函数返回的树不是「React 树」,只是 { type, props } 节点 —— 标准 react
 // jsx-runtime 产的元素恰好就是这个形状。本文件是基础实现:零 react 运行时依赖
 // (只有类型层的 `import type`,编译后擦除);text 宿主遍历渲染不需要 react-dom,
-// web 宿主(web.ts)才真正 import react。渲染面是纯同步函数:零 IO、零 await ——
-// 计算全部发生在报告函数体里,可达百 MB 的 artifact 永远不进渲染路径。
+// web 宿主(web.ts)才真正 import react。管线固定为 装载 → resolve(组合展开 + spec 取数,
+// 同层并行保声明序,按「同引用 input + 深相等 spec」记忆化)→ validate(两面资格)→
+// render(纯同步)。渲染面是纯同步函数:零 IO、零 await —— 可达百 MB 的 artifact
+// 只在 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 { ReportMeta } from "./report.ts";
 
 // ───────────────────────── 节点形状 ─────────────────────────
 
@@ -19,8 +25,12 @@ export interface ReportElement {
   key?: unknown;
 }
 
-/** 报告树节点:元素、文本、数组 / Fragment 的儿子们,或渲染为空的空值。 */
-export type ReportNode = ReportElement | string | number | boolean | null | undefined | ReportNode[];
+/**
+ * 报告树节点,形状穷尽(docs/feature/reports/library/layout.md「树的节点」):
+ * 元素、数组 / Fragment(展平保序),或条件渲染的空分支(渲染为空)。
+ * 裸字符串与数字**不是**节点——自由文本必须经 <Text> 携带,树校验遇到时按完整用户反馈拒绝。
+ */
+export type ReportNode = ReportElement | readonly ReportNode[] | null | undefined | boolean;
 
 // react/jsx-runtime 的 Fragment 是注册符号,跨 react 版本稳定;不 import react 也认得它
 const REACT_FRAGMENT = Symbol.for("react.fragment");
@@ -36,10 +46,19 @@ function isReportElement(node: unknown): node is ReportElement {
   );
 }
 
-// ───────────────────────── 双面组件 ─────────────────────────
+// ───────────────────────── 组件模型 ─────────────────────────
 
-/** 挂 faces 的私有键:text 宿主与树校验靠它识别双面组件。 */
+/** 挂 faces 的私有键:管线与树校验靠它识别双面组件。 */
 export const COMPONENT_FACES: unique symbol = Symbol.for("niceeval.report.faces");
+/** 挂组合函数的私有键:resolve 阶段靠它识别组合组件。 */
+export const COMPONENT_COMPOSE: unique symbol = Symbol.for("niceeval.report.compose");
+/** Tabs / Tab 的结构角色标记:树校验的配对规则靠它,不 import primitives(避免环)。 */
+export const COMPONENT_ROLE: unique symbol = Symbol.for("niceeval.report.role");
+/**
+ * children 是不透明值(自由文本 / CSS 字符串)而非报告树的组件标记(Text / Style):
+ * resolve 与 validate 不下钻它们的 children——那是组件自己的 props,不是树。
+ */
+export const COMPONENT_RAW_CHILDREN: unique symbol = Symbol.for("niceeval.report.rawChildren");
 
 export interface TextContext {
   /** 可用列宽;Row 分栏后变窄。 */
@@ -50,6 +69,11 @@ export interface TextContext {
   render(node: ReportNode, width?: number): string;
   /** 下钻命令,通证据室:`niceeval show @<locator>`。 */
   attemptCommand(locator: AttemptLocator): string;
+  /**
+   * 组索引一类「按实验收窄」命令的生成;宿主注入以携带完整上下文(--results / --report /
+   * --page 与位置参数),默认 `niceeval show --experiment <id>`。非契约字段,官方组件内部用。
+   */
+  experimentCommand(experimentIdPrefix: string): string;
 }
 
 export interface WebContext {
@@ -59,38 +83,49 @@ export interface WebContext {
   locale: ReportLocale;
 }
 
+/** 双面组件解析面的上下文:宿主注入的数据来源;props 显式给出 input 时以 props 为准。 */
+export interface ResolveContext {
+  input: ReportInput;
+}
+
+/** 组合组件的上下文:宿主 Scope、结果根完整读取面与规范化后的报告声明。 */
+export interface ComposeContext {
+  /** 宿主注入的 Scope。 */
+  scope: Scope;
+  /** 结果根完整读取面;历史视图从这里自行挑 Snapshot[]。 */
+  results: Results;
+  /** 规范化后的报告声明,只读(docs/feature/reports/library/layout.md「自定义组件」)。 */
+  report: ReportMeta;
+}
+
 export interface ComponentFaces<P, R = P> {
   /**
-   * 可选的数据解析面:把声明式 props(selection + 计算选项)在渲染前解析成纯数据 props(R)。
-   * 宿主的 {@link resolveReportTree} 在 build 之后、validate / render 之前调用它——这是整条
-   * 管线里唯一允许 await / IO 的组件级步骤;渲染面(web / text)只看已解析的 R,保持同步、零 IO。
-   * 不实现 resolve 时 R = P,组件被当作纯数据组件直接渲染。
+   * 组件唯一的异步 / IO 面:把作者写下的 props 规范化成渲染 props(R)。宿主管线在
+   * resolve 阶段调用它,按「同引用 input + 深相等 spec」在一次页渲染内记忆化;
+   * 渲染面(web / text)只看已解析的 R,保持同步、零 IO。不实现 resolve 时 R = P。
    */
-  resolve?(props: P): Promise<R>;
+  resolve?(props: P, context: ResolveContext): R | Promise<R>;
   /** 真 React JSX 在这个面里;返回静态可渲染的 ReactNode。只看已解析的 R。 */
   web(props: R, ctx: WebContext): ReactNode;
   text(props: R, ctx: TextContext): string;
 }
 
 /**
- * 双面组件的产物:可直接用于 JSX(React 把它当函数组件调用,走 web 面),
- * text 宿主经 COMPONENT_FACES 调 text 面。R(解析后 props 形态)在存储边界抹成 any——
+ * 报告组件的产物:可直接用于 JSX。双面组件当普通 React 组件调用时走 web 面(只接受
+ * 数据形态 props);组合组件只在报告管线内展开,宿主外直接渲染报错。R 在存储边界抹成 any——
  * 树遍历只按 ComponentFaces 的结构调用 resolve / web / text,不需要在类型层追踪 R。
  */
 export type ReportComponent<P> = ((props: P) => ReactNode) & {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  [COMPONENT_FACES]: ComponentFaces<P, any>;
+  [COMPONENT_FACES]?: ComponentFaces<P, any>;
+  [COMPONENT_COMPOSE]?: (props: P, ctx: ComposeContext) => ReportNode | Promise<ReportNode>;
+  [COMPONENT_ROLE]?: "tabs" | "tab";
+  [COMPONENT_RAW_CHILDREN]?: true;
   displayName?: string;
 };
 
 // web 面的环境上下文:web 宿主渲染前设好;宿主之外(组件直接嵌进用户 React 应用)
-// 用默认值 —— attemptHref 默认 view 的 attempt 路由格式(自定义组件显式调 ctx.attemptHref
-// 时总有去处);官方组件的「宿主里自动接证据室」只在宿主上下文激活时发生,
-// 宿主外不传 attemptHref 就是纯展示,不发明断链。
-//
-// URL 格式取 `#/attempt/${locator}`:AttemptLocator 本身已经是 `@` 前缀的不透明短串
-// (如 "@1x7f3q9"),原样嵌进路径段就得到 `#/attempt/@1x7f3q9`——与 docs/feature/reports/view.md「用
-// Reports 积木重建 view」定稿的单段路由逐字一致,不额外拆分或去掉 `@`。
+// 用默认值 —— attemptHref 默认 view 的 attempt 路由格式。
 const DEFAULT_WEB_CONTEXT: WebContext = {
   attemptHref: (locator) => `#/attempt/${locator}`,
   locale: DEFAULT_REPORT_LOCALE,
@@ -113,83 +148,240 @@ export function isHostWebContextActive(): boolean {
   return activeWebContext !== null;
 }
 
-/**
- * 定义一个双面组件:faces 两键必填 —— 少实现一个面编译不过,配对是结构义务。
- * 基础实现不 import react;产物以可调用组件的形状兼容 React 渲染。
- */
-export function defineComponent<P, R = P>(faces: ComponentFaces<P, R>): ReportComponent<P> {
-  if (typeof faces?.web !== "function" || typeof faces?.text !== "function") {
+/** 函数形态:组合组件,只装配已有组件,可以异步;ctx 携带 scope / results / report。 */
+export function defineComponent<P>(
+  compose: (props: P, context: ComposeContext) => ReportNode | Promise<ReportNode>,
+): ReportComponent<P>;
+/** 对象形态:双面组件,自己渲染;text 与 web 两面必填,可选 resolve 承担取数。 */
+export function defineComponent<P, R = P>(faces: ComponentFaces<P, R>): ReportComponent<P>;
+export function defineComponent<P, R = P>(
+  input: ComponentFaces<P, R> | ((props: P, context: ComposeContext) => ReportNode | Promise<ReportNode>),
+): ReportComponent<P> {
+  if (typeof input === "function") {
+    const component = ((_props: P): ReactNode => {
+      throw new Error(
+        `Compose component ${componentDisplayName(input) ?? "(anonymous)"} can only render inside the report pipeline ` +
+          "(niceeval show / view, or renderReportToText / renderReportToStaticHtml): it assembles other components " +
+          "and needs the host context (scope, results, report). To embed in your own React page, compute data with " +
+          "the *Data functions and render the pure components from niceeval/report/react instead.",
+      );
+    }) as ReportComponent<P>;
+    component[COMPONENT_COMPOSE] = input;
+    if (componentDisplayName(input)) component.displayName = componentDisplayName(input);
+    return component;
+  }
+  if (typeof input?.web !== "function" || typeof input?.text !== "function") {
     throw new Error(
-      "defineComponent requires both faces: { web(props, ctx), text(props, ctx) }. " +
-        "Every report component must render in both hosts (niceeval view and niceeval show).",
+      "defineComponent requires both faces: { web(props, ctx), text(props, ctx) } (resolve is optional). " +
+        "Every report component must render in both hosts (niceeval view and niceeval show); " +
+        "define the missing face, or pass a compose function to assemble existing components instead.",
     );
   }
+  const faces = input;
   // 直接调用路径:把组件当普通 React 组件嵌进用户自己的页面时走这里,web 面只接收数据形态
-  // props(R)。带 resolve 的组件若拿 selection 形态 props 走这条裸路径,web 面会缺 data ——
+  // props(R)。带 resolve 的组件若拿 spec 形态 props 走这条裸路径,web 面会缺 data ——
   // 这类组件只有经宿主的 resolveReportTree 解析后才安全渲染;纯数据 props 一直可以裸嵌。
   const component = ((props: P) =>
     faces.web(props as unknown as R, activeWebContext ?? DEFAULT_WEB_CONTEXT)) as ReportComponent<P>;
-  component[COMPONENT_FACES] = faces;
+  component[COMPONENT_FACES] = faces as ComponentFaces<P, unknown>;
   return component;
 }
 
+function componentDisplayName(fn: unknown): string | undefined {
+  const named = fn as { displayName?: string; name?: string };
+  return named.displayName || named.name || undefined;
+}
+
 export function facesOf(type: unknown): ComponentFaces<unknown> | undefined {
   if (typeof type !== "function") return undefined;
-  return (type as Partial<ReportComponent<unknown>>)[COMPONENT_FACES] as ComponentFaces<unknown> | undefined;
+  return (type as ReportComponent<unknown>)[COMPONENT_FACES];
+}
+
+export function composeOf(
+  type: unknown,
+): ((props: unknown, ctx: ComposeContext) => ReportNode | Promise<ReportNode>) | undefined {
+  if (typeof type !== "function") return undefined;
+  return (type as ReportComponent<unknown>)[COMPONENT_COMPOSE] as
+    | ((props: unknown, ctx: ComposeContext) => ReportNode | Promise<ReportNode>)
+    | undefined;
+}
+
+function roleOf(type: unknown): "tabs" | "tab" | undefined {
+  if (typeof type !== "function") return undefined;
+  return (type as ReportComponent<unknown>)[COMPONENT_ROLE];
+}
+
+function hasRawChildren(type: unknown): boolean {
+  return typeof type === "function" && (type as ReportComponent<unknown>)[COMPONENT_RAW_CHILDREN] === true;
+}
+
+// ───────────────────────── 深相等(记忆化的 spec 比较)─────────────────────────
+
+/**
+ * resolve 记忆化的深相等:只递归比较可序列化值(普通对象 / 数组 / 原始值);
+ * 函数与 Metric / Dimension / NumericAxis 一类携带函数的实例按引用比较——
+ * 共享计算的成立条件是引用同一实例,引用不同的等价定义只是各算一次,不构成错误。
+ */
+export function deepEqualSpec(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, i) => deepEqualSpec(item, (b as unknown[])[i]));
+  }
+  const protoA = Object.getPrototypeOf(a);
+  const protoB = Object.getPrototypeOf(b);
+  if ((protoA !== Object.prototype && protoA !== null) || (protoB !== Object.prototype && protoB !== null)) {
+    return false; // 非纯对象(类实例等)按引用比较,=== 已在开头判过
+  }
+  const keysA = Object.keys(a as Record<string, unknown>).filter(
+    (k) => (a as Record<string, unknown>)[k] !== undefined,
+  );
+  const keysB = Object.keys(b as Record<string, unknown>).filter(
+    (k) => (b as Record<string, unknown>)[k] !== undefined,
+  );
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((k) => deepEqualSpec((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]));
+}
+
+// ───────────────────────── resolve 管线 ─────────────────────────
+
+interface MemoEntry {
+  input: unknown;
+  spec: unknown;
+  result: Promise<unknown>;
+}
+
+/** 一次页渲染内的记忆化缓存:键 = 计算函数引用 → (同引用 input + 深相等 spec) 命中。 */
+export class ResolveMemo {
+  private readonly entries = new Map<unknown, MemoEntry[]>();
+
+  fetch(fn: unknown, input: unknown, spec: unknown, compute: () => Promise<unknown>): Promise<unknown> {
+    let list = this.entries.get(fn);
+    if (!list) this.entries.set(fn, (list = []));
+    for (const entry of list) {
+      if (entry.input === input && deepEqualSpec(entry.spec, spec)) return entry.result;
+    }
+    const result = compute();
+    list.push({ input, spec, result });
+    return result;
+  }
+}
+
+/** resolveReportTree 的环境:宿主注入的 Scope / 读取面 / 规范化声明。 */
+export interface ResolveEnv {
+  scope: Scope;
+  results: Results;
+  report: ReportMeta;
+  /** 一次页渲染一份;跨页共享缓存时由宿主显式传同一实例。 */
+  memo?: ResolveMemo;
+}
+
+/** 官方 spec 组件在 resolve 内取数的记忆化入口;经内部扩展的 ResolveContext 传递。 */
+export interface InternalResolveContext extends ResolveContext {
+  /** 按 (计算函数引用, 同引用 input, 深相等 options) 记忆化地调用计算函数。 */
+  memoFetch<T>(dataFn: unknown, input: unknown, options: unknown, compute: () => Promise<T>): Promise<T>;
+}
+
+/** 组件 resolve 里安全取记忆化入口:经宿主管线时在场,手工直调 resolve 时退化为直接计算。 */
+export function memoFetchOf(ctx: ResolveContext): InternalResolveContext["memoFetch"] {
+  const internal = ctx as Partial<InternalResolveContext>;
+  return internal.memoFetch ?? (async (_fn, _input, _options, compute) => compute());
+}
+
+function illegalNodeError(type: unknown, path: string[]): Error {
+  const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
+  if (typeof type === "string") {
+    return new Error(
+      `Report trees cannot contain raw HTML <${type}>${where}. Every node must render in both hosts (niceeval show and niceeval view), and raw HTML has no text face. ` +
+        "Use <Text> for free text, the layout primitives (<Row>/<Col>/<Section>/<Table>), or move the markup into the web face of a defineComponent component.",
+    );
+  }
+  const label = componentLabel(type);
+  return new Error(
+    `${label} is not a report component${where}: plain functions and React components cannot join a report tree because the hosts cannot render them in both faces. ` +
+      "Wrap it with defineComponent — a compose function defineComponent((props, ctx) => tree) to assemble existing components, " +
+      "or an object form defineComponent({ resolve?, text, web }) to render itself.",
+  );
 }
 
-// ───────────────────────── 数据解析(渲染前唯一的 await 边界)─────────────────────────
+function bareTextError(value: string | number, path: string[]): Error {
+  const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
+  const preview = typeof value === "string" ? JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value) : String(value);
+  return new Error(
+    `Report trees cannot contain a bare ${typeof value} (${preview})${where}: free text needs an explicit carrier for terminal line-wrapping and HTML escaping. ` +
+      "Wrap it in <Text>…</Text>.",
+  );
+}
 
 /**
- * 报告 build 之后、树校验与 text/web 渲染之前的解析遍历:把声明式数据组件(实现了
- * `faces.resolve` 的双面组件,如 selection 形态的 MetricScatter)的 props
- * 就地换成算好的数据形态 props(三个实体列表没有 `resolve` 面,不经这一步——它们的 `items`
- * 由报告作者在 `build()` 里直接 `await .data(selection)` 备好)。计算发生在这里(唯一允许
- * await 的组件级步骤,连同报告函数体自己的 `build()`),两个渲染面
- * 之后都只看已解析的树、保持同步零 IO。遍历形状与 {@link validateReportTree} /
- * {@link renderNodeToText} 一致:
- *
- * - 同层数组兄弟并行解析(`Promise.all`),保持原始顺序 / keys;
- * - 双面组件带 resolve 的:调 `faces.resolve(props)` 换 props(有 children 再递归解析);
- * - 双面组件无 resolve 的(Row / Col / Section / RunOverview…):只递归 children,自身 props
- *   原样保留(title / className 等不能动);
- * - 普通函数组件:同步调用展开,展开结果继续解析(与 validate / render 对函数组件的处理一致);
- * - 字符串 intrinsic(<div>):原样返回,交给随后的 validateReportTree 报同一条错误。
- *
- * resolver 跑完后,树里已没有函数组件 / 未解析 props;validate / render 里对这两者的分支在
- * 正常管线下是 no-op,但保留着——手搭树直接调 validate / render(不过 resolver)的低层用法仍需要。
+ * 管线的 resolve 阶段:递归展开组合组件(以 (props, ctx) 调用并 await 返回树)、执行双面
+ * 组件的解析面;同层 sibling 并行取数且不改变节点顺序;带 resolve 的组件按「同引用 input +
+ * 深相等 spec」记忆化。非法节点(React 组件、未经 defineComponent 的普通函数、任意 HTML
+ * intrinsic)在展开遇到时立即以完整用户反馈拒绝,不为非法节点取数。
  */
-export async function resolveReportTree(node: ReportNode): Promise<ReportNode> {
+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 };
+  return resolveNode(node, { memo, composeCtx }, []);
+}
+
+interface ResolveState {
+  memo: ResolveMemo;
+  composeCtx: ComposeContext;
+}
+
+async function resolveNode(node: ReportNode | string | number, state: ResolveState, path: string[]): Promise<ReportNode> {
   if (node === null || node === undefined || typeof node === "boolean") return node;
-  if (typeof node === "string" || typeof node === "number") return node;
-  if (Array.isArray(node)) return Promise.all(node.map(resolveReportTree));
+  if (typeof node === "string" || typeof node === "number") {
+    // 裸字符串在 validate 阶段以带指引的完整反馈拒绝;这里先如实透传,不为它取数。
+    return node as unknown as ReportNode;
+  }
+  if (Array.isArray(node)) {
+    return Promise.all(node.map((child) => resolveNode(child as ReportNode, state, path)));
+  }
   if (!isReportElement(node)) return node;
   const { type, props } = node;
-  // 字符串 intrinsic:不在这里报错,让 resolve 后的 validateReportTree 抛统一的那条。
-  if (typeof type === "string") return node;
   if (type === REACT_FRAGMENT) {
-    const children = await resolveReportTree(props.children as ReportNode);
+    const children = await resolveNode(props.children as ReportNode, state, path);
     return { ...node, props: { ...props, children } };
   }
+  const compose = composeOf(type);
+  if (compose) {
+    // 组合组件不记忆化:它只装配、不承担取数;数据层的去重由其内部 *Data 调用经 memoFetch 命中。
+    const expanded = await compose(props, state.composeCtx);
+    return resolveNode(expanded, state, [...path, componentLabel(type)]);
+  }
   const faces = facesOf(type);
   if (faces) {
     if (typeof faces.resolve === "function") {
-      const resolvedProps = { ...((await faces.resolve(props)) as Record<string, unknown>) };
+      const resolveFn = faces.resolve;
+      const input = ((props as { input?: unknown }).input as ReportInput | undefined) ?? state.composeCtx.scope;
+      const ctx: InternalResolveContext = {
+        input,
+        memoFetch: <T,>(dataFn: unknown, dataInput: unknown, options: unknown, compute: () => Promise<T>) =>
+          state.memo.fetch(dataFn, dataInput, options, compute) as Promise<T>,
+      };
+      const resolved = await state.memo.fetch(resolveFn, input, props, async () =>
+        resolveFn(props, ctx),
+      );
+      const resolvedProps = { ...(resolved as Record<string, unknown>) };
       if (resolvedProps.children !== undefined) {
-        resolvedProps.children = await resolveReportTree(resolvedProps.children as ReportNode);
+        resolvedProps.children = await resolveNode(resolvedProps.children as ReportNode, state, [
+          ...path,
+          componentLabel(type),
+        ]);
       }
       return { ...node, props: resolvedProps };
     }
-    // 无 resolve 的容器 / 数据组件:只解析 children,自身 props 原样保留。
-    const children = await resolveReportTree(props.children as ReportNode);
+    // 无 resolve 的容器 / 纯数据组件:只解析 children,自身 props 原样保留(title / className 不能动)。
+    if (hasRawChildren(type)) return node; // Text / Style 的 children 是不透明值,不是树
+    const children = await resolveNode(props.children as ReportNode, state, [...path, componentLabel(type)]);
     return { ...node, props: { ...props, children } };
   }
-  if (typeof type === "function") {
-    // 普通函数组件:调用展开,展开结果整体替换本节点后继续解析。
-    const expanded = (type as (p: unknown) => ReportNode)(props);
-    return resolveReportTree(expanded);
-  }
-  return node;
+  // 非法节点:HTML intrinsic、React 组件、未经 defineComponent 的普通函数 —— 立即拒绝,不取数。
+  throw illegalNodeError(type, path);
 }
 
 // ───────────────────────── 树校验 ─────────────────────────
@@ -204,46 +396,109 @@ function componentLabel(type: unknown): string {
   return `<${String(type)}>`;
 }
 
+function directChildElements(children: unknown): ReportElement[] {
+  const out: ReportElement[] = [];
+  const visit = (node: unknown): void => {
+    if (node === null || node === undefined || typeof node === "boolean") return;
+    if (Array.isArray(node)) {
+      for (const child of node) visit(child);
+      return;
+    }
+    if (isReportElement(node)) {
+      if (node.type === REACT_FRAGMENT) {
+        visit(node.props.children);
+        return;
+      }
+      out.push(node);
+      return;
+    }
+    out.push(node as never);
+  };
+  visit(children);
+  return out;
+}
+
 /**
- * 渲染前树校验:页面树里只放双面组件、排版原语与普通组合函数,字符串 intrinsic
- * (<div>)报错、指名组件路径。这是运行时校验而非编译期(标准 JSX 下 TS 把一切
- * JSX 表达式统一成 JSX.Element);两个宿主渲染前跑同一遍 —— 不做单侧宽容,否则
- * 对着 view 写的页面到 show 才炸。校验只下钻 children(children 就是报告树);
- * 普通函数组件调用展开(渲染面纯同步,重复调用无副作用)。
+ * 管线的 validate 阶段:确保展开后树中每个组件都有 text 和 web 两面。校验只看节点资格,
+ * 不限定树形:根节点可以是单个组件、Col 或 Tabs,宿主不强制任何最外层容器。
+ * 裸字符串 / 数字、HTML intrinsic、无两面资格的函数都以完整用户反馈拒绝;
+ * Tabs / Tab 的结构配对(空 Tabs、游离 Tab、非 Tab 直接子节点)也在这里校验。
  */
-export function validateReportTree(node: ReportNode, path: string[] = []): void {
+export function validateReportTree(node: ReportNode, path: string[] = [], insideTabs = false): void {
   if (node === null || node === undefined || typeof node === "boolean") return;
-  if (typeof node === "string" || typeof node === "number") return;
+  if (typeof node === "string" || typeof node === "number") {
+    throw bareTextError(node, path);
+  }
   if (Array.isArray(node)) {
-    for (const child of node) validateReportTree(child, path);
+    for (const child of node) validateReportTree(child, path, insideTabs);
+    return;
+  }
+  if (!isReportElement(node)) {
+    if (typeof node === "object" && node !== null && (node as { kind?: unknown }).kind === "report") {
+      const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
+      throw new Error(
+        `A defineReport(...) product is not a report node${where}: the shell cannot nest. ` +
+          "Put the page content (a tree or component) here, and keep defineReport for the file's default export only.",
+      );
+    }
     return;
   }
-  if (!isReportElement(node)) return;
   const { type, props } = node;
-  if (typeof type === "string") {
+  if (type === REACT_FRAGMENT) {
+    validateReportTree(props.children as ReportNode, path, insideTabs);
+    return;
+  }
+  if (typeof type === "string") throw illegalNodeError(type, path);
+  const label = componentLabel(type);
+  const role = roleOf(type);
+  if (role === "tab" && !insideTabs) {
     const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
     throw new Error(
-      `Raw HTML <${type}> has no terminal face; use <Text>, layout primitives, or a defineComponent component.${where}`,
+      `<Tab> can only be a direct child of <Tabs>${where}. Wrap sibling views in <Tabs><Tab title="…">…</Tab></Tabs>, or drop the <Tab> wrapper if you only have one view.`,
     );
   }
-  if (type === REACT_FRAGMENT) {
-    validateReportTree(props.children as ReportNode, path);
+  if (role === "tabs") {
+    const children = directChildElements(props.children);
+    const nonTab = children.find((child) => roleOf(child.type) !== "tab");
+    if (nonTab !== undefined) {
+      throw new Error(
+        `<Tabs> only accepts <Tab> as direct children (found ${
+          isReportElement(nonTab) ? componentLabel(nonTab.type) : typeof nonTab
+        } in ${[...path, label].join(" > ")}). Move the content inside a <Tab title="…">, or lift it out of <Tabs>.`,
+      );
+    }
+    if (children.length === 0) {
+      throw new Error(
+        `<Tabs> needs at least one <Tab> child (in ${[...path, label].join(" > ")}). Add <Tab title="…">…</Tab>, or remove the empty <Tabs>.`,
+      );
+    }
+    for (const tab of children) {
+      validateReportTree((tab.props as { children?: ReportNode }).children, [...path, label, componentLabel(tab.type)], false);
+    }
     return;
   }
-  const label = componentLabel(type);
-  if (facesOf(type)) {
+  const faces = facesOf(type);
+  if (faces) {
+    // 双面资格:无类型 JS 输入可能绕过 defineComponent 的定义期校验,这里再拦一遍
+    if (typeof faces.web !== "function" || typeof faces.text !== "function") {
+      const missing = typeof faces.web !== "function" ? "web" : "text";
+      throw new Error(
+        `${label} is missing its ${missing} face${path.length > 0 ? ` (in ${path.join(" > ")})` : ""}: every component in a report tree must render in both hosts (niceeval show and niceeval view). Define both { text, web } in defineComponent.`,
+      );
+    }
     // 双面组件是校验的信任边界之内的叶子,但 children 仍是报告树的一部分
-    validateReportTree(props.children as ReportNode, [...path, label]);
+    // (Text / Style 除外:它们的 children 是不透明的自由文本 / CSS 字符串)
+    if (!hasRawChildren(type)) validateReportTree(props.children as ReportNode, [...path, label], false);
     return;
   }
-  if (typeof type === "function") {
-    // 普通函数组件 = 用户拿函数组合页面片段:调用展开继续校验
-    const expanded = (type as (p: unknown) => ReportNode)(props);
-    validateReportTree(expanded, [...path, label]);
-    return;
+  if (composeOf(type)) {
+    // 正常管线下 resolve 已把组合组件展开;手搭树直接 validate 时如实指出它还没展开
+    throw new Error(
+      `${label} is a compose component and must be expanded by the resolve pipeline before validation. ` +
+        "Render through defineReport + niceeval show/view (or renderReportToText/renderReportToStaticHtml).",
+    );
   }
-  const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
-  throw new Error(`Unsupported node type ${label} in report tree.${where}`);
+  throw illegalNodeError(type, path);
 }
 
 // ───────────────────────── text 渲染 ─────────────────────────
@@ -253,21 +508,29 @@ export interface TextRenderOptions {
   width?: number;
   /** 下钻命令的生成;宿主注入,默认 `niceeval show @<locator>`(真实可跑的 CLI 语法)。 */
   attemptCommand?: (locator: AttemptLocator) => string;
+  /** 组索引命令的生成;宿主注入以携带 --results / --report / --page 等上下文。 */
+  experimentCommand?: (experimentIdPrefix: string) => string;
   /** chrome 文案的 locale;默认 "en"(`niceeval show` 现有输出不变)。 */
   locale?: ReportLocale;
 }
 
+function shellQuote(value: string): string {
+  return /^[A-Za-z0-9._/@-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
 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/index.ts 已实现的真实 CLI 语法(见该文件 `@<locator>` 位置参数解析),不需要
-  // 反查 eval id 再拼一条近似命令。
+  // show 已实现的真实 CLI 语法,不需要反查 eval id 再拼一条近似命令。
   const attemptCommand = options?.attemptCommand ?? ((locator: AttemptLocator) => `niceeval show ${locator}`);
+  const experimentCommand =
+    options?.experimentCommand ?? ((prefix: string) => `niceeval show --experiment ${shellQuote(prefix)}`);
   const make = (w: number): TextContext => ({
     width: w,
     locale,
     attemptCommand,
+    experimentCommand,
     render(node, childWidth) {
       return renderNodeToText(node, childWidth === undefined ? this : make(Math.max(10, childWidth)));
     },
@@ -275,10 +538,13 @@ export function createTextContext(options?: TextRenderOptions): TextContext {
   return make(width);
 }
 
-/** text 宿主的遍历渲染:双面组件走 text 面,普通函数调用展开,块之间以换行相接。 */
+/** text 宿主的遍历渲染:双面组件走 text 面,块之间以换行相接。只吃已 resolve + validate 的树。 */
 export function renderNodeToText(node: ReportNode, ctx: TextContext): string {
   if (node === null || node === undefined || typeof node === "boolean") return "";
-  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (typeof node === "string" || typeof node === "number") {
+    // 校验先行会拦住;渲染路径自身也不宽容
+    throw bareTextError(node, []);
+  }
   if (Array.isArray(node)) {
     return node
       .map((child) => renderNodeToText(child, ctx))
@@ -287,17 +553,9 @@ export function renderNodeToText(node: ReportNode, ctx: TextContext): string {
   }
   if (!isReportElement(node)) return "";
   const { type, props } = node;
-  if (typeof type === "string") {
-    // 校验先行会拦住;这里兜底同一条错误,渲染路径自身也不宽容
-    throw new Error(
-      `Raw HTML <${type}> has no terminal face; use <Text>, layout primitives, or a defineComponent component.`,
-    );
-  }
+  if (typeof type === "string") throw illegalNodeError(type, []);
   if (type === REACT_FRAGMENT) return renderNodeToText(props.children as ReportNode, ctx);
   const faces = facesOf(type);
   if (faces) return faces.text(props, ctx);
-  if (typeof type === "function") {
-    return renderNodeToText((type as (p: unknown) => ReportNode)(props), ctx);
-  }
-  return "";
+  throw illegalNodeError(type, []);
 }