niceeval 0.6.0 → 0.6.2

package/src/report/react/ExperimentList.tsx

@@ -1,108 +1,226 @@
-// ExperimentList:实体列表的第一级——每项固定代表一个 experiment,主行是身份(experiment id /
-// agent / model / flags)、Eval 判定构成与官方两级聚合汇总指标(passRate/cost/duration/tokens,
-// 复用 MetricCellView 与其它指标图形同一份渲染)。零 JS 用原生 <details> 展开到这个 experiment
-// 的 Eval:每道题一行,判定符 + 该题全部 Attempt 的 locator 徽标(内联,不用再点开一层)+
-// 通过时的平均耗时/成本、失败/出错时的原因摘要。
+// ExperimentList:实体列表的第一级。web 面是一行一个 experiment 的固定列比较表；
+// 每行用原生 <details> 展开到 Eval 与 Attempt locator。数据仍完全来自
+// ExperimentList.data(),不恢复旧 ExperimentTable 的混合实体计算层。
 
 import type { ReactElement } from "react";
-import type { ExperimentListEvalRow, ExperimentListItem } from "../types.ts";
 import type { AttemptLocator } from "../../results/locator.ts";
+import type { AttemptListItem, ExperimentListEvalRow, ExperimentListItem } from "../types.ts";
+import { attemptItemReason, experimentDisplayName } from "../format.ts";
 import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../locale.ts";
-import { MetricCellView } from "./cell.tsx";
 import { AttemptLocatorBadge } from "./AttemptList.tsx";
+import { MetricCellView } from "./cell.tsx";
 import { colorClassForKey } from "./colors.ts";
 import { cx, formatDurationMs, formatUSD, verdictMark } from "./format.ts";
 
-function EvalRow({
-  row,
+const verdictOrder = ["passed", "failed", "errored", "skipped"] as const;
+
+function passRateTone(value: number | null): string | undefined {
+  if (value === null) return undefined;
+  if (value >= 0.8) return "nre-good";
+  if (value >= 0.5) return "nre-warn";
+  return "nre-bad";
+}
+
+function formatDate(value: string, locale: ReportLocale): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.valueOf())) return value;
+  return new Intl.DateTimeFormat(locale === "zh-CN" ? "zh-CN" : "en", {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  }).format(date);
+}
+
+function VerdictSummary({ item, locale }: { item: ExperimentListItem; locale: ReportLocale }): ReactElement {
+  const parts = verdictOrder
+    .filter((verdict) => item.verdicts[verdict] > 0)
+    .map((verdict) => `${item.verdicts[verdict]} ${localeText(locale, `verdict.${verdict}`)}`);
+  return <span className="nre-experiment-pill">{parts.join(" / ") || "—"}</span>;
+}
+
+function ExperimentAttemptRow({
+  attempt,
+  last,
   attemptHref,
 }: {
-  row: ExperimentListEvalRow;
+  attempt: AttemptListItem;
+  last: boolean;
   attemptHref: (locator: AttemptLocator) => string;
 }): ReactElement {
+  const reason = attemptItemReason(attempt);
   return (
-    <li className={cx("nre-experiment-eval-row", `nre-eval-${row.verdict}`)}>
-      <span className={cx("nre-eval-verdict", `nre-verdict-${row.verdict}`)}>{verdictMark(row.verdict)}</span>
-      <span className="nre-eval-id">{row.evalId}</span>
+    <li className={cx("nre-experiment-attempt-row", `nre-eval-${attempt.verdict}`)}>
+      <span className="nre-attempt-branch" aria-hidden="true">{last ? "└─" : "├─"}</span>
       <span className="nre-eval-attempt-badges">
-        {row.attempts.map((attempt) => (
-          <AttemptLocatorBadge key={attempt.locator} item={attempt} attemptHref={attemptHref} />
-        ))}
+        <AttemptLocatorBadge item={attempt} attemptHref={attemptHref} />
       </span>
-      {row.verdict === "passed" ? (
-        <span className="nre-eval-avg">
-          {formatDurationMs(row.duration.value ?? 0)}
-          {row.cost.value !== null && <> · {formatUSD(row.cost.value)}</>}
+      <span className="nre-eval-attempt-metrics">
+        {formatDurationMs(attempt.durationMs)}
+        {attempt.costUSD !== undefined && <> · {formatUSD(attempt.costUSD)}</>}
+      </span>
+      <span className="nre-eval-reason">{reason ?? "—"}</span>
+    </li>
+  );
+}
+
+function EvalAttempts({
+  row,
+  attemptHref,
+  locale,
+}: {
+  row: ExperimentListEvalRow;
+  attemptHref: (locator: AttemptLocator) => string;
+  locale: ReportLocale;
+}): ReactElement {
+  const duration = row.duration.value === null ? localeText(locale, "cell.missing") : formatDurationMs(row.duration.value);
+  const cost = row.cost.value === null ? localeText(locale, "cell.missing") : formatUSD(row.cost.value);
+  return (
+    <li className="nre-experiment-eval">
+      <div className={cx("nre-experiment-eval-header", `nre-eval-${row.verdict}`)}>
+        <span className={cx("nre-eval-verdict", `nre-verdict-${row.verdict}`)}>{verdictMark(row.verdict)}</span>
+        <span className="nre-eval-id">{row.evalId}</span>
+        <span className="nre-eval-attempt-count">{localeText(locale, "overview.attemptsCount", { n: row.attempts.length })}</span>
+        <span className="nre-eval-rollup">
+          {localeText(locale, "entityList.average", { value: duration })}
+          {" · "}
+          {localeText(locale, "entityList.average", { value: cost })}
         </span>
-      ) : (
-        <span className="nre-eval-reason">{row.reason}</span>
-      )}
+      </div>
+      <ul className="nre-experiment-attempts">
+        {row.attempts.map((attempt, index) => (
+          <ExperimentAttemptRow
+            key={attempt.locator}
+            attempt={attempt}
+            last={index === row.attempts.length - 1}
+            attemptHref={attemptHref}
+          />
+        ))}
+      </ul>
     </li>
   );
 }
 
-function ExperimentCard({
+function Flags({ flags, locale }: { flags: Record<string, unknown> | undefined; locale: ReportLocale }): ReactElement | null {
+  if (!flags || Object.keys(flags).length === 0) return null;
+  return (
+    <div className="nre-experiment-flags">
+      <span>{localeText(locale, "experimentList.flags")}</span>
+      {Object.entries(flags).map(([key, value]) => (
+        <b key={key}>{key}={String(value)}</b>
+      ))}
+    </div>
+  );
+}
+
+function ExperimentRow({
   item,
   attemptHref,
   locale,
+  relativeTo,
 }: {
   item: ExperimentListItem;
   attemptHref: (locator: AttemptLocator) => string;
   locale: ReportLocale;
+  relativeTo?: string;
 }): ReactElement {
   return (
-    <li className="nre-experiment-entry">
-      <details className="nre-experiment-details">
-        <summary className="nre-experiment-summary">
-          <span className={cx("nre-experiment-id", "nre-key", colorClassForKey(item.experimentId))}>
-            {item.experimentId}
-          </span>
-          <span className="nre-experiment-agent">{item.agent}</span>
-          {item.model && <span className="nre-experiment-model">{item.model}</span>}
-          <span className="nre-experiment-cell">
-            <MetricCellView cell={item.passRate} attemptHref={attemptHref} locale={locale} />
-          </span>
-          <span className="nre-experiment-cell">
-            <MetricCellView cell={item.cost} attemptHref={attemptHref} locale={locale} />
-          </span>
-          <span className="nre-experiment-cell">
-            <MetricCellView cell={item.duration} attemptHref={attemptHref} locale={locale} />
-          </span>
-          <span className="nre-experiment-meta-sub">
+    <details className="nre-experiment-entry">
+      <summary className="nre-experiment-summary">
+        <span className="nre-experiment-name" data-sort-value={item.experimentId}>
+          <b className={cx("nre-experiment-id", "nre-key", colorClassForKey(item.experimentId))}>
+            {experimentDisplayName(item.experimentId, relativeTo)}
+          </b>
+          <small>
             {localeText(locale, "overview.evalsCount", { n: item.evals })}
             {item.attempts > item.evals ? ` · ${localeText(locale, "overview.attemptsCount", { n: item.attempts })}` : ""}
-            {` · ${localeText(locale, "latestRun", { run: item.lastRunAt })}`}
-          </span>
-        </summary>
+            {` · ${formatDate(item.lastRunAt, locale)}`}
+          </small>
+        </span>
+        <span data-sort-value={item.model ?? ""}>{item.model ?? localeText(locale, "experimentList.defaultModel")}</span>
+        <span data-sort-value={item.agent}>{item.agent}</span>
+        <span className="nre-num" data-sort-value={item.duration.value ?? ""}>
+          <MetricCellView cell={item.duration} locale={locale} />
+        </span>
+        <span className={cx("nre-num", passRateTone(item.passRate.value))} data-sort-value={item.passRate.value ?? ""}>
+          <MetricCellView cell={item.passRate} locale={locale} />
+        </span>
+        <span className="nre-num" data-sort-value={item.tokens.value ?? ""}>
+          <MetricCellView cell={item.tokens} locale={locale} />
+        </span>
+        <span className="nre-num" data-sort-value={item.cost.value ?? ""}>
+          <MetricCellView cell={item.cost} locale={locale} />
+        </span>
+        <span data-sort-value={item.verdicts.passed}><VerdictSummary item={item} locale={locale} /></span>
+      </summary>
+      <div className="nre-experiment-detail">
+        <Flags flags={item.flags} locale={locale} />
         <ul className="nre-experiment-evals">
           {item.evalRows.map((row) => (
-            <EvalRow key={row.evalId} row={row} attemptHref={attemptHref} />
+            <EvalAttempts key={row.evalId} row={row} attemptHref={attemptHref} locale={locale} />
           ))}
         </ul>
-      </details>
-    </li>
+      </div>
+    </details>
   );
 }
 
 export function ExperimentList({
   items,
   attemptHref,
+  filter = false,
   className,
   locale = DEFAULT_REPORT_LOCALE,
+  relativeTo,
 }: {
   items: ExperimentListItem[];
   attemptHref: (locator: AttemptLocator) => string;
+  filter?: boolean;
   className?: string;
   locale?: ReportLocale;
+  relativeTo?: string;
 }): ReactElement {
-  return (
-    <div className={cx("nre", "nre-experiment-list", className)}>
-      {items.length === 0 && <p className="nre-experiment-list-empty">{localeText(locale, "attemptList.empty")}</p>}
-      <ul className="nre-experiments">
-        {items.map((item) => (
-          <ExperimentCard key={item.experimentId} item={item} attemptHref={attemptHref} locale={locale} />
+  const labels = [
+    localeText(locale, "experimentList.experiment"),
+    localeText(locale, "table.model"),
+    localeText(locale, "table.agent"),
+    localeText(locale, "experimentList.avgDuration"),
+    localeText(locale, "experimentList.passRate"),
+    localeText(locale, "experimentList.tokens"),
+    localeText(locale, "experimentList.estimatedCost"),
+    localeText(locale, "experimentList.result"),
+  ];
+  const board = (
+    <div className="nre-experiment-table">
+      <div className="nre-experiment-head">
+        {labels.map((label, index) => (
+          <button
+            type="button"
+            data-nre-experiment-sort={index}
+            className={index === 4 ? "nre-sort-desc" : undefined}
+            key={label}
+          >
+            {label}
+          </button>
         ))}
-      </ul>
+      </div>
+      {items.length === 0 && <p className="nre-experiment-list-empty">{localeText(locale, "attemptList.empty")}</p>}
+      {items.map((item) => (
+        <ExperimentRow key={item.experimentId} item={item} attemptHref={attemptHref} locale={locale} relativeTo={relativeTo} />
+      ))}
+    </div>
+  );
+  return (
+    <div className={cx("nre", "nre-experiment-list", filter && "nre-experiment-table-wrap", className)}>
+      {filter && (
+        <input
+          className="nre-filter"
+          data-nre-experiment-filter=""
+          type="search"
+          placeholder={localeText(locale, "experimentList.filterPlaceholder")}
+        />
+      )}
+      {board}
     </div>
   );
 }

package/src/report/react/MetricScatter.tsx

@@ -1,6 +1,7 @@
 // MetricScatter:质量 × 成本 frontier 的积木,内联 SVG、零图表库、零 hooks。
 // 轴向随 better:"lower" 的轴反向画,「好」的角落恒在右上(成本轴 $20 → $0 就是这么来的);
-// niceTicks 刻度 + 网格线;每个点直接标注(防撞布局,被挤开时补 leader line);
+// niceTicks 刻度 + 网格线;每个点直接标注(placePointLabels 候选位择优:避开其它标签、
+// 数据点与画布边界,离开左右紧邻位时补 leader line);
 // 同系列的点按 x 值排序连线,系列图例列在图下。x 或 y 为 null 的点不画,
 // 底部注脚如实报「n 个点缺数据」;hover 信息退化为 SVG <title>,不 hydrate 也在
 // (enhance.js 在场时升级为样式化 tooltip)。配色走类名(nre-series-cN)由 CSS 上色,
@@ -10,7 +11,7 @@ import type { ReactElement } from "react";
 import type { MetricColumn, ScatterData } from "../types.ts";
 import { formatMetricValue } from "../format.ts";
 import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { layoutLabelOffsets, niceTicks } from "./chart-math.ts";
+import { niceTicks, placePointLabels } from "./chart-math.ts";
 import { colorClassForKey, seriesClassForKey } from "./colors.ts";
 import { cx } from "./format.ts";
 
@@ -88,16 +89,6 @@ export function MetricScatter({
     );
   }
 
-  // 恰好 1 个可画点:成本 × 通过率的对比至少要两个实验,单点不成图 —— 显式说清而不是画个孤点。
-  if (drawableRows.length === 1) {
-    return (
-      <figure className={cx("nre", "nre-metric-scatter", className)}>
-        <p className="nre-scatter-empty">{localeText(locale, "scatter.needTwo", { x: xLabel, y: yLabel })}</p>
-        {missingNote}
-      </figure>
-    );
-  }
-
   const axisLabel = (label: string, col: MetricColumn) => `${label}${col.unit ? `(${col.unit})` : ""}`;
 
   const xScale = axisScale(drawableRows.map((r) => r.x.value as number), data.x.better, MARGIN.left, MARGIN.left + PLOT_W);
@@ -113,7 +104,7 @@ export function MetricScatter({
       label: pointLabel(r.key),
       xValue,
       yValue,
-      // hover 内容:experiment(点键)+ 系列(series,CostPassRateComparison 传的是 agent 维度,
+      // hover 内容:experiment(点键)+ 系列(series,ExperimentComparison 传的是 agent 维度,
       // 有则加一行;无系列的散点没有这行)+ 两轴 display 与 samples/total(docs/feature/reports/library.md「MetricScatter」行为清单)
       title: `${r.key}${r.series !== undefined ? `\n${r.series}` : ""}\n${xLabel}: ${r.x.display}(${r.x.samples}/${r.x.total})\n${yLabel}: ${r.y.display}(${r.y.samples}/${r.y.total})`,
       px: xScale.scale(xValue),
@@ -134,12 +125,11 @@ export function MetricScatter({
   }
   for (const list of bySeries.values()) list.sort((a, b) => a.xValue - b.xValue);
 
-  // 直接标签的防撞布局:靠右的点把标签锚到左侧,重叠的往下推、补 leader line
-  const positions = points.map((p) => {
-    const anchorLeft = p.px >= MARGIN.left + PLOT_W * 0.72;
-    return { cx: p.px, cy: p.py, anchorLeft, width: p.label.length * 6.4 + 10 };
-  });
-  const labelOffsets = layoutLabelOffsets(positions);
+  // 直接标签的候选位择优布局:锚向、避让方向都由布局按空间决定,画布边界含边距
+  const labels = placePointLabels(
+    points.map((p) => ({ cx: p.px, cy: p.py, width: p.label.length * 6.4 + 10 })),
+    { x0: 2, y0: 2, x1: WIDTH - 2, y1: HEIGHT - 2 },
+  );
 
   return (
     <figure className={cx("nre", "nre-metric-scatter", className)}>
@@ -212,20 +202,18 @@ export function MetricScatter({
         {/* 点:g 内带 <title>(无 JS 的原生 hover)、直接标签与 leader line;
             pointHref 时包普通 <a>,静态导出也能下钻 */}
         {points.map((p, i) => {
-          const { anchorLeft } = positions[i];
-          const labelX = p.px + (anchorLeft ? -10 : 10);
-          const labelY = p.py + 4 + labelOffsets[i];
+          const label = labels[i];
           const group = (
             <g
               className={cx("nre-scatter-point", p.series !== undefined ? seriesClassForKey(p.series) : "nre-series-none")}
               data-key={p.key}
             >
               <title>{p.title}</title>
-              {/* 标签被挤开时补一条 leader line,避免脱离原点看不出对应关系 */}
-              {labelOffsets[i] !== 0 && <line className="nre-leader" x1={p.px} y1={p.py} x2={labelX} y2={labelY - 4} />}
+              {/* 标签不在紧邻位时补一条 leader line,避免脱离原点看不出对应关系 */}
+              {label.leader && <line className="nre-leader" x1={p.px} y1={p.py} x2={label.x} y2={label.y - 4} />}
               <circle className="nre-scatter-hit" cx={p.px} cy={p.py} r={12} />
               <circle className="nre-scatter-dot" cx={p.px} cy={p.py} r={4.5} />
-              <text className="nre-scatter-point-label" x={labelX} y={labelY} textAnchor={anchorLeft ? "end" : "start"}>
+              <text className="nre-scatter-point-label" x={label.x} y={label.y} textAnchor={label.anchor}>
                 {p.label}
               </text>
             </g>

package/src/report/react/chart-math.test.ts

@@ -0,0 +1,85 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// 分区「MetricScatter 点标签布局(web 面)」:对 placePointLabels 直接断言标签框与点框的几何关系,不经 HTML。
+
+import { describe, expect, it } from "vitest";
+import { placePointLabels, type LabelBounds, type PlacedPointLabel, type PointLabelInput } from "./chart-math.ts";
+
+const BOUNDS: LabelBounds = { x0: 2, y0: 2, x1: 638, y1: 358 };
+const WIDTH = 90;
+
+interface Box {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+
+// 与契约声明的标签框一致:基线上方 10px、下方 2px,锚向决定水平延伸方向
+function labelBox(l: PlacedPointLabel, width: number): Box {
+  const x0 = l.anchor === "start" ? l.x : l.anchor === "end" ? l.x - width : l.x - width / 2;
+  return { x0, y0: l.y - 10, x1: x0 + width, y1: l.y + 2 };
+}
+
+function dotBox(p: PointLabelInput): Box {
+  return { x0: p.cx - 6, y0: p.cy - 6, x1: p.cx + 6, y1: p.cy + 6 };
+}
+
+function overlaps(a: Box, b: Box): boolean {
+  return a.x0 < b.x1 && a.x1 > b.x0 && a.y0 < b.y1 && a.y1 > b.y0;
+}
+
+describe("placePointLabels", () => {
+  it("近重合点簇:标签框两两不叠、不压任何数据点(只向下推的级联会把第三个标签推到下方点上)", () => {
+    // 三点近重合 + 右下方另一点:down-only 布局把第三个标签推到 y∈[122,134]、x≥310,
+    // 正好压住 (330,128) 的点框;候选位择优必须避开
+    const points: PointLabelInput[] = [
+      { cx: 300, cy: 100, width: WIDTH },
+      { cx: 303, cy: 102, width: WIDTH },
+      { cx: 298, cy: 104, width: WIDTH },
+      { cx: 330, cy: 128, width: WIDTH },
+    ];
+    const labels = placePointLabels(points, BOUNDS);
+    const boxes = labels.map((l) => labelBox(l, WIDTH));
+
+    for (let i = 0; i < boxes.length; i++) {
+      for (let j = i + 1; j < boxes.length; j++) {
+        expect(overlaps(boxes[i], boxes[j]), `标签 ${i} 与标签 ${j} 重叠`).toBe(false);
+      }
+      for (let j = 0; j < points.length; j++) {
+        expect(overlaps(boxes[i], dotBox(points[j])), `标签 ${i} 压住点 ${j}`).toBe(false);
+      }
+    }
+    // 离开左右紧邻位的标签必须带 leader 标记,渲染层据此连回原点
+    for (let i = 0; i < labels.length; i++) {
+      const adjacent =
+        labels[i].y === points[i].cy + 4 &&
+        ((labels[i].anchor === "start" && labels[i].x === points[i].cx + 10) ||
+          (labels[i].anchor === "end" && labels[i].x === points[i].cx - 10));
+      expect(labels[i].leader, `标签 ${i} 的 leader 标记与位置不符`).toBe(!adjacent);
+    }
+  });
+
+  it("无冲突取右侧紧邻位不带 leader;右缘点锚到左侧紧邻位且标签框不越出画布", () => {
+    const sparse = placePointLabels(
+      [
+        { cx: 100, cy: 100, width: WIDTH },
+        { cx: 400, cy: 250, width: WIDTH },
+      ],
+      BOUNDS,
+    );
+    for (const [i, l] of sparse.entries()) {
+      expect(l.anchor).toBe("start");
+      expect(l.x).toBe([100, 400][i] + 10);
+      expect(l.leader).toBe(false);
+    }
+
+    const [edge] = placePointLabels([{ cx: 630, cy: 200, width: WIDTH }], BOUNDS);
+    const box = labelBox(edge, WIDTH);
+    expect(edge.anchor).toBe("end");
+    expect(edge.leader).toBe(false);
+    expect(box.x0).toBeGreaterThanOrEqual(BOUNDS.x0);
+    expect(box.x1).toBeLessThanOrEqual(BOUNDS.x1);
+    expect(box.y0).toBeGreaterThanOrEqual(BOUNDS.y0);
+    expect(box.y1).toBeLessThanOrEqual(BOUNDS.y1);
+  });
+});

package/src/report/react/chart-math.ts

@@ -1,5 +1,4 @@
-// 通用图表数值工具:round-number 刻度生成与标签防撞布局,零依赖纯函数。
-// 从 src/view/app/lib/chart.ts 迁来(view 侧从这里 re-export),报告组件与 view 共用同一份。
+// 通用图表数值工具:round-number 刻度生成与点标签布局,零依赖纯函数。
 
 function niceNumber(range: number, round: boolean): number {
   if (range <= 0) return 1;
@@ -35,34 +34,114 @@ export function niceTicks(min: number, max: number, count = 5): number[] {
   return ticks;
 }
 
-export interface LabelInput {
+export interface PointLabelInput {
   cx: number;
   cy: number;
+  /** 标签文本的估算宽度(px)。 */
   width: number;
-  /** true = 文字锚在点左侧(text-anchor: end),false = 锚在右侧(text-anchor: start)。 */
-  anchorLeft: boolean;
+}
+
+/** 标签允许占用的画布范围(含坐标轴边距,标签可以借用空白边距)。 */
+export interface LabelBounds {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+
+export interface PlacedPointLabel {
+  /** <text> 的锚点坐标(y 为文字基线)。 */
+  x: number;
+  y: number;
+  anchor: "start" | "end" | "middle";
+  /** 标签不在点左右紧邻位:渲染层补 leader line 连回原点。 */
+  leader: boolean;
+}
+
+/** 标签框高度(基线上方 10px、下方 2px,对应 11px 字号)。 */
+const LABEL_ASCENT = 10;
+const LABEL_DESCENT = 2;
+/** 数据点视为边长 2×DOT_R 的方形障碍(点半径 4.5 + 命中余量)。 */
+const DOT_R = 6;
+/** 紧邻位与点的水平间距;候选环按它逐环外扩。 */
+const NEAR = 10;
+const RINGS = [NEAR, NEAR + 12, NEAR + 26];
+
+interface Box {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+
+function labelBoxAt(x: number, y: number, anchor: PlacedPointLabel["anchor"], width: number): Box {
+  const x0 = anchor === "start" ? x : anchor === "end" ? x - width : x - width / 2;
+  return { x0, y0: y - LABEL_ASCENT, x1: x0 + width, y1: y + LABEL_DESCENT };
+}
+
+function overlapArea(a: Box, b: Box): number {
+  const w = Math.min(a.x1, b.x1) - Math.max(a.x0, b.x0);
+  const h = Math.min(a.y1, b.y1) - Math.max(a.y0, b.y0);
+  return w > 0 && h > 0 ? w * h : 0;
+}
+
+function outOfBoundsArea(box: Box, bounds: LabelBounds): number {
+  const total = (box.x1 - box.x0) * (box.y1 - box.y0);
+  const w = Math.min(box.x1, bounds.x1) - Math.max(box.x0, bounds.x0);
+  const h = Math.min(box.y1, bounds.y1) - Math.max(box.y0, bounds.y0);
+  const inside = w > 0 && h > 0 ? w * h : 0;
+  return total - inside;
+}
+
+/** 一个点在距离 d 的候选环:左右紧邻、四个斜角、正上正下。顺序即同代价时的偏好序。 */
+function ringCandidates(p: PointLabelInput, d: number): Omit<PlacedPointLabel, "leader">[] {
+  const diag = d * 0.75;
+  return [
+    { x: p.cx + d, y: p.cy + 4, anchor: "start" },
+    { x: p.cx - d, y: p.cy + 4, anchor: "end" },
+    { x: p.cx + diag, y: p.cy - diag - 2, anchor: "start" },
+    { x: p.cx - diag, y: p.cy - diag - 2, anchor: "end" },
+    { x: p.cx, y: p.cy - d - LABEL_DESCENT - 2, anchor: "middle" },
+    { x: p.cx + diag, y: p.cy + diag + LABEL_ASCENT, anchor: "start" },
+    { x: p.cx - diag, y: p.cy + diag + LABEL_ASCENT, anchor: "end" },
+    { x: p.cx, y: p.cy + d + LABEL_ASCENT + 2, anchor: "middle" },
+  ];
 }
 
 /**
- * 贪心地把互相重叠的直接标签往下推开(按 y 排序、逐个查重叠再下移),点本身位置不变。
- * 散点常见同分不同价的聚簇,这一步避免标签叠成一团糊字。
+ * 散点直接标签的候选位择优布局(docs/feature/reports/library.md「MetricScatter」):
+ * 每个标签在点四周由近及远的候选环上打分——与已放置标签的重叠、与任何数据点的重叠、
+ * 越出画布的面积、离点距离逐项累加,取代价最小的候选。存在无冲突候选时标签必不遮点、
+ * 不叠标签、不越界;全候选冲突时取重叠最小者,绝不丢标签。重合点簇因此向不同方向散开,
+ * 而不是单向堆叠压到下方的数据点上。
  */
-export function layoutLabelOffsets(items: LabelInput[], lineHeight = 14, padX = 4): number[] {
-  const offsets = new Array(items.length).fill(0);
-  const order = [...items.keys()].sort((a, b) => items[a].cy - items[b].cy || items[a].cx - items[b].cx);
-  const placed: { x0: number; x1: number; y: number }[] = [];
+export function placePointLabels(points: PointLabelInput[], bounds: LabelBounds): PlacedPointLabel[] {
+  const dots: Box[] = points.map((p) => ({ x0: p.cx - DOT_R, y0: p.cy - DOT_R, x1: p.cx + DOT_R, y1: p.cy + DOT_R }));
+  const placedBoxes: Box[] = [];
+  const result: PlacedPointLabel[] = new Array(points.length);
+  // 由上到下、由左到右逐个放置,布局确定可复现
+  const order = [...points.keys()].sort((a, b) => points[a].cy - points[b].cy || points[a].cx - points[b].cx);
+
   for (const i of order) {
-    const it = items[i];
-    const x0 = it.anchorLeft ? it.cx - it.width : it.cx;
-    const x1 = it.anchorLeft ? it.cx : it.cx + it.width;
-    let y = it.cy;
-    let guard = 0;
-    while (guard < 40 && placed.some((p) => x0 < p.x1 + padX && x1 > p.x0 - padX && Math.abs(y - p.y) < lineHeight)) {
-      y += lineHeight;
-      guard++;
+    const p = points[i];
+    let best: { candidate: Omit<PlacedPointLabel, "leader">; box: Box; cost: number; leader: boolean } | null = null;
+    for (let ring = 0; ring < RINGS.length; ring++) {
+      const candidates = ringCandidates(p, RINGS[ring]);
+      for (let c = 0; c < candidates.length; c++) {
+        const candidate = candidates[c];
+        const box = labelBoxAt(candidate.x, candidate.y, candidate.anchor, p.width);
+        let cost = 0;
+        for (const placed of placedBoxes) cost += overlapArea(box, placed) * 4;
+        for (const dot of dots) cost += overlapArea(box, dot) * 3;
+        cost += outOfBoundsArea(box, bounds) * 6;
+        cost += ring * 8 + c * 0.5; // 近环、偏好序靠前者优先,只作同冲突程度下的排序
+        if (best === null || cost < best.cost) {
+          best = { candidate, box, cost, leader: !(ring === 0 && c <= 1) };
+        }
+      }
     }
-    placed.push({ x0, x1, y });
-    offsets[i] = y - it.cy;
+    placedBoxes.push(best!.box);
+    result[i] = { ...best!.candidate, leader: best!.leader };
   }
-  return offsets;
+  return result;
 }