niceeval 0.11.4-canary.20 → 0.12.0

package/dist/report/definition/primitives/chart.js

@@ -1,4 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SeriesPatternDefs, seriesClassFromColorVar, seriesClassesFromFill, } from "../../assets/series-encoding.js";
 import { defineComponent } from "../tree.js";
 import { countText, localeText, resolveLocalizedText } from "../../model/locale.js";
 import { formatAxisTick, formatMetricValue, shortestUniqueLabels } from "../../model/format.js";
@@ -91,7 +92,8 @@ function chartFieldLabel(field, meta, locale) {
     const base = dictionary[field] ? localeText(locale, dictionary[field]) : field;
     return meta.unit ? `${base}(${meta.unit})` : base;
 }
-function seriesClass(mapped, series, point, ctx) {
+/** 解析点所属 series 句柄与下标;单系列隐式图不声明视觉身份。 */
+function seriesPresentationOf(mapped, series, point, ctx) {
     let handle;
     let index;
     if (series.byField !== undefined && point.seriesValue !== undefined) {
@@ -101,12 +103,104 @@ function seriesClass(mapped, series, point, ctx) {
     else {
         const ids = mapped.filter((item) => !item.hidden && item.byField === undefined).map((item) => item.id);
         if (ids.length < 2)
-            return "niceeval-series-none";
+            return undefined;
         handle = IMPLICIT_SERIES_HANDLE;
         index = ids.indexOf(series.id);
     }
-    const colorIndex = ctx.dimension(handle).at(index).colorIndex;
-    return colorIndex === undefined ? "niceeval-series-none" : `niceeval-series-c${colorIndex - 1}`;
+    if (index < 0)
+        return undefined;
+    return ctx.dimension(handle).at(index);
+}
+/** SVG 路径:只挂 series-cN 设 --series;pattern 由 fill 属性 / style 承载。 */
+function seriesColorClass(presentation) {
+    if (!presentation)
+        return "niceeval-series-none";
+    if (presentation.kind === "color")
+        return seriesClassFromColorVar(presentation.color);
+    if (presentation.kind !== "series")
+        return "niceeval-series-none";
+    // switch 按 mark 收窄;Fill 的 mark 是 "bar"|"area" 联合,if/|| 在部分 TS 版本下剔不干净。
+    switch (presentation.mark) {
+        case "bar":
+        case "area": {
+            // 只要色类,不要 HTML 专用的 fill-vN(SVG 用 url(#pattern))。
+            const classes = seriesClassesFromFill(presentation.fill).split(" ");
+            return classes.find((c) => c.startsWith("niceeval-series-c") || c === "niceeval-series-none") ?? "niceeval-series-none";
+        }
+        case "line":
+            return seriesClassFromColorVar(presentation.stroke);
+        case "scatter":
+            return seriesClassFromColorVar(presentation.marker.fill);
+    }
+}
+/** HTML 横向柱:色类 + fill-vN 图案类(CSS repeating-linear-gradient 等效 SVG pattern)。 */
+function seriesHtmlBarClass(presentation) {
+    if (!presentation)
+        return "niceeval-series-none";
+    if (presentation.kind === "series" && (presentation.mark === "bar" || presentation.mark === "area")) {
+        return seriesClassesFromFill(presentation.fill);
+    }
+    return seriesColorClass(presentation);
+}
+/**
+ * 作者在 `<Series line>` 上显式声明的 dashed/dotted **优先于** 页级 variant 的 strokeDasharray。
+ * 未声明时消费 LineSeriesPresentation / FillSeriesPresentation 的 strokeDasharray(空串 = 实线)。
+ */
+function resolveStrokeDasharray(series, presentation) {
+    if (series.line !== undefined)
+        return lineDash(series.line);
+    if (presentation?.kind === "series" && "strokeDasharray" in presentation) {
+        return presentation.strokeDasharray || undefined;
+    }
+    return undefined;
+}
+/** SVG 柱/面:pattern fill 必须用 style 压过 `.niceeval-chart-bar { fill: var(--series) }`。 */
+function seriesSvgFillStyle(presentation) {
+    if (presentation?.kind !== "series")
+        return undefined;
+    if (presentation.mark !== "bar" && presentation.mark !== "area")
+        return undefined;
+    if (!presentation.fill.startsWith("url("))
+        return undefined;
+    return { fill: presentation.fill };
+}
+function renderMarkerShape(presentation, px, py, colorClass, title) {
+    const marker = presentation?.kind === "series" && (presentation.mark === "scatter" || presentation.mark === "line")
+        ? presentation.marker
+        : undefined;
+    if (!marker) {
+        return (_jsx("circle", { className: cx("niceeval-chart-dot", colorClass), cx: px, cy: py, r: 4.5, children: title }));
+    }
+    // path 在 0..12 viewBox;缩放到 ~9px 并居中到 (px, py)。
+    return (_jsx("path", { className: cx("niceeval-chart-dot", colorClass), d: marker.path, transform: `translate(${px} ${py}) scale(0.75) translate(-6 -6)`, fill: marker.fill, stroke: "var(--panel)", strokeWidth: 1.6, children: title }));
+}
+function legendSwatch(presentation, mark) {
+    if (!presentation || presentation.kind !== "series") {
+        return _jsx("span", { className: cx("niceeval-chart-legend-swatch", "niceeval-series-none") });
+    }
+    // 图例方块跟 series mark 取义:柱/面用填充图案,线用 dash+marker,散点用 marker 形状。
+    if (mark === "bar" || mark === "area") {
+        const fillClass = presentation.mark === "bar" || presentation.mark === "area"
+            ? seriesClassesFromFill(presentation.fill)
+            : seriesColorClass(presentation);
+        return _jsx("span", { className: cx("niceeval-chart-legend-swatch", fillClass) });
+    }
+    if (mark === "line") {
+        // 线系图例需要 stroke + marker;presentation 可能是 line 或 scatter(by 切分后 mark 对齐)。
+        if (presentation.mark === "line") {
+            return (_jsxs("svg", { className: "niceeval-chart-legend-swatch-svg", width: "16", height: "10", "aria-hidden": "true", children: [_jsx("line", { x1: "0", y1: "5", x2: "16", y2: "5", stroke: presentation.stroke, strokeWidth: 2, strokeDasharray: presentation.strokeDasharray || undefined }), _jsx("path", { d: presentation.marker.path, transform: "translate(8 5) scale(0.55) translate(-6 -6)", fill: presentation.marker.fill })] }));
+        }
+        if (presentation.mark === "scatter") {
+            return (_jsxs("svg", { className: "niceeval-chart-legend-swatch-svg", width: "16", height: "10", "aria-hidden": "true", children: [_jsx("line", { x1: "0", y1: "5", x2: "16", y2: "5", stroke: presentation.marker.fill, strokeWidth: 2 }), _jsx("path", { d: presentation.marker.path, transform: "translate(8 5) scale(0.55) translate(-6 -6)", fill: presentation.marker.fill })] }));
+        }
+        // fill presentation 配 line mark 的退化:只画色块。
+        return _jsx("span", { className: cx("niceeval-chart-legend-swatch", seriesColorClass(presentation)) });
+    }
+    // mark === "scatter"
+    if (presentation.mark === "scatter" || presentation.mark === "line") {
+        return (_jsx("svg", { className: "niceeval-chart-legend-swatch-svg", width: "10", height: "10", "aria-hidden": "true", children: _jsx("path", { d: presentation.marker.path, transform: "translate(5 5) scale(0.7) translate(-6 -6)", fill: presentation.marker.fill }) }));
+    }
+    return _jsx("span", { className: cx("niceeval-chart-legend-swatch", seriesColorClass(presentation)) });
 }
 function metricDisplay(point, axis, meta, locale) {
     if (meta.kind === "dimension") {
@@ -129,10 +223,7 @@ function renderLegend(mapped, visible, locale, ctx) {
                     : implicitIds.indexOf(series.id);
                 const presentation = handle ? ctx.dimension(handle).at(index) : undefined;
                 const label = presentation?.label ?? (series.label ? resolveLocalizedText(series.label, locale) : series.id);
-                const colorClass = presentation?.colorIndex === undefined
-                    ? "niceeval-series-none"
-                    : `niceeval-series-c${presentation.colorIndex - 1}`;
-                return (_jsx("li", { className: cx("niceeval-chart-legend-item", colorClass), children: label }, `${series.id}:${value}`));
+                return (_jsxs("li", { className: "niceeval-chart-legend-item", children: [legendSwatch(presentation, series.mark), label] }, `${series.id}:${value}`));
             });
         }) }));
 }
@@ -142,12 +233,13 @@ function renderHorizontalBarsWeb(mapped, visible, axes, locale, ctx, options) {
     const values = entries.map(({ point }) => point.y);
     const boundMax = axes.yMeta.kind === "metric" ? axes.yMeta.bounds?.max : undefined;
     const max = boundMax !== undefined && boundMax > 0 ? boundMax : Math.max(0, ...values);
-    return (_jsxs("figure", { className: cx("niceeval-report", "niceeval-chart", "niceeval-chart--bars-horizontal", options.className), children: [_jsx("div", { className: "niceeval-chart-bars-heading", children: chartFieldLabel(axes.yField, axes.yMeta, locale) }), _jsx("ol", { className: "niceeval-chart-bars", children: entries.map(({ series, point }) => {
+    return (_jsxs("figure", { className: cx("niceeval-report", "niceeval-chart", "niceeval-chart--bars-horizontal", options.className), children: [_jsx(SeriesPatternDefs, {}), _jsx("div", { className: "niceeval-chart-bars-heading", children: chartFieldLabel(axes.yField, axes.yMeta, locale) }), _jsx("ol", { className: "niceeval-chart-bars", children: entries.map(({ series, point }) => {
                     const rawLabel = point.xLabel ?? point.pointLabel;
                     const label = labels.get(rawLabel) ?? rawLabel;
                     const display = metricDisplay(point, "y", axes.yMeta, locale);
                     const href = pointHref(point, ctx, options.pointTarget);
-                    const colorClass = seriesClass(mapped, series, point, ctx);
+                    const presentation = seriesPresentationOf(mapped, series, point, ctx);
+                    const colorClass = seriesHtmlBarClass(presentation);
                     const ratio = max > 0 ? Math.max(0, Math.min(1, point.y / max)) : 0;
                     const value = (_jsxs("span", { className: "niceeval-chart-bar-value", children: [display, point.yCell && point.yCell.samples < point.yCell.total ? (_jsxs("sup", { children: [point.yCell.samples, "/", point.yCell.total] })) : null] }));
                     return (_jsxs("li", { className: "niceeval-chart-bar-row", children: [_jsx("span", { className: "niceeval-chart-bar-label", title: rawLabel, children: label }), _jsx("span", { className: "niceeval-chart-bar-track", children: _jsx("span", { className: cx("niceeval-chart-bar-fill", colorClass), style: { width: `${ratio * 100}%` }, title: `${rawLabel}\n${axes.yField}: ${display}` }) }), href ? _jsx("a", { className: "niceeval-locator", href: href, children: value }) : value] }, `${series.id}:${point.key}`));
@@ -203,16 +295,20 @@ function renderChartWeb(mapped, axes, locale, ctx, options) {
     const labelByKey = shortestUniqueLabels(allPoints.map((p) => p.pointLabel));
     const xLabel = chartFieldLabel(axes.xField, axes.xMeta, locale);
     const yLabel = chartFieldLabel(axes.yField, axes.yMeta, locale);
-    const drawable = visible.flatMap((series) => series.points.map((point) => ({
-        ...point,
-        sourceSeriesId: series.id,
-        label: labelByKey.get(point.pointLabel) ?? point.pointLabel,
-        px: xScale.scale(point.x),
-        py: yScale.scale(point.y),
-        seriesClass: seriesClass(mapped, series, point, ctx),
-    })));
+    const drawable = visible.flatMap((series) => series.points.map((point) => {
+        const presentation = seriesPresentationOf(mapped, series, point, ctx);
+        return {
+            ...point,
+            sourceSeriesId: series.id,
+            label: labelByKey.get(point.pointLabel) ?? point.pointLabel,
+            px: xScale.scale(point.x),
+            py: yScale.scale(point.y),
+            presentation,
+            seriesClass: seriesColorClass(presentation),
+        };
+    }));
     const labels = placePointLabels(drawable.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 (_jsxs("figure", { className: cx("niceeval-report", "niceeval-chart", "niceeval-chart--scatter", options.className), children: [_jsxs("svg", { className: "niceeval-chart-svg", viewBox: `0 0 ${WIDTH} ${HEIGHT}`, role: "img", "aria-label": `${axes.xField} × ${axes.yField}`, children: [options.grid !== false ? (_jsxs("g", { className: "niceeval-chart-grid", children: [yScale.ticks.map((tick) => (_jsx("line", { x1: MARGIN.left, x2: MARGIN.left + PLOT_W, y1: yScale.scale(tick), y2: yScale.scale(tick) }, `gy${tick}`))), xScale.ticks.map((tick) => (_jsx("line", { y1: MARGIN.top, y2: MARGIN.top + PLOT_H, x1: xScale.scale(tick), x2: xScale.scale(tick) }, `gx${tick}`)))] })) : null, _jsx("g", { className: "niceeval-chart-axis niceeval-chart-axis-y", children: (axes.yMeta.kind === "dimension"
+    return (_jsxs("figure", { className: cx("niceeval-report", "niceeval-chart", "niceeval-chart--scatter", options.className), children: [_jsx(SeriesPatternDefs, {}), _jsxs("svg", { className: "niceeval-chart-svg", viewBox: `0 0 ${WIDTH} ${HEIGHT}`, role: "img", "aria-label": `${axes.xField} × ${axes.yField}`, children: [options.grid !== false ? (_jsxs("g", { className: "niceeval-chart-grid", children: [yScale.ticks.map((tick) => (_jsx("line", { x1: MARGIN.left, x2: MARGIN.left + PLOT_W, y1: yScale.scale(tick), y2: yScale.scale(tick) }, `gy${tick}`))), xScale.ticks.map((tick) => (_jsx("line", { y1: MARGIN.top, y2: MARGIN.top + PLOT_H, x1: xScale.scale(tick), x2: xScale.scale(tick) }, `gx${tick}`)))] })) : null, _jsx("g", { className: "niceeval-chart-axis niceeval-chart-axis-y", children: (axes.yMeta.kind === "dimension"
                             ? [...new Set(drawable.map((point) => point.y))]
                             : yScale.ticks).map((tick) => (_jsx("text", { className: "niceeval-chart-tick", x: MARGIN.left - 8, y: yScale.scale(tick) + 3, textAnchor: "end", children: axes.yMeta.kind === "dimension"
                                 ? drawable.find((point) => point.y === tick)?.yLabel
@@ -226,7 +322,8 @@ function renderChartWeb(mapped, axes, locale, ctx, options) {
                             const seriesPoints = drawable.filter((p) => p.sourceSeriesId === series.id &&
                                 (series.byField === undefined || p.seriesValue === value));
                             const ordered = series.connect ? [...seriesPoints].sort((a, b) => a.x - b.x) : seriesPoints;
-                            const seriesClass = ordered[0]?.seriesClass ?? "niceeval-series-none";
+                            const seriesClassName = ordered[0]?.seriesClass ?? "niceeval-series-none";
+                            const seriesPresentation = ordered[0]?.presentation;
                             const baseline = yScale.scale(0);
                             const barGroups = [...new Set(visible
                                     .filter((item) => item.mark === "bar")
@@ -235,11 +332,13 @@ function renderChartWeb(mapped, axes, locale, ctx, options) {
                             const groupIndex = Math.max(0, barGroups.indexOf(barGroup));
                             const totalBarWidth = Math.max(8, Math.min(48, PLOT_W / Math.max(1, allPoints.length)));
                             const barWidth = totalBarWidth / Math.max(1, barGroups.length);
-                            return (_jsxs("g", { className: cx("niceeval-chart-series", seriesClass), "data-series": `${series.id}:${value}`, children: [series.mark === "area" && ordered.length > 1 ? (_jsx("polygon", { className: "niceeval-chart-area", points: [
+                            const dash = resolveStrokeDasharray(series, seriesPresentation);
+                            const areaFillStyle = seriesSvgFillStyle(seriesPresentation);
+                            return (_jsxs("g", { className: cx("niceeval-chart-series", seriesClassName), "data-series": `${series.id}:${value}`, children: [series.mark === "area" && ordered.length > 1 ? (_jsx("polygon", { className: "niceeval-chart-area", style: areaFillStyle, points: [
                                             `${ordered[0].px},${baseline}`,
                                             ...ordered.map((point) => `${point.px},${point.py}`),
                                             `${ordered[ordered.length - 1].px},${baseline}`,
-                                        ].join(" ") })) : null, (series.mark === "line" || series.mark === "area" || series.connect) && ordered.length > 1 ? (_jsx("polyline", { className: "niceeval-chart-line", points: ordered.map((p) => `${p.px},${p.py}`).join(" "), strokeDasharray: lineDash(series.line) })) : null, ordered.map((p) => {
+                                        ].join(" ") })) : null, (series.mark === "line" || series.mark === "area" || series.connect) && ordered.length > 1 ? (_jsx("polyline", { className: "niceeval-chart-line", points: ordered.map((p) => `${p.px},${p.py}`).join(" "), strokeDasharray: dash })) : null, ordered.map((p) => {
                                         const placed = labels[drawable.indexOf(p)];
                                         const href = pointHref(p, ctx, options.pointTarget);
                                         let shape;
@@ -247,10 +346,10 @@ function renderChartWeb(mapped, axes, locale, ctx, options) {
                                             const baseValue = stackedBarBase(visible, series, p.x);
                                             const baseY = yScale.scale(baseValue);
                                             const topY = yScale.scale(baseValue + p.y);
-                                            shape = (_jsx("rect", { className: cx("niceeval-chart-bar", p.seriesClass), x: p.px - totalBarWidth / 2 + groupIndex * barWidth, y: Math.min(topY, baseY), width: barWidth, height: Math.max(1, Math.abs(baseY - topY)), children: _jsx("title", { children: `${p.pointLabel}\n${series.id}: ${metricDisplay(p, "y", axes.yMeta, locale)}` }) }));
+                                            shape = (_jsx("rect", { className: cx("niceeval-chart-bar", p.seriesClass), style: seriesSvgFillStyle(p.presentation), x: p.px - totalBarWidth / 2 + groupIndex * barWidth, y: Math.min(topY, baseY), width: barWidth, height: Math.max(1, Math.abs(baseY - topY)), children: _jsx("title", { children: `${p.pointLabel}\n${series.id}: ${metricDisplay(p, "y", axes.yMeta, locale)}` }) }));
                                         }
                                         else {
-                                            shape = (_jsx("circle", { className: cx("niceeval-chart-dot", p.seriesClass), cx: p.px, cy: p.py, r: 4.5, children: _jsx("title", { children: `${p.pointLabel}\n${axes.xField}: ${metricDisplay(p, "x", axes.xMeta, locale)}\n${axes.yField}: ${metricDisplay(p, "y", axes.yMeta, locale)}` }) }));
+                                            shape = renderMarkerShape(p.presentation, p.px, p.py, p.seriesClass, _jsx("title", { children: `${p.pointLabel}\n${axes.xField}: ${metricDisplay(p, "x", axes.xMeta, locale)}\n${axes.yField}: ${metricDisplay(p, "y", axes.yMeta, locale)}` }));
                                         }
                                         return (_jsxs("g", { className: "niceeval-chart-point", children: [href ? _jsx("a", { href: href, children: shape }) : shape, series.mark === "scatter" && placed ? (_jsx("text", { className: "niceeval-chart-point-label", x: placed.x, y: placed.y, textAnchor: placed.anchor, children: p.label })) : null] }, p.key));
                                     })] }, `${series.id}:${value}`));
@@ -480,7 +579,8 @@ export const Chart = defineComponent({
                 continue;
             decls[spec.by] = {
                 dimension: spec.by,
-                encoding: { kind: "series", mark: spec.mark === "area" ? "line" : spec.mark },
+                // area 是 FillSeriesPresentation(填充图案),不再折叠成 line。
+                encoding: { kind: "series", mark: spec.mark },
                 values,
             };
         }

package/dist/report/definition/primitives/conversation.d.ts

@@ -22,7 +22,7 @@ export interface CommandEvidenceItem {
     phase: string;
     display: string;
     exitCode: number;
-    classification: "observed" | "failed";
+    classification: "succeeded" | "observed" | "failed";
     durationMs?: number;
     stdout?: string;
     stderr?: string;

package/dist/report/definition/primitives/conversation.js

@@ -110,7 +110,9 @@ function TurnCard({ turn, locale }) {
     return (_jsxs("article", { className: cx("niceeval-conversation-turn", turn.verdict && `niceeval-conversation-turn--${turn.verdict}`), children: [_jsxs("header", { className: "niceeval-conversation-turn-head", children: [_jsx("span", { className: "niceeval-conversation-turn-label", children: resolveLocalizedText(turn.label, locale) }), turn.verdict ? _jsx("span", { className: "niceeval-conversation-turn-verdict", children: turn.verdict }) : null] }), _jsx(ConversationEntries, { entries: turn.entries, locale: locale })] }));
 }
 function commandEvidenceTitle(command) {
-    const title = command.classification === "failed" ? "FAILED COMMAND" : "NON-ZERO COMMAND · observed";
+    const title = command.classification === "succeeded" ? "COMMAND"
+        : command.classification === "failed" ? "FAILED COMMAND"
+            : "NON-ZERO COMMAND · observed";
     return `${title} · ${command.phase} · exit ${command.exitCode}${command.durationMs === undefined ? "" : ` · ${command.durationMs}ms`}`;
 }
 function CommandEvidenceCard({ command }) {
@@ -147,8 +149,8 @@ function assertCommandEvidenceContent(data) {
             throw dataShapeError("CommandEvidence", "commandEvidenceData", "CommandEvidenceContent", `"data.commands[${index}].display" must be a string`);
         if (typeof command.exitCode !== "number")
             throw dataShapeError("CommandEvidence", "commandEvidenceData", "CommandEvidenceContent", `"data.commands[${index}].exitCode" must be a number`);
-        if (command.classification !== "observed" && command.classification !== "failed") {
-            throw dataShapeError("CommandEvidence", "commandEvidenceData", "CommandEvidenceContent", `"data.commands[${index}].classification" must be observed | failed`);
+        if (command.classification !== "succeeded" && command.classification !== "observed" && command.classification !== "failed") {
+            throw dataShapeError("CommandEvidence", "commandEvidenceData", "CommandEvidenceContent", `"data.commands[${index}].classification" must be succeeded | observed | failed`);
         }
         if (command.durationMs !== undefined && typeof command.durationMs !== "number")
             throw dataShapeError("CommandEvidence", "commandEvidenceData", "CommandEvidenceContent", `"data.commands[${index}].durationMs" must be a number`);

package/dist/report/definition/primitives.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { COMPONENT_RAW_CHILDREN, COMPONENT_ROLE, defineComponent, } from "./tree.js";
 import { hrefForLocator } from "../components/shared.js";
 import { localeText, resolveLocalizedText } from "../model/locale.js";
@@ -10,7 +10,7 @@ import { datasetToTableContent, isDataset } from "../model/dataset.js";
 import { isMetricValue } from "../model/calculation.js";
 import { flattenTableContentForText, formatCellText, } from "./cell.js";
 import { MetricCellView } from "../components/cell.js";
-import { verdictMark } from "../model/format.js";
+import { formatTimeDistance, missingText, verdictMark } from "../model/format.js";
 function childArray(children) {
     if (children === null || children === undefined || typeof children === "boolean")
         return [];
@@ -548,18 +548,34 @@ function renderCellWeb(cell, ctx) {
     switch (cell.kind) {
         case "notApplicable":
             return _jsx("span", { className: "niceeval-missing", children: MISSING_MARK });
-        case "missing":
-            return _jsx("span", { className: "niceeval-missing", children: formatCellText(cell, ctx.locale) });
+        case "missing": {
+            const reference = cell.reference;
+            let body;
+            if (reference) {
+                const mark = (_jsx("span", { className: "niceeval-locator-mark", "aria-hidden": "true", children: verdictMark(reference.verdict === "skipped" ? "skipped" : reference.verdict) }));
+                const distance = _jsx("span", { className: "niceeval-stale-distance", children: formatTimeDistance(reference.staleSinceMs, ctx.locale) });
+                const title = localeText(ctx.locale, "experimentList.staleReferenceTooltip");
+                const href = ctx.href(reference.locator);
+                body = href !== undefined ? (_jsxs("a", { className: "niceeval-locator niceeval-stale", href: href, title: title, children: [mark, reference.locator, distance] })) : (_jsxs("span", { className: "niceeval-locator niceeval-stale", title: title, children: [mark, reference.locator, distance] }));
+            }
+            else {
+                body = _jsx("span", { className: "niceeval-missing-reason", children: missingText(cell.code, ctx.locale) });
+            }
+            return (_jsxs("span", { className: "niceeval-missing", children: [body, cell.detail ? _jsx("small", { className: "niceeval-cell-detail", children: cell.detail }) : null] }));
+        }
         case "text":
             return (_jsxs("span", { className: "niceeval-cell-text", children: [_jsx("span", { children: cell.text }), cell.detail ? _jsx("small", { className: "niceeval-cell-detail", children: cell.detail }) : null] }));
         case "locator": {
             // 判定长在 locator 上:判定符与语义色同场,不靠颜色单独表意
             // (docs/feature/reports/components/summaries/experiment-table.md)。
             const verdict = cell.verdict;
-            const className = verdict === undefined ? "niceeval-locator" : `niceeval-locator niceeval-verdict-${verdict}`;
+            const stale = cell.staleSinceMs !== undefined;
+            const className = cx("niceeval-locator", verdict !== undefined ? `niceeval-verdict-${verdict}` : undefined, stale ? "niceeval-stale" : undefined);
             const mark = verdict === undefined ? null : (_jsx("span", { className: "niceeval-locator-mark", "aria-hidden": "true", children: verdictMark(verdict === "skipped" ? "skipped" : verdict) }));
+            const distance = stale ? (_jsx("span", { className: "niceeval-stale-distance", children: formatTimeDistance(cell.staleSinceMs, ctx.locale) })) : null;
+            const title = stale ? localeText(ctx.locale, "experimentList.historicalTooltip") : undefined;
             const href = ctx.href(cell.locator);
-            return href !== undefined ? (_jsxs("a", { className: className, href: href, children: [mark, cell.locator] })) : (_jsx("span", { className: className, children: formatCellText(cell, ctx.locale) }));
+            return href !== undefined ? (_jsxs("a", { className: className, href: href, title: title, children: [mark, cell.locator, distance] })) : (_jsxs("span", { className: className, title: title, children: [mark, cell.locator, distance] }));
         }
         case "summary":
         case "score":
@@ -570,11 +586,20 @@ function renderCellWeb(cell, ctx) {
                 return (_jsxs("span", { className: "niceeval-verdict-tally", children: [parts.map((kind) => (_jsxs("span", { className: `niceeval-verdict-${kind}`, children: [cell.counts[kind], " ", localeText(ctx.locale, `verdict.${kind === "skipped" ? "skipped" : kind}`)] }, kind))), parts.length === 0 ? _jsx("span", { className: "niceeval-missing", children: MISSING_MARK }) : null] }));
             }
             const verdict = cell.verdict ?? "skipped";
+            const stale = cell.staleSinceMs !== undefined;
             // 判定符走 verdictMark 单源,与 locator 格同一张表(errored 是 `!`,不并到 `✗`)。
-            return (_jsxs("span", { className: `niceeval-verdict niceeval-verdict-${verdict}`, children: [verdictMark(verdict === "skipped" ? "skipped" : verdict), " ", localeText(ctx.locale, `verdict.${verdict === "skipped" ? "skipped" : verdict}`)] }));
+            return (_jsxs("span", { className: cx("niceeval-verdict", `niceeval-verdict-${verdict}`, stale ? "niceeval-stale" : undefined), title: stale ? localeText(ctx.locale, "experimentList.historicalTooltip") : undefined, children: [verdictMark(verdict === "skipped" ? "skipped" : verdict), !cell.bare ? _jsxs(_Fragment, { children: [" ", localeText(ctx.locale, `verdict.${verdict === "skipped" ? "skipped" : verdict}`)] }) : null, stale ? _jsx("span", { className: "niceeval-stale-distance", children: formatTimeDistance(cell.staleSinceMs, ctx.locale) }) : null] }));
         }
         case "metric":
             return (_jsx(MetricCellView, { cell: cell.metric, href: ctx.showMeasureRefs === false ? undefined : ctx.href, locale: ctx.locale }));
+        case "composition": {
+            // web 面画成一条分段条,hover 一段给出它的名字与计数;段的业务含义住在投影里,
+            // 这里只按声明序给一条位置驱动的渐隐色阶(docs/feature/reports/components/primitives/table.md「构成格」)。
+            const total = cell.segments.reduce((sum, segment) => sum + segment.count, 0);
+            if (total === 0)
+                return _jsx("span", { className: "niceeval-missing", children: MISSING_MARK });
+            return (_jsx("span", { className: "niceeval-composition", children: cell.segments.map((segment, i) => segment.count > 0 ? (_jsx("span", { className: "niceeval-composition-segment", style: { width: `${(segment.count / total) * 100}%`, "--composition-step": i }, title: `${resolveLocalizedText(segment.label, ctx.locale)}: ${segment.count}` }, i)) : null) }));
+        }
         default: {
             const _e = cell;
             return _e;

package/dist/report/definition/tree.d.ts

@@ -92,8 +92,9 @@ export interface WebContext {
     /** chrome 文案的 locale;官方组件渲染面经上下文读取,宿主外默认 "en"。 */
     locale: ReportLocale;
     /**
-     * 取本组件 `dimensions()` 声明的某个句柄在这一页的呈现面(含 `seriesSlot` / 色板下标 /
-     * 形状变体)。查别的组件的句柄或没声明的句柄抛 `UndeclaredDimensionValueError`。
+     * 取本组件 `dimensions()` 声明的某个句柄在这一页的呈现面(label / color / series 的
+     * fill·stroke·marker 等可直接使用的值)。查别的组件的句柄或没声明的句柄抛
+     * `UndeclaredDimensionValueError`。
      */
     dimension(handle: string): PresentedDimension;
 }
@@ -152,6 +153,8 @@ export type ReportComponent<P extends object> = ((props: P) => ReactNode) & {
  */
 export interface PageDimensions {
     dimension(props: object, handle: string): PresentedDimension;
+    /** 维度 name → 值 → seriesSlot；测试与调试观察槽位分配，组件渲染不读槽号。 */
+    readonly slotsByDimension: ReadonlyMap<string, ReadonlyMap<string, number>>;
 }
 /** 宿主渲染前把这一页的分配结果挂到渲染上下文上(text 与 web 同一条通道)。 */
 export declare function withPageDimensions<C extends object>(ctx: C, plan: PageDimensions | undefined): C;

package/dist/report/definition/tree.js

@@ -142,6 +142,7 @@ export function collectPageDimensions(node, pins = {}, face = "web") {
     visit(node);
     const plan = allocatePageDimensions(handles, pins, { face });
     return {
+        slotsByDimension: plan.slotsByDimension,
         dimension(props, handle) {
             const entry = byProps.get(props);
             const key = entry?.keys.get(handle);

package/dist/report/index.d.ts

@@ -1,8 +1,8 @@
 export { aggregate, agent, costUSD, dedupeLocators, durationMs, evalId, evidenceRow, experiment, isCalculation, isMetricValue, max, mean, metricValue, min, model, parseEvidenceRow, parseEvidenceRows, passRate, percentile, rollup, sum, tokens, totalScore, } from "./model/calculation.ts";
 export type { AggregateRow, AggregationSubject, Calculation, EvidenceRow, GroupFunction, MetricBasis, MetricFormat, MetricValue, Reducer, RollupOptions, } from "./model/calculation.ts";
-export { toAttemptAssertions, toAttemptFixPrompt, toAttemptListRows, toAttemptNotices, toAttemptRows, toAttemptSource, toAttemptSummary, toAttemptUsage, toConversationTurns, toDiffFiles, toEvalRows, toExperimentDetails, toExperimentRows, toHeroData, toRunNotices, toSampleFixPrompt, toSampleNotices, toSummaryItems, toTimelineNodes, toTraceNodes, } from "./model/conversions.ts";
+export { toAttemptAssertions, toAttemptFacts, toAttemptFixPrompt, toAttemptListRows, toAttemptNotices, toAttemptRows, toAttemptSource, toAttemptSummary, toAttemptUsage, toConversationTurns, toDiffFiles, toEvalRows, toExperimentDetails, toExperimentRows, toHeroData, toRunNotices, toSampleFixPrompt, toSampleNotices, toSummaryItems, toTimelineNodes, toTraceNodes, } from "./model/conversions.ts";
 export { presentDimension, shortestUniqueLabels } from "./presentation.ts";
-export type { DimensionDeclaration, DimensionEncoding, PresentedDimension } from "./presentation.ts";
+export type { ColorPresentation, DimensionDeclaration, DimensionEncoding, DimensionPresentation, FillSeriesPresentation, LabelPresentation, LineSeriesPresentation, PresentedDimension, ScatterSeriesPresentation, } from "./presentation.ts";
 export { flag, label, numericFlag, numericLabel, numericRunConfig, runConfig } from "./model/flag.ts";
 export { evaluationKindComposition } from "./model/evaluation-kind.ts";
 export { annotatedSourceResult, attemptDetailsResult, comparisonResult, conversationResult, diffResult, historyResult, stabilityResult, standardOverviewResult, timingResult, usageResult, } from "./tasks.ts";
@@ -22,7 +22,7 @@ export { Area, Bars, Callouts, Chart, Col, CommandEvidence, Conversation, CopyBl
 export type { AreaProps, BarsProps, BarsSort, EvidenceAxisKey, EvidenceDimensionKey, CalloutGroup, CalloutItem, CalloutLevel, CalloutsProps, ChartPresentation, ChartProps, ChartAxisBinding, ChartFieldBinding, ChartSeriesOverride, ColProps, ConversationContent, ConversationEntry, ConversationProps, ConversationTurn, CopyBlockContent, CopyBlockProps, DiffChange, DiffContent, DiffFile, DiffFileWindow, DiffViewProps, ExternalAreaProps, ExternalAxisKey, ExternalBarsProps, ExternalLineProps, ExternalScatterProps, CommandEvidenceContent, CommandEvidenceItem, CommandEvidenceProps, GridProps, LayoutProps, LineProps, MarkdownProps, PlainTableColumn, RowProps, ScatterProps, SectionProps, SeriesProps, SourceBlockContent, SourceCallContent, SourceContent, SourceLine, SourceViewProps, StatProps, StatTone, StyleProps, TabProps, TableProps, TabsProps, TextProps, WaterfallContent, WaterfallNode, WaterfallProps, WaterfallRow, } from "./definition/primitives.tsx";
 export type { Cell, VerdictCounts } from "./definition/cell.ts";
 export { formatCellText } from "./definition/cell.ts";
-export { formatAxisTick, formatInstant, formatMetricValue, missingText } from "./model/format.ts";
+export { formatAxisTick, formatInstant, formatMetricValue, formatTimeDistance, missingText } from "./model/format.ts";
 export { stringWidth, padDisplay as padEnd, padStartDisplay as padStart, wrapDisplay as wrapText, indentBlock as indent, textBar as bar, joinColumns as columns, } from "./model/text-layout.ts";
 export type { ColumnAlign } from "./model/text-layout.ts";
 export { DEFAULT_REPORT_LOCALE, localizedTextEquals, resolveLocalizedText, resolveMetricLabel, } from "./model/locale.ts";
@@ -38,6 +38,6 @@ export { AttemptAssessment, AttemptDetails, AttemptSummary, } from "./components
 export type { AttemptDetailsProps } from "./components/attempt-detail/index.tsx";
 export { ExperimentDetails } from "./components/experiment-detail/index.tsx";
 export type { ExperimentDetailsProps } from "./components/experiment-detail/index.tsx";
-export type { Aggregator, AttemptListItem, AttemptLocator, BuiltInDimension, CopyFixPromptData, CustomDimension, DeltaCell, DeltaData, DimensionInput, DimensionOptions, DimensionRef, EvalListItem, ExperimentDetailsData, ExperimentListEvalRow, ExperimentListItem, FlagConditions, HeroData, NumericAxis, NumericAxisOptions, NumericRunConfigAxisOptions, ReportInput, RunConfigKey, SampleSummaryContent, SampleIssue, EvaluationKindComposition, SeriesInput, SnapshotDiagnosticsData, SnapshotDiagnosticsItem, TraceSpanSummary, TraceWaterfallRow, VerdictTally, } from "./model/types.ts";
-export type { AttemptAssertionsData, AttemptConversationData, AttemptConversationReply, AttemptConversationRound, AttemptDiagnosticsData, AttemptDiffData, AttemptErrorData, AttemptFixPromptData, AttemptSummaryData, AttemptTimelineData, AttemptTraceData, UsageTableData, } from "./model/types.ts";
+export type { Aggregator, AttemptListItem, AttemptLocator, BuiltInDimension, CopyFixPromptData, CustomDimension, DeltaCell, DeltaData, DimensionInput, DimensionOptions, DimensionRef, EvalListItem, ExperimentDetailsData, ExperimentListEvalRow, ExperimentListItem, FlagConditions, HeroData, NumericAxis, NumericAxisOptions, NumericRunConfigAxisOptions, ReportInput, RunConfigKey, SampleSummaryContent, SampleIssue, EvaluationKindComposition, SeriesInput, SnapshotDiagnosticsData, SnapshotDiagnosticsItem, StaleConclusionReference, TraceSpanSummary, TraceWaterfallRow, VerdictTally, } from "./model/types.ts";
+export type { AttemptAssertionsData, AttemptConversationData, AttemptConversationReply, AttemptConversationRound, AttemptDiagnosticsData, AttemptDiffData, AttemptErrorData, AttemptFactsData, AttemptFixPromptData, AttemptSummaryData, AttemptTimelineData, AttemptTraceData, UsageTableData, } from "./model/types.ts";
 export type { AttemptHandle, Record, Sample, Run } from "../record/types.ts";

package/dist/report/index.js

@@ -8,7 +8,7 @@
 // 官方 Calculation（普通值作者模型）；内部切片仍可用 AttemptMetric 字面量，不导出 defineMeasure。
 // 普通值计算内核
 export { aggregate, agent, costUSD, dedupeLocators, durationMs, evalId, evidenceRow, experiment, isCalculation, isMetricValue, max, mean, metricValue, min, model, parseEvidenceRow, parseEvidenceRows, passRate, percentile, rollup, sum, tokens, totalScore, } from "./model/calculation.js";
-export { toAttemptAssertions, toAttemptFixPrompt, toAttemptListRows, toAttemptNotices, toAttemptRows, toAttemptSource, toAttemptSummary, toAttemptUsage, toConversationTurns, toDiffFiles, toEvalRows, toExperimentDetails, toExperimentRows, toHeroData, toRunNotices, toSampleFixPrompt, toSampleNotices, toSummaryItems, toTimelineNodes, toTraceNodes, } from "./model/conversions.js";
+export { toAttemptAssertions, toAttemptFacts, toAttemptFixPrompt, toAttemptListRows, toAttemptNotices, toAttemptRows, toAttemptSource, toAttemptSummary, toAttemptUsage, toConversationTurns, toDiffFiles, toEvalRows, toExperimentDetails, toExperimentRows, toHeroData, toRunNotices, toSampleFixPrompt, toSampleNotices, toSummaryItems, toTimelineNodes, toTraceNodes, } from "./model/conversions.js";
 export { presentDimension, shortestUniqueLabels } from "./presentation.js";
 export { flag, label, numericFlag, numericLabel, numericRunConfig, runConfig } from "./model/flag.js";
 export { evaluationKindComposition } from "./model/evaluation-kind.js";
@@ -24,7 +24,7 @@ export { defineComponent, createTextContext, renderNodeToText, resolveReportTree
 export { Area, Bars, Callouts, Chart, Col, CommandEvidence, Conversation, CopyBlock, DiffView, Grid, Line, Markdown, Row, Scatter, Section, Series, SourceView, Stat, Style, Tab, Table, Tabs, Text, Waterfall, applyBarsSortLimit, } from "./definition/primitives.js";
 export { formatCellText } from "./definition/cell.js";
 // 格式化与呈现工具箱(docs/feature/reports/library/presentation.md):渲染侧单点入口。
-export { formatAxisTick, formatInstant, formatMetricValue, missingText } from "./model/format.js";
+export { formatAxisTick, formatInstant, formatMetricValue, formatTimeDistance, missingText } from "./model/format.js";
 // 文本排版工具箱:自定义组件的 text 面用的就是官方组件那把尺子。
 // 表格有 <Table> 承担,这里只给表以外的形态用 —— 尤其别拿 String.prototype.padEnd 对齐:
 // 它数 UTF-16 码元不数显示列宽,一带中文列就撕歪。renderAlignedRows 刻意不导出。

package/dist/report/model/aggregate.d.ts

@@ -1,6 +1,6 @@
 import type { AttemptHandle, SampleCoverage, SampleIssue, Run } from "../../record/types.ts";
 import { type AttemptLocator } from "../../record/locator.ts";
-import type { Aggregator, DimensionInput, AttemptMetric, MetricValue, MetricColumn, NumericAxis, ReportInput, SeriesInput } from "./types.ts";
+import type { Aggregator, DimensionInput, AttemptMetric, MetricValue, MetricColumn, NumericAxis, ReportInput, SeriesInput, StaleConclusionReference } from "./types.ts";
 import { type LocalizedText } from "./locale.ts";
 import { evalPrefixPredicate } from "../../shared/aggregate.ts";
 import type { JsonValue } from "../../shared/types.ts";
@@ -15,6 +15,10 @@ export declare function resolveInput(input: ReportInput): {
     attempts: readonly AttemptHandle[];
     issues: readonly SampleIssue[];
     coverage: readonly SampleCoverage[];
+    /** 同一总体内按 locator 去重的完整历史 attempt;裸 `Run[]` 没有挑选过程,取全部。 */
+    historyAttempts: readonly AttemptHandle[];
+    /** 是否只保留新执行的 attempt;裸 `Run[]` 没有这个口径,恒为 false。 */
+    fresh: boolean;
 };
 /**
  * 展平后的一条样本:`run` 始终是 attempt 的真实来源(= `attempt.run`,快照维度/
@@ -37,6 +41,15 @@ export declare function evalIdOf(item: Item): string;
  * 来源可能有多个,水位基准是其中 startedAt 最新的一个。
  */
 export declare function historicalOf(item: Item): boolean;
+/** 一个 ISO 时刻距渲染时刻(`Date.now()`)的毫秒数,恒不小于 0。 */
+export declare function msSince(iso: string): number;
+/**
+ * 覆盖缺口 / 对照矩阵缺席格的「过期结论」参考(docs/feature/reports/components/summaries/
+ * experiment-table.md「覆盖缺口的两档占位行」、show/compare.md 同一套口径):候选已经是与
+ * 当前基准 configHash 不可比的那些,取其中最近一条;两个消费方(entity-lists 的占位行、
+ * DeltaTable 的缺席格)共用同一份「取最新」判据,不各自实现一遍。
+ */
+export declare function staleReferenceOf(candidates: readonly AttemptHandle[]): StaleConclusionReference | undefined;
 /** 快照键:"<experimentId> @ <startedAt>"("run" 维度与手挑快照数组的对比用)。 */
 export declare function snapshotKeyOf(run: Run): string;
 /** 一组 Item 的 eval 全身份键:experimentId + eval id(聚合中的题级身份始终是这一对)。 */

package/dist/report/model/aggregate.js

@@ -22,10 +22,18 @@ const KEY_SEP = "\u0000";
 export function resolveInput(input) {
     if (Array.isArray(input)) {
         const runs = input;
-        return { runs, attempts: runs.flatMap((s) => s.attempts), issues: [], coverage: [] };
+        const attempts = runs.flatMap((s) => s.attempts);
+        return { runs, attempts, issues: [], coverage: [], historyAttempts: attempts, fresh: false };
     }
     const scope = input;
-    return { runs: scope.runs, attempts: scope.attempts, issues: scope.issues, coverage: scope.coverage };
+    return {
+        runs: scope.runs,
+        attempts: scope.attempts,
+        issues: scope.issues,
+        coverage: scope.coverage,
+        historyAttempts: scope.historyAttempts,
+        fresh: scope.fresh,
+    };
 }
 export function experimentIdOf(item) {
     return item.attempt.experimentId || item.run.experimentId;
@@ -42,6 +50,30 @@ export function evalIdOf(item) {
 export function historicalOf(item) {
     return item.attempt.carried || item.run.startedAt < item.watermark.startedAt;
 }
+/** 一个 ISO 时刻距渲染时刻(`Date.now()`)的毫秒数,恒不小于 0。 */
+export function msSince(iso) {
+    return Math.max(0, Date.now() - Date.parse(iso));
+}
+/**
+ * 覆盖缺口 / 对照矩阵缺席格的「过期结论」参考(docs/feature/reports/components/summaries/
+ * experiment-table.md「覆盖缺口的两档占位行」、show/compare.md 同一套口径):候选已经是与
+ * 当前基准 configHash 不可比的那些,取其中最近一条;两个消费方(entity-lists 的占位行、
+ * DeltaTable 的缺席格)共用同一份「取最新」判据,不各自实现一遍。
+ */
+export function staleReferenceOf(candidates) {
+    if (candidates.length === 0)
+        return undefined;
+    const newest = candidates.reduce((a, b) => ((a.result.startedAt ?? "") >= (b.result.startedAt ?? "") ? a : b));
+    const startedAt = newest.result.startedAt;
+    if (!startedAt)
+        return undefined; // 无时刻的 legacy 落盘算不出时距,不伪造参考
+    return {
+        locator: newest.locator ??
+            encodeAttemptLocator({ runId: newest.run.runId, evalId: newest.evalId, attempt: newest.result.attempt }),
+        verdict: newest.result.verdict,
+        staleSinceMs: msSince(startedAt),
+    };
+}
 /** 快照键:"<experimentId> @ <startedAt>"("run" 维度与手挑快照数组的对比用)。 */
 export function snapshotKeyOf(run) {
     return `${run.experimentId} @ ${run.startedAt}`;

package/dist/report/model/conversions.d.ts

@@ -37,3 +37,4 @@ export declare function toAttemptSource(attempt: AttemptEvidence): Promise<impor
 export declare function toAttemptAssertions(attempt: AttemptEvidence): Promise<import("../definition/cell.ts").TableContent | null>;
 export declare function toAttemptFixPrompt(attempt: AttemptEvidence): Promise<CopyBlockContent | null>;
 export declare function toAttemptUsage(attempt: AttemptEvidence): Promise<import("./types.ts").UsageTableData | null>;
+export declare function toAttemptFacts(attempt: AttemptEvidence): Promise<import("./types.ts").AttemptFactsData | null>;

package/dist/report/model/conversions.js

@@ -6,7 +6,7 @@ import { sampleSummary } from "../components/summaries/compute.js";
 import { runNoticesContent, sampleFixPromptContent, sampleNoticesContent, sampleTracesContent, } from "../components/site-components/projections.js";
 import { heroData } from "../components/site-components/compute.js";
 import { attemptAssertionsContent, attemptCommandEvidenceContent, attemptConversationContent, attemptDiffContent, attemptFixPromptContent, attemptNoticesContent, projectedSourceContent, attemptTimelineContent, } from "../components/attempt-detail/content.js";
-import { attemptAssertionsData, attemptCommandEvidenceData, attemptConversationData, attemptDiagnosticsData, attemptDiffData, attemptErrorData, attemptFixPromptData, attemptSummaryData, attemptTimelineData, usageTableData, } from "../components/attempt-detail/compute.js";
+import { attemptAssertionsData, attemptCommandEvidenceData, attemptConversationData, attemptDiagnosticsData, attemptDiffData, attemptErrorData, attemptFactsData, attemptFixPromptData, attemptSummaryData, attemptTimelineData, usageTableData, } from "../components/attempt-detail/compute.js";
 /** Sample 挑选警告 → Callouts items。 */
 export function toSampleNotices(sample) {
     return sampleNoticesContent(sample);
@@ -83,3 +83,6 @@ export async function toAttemptFixPrompt(attempt) {
 export async function toAttemptUsage(attempt) {
     return usageTableData(attempt);
 }
+export async function toAttemptFacts(attempt) {
+    return attemptFactsData(attempt);
+}

package/dist/report/model/format.d.ts

@@ -68,12 +68,13 @@ export declare function formatReportDateTimeRange(fromIso: string, toIso: string
     to: string;
 };
 /**
- * 历史执行的紧凑时距("3d" / "2h" / "5m" / "10s"):自 `startedAt` 起算,渲染时刻由调用方
- * 传入(`nowIso` 缺省当前时刻)——粒度阈值复用 `gapParts`(与曾经的 stale-run message
- * 同一套单源,见 `results/select.ts`),只是这里的呈现是紧凑单字母,不是完整单词
- * (docs/feature/reports/library.md「时效标注」)。
+ * 一段时长(毫秒) → 当前 locale 的紧凑相对时距("12d" / "12 天")。按区间选粒度最大的单位
+ * 取整,结果恒不小于一个单位(docs/feature/reports/library/presentation.md「相对时距是数据,
+ * 不是文案」):不足 1 小时→分钟,不足 1 天→小时,不足 30 天→天,30 天及以上→月。
+ * `locator` 格与占位行参考的 `staleSinceMs` 都经这一个入口,不各写各的措辞;不加箭头、回环
+ * 之类的装饰记号——记号不携带时长,读者还要先学会它。
  */
-export declare function formatHistoricalGap(startedAtIso: string, nowIso?: string): string;
+export declare function formatTimeDistance(ms: number, locale?: ReportLocale): string;
 /** passed / failed / errored / skipped 的判定符。 */
 export declare function verdictMark(verdict: Verdict): string;
 /**