niceeval 0.9.1 → 0.10.2

package/src/report/components/entity-lists/index.tsx

@@ -0,0 +1,238 @@
+// 官方双面组件的装配点:web 面(./ExperimentList.tsx / EvalList.tsx / AttemptList.tsx 的纯
+// React 组件)+ text 面(./faces.ts)+ resolve 解析面(spec 形态由管线代调配套 ./compute.ts)。
+// FailureList 是组合组件,内部就是 attemptListData → 过滤 → AttemptList data 形态,不产生
+// 自己的 data。
+
+import { defineComponent, type ReportComponent } from "../../definition/tree.ts";
+import type { AttemptListItem, EvalListItem, ExperimentListItem, ReportInput } from "../../model/types.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import { collectItems, locatorOf, resolveInput } from "../../model/aggregate.ts";
+import type { ReportLocale } from "../../model/locale.ts";
+import {
+  arrayProblem,
+  cellProblem,
+  isObject,
+  makeDataComponent,
+  hrefOf,
+  tallyProblem,
+  type ChromeProps,
+  type DataProps,
+  type Validator,
+} from "../shared.ts";
+import { attemptListData, evalListData, experimentListData } from "./compute.ts";
+import { attemptListText, evalListText, experimentListText } from "./faces.ts";
+import { AttemptList as AttemptListWeb } from "./AttemptList.tsx";
+import { EvalList as EvalListWeb } from "./EvalList.tsx";
+import { ExperimentList as ExperimentListWeb } from "./ExperimentList.tsx";
+
+/** AttemptListItem(src/report/model/types.ts):三个组件族共用的叶子形状(独立 data 或嵌套在 evalRows/attempts 里)。 */
+function attemptListItemProblem(value: unknown, path: string): string | null {
+  if (!isObject(value)) return `"${path}" must be an object`;
+  if (typeof value.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+  if (typeof value.evalId !== "string") return `"${path}.evalId" must be a string`;
+  if (typeof value.attempt !== "number") return `"${path}.attempt" must be a number`;
+  if (typeof value.agent !== "string") return `"${path}.agent" must be a string`;
+  if (typeof value.verdict !== "string") return `"${path}.verdict" must be a string`;
+  if (!(value.failureSummary === null || typeof value.failureSummary === "string")) {
+    return `"${path}.failureSummary" must be a string or null`;
+  }
+  if (typeof value.moreFailures !== "number") return `"${path}.moreFailures" must be a number`;
+  const examScoreProblem = cellProblem(value.examScore, `${path}.examScore`);
+  if (examScoreProblem !== null) return examScoreProblem;
+  if (typeof value.durationMs !== "number") return `"${path}.durationMs" must be a number`;
+  if (!(value.costUSD === null || typeof value.costUSD === "number")) return `"${path}.costUSD" must be a number or null`;
+  if (typeof value.locator !== "string") return `"${path}.locator" must be a string`;
+  return null;
+}
+
+export const validateExperimentListData: Validator = (data) =>
+  arrayProblem(data, "data", (item, path) => {
+    if (!isObject(item)) return `"${path}" must be an object`;
+    if (typeof item.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+    if (typeof item.agent !== "string") return `"${path}.agent" must be a string`;
+    const verdictsProblem = tallyProblem(item.evalVerdicts, `${path}.evalVerdicts`);
+    if (verdictsProblem !== null) return verdictsProblem;
+    const passRateProblem = cellProblem(item.endToEndPassRate, `${path}.endToEndPassRate`);
+    if (passRateProblem !== null) return passRateProblem;
+    const costProblem = cellProblem(item.costUSD, `${path}.costUSD`);
+    if (costProblem !== null) return costProblem;
+    const durationProblem = cellProblem(item.durationMs, `${path}.durationMs`);
+    if (durationProblem !== null) return durationProblem;
+    const tokensProblem = cellProblem(item.tokens, `${path}.tokens`);
+    if (tokensProblem !== null) return tokensProblem;
+    if (typeof item.evals !== "number") return `"${path}.evals" must be a number`;
+    if (typeof item.attempts !== "number") return `"${path}.attempts" must be a number`;
+    if (typeof item.lastRunAt !== "string") return `"${path}.lastRunAt" must be a string`;
+    return arrayProblem(item.evalRows, `${path}.evalRows`, (row, rowPath) => {
+      if (!isObject(row) || typeof row.evalId !== "string") {
+        return `"${rowPath}" must be an object with a string "evalId"`;
+      }
+      const rowDurationProblem = cellProblem(row.durationMs, `${rowPath}.durationMs`);
+      if (rowDurationProblem !== null) return rowDurationProblem;
+      const rowCostProblem = cellProblem(row.costUSD, `${rowPath}.costUSD`);
+      if (rowCostProblem !== null) return rowCostProblem;
+      return arrayProblem(row.attempts, `${rowPath}.attempts`, attemptListItemProblem);
+    });
+  });
+export const validateEvalListData: Validator = (data) =>
+  arrayProblem(data, "data", (item, path) => {
+    if (!isObject(item)) return `"${path}" must be an object`;
+    if (typeof item.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+    if (typeof item.evalId !== "string") return `"${path}.evalId" must be a string`;
+    if (typeof item.verdict !== "string") return `"${path}.verdict" must be a string`;
+    const examScoreProblem = cellProblem(item.examScore, `${path}.examScore`);
+    if (examScoreProblem !== null) return examScoreProblem;
+    const durationProblem = cellProblem(item.durationMs, `${path}.durationMs`);
+    if (durationProblem !== null) return durationProblem;
+    const costProblem = cellProblem(item.costUSD, `${path}.costUSD`);
+    if (costProblem !== null) return costProblem;
+    return arrayProblem(item.attempts, `${path}.attempts`, attemptListItemProblem);
+  });
+export const validateAttemptListData: Validator = (data) => arrayProblem(data, "data", attemptListItemProblem);
+
+// ───────────────────────── 实体列表 ─────────────────────────
+
+interface EntityListChrome extends ChromeProps {
+  attemptHref?: (locator: AttemptLocator) => string;
+}
+
+export type ExperimentListProps = DataProps<
+  readonly ExperimentListItem[],
+  Record<never, never>,
+  EntityListChrome & {
+    /** web 面在比较表前显示实验过滤框;text 面忽略。 */
+    filter?: boolean;
+  }
+>;
+
+/**
+ * 实验列表:每项一个 experiment,固定八列比较表 + 展开到 Eval / Attempt。行标签是
+ * experiment id 在当前列表里的最短唯一后缀(与 MetricScatter 点标签同一算法,重名逐步
+ * 加长到能区分为止);完整 id 不受影响,仍是排序 / 过滤 / 折叠的键。
+ */
+export const ExperimentList = makeDataComponent<
+  readonly ExperimentListItem[],
+  Record<never, never>,
+  EntityListChrome & { filter?: boolean }
+>({
+  name: "ExperimentList",
+  dataFnName: "experimentListData",
+  shapeName: "ExperimentListItem[]",
+  dataFn: (input) => experimentListData(input),
+  specKeys: [],
+  validate: validateExperimentListData,
+  web: (props, ctx) => (
+    <ExperimentListWeb
+      data={props.data}
+      filter={props.filter}
+      locale={props.locale ?? ctx.locale}
+      attemptHref={hrefOf(props, ctx)}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => experimentListText(props.data, ctx),
+}) as unknown as ReportComponent<ExperimentListProps>;
+
+export type EvalListProps = DataProps<readonly EvalListItem[], Record<never, never>, EntityListChrome>;
+
+/** Eval 列表:每项一个 experimentId + evalId,展开到这道题的 Attempt。 */
+export const EvalList = makeDataComponent<readonly EvalListItem[], Record<never, never>, EntityListChrome>({
+  name: "EvalList",
+  dataFnName: "evalListData",
+  shapeName: "EvalListItem[]",
+  dataFn: (input) => evalListData(input),
+  specKeys: [],
+  validate: validateEvalListData,
+  web: (props, ctx) => (
+    <EvalListWeb
+      data={props.data}
+      locale={props.locale ?? ctx.locale}
+      attemptHref={hrefOf(props, ctx)}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => evalListText(props.data, ctx),
+}) as unknown as ReportComponent<EvalListProps>;
+
+export type AttemptListProps = DataProps<
+  readonly AttemptListItem[],
+  Record<never, never>,
+  EntityListChrome & {
+    /** 过滤 / 截断前的总数;省略时等于 data 长度。 */
+    total?: number;
+    /** web 面加过滤输入框(按 experiment、eval、agent、verdict 或摘要文本收窄行);渐进增强,不改变数据与 text 面。 */
+    filter?: boolean;
+  }
+>;
+
+/** Attempt 列表:实体列表的叶子层,每项一次 attempt 的判定、单行摘要与 locator。 */
+export const AttemptList = makeDataComponent<
+  readonly AttemptListItem[],
+  Record<never, never>,
+  EntityListChrome & { total?: number; filter?: boolean }
+>({
+  name: "AttemptList",
+  dataFnName: "attemptListData",
+  shapeName: "AttemptListItem[]",
+  dataFn: (input) => attemptListData(input),
+  specKeys: [],
+  validate: validateAttemptListData,
+  web: (props, ctx) => (
+    <AttemptListWeb
+      data={props.data}
+      total={props.total}
+      filter={props.filter}
+      locale={props.locale ?? ctx.locale}
+      attemptHref={hrefOf(props, ctx)}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => attemptListText(props.data, props.total, ctx),
+}) as unknown as ReportComponent<AttemptListProps>;
+
+// ───────────────────────── FailureList(官方组合件)─────────────────────────
+
+export interface FailureListProps {
+  /** 显示的最大条数;默认 20。 */
+  limit?: number;
+  /** 默认宿主注入的 Scope。 */
+  input?: ReportInput;
+  attemptHref?: (locator: AttemptLocator) => string;
+  locale?: ReportLocale;
+  className?: string;
+}
+
+/**
+ * 「现在有哪些失败要处理」的成品组合件:内部就是 attemptListData → 过滤 → AttemptList
+ * data 形态,与手写组合严格等价、没有私有能力(docs/feature/reports/library/entity-lists.md)。
+ * verdict ∈ failed / errored,按 attempt 开始时间降序(同刻按 locator 字典序),
+ * 截断到 limit(默认 20),total 报告截断前总数。
+ */
+export const FailureList = defineComponent<FailureListProps>(async (props, ctx) => {
+  const input = props.input ?? ctx.scope;
+  const all = await attemptListData(input);
+  // attempt 开始时间不在列表条目里(它不是列表展示字段);从同一 input 的读取面按 locator 对回。
+  const startedAtByLocator = new Map<string, string>();
+  for (const item of collectItems(resolveInput(input).snapshots)) {
+    startedAtByLocator.set(locatorOf(item), item.attempt.result.startedAt ?? "");
+  }
+  const failures = all
+    .filter((item) => item.verdict === "failed" || item.verdict === "errored")
+    .sort((a, b) => {
+      const ta = startedAtByLocator.get(a.locator) ?? "";
+      const tb = startedAtByLocator.get(b.locator) ?? "";
+      if (ta !== tb) return ta < tb ? 1 : -1; // 最近的失败在前
+      return a.locator < b.locator ? -1 : a.locator > b.locator ? 1 : 0;
+    });
+  const limit = props.limit ?? 20;
+  return (
+    <AttemptList
+      data={failures.slice(0, limit)}
+      total={failures.length}
+      attemptHref={props.attemptHref}
+      locale={props.locale}
+      className={props.className}
+    />
+  );
+});
+FailureList.displayName = "FailureList";

package/src/report/components/entity-lists/validate.test.ts

@@ -0,0 +1,114 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// "validate*Data 递归覆盖到嵌套字段" 行:entity-lists 三个 validate*Data 的表驱动字段突变覆盖,AttemptListItem 的形状在三个组件族
+// 共用(独立 data 或嵌套在 evalRows/attempts 里),重点覆盖嵌套 MetricCell/tally 字段与
+// 深层嵌套(ExperimentListItem.evalRows[i].attempts[j])的路径定位。
+
+import { describe, expect, it } from "vitest";
+import { validateAttemptListData, validateEvalListData, validateExperimentListData } from "./index.tsx";
+
+const validCell = { value: 1, display: "1", samples: 1, total: 1, refs: [] };
+const validTally = { passed: 1, failed: 0, errored: 0, skipped: 0 };
+
+const validAttemptItem = {
+  experimentId: "compare/codex",
+  evalId: "q1",
+  attempt: 0,
+  agent: "codex",
+  verdict: "passed",
+  failureSummary: null,
+  moreFailures: 0,
+  examScore: validCell,
+  durationMs: 1000,
+  costUSD: 0.01,
+  locator: "@1abcdef2",
+};
+
+describe("validateAttemptListData", () => {
+  it("合规 literal 通过,costUSD 为 null 与 failureSummary 为 null 合法", () => {
+    expect(validateAttemptListData([{ ...validAttemptItem, costUSD: null }])).toBeNull();
+  });
+
+  it("非数组整体报错", () => {
+    expect(validateAttemptListData({})).toMatch(/"data" must be an array/);
+  });
+
+  it("[i].examScore 结构错误定位到嵌套 MetricCell 字段", () => {
+    const bad = [{ ...validAttemptItem, examScore: { value: 1 } }];
+    expect(validateAttemptListData(bad)).toMatch(/"data\[0\]\.examScore\.display"/);
+  });
+
+  it("[i].verdict 非字符串报错", () => {
+    const bad = [{ ...validAttemptItem, verdict: 1 }];
+    expect(validateAttemptListData(bad)).toMatch(/"data\[0\]\.verdict"/);
+  });
+});
+
+describe("validateEvalListData", () => {
+  const valid = [
+    {
+      experimentId: "compare/codex",
+      evalId: "q1",
+      verdict: "passed",
+      examScore: validCell,
+      durationMs: validCell,
+      costUSD: validCell,
+      attempts: [validAttemptItem],
+    },
+  ];
+
+  it("合规 literal 通过", () => {
+    expect(validateEvalListData(valid)).toBeNull();
+  });
+
+  it("[i].durationMs(MetricCell)结构错误报错", () => {
+    const bad = [{ ...valid[0], durationMs: { value: 1, display: "1", samples: 1, total: 1 } }];
+    expect(validateEvalListData(bad)).toMatch(/"data\[0\]\.durationMs\.refs"/);
+  });
+
+  it("[i].attempts[j] 嵌套 AttemptListItem 结构错误定位到深层下标", () => {
+    const bad = [{ ...valid[0], attempts: [{ ...validAttemptItem, locator: 1 }] }];
+    expect(validateEvalListData(bad)).toMatch(/"data\[0\]\.attempts\[0\]\.locator"/);
+  });
+});
+
+describe("validateExperimentListData", () => {
+  const validEvalRow = { evalId: "q1", verdict: "passed", durationMs: validCell, costUSD: validCell, attempts: [validAttemptItem] };
+  const valid = [
+    {
+      experimentId: "compare/codex",
+      agent: "codex",
+      evalVerdicts: validTally,
+      endToEndPassRate: validCell,
+      costUSD: validCell,
+      durationMs: validCell,
+      tokens: validCell,
+      evals: 1,
+      attempts: 1,
+      lastRunAt: "2026-07-01T00:00:00Z",
+      evalRows: [validEvalRow],
+    },
+  ];
+
+  it("合规 literal 通过", () => {
+    expect(validateExperimentListData(valid)).toBeNull();
+  });
+
+  it("[i].evalVerdicts(四态 tally)缺字段报错", () => {
+    const bad = [{ ...valid[0], evalVerdicts: { passed: 1, failed: 0, errored: 0 } }];
+    expect(validateExperimentListData(bad)).toMatch(/"data\[0\]\.evalVerdicts\.skipped"/);
+  });
+
+  it("[i].evalRows[j].attempts[k] 三层嵌套报错精确定位", () => {
+    const bad = [
+      {
+        ...valid[0],
+        evalRows: [{ ...validEvalRow, attempts: [{ ...validAttemptItem, examScore: null }] }],
+      },
+    ];
+    expect(validateExperimentListData(bad)).toMatch(/"data\[0\]\.evalRows\[0\]\.attempts\[0\]\.examScore"/);
+  });
+
+  it("model / flags 可选字段省略仍合法", () => {
+    expect(validateExperimentListData(valid)).toBeNull();
+  });
+});

package/src/report/{react → components}/fixtures.ts

@@ -15,7 +15,7 @@ import type {
   ScopeSummaryData,
   ScoreboardData,
   TableData,
-} from "../types.ts";
+} from "../model/types.ts";
 import type { AttemptLocator } from "../../results/locator.ts";
 
 const locator = (s: string): AttemptLocator => s as AttemptLocator;
@@ -24,7 +24,7 @@ export const passRateColumn: MetricColumn = { key: "task-pass-rate", label: "pas
 export const codeLinesColumn: MetricColumn = { key: "code-lines", label: "code lines", unit: "lines", better: "lower" };
 export const costColumn: MetricColumn = { key: "cost", label: "cost", unit: "$", better: "lower" };
 
-/** scopeSummaryData 的产物形态:两级计票恒随行,成功率与总成本是官方 MetricCell。 */
+/** scopeSummaryData 的产物形态:两级计票恒随行,通过率与总成本是官方 MetricCell。 */
 export const scopeSummaryData: ScopeSummaryData = {
   range: { earliestStartedAt: "2026-07-01T10:00:00Z", latestStartedAt: "2026-07-01T11:30:00Z" },
   experiments: 2,

package/src/report/{react → components/metric-views}/DeltaTable.tsx

@@ -4,11 +4,11 @@
 // 0 对不是错误:派生形态(pairsByFlag)配不出对时显示明确空态并报告配对域实验数。
 
 import type { ReactElement } from "react";
-import type { DeltaData } from "../types.ts";
-import { DEFAULT_REPORT_LOCALE, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { MetricCellView } from "./cell.tsx";
-import { colorClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { DeltaData } from "../../model/types.ts";
+import { DEFAULT_REPORT_LOCALE, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
+import { MetricCellView } from "../cell.tsx";
+import { colorClassForKey } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 const OUTCOME_CLASS: Record<string, string> = {
   improved: "nre-delta-good",

package/src/report/{react → components/metric-views}/MetricBars.tsx

@@ -4,11 +4,11 @@
 // 组内按值排序,方向随 better;缺数据的系列不画柱、不编 0(与 text 面的 — 同口径)。
 
 import type { ReactElement } from "react";
-import type { MatrixData, MetricCell } from "../types.ts";
-import type { AttemptLocator } from "../../results/locator.ts";
-import { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { colorClassForKey, seriesClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { MatrixData, MetricCell } from "../../model/types.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
+import { colorClassForKey, seriesClassForKey } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 const WIDTH = 640;
 const HEIGHT = 320;

package/src/report/{react → components/metric-views}/MetricLine.tsx

@@ -6,10 +6,10 @@
 // 上色,深色主题跟随,不留内联 hex。
 
 import type { ReactElement } from "react";
-import type { LineData } from "../types.ts";
-import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { seriesClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { LineData } from "../../model/types.ts";
+import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
+import { colorIndicesForKeys } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 const WIDTH = 640;
 const HEIGHT = 360;
@@ -101,6 +101,9 @@ export function MetricLine({
     bySeries.get(key)!.push(p);
   }
   for (const list of bySeries.values()) list.sort((a, b) => a.xValue - b.xValue);
+  // 同图撞色消解:散列格作起点,按图例顺序线性探测空格(colors.ts 的契约注释)
+  const colorIdx = colorIndicesForKeys(seriesOrder.filter((s) => s !== ""));
+  const seriesClassOf = (series: string) => (series === "" ? "nre-series-none" : `nre-series-c${colorIdx.get(series) ?? 0}`);
 
   const xTicks = xScale.lo === xScale.hi ? [xScale.lo] : [xScale.lo, xScale.hi];
   const yTicks = yScale.lo === yScale.hi ? [yScale.lo] : [yScale.lo, yScale.hi];
@@ -157,7 +160,7 @@ export function MetricLine({
 
         {seriesOrder.map((series) => {
           const list = bySeries.get(series)!;
-          const seriesClass = series === "" ? "nre-series-none" : seriesClassForKey(series);
+          const seriesClass = seriesClassOf(series);
           const labelAt = list.reduce((a, b) => (b.px > a.px ? b : a));
           return (
             <g key={series || "(single)"} className={cx("nre-line-series", seriesClass)} data-series={series || undefined}>
@@ -180,7 +183,7 @@ export function MetricLine({
         {points.map((p, i) => {
           const circle = (
             <circle
-              className={cx("nre-line-point", p.series !== undefined ? seriesClassForKey(p.series) : "nre-series-none")}
+              className={cx("nre-line-point", p.series !== undefined ? seriesClassOf(p.series) : "nre-series-none")}
               data-key={p.key}
               cx={p.px}
               cy={p.py}

package/src/report/{react → components/metric-views}/MetricMatrix.tsx

@@ -5,12 +5,12 @@
 // 是格子里的普通 <a>,不 hydrate 也能点。
 
 import type { ReactElement } from "react";
-import type { MatrixData } from "../types.ts";
-import type { AttemptLocator } from "../../results/locator.ts";
-import { DEFAULT_REPORT_LOCALE, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { MetricCellView } from "./cell.tsx";
-import { colorClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { MatrixData } from "../../model/types.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import { DEFAULT_REPORT_LOCALE, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
+import { MetricCellView } from "../cell.tsx";
+import { colorClassForKey } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 export function MetricMatrix({
   data,

package/src/report/{react → components/metric-views}/MetricScatter.tsx

@@ -3,22 +3,24 @@
 // 「越靠右上越好」且仅当两轴都声明 better 时显示;刻度显示真实值。
 // niceTicks 刻度 + 网格线;每个点直接标注(placePointLabels 候选位择优:避开其它标签、
 // 数据点与画布边界,离开左右紧邻位时补 leader line);
-// 同系列的点按 x 值排序连线,系列图例列在图下。x 或 y 为 null 的点不画,
+// 默认不连线,`connect` 显式开启时同系列的点按 x 升序连折线(lineage series),
+// 系列图例按显示键字典序列在图下。x 或 y 为 null 的点不画,
 // 底部注脚如实报「n 个点缺数据」;hover 信息退化为 SVG <title>,不 hydrate 也在
 // (enhance.js 在场时升级为样式化 tooltip)。配色走类名(nre-series-cN)由 CSS 上色,
-// 深色主题下图表随令牌切换,不留内联 hex。
+// 深色主题下图表随令牌切换,不留内联 hex;同图 series 撞色按图例顺序线性探测消解
+// (colorIndicesForKeys),跨图稳定让位给图内可辨。
 
 import type { ReactElement } from "react";
-import type { MetricColumn, ScatterData } from "../types.ts";
-import { formatMetricValue } from "../format.ts";
-import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
+import type { MetricColumn, ScatterData } from "../../model/types.ts";
+import { formatMetricValue, shortestUniqueLabels } from "../../model/format.ts";
+import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
 import { niceTicks, placePointLabels } from "./chart-math.ts";
-import { colorClassForKey, seriesClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import { colorIndicesForKeys } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
-const WIDTH = 640;
-const HEIGHT = 360;
-const MARGIN = { top: 26, right: 24, bottom: 46, left: 62 };
+const WIDTH = 760;
+const HEIGHT = 400;
+const MARGIN = { top: 28, right: 32, bottom: 48, left: 64 };
 const PLOT_W = WIDTH - MARGIN.left - MARGIN.right;
 const PLOT_H = HEIGHT - MARGIN.top - MARGIN.bottom;
 
@@ -34,42 +36,6 @@ interface DrawablePoint {
   py: number;
 }
 
-/**
- * 点的直接标签:末段在当前 data 中唯一才缩成末段;重名时逐步加长为能区分它们的最短
- * 路径后缀(完整 id 与两轴值仍进 <title>)。
- */
-function pointLabels(keys: readonly string[]): Map<string, string> {
-  const segsOf = (key: string) => key.split("/").filter(Boolean);
-  const depth = new Map<string, number>(keys.map((key) => [key, 1]));
-  for (;;) {
-    const byLabel = new Map<string, string[]>();
-    for (const key of keys) {
-      const segs = segsOf(key);
-      const label = segs.slice(-Math.min(depth.get(key)!, segs.length)).join("/") || key;
-      byLabel.set(label, [...(byLabel.get(label) ?? []), key]);
-    }
-    let grew = false;
-    for (const group of byLabel.values()) {
-      if (group.length < 2) continue;
-      for (const key of group) {
-        const segs = segsOf(key);
-        if (depth.get(key)! < segs.length) {
-          depth.set(key, depth.get(key)! + 1);
-          grew = true;
-        }
-      }
-    }
-    if (!grew) {
-      const out = new Map<string, string>();
-      for (const key of keys) {
-        const segs = segsOf(key);
-        out.set(key, segs.slice(-Math.min(depth.get(key)!, segs.length)).join("/") || key);
-      }
-      return out;
-    }
-  }
-}
-
 /**
  * 一根轴:niceTicks 撑出整齐的值域,值 → 像素做线性映射。轴方向跟随指标的 `better`:
  * `better: "lower"` 的轴反向渲染(值大的一端在左 / 下),「更好」因此恒指向右与上;
@@ -89,11 +55,14 @@ function axisScale(values: number[], pixelLo: number, pixelHi: number, invert: b
 
 export function MetricScatter({
   data,
+  connect = false,
   pointHref,
   className,
   locale = DEFAULT_REPORT_LOCALE,
 }: {
   data: ScatterData;
+  /** series 内按 x 升序连折线;默认 false,只给「线 = 同族变体」的 lineage series 用。 */
+  connect?: boolean;
   pointHref?: (row: ScatterData["rows"][number]) => string;
   className?: string;
   locale?: ReportLocale;
@@ -138,7 +107,7 @@ export function MetricScatter({
     MARGIN.top,
     data.y.better === "lower",
   );
-  const labelByKey = pointLabels(drawableRows.map((r) => r.key));
+  const labelByKey = shortestUniqueLabels(drawableRows.map((r) => r.key));
   // 方向提示恒为「越靠右上越好」,仅当两轴都声明 better 时显示——任一轴未声明,
   // 组件不猜「更好」朝哪边,整图无提示。
   const showBetterHint = data.x.better !== undefined && data.y.better !== undefined;
@@ -159,18 +128,20 @@ export function MetricScatter({
     };
   });
 
-  // 同系列的点按 x 值排序连线;无系列的点只画点不连线
-  const seriesOrder: string[] = [];
+  // 系列分组:图例与配色按显示键字典序;connect 时 series 内按 x 升序连折线
   const bySeries = new Map<string, DrawablePoint[]>();
   for (const p of points) {
     if (p.series === undefined) continue;
-    if (!bySeries.has(p.series)) {
-      bySeries.set(p.series, []);
-      seriesOrder.push(p.series);
-    }
-    bySeries.get(p.series)!.push(p);
+    const list = bySeries.get(p.series) ?? [];
+    list.push(p);
+    bySeries.set(p.series, list);
   }
+  const seriesOrder = [...bySeries.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
   for (const list of bySeries.values()) list.sort((a, b) => a.xValue - b.xValue);
+  // 同图撞色消解:散列格作起点,按图例顺序线性探测空格(colors.ts 的契约注释)
+  const colorIdx = colorIndicesForKeys(seriesOrder);
+  const seriesClassOf = (series: string) => `nre-series-c${colorIdx.get(series) ?? 0}`;
+  const keyClassOf = (series: string) => `nre-c${colorIdx.get(series) ?? 0}`;
 
   // 直接标签的候选位择优布局:锚向、避让方向都由布局按空间决定,画布边界含边距
   const labels = placePointLabels(
@@ -238,20 +209,21 @@ export function MetricScatter({
           {axisLabel(yLabel, data.y)}
         </text>
 
-        {/* 系列连线:类名上色(nre-series-cN),深色主题跟随 */}
-        {seriesOrder.map((series) => {
-          const list = bySeries.get(series)!;
-          if (list.length < 2) return null;
-          return (
-            <polyline
-              key={series}
-              className={cx("nre-scatter-line", seriesClassForKey(series))}
-              data-series={series}
-              points={list.map((p) => `${p.px},${p.py}`).join(" ")}
-              fill="none"
-            />
-          );
-        })}
+        {/* 系列折线:仅 connect 显式开启时画(lineage series 的位移),按 x 升序;类名上色,深色主题跟随 */}
+        {connect &&
+          seriesOrder.map((series) => {
+            const list = bySeries.get(series)!;
+            if (list.length < 2) return null;
+            return (
+              <polyline
+                key={series}
+                className={cx("nre-scatter-line", seriesClassOf(series))}
+                data-series={series}
+                points={list.map((p) => `${p.px},${p.py}`).join(" ")}
+                fill="none"
+              />
+            );
+          })}
 
         {/* 点:g 内带 <title>(无 JS 的原生 hover)、直接标签与 leader line;
             pointHref 时包普通 <a>,静态导出也能下钻 */}
@@ -259,7 +231,7 @@ export function MetricScatter({
           const label = labels[i];
           const group = (
             <g
-              className={cx("nre-scatter-point", p.series !== undefined ? seriesClassForKey(p.series) : "nre-series-none")}
+              className={cx("nre-scatter-point", p.series !== undefined ? seriesClassOf(p.series) : "nre-series-none")}
               data-key={p.key}
             >
               <title>{p.title}</title>
@@ -287,7 +259,7 @@ export function MetricScatter({
       {seriesOrder.length > 0 && (
         <figcaption className="nre-scatter-legend">
           {seriesOrder.map((series) => (
-            <span key={series} className={cx("nre-legend-key", "nre-key", colorClassForKey(series))}>
+            <span key={series} className={cx("nre-legend-key", "nre-key", keyClassOf(series))}>
               {series}
             </span>
           ))}