niceeval 0.6.1 → 0.7.0

package/src/show/report-host.test.ts

@@ -0,0 +1,188 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// 「外壳、页面与 Tabs」——宿主装载规范化、页索引命令上下文与标题回退链
+// (契约:docs/feature/reports/library/shell.md)。
+// 页内树的 resolve / render 归报告库测试;这里只测宿主侧的规范化与选择逻辑(纯函数)。
+
+import { describe, expect, it } from "vitest";
+import {
+  BUILT_IN_PAGE_TITLE,
+  BUILT_IN_REPORT_TITLE,
+  HostReportError,
+  localizeText,
+  localizedTextEquals,
+  normalizeHostReport,
+  resolveReportTitle,
+  showCommand,
+} from "./report-host.ts";
+import { pageIndexText } from "./render.ts";
+
+const tree = { kind: "node" }; // 页 content 对宿主是不透明值,规范化不解析树
+
+describe("装载规范化:外壳 + 非空页列表", () => {
+  it("content 缩写展开为唯一页 id `report`,页名是内置页名「报告 / Report」", () => {
+    const report = normalizeHostReport({ kind: "report", content: tree }, "reports/frontier.tsx");
+    expect(report.pages).toHaveLength(1);
+    expect(report.pages[0]).toMatchObject({ id: "report", title: BUILT_IN_PAGE_TITLE, content: tree });
+    expect(report.links).toEqual([]);
+  });
+
+  it("pages 形态按声明序保留页列表与外壳字段", () => {
+    const report = normalizeHostReport(
+      {
+        kind: "report",
+        title: { en: "Memory Evals", "zh-CN": "记忆能力评测" },
+        links: [{ label: "GitHub", href: "https://example.com" }],
+        footer: "Published nightly.",
+        pages: [
+          { id: "overview", title: { en: "Overview", "zh-CN": "总览" }, content: tree },
+          { id: "exam", title: { en: "Exam", "zh-CN": "成绩单" }, content: tree },
+        ],
+      },
+      "reports/site.tsx",
+    );
+    expect(report.pages.map((p) => p.id)).toEqual(["overview", "exam"]);
+    expect(report.title).toEqual({ en: "Memory Evals", "zh-CN": "记忆能力评测" });
+    expect(report.footer).toBe("Published nightly.");
+  });
+
+  it("content 与 pages 恰好声明一个:同给 / 同缺都报错,文案给出 <ExperimentComparison /> 下一步", () => {
+    for (const bad of [
+      { kind: "report", content: tree, pages: [{ id: "a", title: "A", content: tree }] },
+      { kind: "report", title: "T" },
+    ]) {
+      expect(() => normalizeHostReport(bad, "reports/site.tsx")).toThrow(HostReportError);
+      expect(() => normalizeHostReport(bad, "reports/site.tsx")).toThrow(/<ExperimentComparison \/>/);
+    }
+  });
+
+  it("空 pages 列表 / 重复 page id / 非法 page id 在装载期报错", () => {
+    expect(() => normalizeHostReport({ kind: "report", pages: [] }, "r.tsx")).toThrow(/non-empty/);
+    expect(() =>
+      normalizeHostReport(
+        { kind: "report", pages: [{ id: "exam", title: "A", content: tree }, { id: "exam", title: "B", content: tree }] },
+        "r.tsx",
+      ),
+    ).toThrow(/duplicate page id "exam"/);
+    for (const id of ["Exam", "a/b"]) {
+      expect(() =>
+        normalizeHostReport({ kind: "report", pages: [{ id, title: "A", content: tree }] }, "r.tsx"),
+      ).toThrow(/invalid/);
+    }
+  });
+
+  it("默认导出不是 defineReport 产物:完整用户反馈", () => {
+    expect(() => normalizeHostReport({ some: "object" }, "reports/bad.tsx")).toThrow(
+      /does not default-export a report/,
+    );
+  });
+
+  it("ReportLink.icon 是 { svg: string }:合法形状原样透传;无类型 JS 传其它形状装载报错", () => {
+    const svg = '<svg viewBox="0 0 16 16"><path d="M0 0h16v16z"/></svg>';
+    const report = normalizeHostReport(
+      { kind: "report", content: tree, links: [{ label: "GitHub", href: "https://example.com", icon: { svg } }] },
+      "reports/site.tsx",
+    );
+    expect(report.links[0]!.icon).toEqual({ svg });
+
+    // ReactNode / 组件 / 裸字符串都不是 { svg: string },装载期以完整用户反馈拒绝。
+    const reactNode = { $$typeof: Symbol.for("react.transitional.element"), type: "svg", props: {} };
+    for (const icon of [reactNode, "<svg/>", { svg: 42 }, { svg: "" }]) {
+      expect(() =>
+        normalizeHostReport(
+          { kind: "report", content: tree, links: [{ label: "GitHub", href: "https://example.com", icon }] },
+          "reports/site.tsx",
+        ),
+      ).toThrow(/icon" must be \{ svg: string \}/);
+    }
+  });
+
+  it("旧 build 函数形态(集成前桥接)恒为单页 report", () => {
+    const legacy = { build: () => tree };
+    const report = normalizeHostReport(legacy, "the built-in report");
+    expect(report.pages.map((p) => p.id)).toEqual(["report"]);
+    expect(report.pages[0]!.content).toBe(legacy);
+  });
+});
+
+describe("标题回退链:def.title → 唯一且相同的快照 name → 内置文案「Eval 运行结果 / Eval Results」", () => {
+  it("def.title 优先", () => {
+    expect(resolveReportTitle({ en: "T" }, [{ name: "S" }])).toEqual({ en: "T" });
+  });
+
+  it("无 def.title 时取 Scope 中唯一且相同(深相等,键顺序无关)的非空快照 name", () => {
+    expect(resolveReportTitle(undefined, [{ name: { en: "S", "zh-CN": "斯" } }, { name: { "zh-CN": "斯", en: "S" } }]))
+      .toEqual({ en: "S", "zh-CN": "斯" });
+    expect(resolveReportTitle(undefined, [{}, { name: "Only" }])).toBe("Only");
+  });
+
+  it("多个不同 name(en 相同、zh-CN 不同也算不同)不随机挑,落内置文案;全无 name 亦然", () => {
+    expect(
+      resolveReportTitle(undefined, [{ name: { en: "S", "zh-CN": "甲" } }, { name: { en: "S", "zh-CN": "乙" } }]),
+    ).toEqual(BUILT_IN_REPORT_TITLE);
+    expect(resolveReportTitle(undefined, [{}, {}])).toEqual(BUILT_IN_REPORT_TITLE);
+    expect(resolveReportTitle("", [])).toEqual(BUILT_IN_REPORT_TITLE); // 空串标题不算声明
+    // 链终点是内置文案(shell.md),不是产品名——品牌位固定 NiceEval,不吃标题。
+    expect(BUILT_IN_REPORT_TITLE).toEqual({ en: "Eval Results", "zh-CN": "Eval 运行结果" });
+  });
+
+  it("LocalizedText 深相等按字段值,不看键顺序", () => {
+    expect(localizedTextEquals({ a: "1", b: "2" }, { b: "2", a: "1" })).toBe(true);
+    expect(localizedTextEquals({ a: "1" }, { a: "1", b: "2" })).toBe(false);
+  });
+});
+
+describe("LocalizedText 回退:locale → en → 键字典序第一个非空值", () => {
+  it("三级回退各自命中", () => {
+    expect(localizeText({ "zh-CN": "中", en: "E" }, "zh-CN")).toBe("中");
+    expect(localizeText({ "zh-CN": "中", en: "E" }, "fr")).toBe("E");
+    expect(localizeText({ "zh-TW": "繁", ja: "日" }, "en")).toBe("日"); // ja < zh-TW 字典序
+    expect(localizeText("plain", "en")).toBe("plain");
+    expect(localizeText({}, "en")).toBeUndefined();
+  });
+});
+
+describe("页索引与索引命令上下文", () => {
+  const report = normalizeHostReport(
+    {
+      kind: "report",
+      title: { en: "Memory Evals", "zh-CN": "记忆能力评测" },
+      links: [{ label: "GitHub", href: "https://example.com", icon: { svg: "<svg data-mark></svg>" } }],
+      pages: [
+        { id: "overview", title: { en: "Overview", "zh-CN": "总览" }, content: tree },
+        { id: "exam", title: { en: "Exam", "zh-CN": "成绩单" }, content: tree },
+      ],
+    },
+    "reports/site.tsx",
+  );
+
+  it("索引命令保留当前 --results / --report 与位置参数,复制即可复现下一层视图", () => {
+    const text = pageIndexText({
+      report,
+      title: "记忆能力评测",
+      command: { patterns: [], results: "tmp/published-results", report: "reports/site.tsx" },
+      locale: "zh-CN",
+    });
+    expect(text).toContain("记忆能力评测 · 2 页");
+    expect(text).toContain("niceeval show --results tmp/published-results --report reports/site.tsx --page overview");
+    expect(text).toContain("niceeval show --results tmp/published-results --report reports/site.tsx --page exam");
+    expect(text).toContain("总览");
+    expect(text).toContain("成绩单");
+  });
+
+  it("show 不消费 links:页索引不含 icon svg 与 href(icon 是 web 面属性)", () => {
+    const text = pageIndexText({
+      report,
+      title: "Memory Evals",
+      command: { patterns: [] },
+      locale: "en",
+    });
+    expect(text).not.toContain("<svg");
+    expect(text).not.toContain("https://example.com");
+  });
+
+  it("showCommand 按序携带位置参数与 --experiment / --results / --report / --page", () => {
+    expect(
+      showCommand({ patterns: ["memory/swelancer"], experiment: "dev-e2b", report: "reports/site.tsx", page: "exam" }),
+    ).toBe("niceeval show memory/swelancer --experiment dev-e2b --report reports/site.tsx --page exam");
+  });
+});

package/src/show/report-host.ts

@@ -0,0 +1,375 @@
+// 报告装载的宿主联系面:show 与 view 共用(view 从这里 import;两个宿主对同一份
+// defineReport 产物必须得到同一个规范化结果,见 docs/feature/reports/library/shell.md)。
+//
+// 契约(docs/feature/reports/library/shell.md「行为约束」/ architecture.md「外壳与页:装载规范化」):
+// - `--report` 文件默认导出恒为 defineReport 产物;裸宿主装载 `niceeval/report/built-in` 的默认导出,
+//   走同一条「装载 → resolve → validate → render」管线。
+// - 装载规范化唯一产物是「外壳 + 非空页列表」:`defineReport(树)` ≡ `{ content: 树 }` ≡
+//   `pages: [{ id: "report", title: 内置页名, content: 树 }]`。
+// - 标题回退单点:def.title → Scope 中唯一且相同(LocalizedText 深相等)的非空快照 name →
+//   内置文案「Eval 运行结果 / Eval Results」。落点是首页 hero、浏览器标题与 show 页索引标题行;
+//   页头品牌位恒为 NiceEval 字标,不归 title。
+// - LocalizedText 回退:当前 locale → en → 按 locale 键字典序的第一个非空值。
+//
+// ⚠ 集成状态:src/report/** 正被并行重写(plan/reports-redesign-implementation.md)。这里把宿主
+// 需要的新报告 runtime API 收敛成唯一联系面,并对「新 dist 尚未产出」提供旧 API 桥接
+// (旧 ReportDefinition 是 build 函数形态,恒为单页)。集成阶段的对接点(搜索 INTEGRATION):
+//   1. `dist/report/built-in/index.js` 默认导出(内建报告入口;恒为新格式,无桥接——
+//      它随本包源码一起构建,不存在旧产物)。
+//   2. `normalizeReport(definition)`:装载规范化(外壳 + 非空页列表);旧桥接对 build 形态自行包单页。
+//   3. `renderReportTreeToText(tree, ctx, options)` / `renderReportTreeToStaticHtml(tree, ctx, options)`:
+//      逐页渲染入口(ctx = { scope, results, report });旧桥接调 renderReportToText /
+//      renderReportToStaticHtml(definition 整体)。
+
+import type { Results } from "../results/index.ts";
+import type { LocalizedText } from "../types.ts";
+
+/** 页:宿主寻址单位(`--page <id>` / `#/page/<id>`)。content 是报告树(旧桥接下是整个旧 definition)。 */
+export interface HostReportPage {
+  id: string;
+  title: LocalizedText;
+  content: unknown;
+}
+
+export interface HostReportLink {
+  label: LocalizedText;
+  href: string;
+  /**
+   * 可选内联 SVG 字标(shell.md「字段穷尽」):web 面渲染在 label 前,静态导出原样内联;
+   * 不收组件(外壳声明经 viewData 序列化边界);show 不消费。
+   */
+  icon?: { svg: string };
+}
+
+/** `{src}` 与 `{inline}` 两种形态不可同时出现(shell.md「字段穷尽」)。 */
+export type HostReportAsset = { src: string; inline?: never } | { inline: string; src?: never };
+
+/** 装载规范化产物:外壳 + 非空页列表。show 只消费 title / pages;其余是 web 面属性。 */
+export interface HostReport {
+  title?: LocalizedText;
+  links: HostReportLink[];
+  footer?: LocalizedText;
+  scripts: HostReportAsset[];
+  styles: HostReportAsset[];
+  pages: HostReportPage[];
+}
+
+/** 单页缩写展开出的唯一页使用内置页名(shell.md:「报告 / Report」)。 */
+export const BUILT_IN_PAGE_TITLE: LocalizedText = { en: "Report", "zh-CN": "报告" };
+export const SINGLE_PAGE_ID = "report";
+
+/** 标题回退链的终点:内置文案「Eval 运行结果 / Eval Results」(shell.md「行为约束」)。 */
+export const BUILT_IN_REPORT_TITLE: LocalizedText = { en: "Eval Results", "zh-CN": "Eval 运行结果" };
+
+/** 规范化报告声明的只读注入(组合组件 ctx.report;ReportMeta,见 library/layout.md)。 */
+export interface HostReportMeta {
+  title: LocalizedText;
+  links: HostReportLink[];
+  footer?: LocalizedText;
+  pages: { id: string; title: LocalizedText }[];
+  pageId: string;
+}
+
+/** 可预期的装载用户错误(与 ReportLoadError 同待遇:打一句直说问题与下一步,不抛堆栈)。 */
+export class HostReportError extends Error {}
+
+// ───────────────────────── LocalizedText ─────────────────────────
+
+/**
+ * LocalizedText 的确定回退(shell.md「行为约束」):当前 locale → en → 按 locale 键字典序的
+ * 第一个非空值。对象没有任何非空值时返回 undefined(装载期应当已报错,渲染兜底不再抛)。
+ */
+export function localizeText(text: LocalizedText | undefined, locale: string): string | undefined {
+  if (text === undefined) return undefined;
+  if (typeof text === "string") return text || undefined;
+  const exact = text[locale];
+  if (exact) return exact;
+  if (text.en) return text.en;
+  for (const key of Object.keys(text).sort()) {
+    if (text[key]) return text[key];
+  }
+  return undefined;
+}
+
+/** LocalizedText 深相等:按字段值比较,对象键顺序不影响结果(shell.md「标题回退必须确定」)。 */
+export function localizedTextEquals(a: LocalizedText, b: LocalizedText): boolean {
+  if (typeof a === "string" || typeof b === "string") return a === b;
+  const keysA = Object.keys(a).sort();
+  const keysB = Object.keys(b).sort();
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((key, i) => key === keysB[i] && a[key] === b[key]);
+}
+
+/** LocalizedText 是否有任何非空值(空串 / 全空对象都算空)。 */
+function hasText(text: LocalizedText | undefined): text is LocalizedText {
+  if (text === undefined) return false;
+  if (typeof text === "string") return text.length > 0;
+  return Object.values(text).some((v) => typeof v === "string" && v.length > 0);
+}
+
+/**
+ * 标题回退单点(show 页索引标题与 view hero / 浏览器标题共用):def.title → Scope 中唯一且相同
+ * (深相等)的非空快照 name → 内置文案「Eval 运行结果 / Eval Results」。多个不同 name 时
+ * 不随机挑一个,直接落到内置文案。
+ */
+export function resolveReportTitle(
+  defTitle: LocalizedText | undefined,
+  snapshots: readonly { name?: LocalizedText }[],
+): LocalizedText {
+  if (hasText(defTitle)) return defTitle;
+  let unique: LocalizedText | undefined;
+  for (const snapshot of snapshots) {
+    if (!hasText(snapshot.name)) continue;
+    if (unique === undefined) {
+      unique = snapshot.name;
+    } else if (!localizedTextEquals(unique, snapshot.name)) {
+      return BUILT_IN_REPORT_TITLE;
+    }
+  }
+  return unique ?? BUILT_IN_REPORT_TITLE;
+}
+
+/** 组合组件 ctx.report 的形状(走完回退链的 title;scripts / styles 不进)。 */
+export function reportMetaFor(
+  report: HostReport,
+  pageId: string,
+  snapshots: readonly { name?: LocalizedText }[],
+): HostReportMeta {
+  return {
+    title: resolveReportTitle(report.title, snapshots),
+    links: report.links,
+    ...(report.footer !== undefined ? { footer: report.footer } : {}),
+    pages: report.pages.map((p) => ({ id: p.id, title: p.title })),
+    pageId,
+  };
+}
+
+// ───────────────────────── 装载与规范化 ─────────────────────────
+
+/** 旧(集成前)ReportDefinition:build 函数形态,恒为单页。集成阶段删除。 */
+interface LegacyReportDefinition {
+  build: (ctx: unknown) => unknown;
+}
+
+function isLegacyDefinition(value: unknown): value is LegacyReportDefinition {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    typeof (value as Partial<LegacyReportDefinition>).build === "function"
+  );
+}
+
+const PAGE_ID_PATTERN = /^[a-z0-9-]+$/;
+
+/**
+ * 装载期校验 `ReportLink.icon`(shell.md「字段穷尽」):唯一合法形状是 `{ svg: string }`。
+ * 无类型 JS 传组件 / ReactNode / 裸字符串都在这里被完整用户反馈拒绝——外壳声明要过
+ * viewData 的序列化边界,ReactNode 过不去,可序列化是外壳契约的一部分。
+ */
+function assertLinkIcon(link: unknown, sourceLabel: string): void {
+  const icon = (link as { icon?: unknown })?.icon;
+  if (icon === undefined) return;
+  const svg = (icon as { svg?: unknown })?.svg;
+  if (typeof icon !== "object" || icon === null || typeof svg !== "string" || svg.length === 0) {
+    throw new HostReportError(
+      `${sourceLabel}: a link "icon" must be { svg: string } — an inline SVG string rendered before the label. ` +
+        "Components and React nodes are not accepted: the shell declaration crosses a serialization boundary. " +
+        'Write e.g. icon: { svg: "<svg …>…</svg>" }.',
+    );
+  }
+}
+
+/**
+ * 装载规范化:把 defineReport 产物折成「外壳 + 非空页列表」。三种入参写法
+ * (树 / `content:` / `pages:`)展开成同一形状;page id 的唯一性与字符纪律在这里校验
+ * (shell.md「校验分两期」的装载期部分)。
+ */
+export function normalizeHostReport(definition: unknown, sourceLabel: string): HostReport {
+  // INTEGRATION(2):新 defineReport 产物(kind === "report")。规范化后的外壳与页列表
+  // 若由新报告 runtime 导出的 normalizeReport 承担,这里改为直接调它;当前按 docs 的
+  // 字段穷尽读取产物自带的声明。
+  if (typeof definition === "object" && definition !== null && (definition as { kind?: unknown }).kind === "report") {
+    const def = definition as {
+      title?: LocalizedText;
+      links?: HostReportLink[];
+      footer?: LocalizedText;
+      scripts?: HostReportAsset[];
+      styles?: HostReportAsset[];
+      content?: unknown;
+      pages?: { id: string; title: LocalizedText; content: unknown }[];
+    };
+    const hasContent = def.content !== undefined;
+    const hasPages = def.pages !== undefined;
+    if (hasContent === hasPages) {
+      // content / pages 同缺或同给:装载期完整用户反馈,下一步是 content: <ExperimentComparison />。
+      throw new HostReportError(
+        `${sourceLabel}: a report declares exactly one of "content" or "pages" — ` +
+          (hasContent ? "it declares both. " : "it declares neither. ") +
+          `To render the built-in report content, write: content: <ExperimentComparison />.`,
+      );
+    }
+    const pages: HostReportPage[] = hasPages
+      ? def.pages!.map((p) => ({ id: p.id, title: p.title, content: p.content }))
+      : [{ id: SINGLE_PAGE_ID, title: BUILT_IN_PAGE_TITLE, content: def.content }];
+    if (pages.length === 0) {
+      throw new HostReportError(`${sourceLabel}: "pages" must be a non-empty list of report pages.`);
+    }
+    const seen = new Set<string>();
+    for (const page of pages) {
+      if (!PAGE_ID_PATTERN.test(page.id)) {
+        throw new HostReportError(
+          `${sourceLabel}: page id "${page.id}" is invalid. Page ids use lowercase letters, digits and hyphens.`,
+        );
+      }
+      if (seen.has(page.id)) {
+        throw new HostReportError(`${sourceLabel}: duplicate page id "${page.id}". Page ids must be unique per file.`);
+      }
+      seen.add(page.id);
+    }
+    for (const link of def.links ?? []) assertLinkIcon(link, sourceLabel);
+    return {
+      ...(def.title !== undefined ? { title: def.title } : {}),
+      links: def.links ?? [],
+      ...(def.footer !== undefined ? { footer: def.footer } : {}),
+      scripts: def.scripts ?? [],
+      styles: def.styles ?? [],
+      pages,
+    };
+  }
+
+  // INTEGRATION(2) 桥接:旧 build 函数形态(集成前的 dist);恒为单页,无外壳字段。
+  if (isLegacyDefinition(definition)) {
+    return {
+      links: [],
+      scripts: [],
+      styles: [],
+      pages: [{ id: SINGLE_PAGE_ID, title: BUILT_IN_PAGE_TITLE, content: definition }],
+    };
+  }
+
+  throw new HostReportError(
+    `${sourceLabel} does not default-export a report. Export default defineReport(<ExperimentComparison />) (or defineReport({ title, content })) from "niceeval/report".`,
+  );
+}
+
+/**
+ * 装载宿主报告:`--report <file>` 走 loadReportFile;缺省(裸 show / 裸 view)装载内建报告的
+ * 默认导出。两条路都进 normalizeHostReport,同一条装载管线。
+ */
+export async function loadHostReport(
+  cwd: string,
+  reportPath: string | undefined,
+  options?: { freshImport?: boolean },
+): Promise<HostReport> {
+  if (reportPath !== undefined) {
+    const { loadReportFile } = await import("../../dist/report/load.js");
+    const definition = await loadReportFile(cwd, reportPath, options);
+    return normalizeHostReport(definition, reportPath);
+  }
+  return normalizeHostReport(await loadBuiltInDefinition(), "the built-in report");
+}
+
+/** 内建报告即 `niceeval/report/built-in` 的默认导出(dist 预编译产物,`prepare` 时构建)。 */
+async function loadBuiltInDefinition(): Promise<unknown> {
+  const mod = await import("../../dist/report/built-in/index.js");
+  return mod.default;
+}
+
+// ───────────────────────── 逐页渲染 ─────────────────────────
+
+export interface HostRenderContext {
+  /** 宿主按官方现刻水位挑好的 Scope(集成前类型名仍是 Selection;两者同物)。 */
+  scope: unknown;
+  results: Results;
+  report: HostReportMeta;
+}
+
+export interface HostTextRenderOptions {
+  width?: number;
+  locale?: string;
+  /**
+   * 索引命令的完整上下文(docs/feature/reports/show/reports.md:「索引命令携带完整上下文」):
+   * 组索引 / 页索引输出的每一条可复制命令都保留当前 --results / --report / --page 与位置参数。
+   * INTEGRATION(3):由新 text 面消费;旧桥接的 renderReportToText 不认识该字段,原样忽略。
+   */
+  commandContext?: HostCommandContext;
+}
+
+export interface HostCommandContext {
+  patterns: string[];
+  results?: string;
+  experiment?: string;
+  report?: string;
+  page?: string;
+}
+
+/** 按上下文拼一条可复制的 show 命令(页索引 / 组索引共用的携带规则)。 */
+export function showCommand(ctx: HostCommandContext, extra: string[] = []): string {
+  const parts = ["niceeval show", ...ctx.patterns];
+  if (ctx.experiment !== undefined) parts.push(`--experiment ${ctx.experiment}`);
+  if (ctx.results !== undefined) parts.push(`--results ${ctx.results}`);
+  if (ctx.report !== undefined) parts.push(`--report ${ctx.report}`);
+  if (ctx.page !== undefined) parts.push(`--page ${ctx.page}`);
+  parts.push(...extra);
+  return parts.join(" ");
+}
+
+/**
+ * 渲染一页的 text 面。INTEGRATION(3):新 runtime 的入口是
+ * `renderReportTreeToText(tree, { scope, results, report }, options)`;旧桥接下 content 是
+ * 整个旧 definition,调 renderReportToText(definition, { selection, results }, options)。
+ */
+export async function renderHostPageText(
+  page: HostReportPage,
+  ctx: HostRenderContext,
+  options: HostTextRenderOptions,
+): Promise<string> {
+  const mod = (await import("../../dist/report/report.js")) as Record<string, unknown>;
+  const renderTree = mod.renderReportTreeToText as
+    | ((tree: unknown, ctx: HostRenderContext, options: HostTextRenderOptions) => Promise<string>)
+    | undefined;
+  if (typeof renderTree === "function" && !isLegacyDefinition(page.content)) {
+    return renderTree(page.content, ctx, options);
+  }
+  if (isLegacyDefinition(page.content)) {
+    const renderLegacy = mod.renderReportToText as (
+      definition: unknown,
+      ctx: { selection: unknown; results: Results },
+      options: { width?: number; locale?: string },
+    ) => Promise<string>;
+    return renderLegacy(
+      page.content,
+      { selection: ctx.scope, results: ctx.results },
+      { ...(options.width !== undefined ? { width: options.width } : {}), ...(options.locale !== undefined ? { locale: options.locale } : {}) },
+    );
+  }
+  throw new HostReportError(
+    "The installed report runtime cannot render this report page yet (renderReportTreeToText is missing). Rebuild dist/report with `pnpm run build:report`.",
+  );
+}
+
+/** 渲染一页的 web 面(静态 HTML)。INTEGRATION(3) 同上,web 侧入口在 dist/report/web.js。 */
+export async function renderHostPageHtml(
+  page: HostReportPage,
+  ctx: HostRenderContext,
+  options: { locale: string },
+): Promise<string> {
+  const mod = (await import("../../dist/report/web.js")) as Record<string, unknown>;
+  const renderTree = mod.renderReportTreeToStaticHtml as
+    | ((tree: unknown, ctx: HostRenderContext, options: { locale: string }) => Promise<string>)
+    | undefined;
+  if (typeof renderTree === "function" && !isLegacyDefinition(page.content)) {
+    return renderTree(page.content, ctx, options);
+  }
+  if (isLegacyDefinition(page.content)) {
+    const renderLegacy = mod.renderReportToStaticHtml as (
+      definition: unknown,
+      ctx: { selection: unknown; results: Results },
+      options: { locale: string },
+    ) => Promise<string>;
+    return renderLegacy(page.content, { selection: ctx.scope, results: ctx.results }, options);
+  }
+  throw new HostReportError(
+    "The installed report runtime cannot render this report page yet (renderReportTreeToStaticHtml is missing). Rebuild dist/report with `pnpm run build:report`.",
+  );
+}