@gaia-ai/addon-gaia-ui 0.7.0 → 0.9.0

package/dist/src/Agent/launch.d.ts

@@ -17,9 +17,9 @@ export declare function buildCreateLaunch(opts: {
     label?: string | undefined;
 }): CreateLaunch;
 /**
- * A short human label for the agent list: the description's first line (capped to 40
- * incl. the ellipsis), else "New <workflow>". GAIA-236 AC-8: it builds the `label`
- * `buildCreateLaunch` takes, so it belongs to the module that builds the launch
- * intent — moved from `Service/create-form.ts` unchanged.
+ * A short human label for the agent list: the ticket's title, else the
+ * description's first line (both capped to 40 incl. the ellipsis), else
+ * "New <workflow>". GAIA-236 AC-8: it builds the `label` `buildCreateLaunch`
+ * takes, so it belongs to the module that builds the launch intent.
  */
 export declare function shortName(payload: CreateFormPayload): string;

package/dist/src/Agent/launch.js

@@ -32,18 +32,25 @@ export function buildCreateLaunch(opts) {
     };
 }
 /**
- * A short human label for the agent list: the description's first line (capped to 40
- * incl. the ellipsis), else "New <workflow>". GAIA-236 AC-8: it builds the `label`
- * `buildCreateLaunch` takes, so it belongs to the module that builds the launch
- * intent — moved from `Service/create-form.ts` unchanged.
+ * A short human label for the agent list: the ticket's title, else the
+ * description's first line (both capped to 40 incl. the ellipsis), else
+ * "New <workflow>". GAIA-236 AC-8: it builds the `label` `buildCreateLaunch`
+ * takes, so it belongs to the module that builds the launch intent.
  */
 export function shortName(payload) {
+    // GAIA-309 D9: the title is what the operator NAMED the ticket, so it is the
+    // better tab label; the description's first line stays the fallback for a
+    // payload that has no title yet. This touches the launch intent's `label`
+    // ONLY — never `prompt`, never `env`, which is what AC-6 pins.
+    const cap = (line) => line.length > 40 ? `${line.slice(0, 39)}…` : line;
+    const title = payload.title.trim();
+    if (title)
+        return cap(title);
     const firstLine = payload.description
         .split('\n')
         .map((l) => l.trim())
         .find((l) => l.length > 0);
-    if (firstLine) {
-        return firstLine.length > 40 ? `${firstLine.slice(0, 39)}…` : firstLine;
-    }
+    if (firstLine)
+        return cap(firstLine);
     return `New ${payload.workflow?.label ?? 'ticket'}`;
 }

package/dist/src/Component/section-list/index.d.ts

@@ -1,8 +1,104 @@
+import type { VNode } from '@opentui/core';
+import { type Cell } from '../../lib/vnode.js';
+/**
+ * A section body row that is COLUMNS rather than prose — GAIA-340 Task 13.
+ *
+ * The two producers are the dashboard's bars and the ticket detail's Runs
+ * table, and both used to compose their columns into one padded string with
+ * `lib/format.ts`'s `pad`. They describe their cells instead: the tree lays them
+ * out with Yoga budgets, and a surface with no layout — the pipe — prints
+ * {@link lineText}'s join. That is the operator-approved cost of retiring the
+ * padding, and it is what lets `pad` (and with it two of `lib/width.ts`'s
+ * consumers) go.
+ */
+export interface SectionCells {
+    readonly cells: readonly Cell[];
+}
+/** One body row of a section: prose, or columns a renderer places itself. */
+export type SectionLine = string | SectionCells;
+/**
+ * A line as the text a surface with no layout prints.
+ *
+ * The separator is ONE space because that is the gap `lib/vnode.ts`'s `rowNode`
+ * puts between two cells: the pipe and the tree then say the same thing about
+ * what separates two columns, and only the alignment inside a column is the
+ * renderer's own.
+ */
+export declare const lineText: (line: SectionLine) => string;
 /** A titled block of already-flattened physical rows. */
 export interface Section {
     heading: string;
-    lines: string[];
+    lines: SectionLine[];
+}
+/**
+ * The MINIMAL MARKDOWN rule: an ATX heading (`#`…`######`) renders as bold with
+ * the markers stripped — the same rule a section heading follows. Bullets and
+ * code fences stay raw by design (explicit v1 decision).
+ *
+ * ONE function, because every renderer of a body line goes through it:
+ * {@link sectionRows} for a flat section, {@link expandableRows} for a
+ * collapsible one, and `Entity/run/Component/run-detail` for a log entry. The
+ * Description block is rendered by two of them at once — flat on the piped
+ * render, expandable on the Overview tab — and a rule living in only one would
+ * make the same body look different depending on which renderer reached it.
+ */
+export declare function markdownRow(line: string): {
+    text: string;
+    bold: boolean;
+};
+/**
+ * One flattened row: its text, whether it is bold, and WHICH ROW IT IS
+ * (GAIA-340 D3/D4).
+ *
+ * `key` is what a converted screen turns into its node's `props.id`, so a row
+ * has to be able to say what it is rather than where it sits. It is scoped by
+ * the section's own HEADING — `per-user-0`, never `row-14` — so a section keeps
+ * its keys when the section above it is absent. Two sections sharing a heading
+ * would collide, and `Kernel/mount.ts` refuses a repeated id loudly rather than
+ * patching one row's content onto another's node.
+ */
+export interface SectionRow {
+    readonly key: string;
+    readonly text: string;
+    readonly bold: boolean;
+    /**
+     * The row's columns, when it has any — see {@link SectionCells}.
+     *
+     * `text` is the same row for a surface that cannot lay one out, so a consumer
+     * that only prints never has to know the difference; {@link sectionRowNode} is
+     * where the difference is made.
+     */
+    readonly cells?: readonly Cell[];
 }
+/**
+ * A heading as an id fragment: `PER USER` → `per-user`.
+ *
+ * Exported because a tab that renders one of its sections as a COLLAPSIBLE entry
+ * has to key that entry the same way `sectionRows` keys a flat one — otherwise
+ * the same section would carry different node ids depending on which tab reached
+ * it, and `patchTree` would rebuild it instead of writing to it (GAIA-340 D4).
+ */
+export declare const sectionKey: (heading: string) => string;
+/**
+ * Flatten `{heading, lines}` sections into KEYED rows: the heading, its body,
+ * and the blank line that closes the section.
+ *
+ * The one description of what a section renders as. {@link flattenSections}
+ * derives the row surface from it and a converted screen derives its nodes from
+ * it, so the two cannot answer differently for the same document — which is the
+ * property that lets the Dashboard hand over renderables while its pipe keeps
+ * emitting the bytes it always did (spec F5).
+ */
+export declare function sectionRows(sections: Section[]): SectionRow[];
+/**
+ * One flattened row as the node a converted screen hands over — GAIA-340 D1.
+ *
+ * The ONE place a `SectionRow` becomes a renderable, so the two screens that
+ * render section rows (the dashboard and the ticket detail's tabs) cannot
+ * disagree about what a columned row looks like. `prefix` is the screen's own
+ * body id, which is what keeps two screens' rows apart in one tree.
+ */
+export declare const sectionRowNode: (prefix: string, row: SectionRow, selected?: boolean) => VNode;
 export declare function flattenSections(sections: Section[]): {
     lines: string[];
     boldRows: Set<number>;
@@ -16,6 +112,12 @@ export declare function flattenSections(sections: Section[]): {
  * and structural sharing is the only form of that claim a test can hold.
  */
 export interface ExpandableEntry {
+    /**
+     * What this entry IS, as an id fragment (GAIA-340 D4/R4) — a comment's uuid,
+     * a section's slug. Its rows are keyed under it, so an entry's content and its
+     * identity move together when the list re-sorts.
+     */
+    key: string;
     /** The header row's text, after the caret. */
     header: string;
     /** Rows shown while collapsed (indented like the expanded body). */
@@ -25,22 +127,29 @@ export interface ExpandableEntry {
 }
 /** The rendered rows of a list of expandable entries. */
 export interface ExpandableView {
-    lines: string[];
-    boldRows: Set<number>;
+    rows: SectionRow[];
     /** `headerRows[i]` is the row index of entry i's header — the selection map. */
     headerRows: number[];
     selectable: number;
 }
 /**
- * Flatten expandable entries: one caret header row per entry (`▸` collapsed,
- * `▾` expanded) followed by that state's rows. `headerRows[i]` is entry i's
- * header row, which is both the highlight target and the click map (the rows are
- * NOT uniformly spaced — an expanded entry appends its body).
+ * Expandable entries as KEYED rows: one caret header row per entry (`▸`
+ * collapsed, `▾` expanded) followed by that state's rows. `headerRows[i]` is
+ * entry i's header row, which is both the highlight target and the click map
+ * (the rows are NOT uniformly spaced — an expanded entry appends its body).
  *
  * Zero entries render `emptyMessage` and nothing selectable, so an empty list is
  * an explicit statement rather than a blank screen.
+ *
+ * GAIA-340 D1/D3 — rows rather than lines-plus-a-`boldRows`-set, and the two
+ * halves of that are the same change: the caller turns each row into a node, so
+ * "this row is a heading" is a prop on the node and no longer an index into a
+ * surface somebody else styles. `SectionRow` is the shape {@link sectionRows}
+ * already produces, so a tab that mixes flat sections with expandable ones has
+ * one row type rather than two.
  */
-export declare function flattenExpandable(entries: ExpandableEntry[], { expanded, emptyMessage, }: {
+export declare function expandableRows(entries: ExpandableEntry[], { expanded, emptyMessage, emptyKey, }: {
     expanded?: ReadonlySet<number>;
     emptyMessage: string;
+    emptyKey: string;
 }): ExpandableView;

package/dist/src/Component/section-list/index.js

@@ -1,51 +1,120 @@
+import { cellsRow, textNode } from '../../lib/vnode.js';
 /**
- * Append one body row, applying the MINIMAL MARKDOWN rule: an ATX heading
- * (`#`…`######`) renders as bold with the markers stripped — the same rule a
- * section heading follows, styled after fit(). Bullets and code fences stay raw
- * by design (explicit v1 decision).
+ * A line as the text a surface with no layout prints.
  *
- * Extracted so `flattenSections` and `flattenExpandable` cannot answer "what does
- * a `## Context` line render as" differently: the Description block is rendered
- * by BOTH (flat on the piped render, expandable on the Overview tab), and a rule
- * living in only one of them would make the same body look different depending on
- * which renderer reached it.
+ * The separator is ONE space because that is the gap `lib/vnode.ts`'s `rowNode`
+ * puts between two cells: the pipe and the tree then say the same thing about
+ * what separates two columns, and only the alignment inside a column is the
+ * renderer's own.
  */
-function pushRow(lines, boldRows, line) {
+export const lineText = (line) => typeof line === 'string'
+    ? line
+    : line.cells
+        .map((cell) => cell.text)
+        .join(' ')
+        .replace(/\s+$/, '');
+/**
+ * The MINIMAL MARKDOWN rule: an ATX heading (`#`…`######`) renders as bold with
+ * the markers stripped — the same rule a section heading follows. Bullets and
+ * code fences stay raw by design (explicit v1 decision).
+ *
+ * ONE function, because every renderer of a body line goes through it:
+ * {@link sectionRows} for a flat section, {@link expandableRows} for a
+ * collapsible one, and `Entity/run/Component/run-detail` for a log entry. The
+ * Description block is rendered by two of them at once — flat on the piped
+ * render, expandable on the Overview tab — and a rule living in only one would
+ * make the same body look different depending on which renderer reached it.
+ */
+export function markdownRow(line) {
     const md = /^(#{1,6})\s+(.*)$/.exec(line);
-    if (md) {
-        boldRows.add(lines.length);
-        lines.push(md[2] ?? '');
-    }
-    else {
-        lines.push(line);
-    }
+    return md ? { text: md[2] ?? '', bold: true } : { text: line, bold: false };
 }
-// Flatten `{heading, lines}` sections into plain rows plus the indices that are
-// bold (section headings + markdown ATX headings). Headings carry NO ANSI here —
-// the draw step applies bold after fit(), so sanitizeDisplay never sees (and
-// never strips) the ESC.
-export function flattenSections(sections) {
-    const lines = [];
-    const boldRows = new Set();
+/**
+ * A heading as an id fragment: `PER USER` → `per-user`.
+ *
+ * Exported because a tab that renders one of its sections as a COLLAPSIBLE entry
+ * has to key that entry the same way `sectionRows` keys a flat one — otherwise
+ * the same section would carry different node ids depending on which tab reached
+ * it, and `patchTree` would rebuild it instead of writing to it (GAIA-340 D4).
+ */
+export const sectionKey = (heading) => heading
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+/**
+ * Flatten `{heading, lines}` sections into KEYED rows: the heading, its body,
+ * and the blank line that closes the section.
+ *
+ * The one description of what a section renders as. {@link flattenSections}
+ * derives the row surface from it and a converted screen derives its nodes from
+ * it, so the two cannot answer differently for the same document — which is the
+ * property that lets the Dashboard hand over renderables while its pipe keeps
+ * emitting the bytes it always did (spec F5).
+ */
+export function sectionRows(sections) {
+    const out = [];
     for (const section of sections) {
-        boldRows.add(lines.length);
-        lines.push(section.heading);
-        for (const line of section.lines)
-            pushRow(lines, boldRows, line);
-        lines.push('');
+        const id = sectionKey(section.heading);
+        out.push({ key: `${id}-heading`, text: section.heading, bold: true });
+        section.lines.forEach((line, index) => {
+            const key = `${id}-${index}`;
+            // Columns are never read as markdown: a run number opens with `#`, and the
+            // ATX rule would both bold the row and eat the number.
+            if (typeof line !== 'string') {
+                out.push({ key, text: lineText(line), bold: false, cells: line.cells });
+                return;
+            }
+            const { text, bold } = markdownRow(line);
+            out.push({ key, text, bold });
+        });
+        out.push({ key: `${id}-gap`, text: '', bold: false });
     }
-    return { lines, boldRows };
+    return out;
 }
 /**
- * Flatten expandable entries: one caret header row per entry (`▸` collapsed,
- * `▾` expanded) followed by that state's rows. `headerRows[i]` is entry i's
- * header row, which is both the highlight target and the click map (the rows are
- * NOT uniformly spaced — an expanded entry appends its body).
+ * One flattened row as the node a converted screen hands over — GAIA-340 D1.
+ *
+ * The ONE place a `SectionRow` becomes a renderable, so the two screens that
+ * render section rows (the dashboard and the ticket detail's tabs) cannot
+ * disagree about what a columned row looks like. `prefix` is the screen's own
+ * body id, which is what keeps two screens' rows apart in one tree.
+ */
+export const sectionRowNode = (prefix, row, selected = false) => row.cells === undefined
+    ? textNode({
+        id: `${prefix}-${row.key}`,
+        content: row.text,
+        bold: row.bold,
+        selected,
+    })
+    : cellsRow(`${prefix}-${row.key}`, row.cells, selected);
+// The same rows as plain text plus the INDICES that are bold (section headings +
+// markdown ATX headings) — the shape the row surface needs. Headings carry NO
+// ANSI here: the draw step applies bold after fit(), so sanitizeDisplay never
+// sees (and never strips) the ESC.
+export function flattenSections(sections) {
+    const rows = sectionRows(sections);
+    return {
+        lines: rows.map((row) => row.text),
+        boldRows: new Set(rows.flatMap((row, index) => (row.bold ? [index] : []))),
+    };
+}
+/**
+ * Expandable entries as KEYED rows: one caret header row per entry (`▸`
+ * collapsed, `▾` expanded) followed by that state's rows. `headerRows[i]` is
+ * entry i's header row, which is both the highlight target and the click map
+ * (the rows are NOT uniformly spaced — an expanded entry appends its body).
  *
  * Zero entries render `emptyMessage` and nothing selectable, so an empty list is
  * an explicit statement rather than a blank screen.
+ *
+ * GAIA-340 D1/D3 — rows rather than lines-plus-a-`boldRows`-set, and the two
+ * halves of that are the same change: the caller turns each row into a node, so
+ * "this row is a heading" is a prop on the node and no longer an index into a
+ * surface somebody else styles. `SectionRow` is the shape {@link sectionRows}
+ * already produces, so a tab that mixes flat sections with expandable ones has
+ * one row type rather than two.
  */
-export function flattenExpandable(entries, { expanded = new Set(), emptyMessage,
+export function expandableRows(entries, { expanded = new Set(), emptyMessage, emptyKey,
 // GAIA-255 AC-11 review: `ReadonlySet` because the render path is handed ONE
 // shared empty set for every not-yet-expanded tab (`expandedFor`) — growing
 // it here would leak one tab's expansion into all the others. The renderer
@@ -53,22 +122,25 @@ export function flattenExpandable(entries, { expanded = new Set(), emptyMessage,
  }) {
     if (!entries.length) {
         return {
-            lines: [emptyMessage],
-            boldRows: new Set(),
+            rows: [{ key: emptyKey, text: emptyMessage, bold: false }],
             headerRows: [],
             selectable: 0,
         };
     }
-    const lines = [];
-    const boldRows = new Set();
+    const rows = [];
     const headerRows = [];
     entries.forEach((entry, i) => {
-        headerRows.push(lines.length);
-        boldRows.add(lines.length);
-        lines.push(`${expanded.has(i) ? '▾' : '▸'} ${entry.header}`);
-        for (const line of expanded.has(i) ? entry.expanded : entry.collapsed) {
-            pushRow(lines, boldRows, line);
-        }
+        headerRows.push(rows.length);
+        rows.push({
+            key: `${entry.key}-header`,
+            text: `${expanded.has(i) ? '▾' : '▸'} ${entry.header}`,
+            bold: true,
+        });
+        const body = expanded.has(i) ? entry.expanded : entry.collapsed;
+        body.forEach((line, index) => {
+            const { text, bold } = markdownRow(line);
+            rows.push({ key: `${entry.key}-${index}`, text, bold });
+        });
     });
-    return { lines, boldRows, headerRows, selectable: entries.length };
+    return { rows, headerRows, selectable: entries.length };
 }

package/dist/src/Component/stats-panel/index.d.ts

@@ -1,3 +1,4 @@
+import type { SectionLine } from '../section-list/index.js';
 /** A filled bar cell. U+2588 FULL BLOCK. */
 export declare const BAR_FULL = "\u2588";
 /** An empty bar cell. U+2591 LIGHT SHADE. */
@@ -36,14 +37,25 @@ export interface StatsPanelOptions {
      * components keep their boundary.
      */
     columns?: readonly string[] | undefined;
+    /**
+     * The group's name, printed in the header row's already-empty label field
+     * (GAIA-324 D4). A caller that renders several groups under one heading uses
+     * it to say which group each block of bars is.
+     *
+     * The component stays ENTITY-NEUTRAL: this is a string, and nothing here knows
+     * a ticket from a run. It declares exactly the data label's budget, so the
+     * title, the labels beneath it and the column titles keep one geometry.
+     */
+    title?: string | undefined;
     /** What to render instead of rows when there are none (spec R7). */
     emptyMessage?: string | undefined;
 }
 /**
- * One block's body rows: an optional column header, then one row per entry.
+ * One block's body rows: an optional header row (the group's title, the column
+ * titles, or both), then one row per entry.
  *
- * Every column is measured with `displayWidth` (through `pad`/`padNumber`), so a
- * wide-character label cannot shift the numbers out of alignment — the failure
- * that makes a table of counts unreadable exactly when the data is interesting.
+ * Every row declares the SAME cell budgets in the same order, which is what
+ * keeps the header's titles over the columns they name — the structural form of
+ * the claim the padded rows used to make by measuring each field.
  */
-export declare function statsPanelRows(rows: readonly StatsPanelRow[], { columns, emptyMessage }?: StatsPanelOptions): string[];
+export declare function statsPanelRows(rows: readonly StatsPanelRow[], { columns, title, emptyMessage }?: StatsPanelOptions): SectionLine[];

package/dist/src/Component/stats-panel/index.js

@@ -1,5 +1,3 @@
-import { pad } from '../../lib/format.js';
-import { displayWidth } from '../../lib/width.js';
 // GAIA-256 spec D11 — the Dashboard's `/usage`-style bar rows.
 //
 // A SHARED component (the third in `src/Component/`), and it earns that place by
@@ -11,6 +9,14 @@ import { displayWidth } from '../../lib/width.js';
 // It produces the ROWS OF ONE BLOCK. Stacking blocks under bold headings is
 // `flattenSections`' job (`Component/section-list`), unchanged: this component
 // only fills a block's body.
+//
+// GAIA-340 Task 13 — a row is CELLS AND THEIR BUDGETS, not a padded string.
+// `lib/format.ts`'s `pad` used to fill the label field and a local `padNumber`
+// the count columns, both of which had to measure the value in display columns
+// first (`lib/width.ts`). The renderer places a value inside its budget, so the
+// alignment is Yoga's and nothing here measures. The operator approved what that
+// costs: the pipe prints the same values with one space between them and no
+// column alignment, because a pipe runs no layout (spec F5, A4 re-pinned).
 /** A filled bar cell. U+2588 FULL BLOCK. */
 export const BAR_FULL = '█';
 /** An empty bar cell. U+2591 LIGHT SHADE. */
@@ -28,43 +34,25 @@ export const BAR_EMPTY = '░';
  * ever bites, the fix is an ASCII bar glyph, never a width-table change.
  */
 export const BAR_WIDTH = 20;
+/** The indent every row of a block carries, matching the other body renderers. */
+const INDENT = '  ';
 /**
- * The label column, in display columns: 26 for the text plus {@link LABEL_GAP}.
- *
- * The text budget is wide enough for the longest label the Dashboard actually
- * builds: a breakdown row suffixes its entity type (`gaia · tickets`), the
- * unattributed bucket's `— unattributed · tickets` is 24 columns and a real
- * project name reaches 26 (`gaia-e2e-project · tickets`). At 18 that suffix was
- * cut to `— unattributed · t…`, which silently made the two entity types
- * indistinguishable in exactly the row where attribution is already unclear.
- */
-const LABEL_WIDTH = 27;
-/**
- * Columns of the label field reserved as the gap before the bar.
+ * The label column's budget: {@link INDENT} plus 27 columns of text.
  *
- * Load-bearing, not decoration. `pad` fills a label to exactly `LABEL_WIDTH`, so
- * a label of precisely that width left NO separator and the row rendered
- * `gaia-e2e-project · tickets████████` — a real project name, at exactly 26
- * columns. A truncated label collided the same way, ending in `…` against the
- * bar. Every fixture in the tests was shorter, which is why the suite was green
- * while the screen was wrong; the gap is part of the geometry now so the label
- * length cannot decide whether it exists.
+ * The text budget is what the field has to hold, and after GAIA-324 that is two
+ * different kinds of text sharing one column: a breakdown row's bare entity name
+ * (a real project name reaches 26 columns on its own — `gaia-e2e-project` plus a
+ * suffix used to; a long one still does), and the group TITLE printed in the
+ * header row's label field above it. Both declare the same budget, which is what
+ * keeps a title, the labels it captions and the column titles on one geometry.
  *
- * It is ADDED to the field rather than taken out of it: the 26 columns above are
- * a content budget with a stated reason, and spending one of them on the gap
- * would cut `gaia-e2e-project · tickets` to `gaia-e2e-project · ticke…` — losing
- * exactly the entity-type suffix that tells the two rows of a project apart.
+ * The indent rides INSIDE the cell's text rather than beside it as a cell of its
+ * own, so a row's first column starts where the other body renderers' rows do
+ * and the row's own `gap` is not spent separating an empty cell from the label.
  */
-const LABEL_GAP = 1;
-/** One number column, in display columns. */
+const LABEL_WIDTH = INDENT.length + 27;
+/** One number column's budget, in display columns. */
 const NUMBER_WIDTH = 8;
-/** The indent every row of a block carries, matching the other body renderers. */
-const INDENT = '  ';
-/** `value` right-aligned to `width` DISPLAY columns — the number columns' rule. */
-function padNumber(value, width) {
-    const gap = Math.max(0, width - displayWidth(value));
-    return ' '.repeat(gap) + value;
-}
 /**
  * The bar for `value` within a group whose largest bar value is `max`.
  *
@@ -81,34 +69,44 @@ function bar(value, max) {
     return BAR_FULL.repeat(filled) + BAR_EMPTY.repeat(BAR_WIDTH - filled);
 }
 /**
- * One block's body rows: an optional column header, then one row per entry.
+ * One block's body rows: an optional header row (the group's title, the column
+ * titles, or both), then one row per entry.
  *
- * Every column is measured with `displayWidth` (through `pad`/`padNumber`), so a
- * wide-character label cannot shift the numbers out of alignment — the failure
- * that makes a table of counts unreadable exactly when the data is interesting.
+ * Every row declares the SAME cell budgets in the same order, which is what
+ * keeps the header's titles over the columns they name — the structural form of
+ * the claim the padded rows used to make by measuring each field.
  */
-export function statsPanelRows(rows, { columns, emptyMessage } = {}) {
+export function statsPanelRows(rows, { columns, title, emptyMessage } = {}) {
     if (rows.length === 0) {
         return emptyMessage === undefined ? [] : [`${INDENT}${emptyMessage}`];
     }
     const barValue = (row) => row.numbers.at(-1) ?? 0;
     const max = Math.max(...rows.map(barValue));
+    const number = (text) => ({
+        text,
+        width: NUMBER_WIDTH,
+        right: true,
+    });
     const out = [];
-    if (columns && columns.length > 0) {
-        out.push(INDENT +
-            pad('', LABEL_WIDTH) +
-            ' '.repeat(BAR_WIDTH) +
-            columns.map((c) => padNumber(c, NUMBER_WIDTH)).join(''));
+    if ((columns && columns.length > 0) || title !== undefined) {
+        out.push({
+            cells: [
+                { text: `${INDENT}${title ?? ''}`, width: LABEL_WIDTH },
+                // The bar's column, empty: the header row has no bar, and the cell is
+                // what holds the column titles over the numbers rather than over it.
+                { text: '', width: BAR_WIDTH },
+                ...(columns ?? []).map(number),
+            ],
+        });
     }
     for (const row of rows) {
-        out.push(INDENT +
-            // Padded to the field width MINUS the gap, then the gap: the label
-            // column stays `LABEL_WIDTH` wide either way, so the header row above
-            // and every bar below still line up.
-            pad(row.label, LABEL_WIDTH - LABEL_GAP) +
-            ' '.repeat(LABEL_GAP) +
-            bar(barValue(row), max) +
-            row.numbers.map((n) => padNumber(String(n), NUMBER_WIDTH)).join(''));
+        out.push({
+            cells: [
+                { text: `${INDENT}${row.label}`, width: LABEL_WIDTH },
+                { text: bar(barValue(row), max), width: BAR_WIDTH },
+                ...row.numbers.map((n) => number(String(n))),
+            ],
+        });
     }
     return out;
 }