niceeval 0.9.0 → 0.10.0

package/src/report/components/summaries/faces.ts

@@ -0,0 +1,48 @@
+// ScopeSummary 的 text 面:同一份算好的数据,渲染成终端字符(niceeval show 的形态)。
+// 与 web 面共守诚实契约:排序随 better、samples < total 角标、缺数据 — 不补 0。
+// 零 react、零 IO、纯同步。
+
+import type { ScopeSummaryData } from "../../model/types.ts";
+import type { TextContext } from "../../definition/tree.ts";
+import { countText, localeText, resolveLocalizedText } from "../../model/locale.ts";
+import { formatReportDateTime, formatReportDateTimeRange } from "../../model/format.ts";
+import { wrapDisplay } from "../../model/text-layout.ts";
+import { cellText, verdictTallyText, MISSING_MARK } from "../shared-faces.ts";
+
+/**
+ * 一至两行:头行是端到端通过率(官方 MetricCell,不重算)+ experiment/eval/attempt 数 +
+ * `votes` 选中的那级计票 + 总成本;第二行(有则加)是快照时间窗。
+ */
+export function scopeSummaryText(data: ScopeSummaryData, votes: "eval" | "attempt", ctx: TextContext): string {
+  const locale = ctx.locale;
+  const tally = votes === "attempt" ? data.attemptVerdicts : data.evalVerdicts;
+  const head = [
+    `${localeText(locale, "scopeSummary.passRate")} ${cellText(data.endToEndPassRate, locale)}`,
+    countText(locale, "overview.experiments", data.experiments),
+    localeText(locale, "overview.evalsCount", { n: data.evals }),
+    localeText(locale, "overview.attemptsCount", { n: data.attempts }),
+    verdictTallyText(tally, locale),
+    `${localeText(locale, "scopeSummary.totalCost")} ${
+      data.totalCostUSD.value === null ? MISSING_MARK : resolveLocalizedText(data.totalCostUSD.display, locale)
+    }${
+      data.totalCostUSD.samples < data.totalCostUSD.total
+        ? ` (${localeText(locale, "scopeSummary.costCoverage", {
+            samples: data.totalCostUSD.samples,
+            total: data.totalCostUSD.total,
+          })})`
+        : ""
+    }`,
+  ].join(" · ");
+  // 头行拼接的字段较多,窄终端下按显示宽度折行(不截断内容)。
+  const lines = wrapDisplay(head, ctx.width);
+  if (data.range.latestStartedAt !== null) {
+    const from = data.range.earliestStartedAt;
+    const to = data.range.latestStartedAt;
+    lines.push(
+      from !== null && from !== to
+        ? localeText(locale, "scopeSummary.runRange", formatReportDateTimeRange(from, to, locale))
+        : localeText(locale, "scopeSummary.lastRun", { time: formatReportDateTime(to, locale) }),
+    );
+  }
+  return lines.join("\n");
+}

package/src/report/components/summaries/index.tsx

@@ -0,0 +1,127 @@
+// 官方双面组件的装配点:web 面(./ScopeSummary.tsx 的纯 React 组件)+ text 面(./faces.ts)
+// + resolve 解析面(spec 形态由管线代调配套 ./compute.ts)。ScopeSummary 与 ExperimentComparison
+// 同属汇总族——前者是范围摘要卡,后者是内建报告默认使用的组合件(装配 ScopeSummary +
+// MetricScatter + ExperimentList,不产生自己的 data)。
+
+import { defineComponent, type ReportComponent } from "../../definition/tree.ts";
+import { Col } from "../../definition/primitives.tsx";
+import type { ReportInput, ScopeSummaryData, SeriesInput } from "../../model/types.ts";
+import { resolveInput, seriesName } from "../../model/aggregate.ts";
+import { label } from "../../model/flag.ts";
+import { costUSD, endToEndPassRate } from "../../model/metrics.ts";
+import {
+  cellProblem,
+  isObject,
+  makeDataComponent,
+  tallyProblem,
+  type ChromeProps,
+  type DataProps,
+  type Validator,
+} from "../shared.ts";
+import { scopeSummaryData } from "./compute.ts";
+import { scopeSummaryText } from "./faces.ts";
+import { ScopeSummary as ScopeSummaryWeb } from "./ScopeSummary.tsx";
+import { MetricScatter } from "../metric-views/index.tsx";
+import { ExperimentList } from "../entity-lists/index.tsx";
+
+export const validateScopeSummaryData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (!isObject(data.range)) return 'missing "range" ({ earliestStartedAt, latestStartedAt })';
+  if (!(data.range.earliestStartedAt === null || typeof data.range.earliestStartedAt === "string")) {
+    return '"range.earliestStartedAt" must be a string or null';
+  }
+  if (!(data.range.latestStartedAt === null || typeof data.range.latestStartedAt === "string")) {
+    return '"range.latestStartedAt" must be a string or null';
+  }
+  if (typeof data.experiments !== "number") return '"experiments" must be a number';
+  if (typeof data.evals !== "number") return '"evals" must be a number';
+  if (typeof data.attempts !== "number") return '"attempts" must be a number';
+  const evalVerdictsProblem = tallyProblem(data.evalVerdicts, "evalVerdicts");
+  if (evalVerdictsProblem !== null) return evalVerdictsProblem;
+  const attemptVerdictsProblem = tallyProblem(data.attemptVerdicts, "attemptVerdicts");
+  if (attemptVerdictsProblem !== null) return attemptVerdictsProblem;
+  const passRateProblem = cellProblem(data.endToEndPassRate, "endToEndPassRate");
+  if (passRateProblem !== null) return passRateProblem;
+  return cellProblem(data.totalCostUSD, "totalCostUSD");
+};
+
+// ───────────────────────── 概览组件 ─────────────────────────
+
+export type ScopeSummaryProps = DataProps<
+  ScopeSummaryData,
+  Record<never, never>,
+  ChromeProps & {
+    /** 显示哪一级计票;默认 "eval"。data 恒携带两级,votes 只选择呈现。 */
+    votes?: "eval" | "attempt";
+  }
+>;
+
+/** 范围摘要卡:时间窗、数量、两级计票、端到端通过率与总成本。 */
+export const ScopeSummary = makeDataComponent<
+  ScopeSummaryData,
+  Record<never, never>,
+  ChromeProps & { votes?: "eval" | "attempt" }
+>({
+  name: "ScopeSummary",
+  dataFnName: "scopeSummaryData",
+  shapeName: "ScopeSummaryData",
+  dataFn: (input) => scopeSummaryData(input),
+  specKeys: [],
+  validate: validateScopeSummaryData,
+  web: (props, ctx) => <ScopeSummaryWeb {...props} locale={props.locale ?? ctx.locale} />,
+  text: (props, ctx) => scopeSummaryText(props.data, props.votes ?? "eval", ctx),
+}) as unknown as ReportComponent<ScopeSummaryProps>;
+
+type ComparisonChrome = ChromeProps & {
+  /** 透传给散点;缺省跟随缺省 series 解析——按 line 归类时连线(声明了线就画线)。 */
+  connect?: boolean;
+};
+
+export type ExperimentComparisonProps = ComparisonChrome & {
+  input?: ReportInput;
+  /** 散点的 series 维度。缺省解析:Scope 内任一实验声明了 label `line` → `label("line")` 并连线;否则 `"agent"`、不连线。 */
+  series?: SeriesInput;
+};
+
+/** 默认报告识别的归类键:声明了它的实验按线归类并连线(docs/feature/experiments/library.md「labels」)。 */
+const LINE_LABEL_KEY = "line";
+
+/**
+ * 缺省 series:Scope 内任一快照声明了 labels.line 用 line 维度,否则 agent;显式传入覆盖。
+ * connect 缺省跟随最终 series 是否解析为 line(即便是显式传入的)。
+ */
+function resolveComparisonSeries(
+  input: ReportInput,
+  props: { series?: SeriesInput; connect?: boolean },
+): { series: SeriesInput; connect: boolean } {
+  const hasLine = resolveInput(input).snapshots.some((s) => s.experiment?.labels?.[LINE_LABEL_KEY] !== undefined);
+  const series = props.series ?? (hasLine ? label(LINE_LABEL_KEY) : "agent");
+  return { series, connect: props.connect ?? seriesName(series) === LINE_LABEL_KEY };
+}
+
+/**
+ * 内建报告的默认组合件:把同一个 input(缺省 ctx.scope)原样透传给 ScopeSummary、
+ * 成本 × 端到端通过率的 MetricScatter 与 ExperimentList——组合本身不二次计算或过滤,
+ * 也不导出自己的 data 形态;每个叶子组件按自己的公开契约取数,共享计算由 resolve 的
+ * 「同引用 input + 深相等 spec」记忆化保证。
+ */
+export const ExperimentComparison = defineComponent<ExperimentComparisonProps>((props, ctx) => {
+  const input = props.input ?? ctx.scope;
+  const { series, connect } = resolveComparisonSeries(input, props);
+  return (
+    <Col className={props.className}>
+      <ScopeSummary input={input} locale={props.locale} />
+      <MetricScatter
+        input={input}
+        points="experiment"
+        series={series}
+        connect={connect}
+        x={costUSD}
+        y={endToEndPassRate}
+        locale={props.locale}
+      />
+      <ExperimentList input={input} filter locale={props.locale} />
+    </Col>
+  );
+});
+ExperimentComparison.displayName = "ExperimentComparison";

package/src/report/components/summaries/validate.test.ts

@@ -0,0 +1,49 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// "validate*Data 递归覆盖到嵌套字段" 行:summaries 的 validateScopeSummaryData 表驱动字段突变覆盖,range 的 null 边界、两级 tally、
+// 两个 MetricCell 字段各自的嵌套校验。
+
+import { describe, expect, it } from "vitest";
+import { validateScopeSummaryData } 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 valid = {
+  range: { earliestStartedAt: "2026-07-01T00:00:00Z", latestStartedAt: "2026-07-02T00:00:00Z" },
+  experiments: 1,
+  evals: 6,
+  attempts: 6,
+  evalVerdicts: validTally,
+  attemptVerdicts: validTally,
+  endToEndPassRate: validCell,
+  totalCostUSD: validCell,
+};
+
+describe("validateScopeSummaryData", () => {
+  it("合规 literal 通过", () => {
+    expect(validateScopeSummaryData(valid)).toBeNull();
+  });
+
+  it("range 两端为 null 合法(空范围不编造当前时间)", () => {
+    expect(validateScopeSummaryData({ ...valid, range: { earliestStartedAt: null, latestStartedAt: null } })).toBeNull();
+  });
+
+  it("range.earliestStartedAt 非法类型报错", () => {
+    const bad = { ...valid, range: { earliestStartedAt: 123, latestStartedAt: null } };
+    expect(validateScopeSummaryData(bad)).toMatch(/"range\.earliestStartedAt"/);
+  });
+
+  it("evalVerdicts 与 attemptVerdicts 分别校验:错的那个才报错", () => {
+    const bad = { ...valid, attemptVerdicts: { passed: 1, failed: 0, errored: 0, skipped: "0" } };
+    expect(validateScopeSummaryData(bad)).toMatch(/"attemptVerdicts\.skipped"/);
+  });
+
+  it("endToEndPassRate 结构错误定位到嵌套 MetricCell", () => {
+    const bad = { ...valid, endToEndPassRate: { value: 1, display: "1", samples: 1, total: 1, refs: "x" } };
+    expect(validateScopeSummaryData(bad)).toMatch(/"endToEndPassRate\.refs"/);
+  });
+
+  it("experiments 非数字报错", () => {
+    expect(validateScopeSummaryData({ ...valid, experiments: "1" })).toMatch(/"experiments"/);
+  });
+});

package/src/report/definition/grid-layout.test.ts

@@ -0,0 +1,124 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// 分区「Table 与文本排版原语」:Grid 展平规则、columns 校验与 TextGridPlan 的宽度算术
+// 直接对 normalizeGrid / planTextGrid 断言,不经渲染面或 HTML。
+
+import { describe, expect, it } from "vitest";
+import { normalizeGrid, planTextGrid, validateGridColumns } from "./grid-layout.ts";
+import type { ReportElement } from "./tree.ts";
+
+const FRAGMENT = Symbol.for("react.fragment");
+
+function el(type: string, props: Record<string, unknown> = {}): ReportElement {
+  return { type, props };
+}
+
+describe("validateGridColumns", () => {
+  it("接受有限正整数", () => {
+    expect(validateGridColumns(1)).toBe(1);
+    expect(validateGridColumns(9)).toBe(9);
+  });
+
+  for (const bad of [0, -1, 1.5, NaN, Infinity, -Infinity]) {
+    it(`拒绝 ${bad} 并给出完整用户反馈`, () => {
+      expect(() => validateGridColumns(bad)).toThrowError(/columns/i);
+      try {
+        validateGridColumns(bad);
+      } catch (err) {
+        const message = (err as Error).message;
+        expect(message).toContain(JSON.stringify(bad));
+        expect(message).toContain("columns={N}");
+      }
+    });
+  }
+});
+
+describe("normalizeGrid", () => {
+  it("展平数组与 Fragment、跳过空分支,任意 ReportNode 各占一格", () => {
+    const a = el("Stat", { label: "a" });
+    const b = el("Stat", { label: "b" });
+    const c = el("Col", { children: [el("Stat", { label: "c1" }), el("Stat", { label: "c2" })] });
+    const children = [
+      a,
+      null,
+      undefined,
+      false,
+      { type: FRAGMENT, props: { children: [b, null] } },
+      c,
+    ];
+    const normalized = normalizeGrid({ children, columns: 3 });
+    expect(normalized.cells.map((cell) => cell.node)).toEqual([a, b, c]);
+    // Col 归拢的两个 Stat 仍是同一格,不下钻展开成两格
+    expect(normalized.cells).toHaveLength(3);
+  });
+
+  it("全部子节点为空分支时 0 格", () => {
+    const normalized = normalizeGrid({ children: [null, undefined, false], columns: 3 });
+    expect(normalized.cells).toHaveLength(0);
+  });
+
+  it("variant / density 默认 plain / regular", () => {
+    const normalized = normalizeGrid({ children: el("Stat"), columns: 1 });
+    expect(normalized.variant).toBe("plain");
+    expect(normalized.density).toBe("regular");
+  });
+
+  it("单个裸元素(非数组)也能展平为一格并生成稳定 key", () => {
+    const normalized = normalizeGrid({ children: el("Stat", { label: "solo" }), columns: 1 });
+    expect(normalized.cells).toHaveLength(1);
+    expect(normalized.cells[0].key).toBe("nre-grid-cell-0");
+  });
+});
+
+describe("planTextGrid", () => {
+  // 与 docs/feature/reports/library/layout.md 的运行总览示例逐字核对:Section 缩进后
+  // Grid 收到 98 显示列可用宽度,两个 Grid 都必须恰好降到三列且逐行不超过 100(=98+2 缩进)。
+  it("目标示例 Grid(columns=6, 6 cell, regular)在 98 可用宽度降为三列,内容宽 28/27/27", () => {
+    const plan = planTextGrid({ availableWidth: 98, cellCount: 6, columns: 6, density: "regular" });
+    expect(plan.columns).toBe(3);
+    expect(plan.contentWidths).toEqual([28, 27, 27]);
+    expect(plan.gutter).toBe(2);
+    const rowWidth = plan.contentWidths.reduce((sum, w) => sum + w + 4, 0) + plan.gutter * (plan.columns - 1);
+    expect(rowWidth).toBe(98);
+  });
+
+  it("目标示例 Grid(columns=9, 9 cell, compact)在 98 可用宽度降为三列,内容宽 28/28/28", () => {
+    const plan = planTextGrid({ availableWidth: 98, cellCount: 9, columns: 9, density: "compact" });
+    expect(plan.columns).toBe(3);
+    expect(plan.contentWidths).toEqual([28, 28, 28]);
+    expect(plan.gutter).toBe(1);
+    const rowWidth = plan.contentWidths.reduce((sum, w) => sum + w + 4, 0) + plan.gutter * (plan.columns - 1);
+    expect(rowWidth).toBe(98);
+  });
+
+  it("继续收窄宽度时降为一列(无条件 fallback,即使内容宽度小于 24)", () => {
+    const plan = planTextGrid({ availableWidth: 20, cellCount: 6, columns: 6, density: "regular" });
+    expect(plan.columns).toBe(1);
+    expect(plan.contentWidths).toEqual([16]); // 20 - BOXED_OVERHEAD_PER_CELL(4)
+  });
+
+  it("columns=1 时无条件单列,不因宽度充裕而尝试更多列", () => {
+    const plan = planTextGrid({ availableWidth: 200, cellCount: 6, columns: 1, density: "regular" });
+    expect(plan.columns).toBe(1);
+  });
+
+  it("列数不超过 min(declared columns, cellCount)", () => {
+    const plan = planTextGrid({ availableWidth: 400, cellCount: 2, columns: 9, density: "regular" });
+    expect(plan.columns).toBeLessThanOrEqual(2);
+  });
+
+  it("plain 与 boxed 复用同一份 plan:规划不吃 variant,列数与内容宽只随 columns/density/availableWidth 变化", () => {
+    const a = planTextGrid({ availableWidth: 98, cellCount: 6, columns: 6, density: "regular" });
+    const b = planTextGrid({ availableWidth: 98, cellCount: 6, columns: 6, density: "regular" });
+    expect(a).toEqual(b);
+  });
+
+  it("整除余数从左向右各补一列,行宽不超过 availableWidth", () => {
+    const plan = planTextGrid({ availableWidth: 100, cellCount: 4, columns: 4, density: "regular" });
+    const rowWidth = plan.contentWidths.reduce((sum, w) => sum + w + 4, 0) + plan.gutter * (plan.columns - 1);
+    expect(rowWidth).toBeLessThanOrEqual(100);
+    // 余数只补到最左侧若干列,不累积到行尾
+    for (let i = 1; i < plan.contentWidths.length; i++) {
+      expect(plan.contentWidths[i]).toBeLessThanOrEqual(plan.contentWidths[i - 1]);
+    }
+  });
+});

package/src/report/definition/grid-layout.ts

@@ -0,0 +1,146 @@
+// Grid 的语义层与面内布局(docs/feature/reports/architecture.md「排版原语的语义层与面内布局」、
+// docs/feature/reports/library/layout.md「Grid 与 Stat」)。只放同步纯函数与中间类型:
+// normalizeGrid 把 resolved ReportNode children 校验并展平成有序 cell 列表;planTextGrid
+// 只依赖 availableWidth / cell 数 / 规范化 Grid props,规划 text 面的列数与每列宽度。
+// 不 import show / view、Results IO 或 stylesheet;primitives.tsx 消费本文件产出两面适配。
+
+import type { ReportNode } from "./tree.ts";
+
+export type GridVariant = "plain" | "boxed";
+export type GridDensity = "regular" | "compact";
+
+// react/jsx-runtime 的 Fragment 注册符号,跨 react 版本稳定(tree.ts 同一常量的独立取用,
+// Symbol.for 全局注册表保证同一符号,不产生耦合)。
+const REACT_FRAGMENT = Symbol.for("react.fragment");
+
+function isElementNode(node: unknown): node is { type: unknown; props: Record<string, unknown>; key?: unknown } {
+  return typeof node === "object" && node !== null && !Array.isArray(node) && "type" in node && "props" in node;
+}
+
+function keyOf(node: unknown, fallback: string): string {
+  if (isElementNode(node)) {
+    const key = node.key;
+    if (typeof key === "string" || typeof key === "number") return String(key);
+  }
+  return fallback;
+}
+
+/** 校验 `columns`:必须是有限正整数——TypeScript 的 `number` 排除不了 0/负数/小数/NaN/Infinity。 */
+export function validateGridColumns(columns: number): number {
+  if (!(Number.isFinite(columns) && Number.isInteger(columns) && columns > 0)) {
+    throw new Error(
+      `Grid columns must be a finite positive integer, received ${JSON.stringify(columns)}. ` +
+        "Pass columns={N} with a whole number greater than 0 (e.g. columns={3}).",
+    );
+  }
+  return columns;
+}
+
+export interface NormalizedGridCell {
+  readonly node: ReportNode;
+  /** React key:复用元素自带 key,缺失时按展平后的声明序生成稳定回退。 */
+  readonly key: string;
+}
+
+/**
+ * `normalizeGrid` 的产物:有序、不可拆的 cell 列表 + columns / variant / density。
+ * 不是公开 data shape,也不进结果或 artifact——只是两个渲染面共享的同步排版中间值。
+ */
+export interface NormalizedGrid {
+  readonly cells: readonly NormalizedGridCell[];
+  readonly columns: number;
+  readonly variant: GridVariant;
+  readonly density: GridDensity;
+}
+
+/**
+ * 递归展开数组与 Fragment、跳过空分支(null/undefined/boolean),其余节点各占一格
+ * ——`Col` 归拢的多个子节点、任意自定义组件的渲染结果都是不透明的一格,不下钻其内部结构。
+ */
+function flattenGridChildren(children: ReportNode): NormalizedGridCell[] {
+  const cells: NormalizedGridCell[] = [];
+  const visit = (node: ReportNode): void => {
+    if (node === null || node === undefined || typeof node === "boolean") return;
+    if (Array.isArray(node)) {
+      for (const child of node) visit(child);
+      return;
+    }
+    if (isElementNode(node) && node.type === REACT_FRAGMENT) {
+      visit(node.props.children as ReportNode);
+      return;
+    }
+    cells.push({ node, key: keyOf(node, `nre-grid-cell-${cells.length}`) });
+  };
+  visit(children);
+  return cells;
+}
+
+/** `Grid` 组件创建时的一次性规范化:校验 props、展平 children 成有序 cell 列表。 */
+export function normalizeGrid(input: {
+  children: ReportNode;
+  columns: number;
+  variant?: GridVariant;
+  density?: GridDensity;
+}): NormalizedGrid {
+  return {
+    cells: flattenGridChildren(input.children),
+    columns: validateGridColumns(input.columns),
+    variant: input.variant ?? "plain",
+    density: input.density ?? "regular",
+  };
+}
+
+/** text 面规划的输入:只有可用宽度、cell 数与规范化 Grid props 里跟宽度有关的两项。 */
+export interface TextGridPlanInput {
+  readonly availableWidth: number;
+  readonly cellCount: number;
+  readonly columns: number;
+  readonly density: GridDensity;
+}
+
+/**
+ * text 面的一次性排版计划:实际列数、每列内容显示宽度、格间 gutter。
+ * `boxed` 与 `plain` 复用同一份计划(规划总是先扣 boxed 的四边框与内 padding),
+ * `plain` 渲染时只是不打印这部分字符——两个 variant 因此列数一致,不会各挑各的列数。
+ */
+export interface TextGridPlan {
+  readonly columns: number;
+  readonly contentWidths: readonly number[];
+  readonly gutter: number;
+}
+
+/** text 面每 cell 的最小可读内容宽度;density 不以挤坏字段换取更多列。 */
+const MIN_CONTENT_WIDTH = 24;
+/** boxed 单 cell 的固定开销:左右各一根边框 + 左右各一格 padding。 */
+const BOXED_OVERHEAD_PER_CELL = 4;
+
+function gridGutter(density: GridDensity): number {
+  return density === "compact" ? 1 : 2;
+}
+
+/**
+ * 从 `min(columns, cellCount)` 向一列尝试,选出满足每格最小可读内容宽度的最大列数;
+ * 一列是无条件 fallback(即使内容宽度因此小于 24)。选定列数后,余下的显示列从左向右
+ * 逐列多补一列,因此任意一行的显示宽度都不会超过 `availableWidth`(见调用方组装)。
+ */
+export function planTextGrid(input: TextGridPlanInput): TextGridPlan {
+  const { availableWidth, cellCount, columns, density } = input;
+  const gutter = gridGutter(density);
+  const maxColumns = Math.max(1, Math.min(columns, Math.max(cellCount, 1)));
+
+  let chosen = 1;
+  for (let n = maxColumns; n >= 2; n--) {
+    const budget = availableWidth - BOXED_OVERHEAD_PER_CELL * n - gutter * (n - 1);
+    if (budget >= 0 && Math.floor(budget / n) >= MIN_CONTENT_WIDTH) {
+      chosen = n;
+      break;
+    }
+  }
+
+  const budget = Math.max(0, availableWidth - BOXED_OVERHEAD_PER_CELL * chosen - gutter * (chosen - 1));
+  const base = Math.floor(budget / chosen);
+  const remainder = budget - base * chosen;
+  const contentWidths = Array.from({ length: chosen }, (_, i) => Math.max(1, base + (i < remainder ? 1 : 0)));
+
+  return { columns: chosen, contentWidths, gutter };
+}