@oh-my-pi/pi-tui 18.6.3 → 18.7.0

package/dist/types/fuzzy.d.ts

@@ -32,6 +32,20 @@ export declare class FuzzyText {
     /** Match `query` (space-separated tokens; all must match) against the prepared text. */
     match(query: string): FuzzyMatch;
 }
+/**
+ * Items prepared once for repeated {@link fuzzyRank}-equivalent ranking.
+ *
+ * `fuzzyRank` resolves each candidate's search index through the module cache,
+ * which stops admitting entries at {@link INDEX_CACHE_MAX}; larger candidate
+ * lists (the full model catalog) rebuild the overflow on every query. Hold one
+ * corpus per stable candidate list and call {@link rank} per keystroke instead.
+ */
+export declare class FuzzyCorpus<T> {
+    #private;
+    constructor(items: readonly T[], getText: (item: T) => string);
+    /** Same results as `fuzzyRank(items, query, getText)` for the prepared items. */
+    rank(query: string): FuzzyFilterResult<T>[];
+}
 /**
  * Filter and sort items by fuzzy match quality (best matches first).
  * Supports space-separated tokens: all tokens must match.

package/dist/types/keybindings.d.ts

@@ -107,7 +107,7 @@ export declare const TUI_KEYBINDINGS: {
         readonly description: "Delete word backward";
     };
     readonly "tui.editor.deleteWordForward": {
-        readonly defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"];
+        readonly defaultKeys: ["alt+delete", "alt+d", "ctrl+delete", "super+alt+delete", "super+alt+d"];
         readonly description: "Delete word forward";
     };
     readonly "tui.editor.deleteToLineStart": {

package/dist/types/overlays/agents-hub.d.ts

@@ -60,6 +60,15 @@ export interface AgentsHubDeps {
 export interface AgentsHubCallbacks {
     onCancel: () => void;
 }
+/**
+ * Parse model output into a {@link GeneratedAgentSpec}. Accepts a bare JSON object
+ * (tried first) or one wrapped in a code fence. Returns the spec with trimmed fields.
+ * Throws if the output is not valid JSON or not an object, if `identifier`, `whenToUse`
+ * or `systemPrompt` is missing or not a string, if the identifier is not lowercase
+ * kebab-case with 2+ words, if `whenToUse` does not start with "Use this agent when",
+ * or if `systemPrompt` is empty.
+ */
+export declare function parseGeneratedAgentSpec(raw: string): GeneratedAgentSpec;
 /**
  * The fullscreen agents hub component. Hosted via
  * `ui.showOverlay(..., { fullscreen: true })`; the host must call

package/dist/types/overlays/annotation-overlay.d.ts

@@ -1,4 +1,4 @@
-import { type Component, type TUI } from "../index.js";
+import { type Focusable, type TUI } from "../index.js";
 import { type KeybindingsManager } from "../app-keybindings.js";
 import { type Theme } from "../theme/theme.js";
 import type { CodeReviewAnnotation, CodeReviewOverlayResult, ReviewDiffFile, TextReviewAnnotation, TextReviewOverlayResult, TextReviewSource } from "./annotation-types.js";
@@ -18,10 +18,13 @@ export interface TextReviewOverlayCallbacks extends AnnotationOverlayCallbacks {
     onComplete(result: TextReviewOverlayResult | undefined): void;
 }
 /** A fullscreen, annotated diff picker that only relies on public OMP APIs. */
-export declare class AnnotationOverlay implements Component {
+export declare class AnnotationOverlay implements Focusable {
     #private;
+    focused: boolean;
     constructor(tui: TUI, theme: Theme, keybindings: KeybindingsManager, files: readonly ReviewDiffFile[], mode: string, callbacks: CodeReviewOverlayCallbacks);
     constructor(tui: TUI, theme: Theme, keybindings: KeybindingsManager, source: TextReviewSource, callbacks: TextReviewOverlayCallbacks);
+    /** Keep the nested editor's cursor mode aligned with the overlay focus target. */
+    setUseTerminalCursor(useTerminalCursor: boolean): void;
     invalidate(): void;
     dispose(): void;
     getAnnotations(): CodeReviewAnnotation[];

package/dist/types/overlays/model-browser.d.ts

@@ -49,6 +49,12 @@ export interface ModelBrowserSource extends ModelRoleLookup {
     readonly knownRoleIds: readonly string[];
     readonly mruOrder: readonly string[];
     readonly modelPerf: ReadonlyMap<string, ModelBrowserPerf>;
+    /**
+     * Service tier the host would send for `model`, when it runs one. Rows with a
+     * measured tier aggregate (`selector@tier`) then display that tier's numbers
+     * instead of the standard aggregate.
+     */
+    serviceTierFor?(model: Model): string | undefined;
     getRoleInfo(role: string): ModelBrowserRoleInfo;
     defaultRoleChain(role: string): string[];
     resolveRoleValue(value: string | undefined, models: Model[], roleLookup?: ModelRoleLookup): ResolvedModelRoleValue;
@@ -134,12 +140,28 @@ export interface SearchAffinity {
  * policy, not evidence of user preference.
  */
 export declare function buildSearchAffinity(providerOrder: ReadonlyArray<string>, roles: RoleAssignments, mruOrder: ReadonlyArray<string>): SearchAffinity;
-/** Rank picker and mention candidates by text relevance, user affinity, and MRU/version order. */
-export declare function rankModelItems(query: string, items: ReadonlyArray<ModelBrowserItem>, options: {
+/** Inputs to {@link rankModelItems} / {@link ModelItemRanker}. */
+export interface ModelRankOptions {
     roles: RoleAssignments;
     mruOrder: ReadonlyArray<string>;
     affinity: SearchAffinity;
-}): ModelBrowserItem[];
+}
+/**
+ * {@link rankModelItems} prepared for one candidate list: the fuzzy index, the
+ * MRU/version order, and the affinity ranks depend only on the items and options,
+ * so per-keystroke callers (composer mentions, `/switch` arguments, the picker)
+ * hold one ranker and pay only the per-query fuzzy scan.
+ */
+export declare class ModelItemRanker {
+    #private;
+    readonly items: ReadonlyArray<ModelBrowserItem>;
+    readonly options: ModelRankOptions;
+    constructor(items: ReadonlyArray<ModelBrowserItem>, options: ModelRankOptions);
+    /** Rank by text relevance, user affinity, and MRU/version order. */
+    rank(query: string): ModelBrowserItem[];
+}
+/** Rank picker and mention candidates by text relevance, user affinity, and MRU/version order. */
+export declare function rankModelItems(query: string, items: ReadonlyArray<ModelBrowserItem>, options: ModelRankOptions): ModelBrowserItem[];
 /**
  * A slim role chip: `● default ◉` — solid dot for configured assignments,
  * hollow for auto-selected fallbacks, thinking glyph attached when set.

package/dist/types/overlays/plan-review-overlay.d.ts

@@ -13,8 +13,9 @@
  * Focus regions (`toc`/`body`/`actions`) cycle with Tab/Shift+Tab; arrows move
  * within the focused region and step left into the sidebar. The default focus is
  * `actions`, so the muscle memory of the old single-target overlay carries over:
- * ↑/↓ select options, Enter confirms, ←/→ drives the slider when there is no
- * sidebar, g/G + PgUp/PgDn scroll, and the external-editor key opens the plan.
+ * ↑/↓ select options, Enter confirms, ←/→ drives the slider, g/G + PgUp/PgDn
+ * scroll, and the external-editor key opens the plan. Under Tern the options
+ * are a horizontal bar, so ←/→ select options and Shift+←/→ drive the slider.
  */
 import { type Component } from "../index.js";
 import type { HookSelectorSlider } from "./hook-selector.js";

package/dist/types/prompt/interactive-context-helpers.d.ts

@@ -17,6 +17,8 @@ export interface AssistantMessageHost {
     readonly proseOnlyThinking: boolean;
     readonly expandThinkingBlocks: boolean;
     readonly assistantImagesVisible: boolean;
+    /** Whether the viewed session's tables get charts: the main session's do, a focused subagent's do not. */
+    readonly tableChartsVisible: boolean;
     readonly hideToolActivity: boolean;
     readonly toolOutputExpanded: boolean;
     readonly ui: {

package/dist/types/prompt/model-mention-autocomplete.d.ts

@@ -19,7 +19,7 @@ export declare function applyModelMentionCompletion(lines: string[], cursorLine:
 };
 /**
  * Create a session-scoped model candidate lookup using picker ordering. The
- * scope and search affinity are reused across queries until their inputs change.
+ * scope and its prepared ranker are reused across queries until their inputs change.
  */
 export declare function createModelMentionSource(host: {
     source: ModelBrowserSource;

package/dist/types/render/composite.d.ts

@@ -0,0 +1,2 @@
+/** Splice overlay content into a base line at a specific column. Single-pass optimized. */
+export declare function compositeLineAt(baseLine: string, overlayLine: string, startCol: number, overlayWidth: number, totalWidth: number): string;

package/dist/types/tools/glob.d.ts

@@ -12,6 +12,10 @@ export interface GlobToolDetails {
     fileCount?: number;
     files?: string[];
     truncated?: boolean;
+    /** The scan hit the tool deadline, so the listed files are an incomplete
+     * set rather than a complete answer. Distinct from `truncated`, which also
+     * covers result-limit and output truncation. */
+    timedOut?: boolean;
     error?: string;
     /** Working directory at search time. Used by the renderer to resolve relative
      * file paths to absolute paths for OSC 8 hyperlinks. */

package/dist/types/utils.d.ts

@@ -26,6 +26,12 @@ export interface TextSizingOptions {
  */
 export declare function encodeTextSized(text: string, options?: TextSizingOptions): string;
 export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult;
+/**
+ * Hard-wrap one literal terminal row without trimming spaces or splitting graphemes.
+ * An oversized grapheme is emitted intact even when it exceeds the requested width.
+ * Zero-cell rows remain one empty row, matching restored-terminal reflow.
+ */
+export declare function wrapLiteralLine(line: string, width: number): string[];
 export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind?: Ellipsis | null | "", pad?: boolean | null): string;
 export declare function wrapTextWithAnsi(text: string, width: number): string[];
 export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter: boolean): ExtractSegmentsResult;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.6.3",
+	"version": "18.7.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -41,14 +41,14 @@
 		"gen:glyphs": "bun scripts/gen-glyphs.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.6.3",
-		"@oh-my-pi/pi-agent-core": "18.6.3",
-		"@oh-my-pi/pi-ai": "18.6.3",
-		"@oh-my-pi/pi-catalog": "18.6.3",
-		"@oh-my-pi/pi-natives": "18.6.3",
-		"@oh-my-pi/pi-utils": "18.6.3",
-		"@oh-my-pi/pi-wire": "18.6.3",
-		"@oh-my-pi/snapcompact": "18.6.3"
+		"@oh-my-pi/omptype": "18.7.0",
+		"@oh-my-pi/pi-agent-core": "18.7.0",
+		"@oh-my-pi/pi-ai": "18.7.0",
+		"@oh-my-pi/pi-catalog": "18.7.0",
+		"@oh-my-pi/pi-natives": "18.7.0",
+		"@oh-my-pi/pi-utils": "18.7.0",
+		"@oh-my-pi/pi-wire": "18.7.0",
+		"@oh-my-pi/snapcompact": "18.7.0"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/autocomplete.ts

@@ -263,8 +263,11 @@ export interface AutocompleteProvider {
 
 	/** Get inline hint text to show as dim ghost text after the cursor */
 	getInlineHint?(lines: string[], cursorLine: number, cursorCol: number): string | null;
-	/** Synchronously try to complete a slash command at the start of a line (no async I/O). */
-	/** Returns matched items and the full prefix, or null if not applicable. */
+	/**
+	 * Synchronously list slash command-name completions for a leading slash token (no async I/O).
+	 * Mirrors the command-name branch of {@link getSuggestions}, including the bare `/` listing and
+	 * the collapsed `/skill:` namespace row. Returns null outside a command-name token or with no match.
+	 */
 	trySyncSlashCompletion?(textBeforeCursor: string): { items: AutocompleteItem[]; prefix: string } | null;
 	/**
 	 * Synchronously try to expand text immediately before the cursor (no async I/O).
@@ -806,7 +809,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 			};
 		}
 
-		// Slash command suggestions can be accepted before the debounced refresh
+		// Slash command suggestions can be accepted before an async refresh
 		// catches up to newly typed characters. Replace the live command token,
 		// not only the prefix captured when the suggestion list was rendered.
 		// Absolute-path completions share the leading-slash prefix shape but
@@ -1300,19 +1303,14 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		const slashStart = findLeadingSlashCommandStart(textBeforeCursor);
 		if (slashStart === null) return null;
 		const commandText = textBeforeCursor.slice(slashStart);
-		if (commandText.length <= 1) return null; // Bare "/" alone, don't auto-complete
 		if (commandText.includes(" ")) return null; // Only complete command name, not args
 
-		const prefix = commandText.slice(1);
-		const lowerPrefix = prefix.toLowerCase();
-
-		// The `/skill:` namespace row is excluded here: the sync path submits
-		// immediately after applying, and the bare namespace is not a command.
+		const lowerPrefix = commandText.slice(1).toLowerCase();
 		const matches = buildSlashCommandCompletions(
 			collapseSkillNamespace(this.#commands, lowerPrefix),
 			lowerPrefix,
 			this.#commandUsage,
-		).filter(item => item.value !== SKILL_NAMESPACE);
+		);
 
 		if (matches.length === 0) return null;
 		// Mirror `getSuggestions`: preserve leading whitespace so the editor's

package/src/charts/chart-plan.ts

@@ -0,0 +1,367 @@
+/**
+ * Which chart a table becomes and the data it plots. {@link planChart} is the
+ * local best guess over a {@link TableAnalysis}: the chart kind, the label
+ * column and the measure columns to draw. A host may substitute its own
+ * {@link ChartPlan} (a model's pick for a multi-series table); either way
+ * {@link buildChart} turns it into the {@link ChartSpec} that
+ * {@link renderChartSvg} draws, and {@link worthCharting} decides whether
+ * the picture says more than the table already does.
+ *
+ * The heuristics were fitted on ~7k tables from real assistant answers: the
+ * label is the first text column (index columns like `#`/`Rank` never are),
+ * table order is kept (most tables are deliberately unsorted), total rows stay
+ * out of the scale, and units never share an axis.
+ */
+import {
+	type Dimension,
+	isMonotonic,
+	isNumber,
+	type NumberCell,
+	type TableAnalysis,
+	type TableColumn,
+} from "./table-data";
+
+/**
+ * Chart kinds, by the table shapes they fit:
+ * - `bar`: one measure across categories.
+ * - `paired`: two same-unit measures per category (before/after, A vs B), or `a → b` cells.
+ * - `grouped`: three or four same-unit measures per category.
+ * - `line`: measures over an ordered axis (dates, runs, sizes).
+ * - `heatmap`: a matrix of same-unit values.
+ * - `multiples`: measures in different units, each scaled on its own; transposed when each row is its own metric.
+ * - `share`: parts of a whole (percentages summing to 100).
+ * - `diverging`: signed changes around zero.
+ * - `scatter`: two continuous measures per item.
+ */
+export type ChartKind =
+	| "bar"
+	| "paired"
+	| "grouped"
+	| "line"
+	| "heatmap"
+	| "multiples"
+	| "share"
+	| "diverging"
+	| "scatter";
+
+/** What to draw from a table: the kind, the column naming each category, and the columns plotted. */
+export interface ChartPlan {
+	readonly kind: ChartKind;
+	/** Column naming each category (or holding the x values of a line); rows are numbered without one. */
+	readonly label: number | undefined;
+	/** Plotted columns, in order. */
+	readonly series: readonly number[];
+	/** Each data row is its own series (a metric with its own unit) and the plotted columns are the categories. */
+	readonly transpose: boolean;
+}
+
+/** One plotted value. */
+export interface ChartPoint {
+	/** Value in base units (seconds, bytes, …). */
+	readonly value: number;
+	/** The number as the table wrote it (`~$250`, `12.5 ms`), shown as the value label. */
+	readonly text: string;
+	/** The table bolded the cell. */
+	readonly emphasis: boolean;
+	/** Upper end of a range cell (`24–72 h`). */
+	readonly upper?: number;
+}
+
+export interface ChartSeries {
+	readonly name: string;
+	readonly dim: Dimension;
+	/** Currency symbol or rate unit the axis prints; empty for other dimensions. */
+	readonly unit: string;
+	/** One per category; `null` where the cell holds no number of this series' dimension. */
+	readonly points: readonly (ChartPoint | null)[];
+	/** Status words standing in for a value (`TIMEOUT`, `OOM`), one per category. */
+	readonly notes: readonly (string | undefined)[];
+}
+
+/** The data a chart draws, independent of how it is drawn. */
+export interface ChartSpec {
+	readonly kind: ChartKind;
+	readonly categories: readonly string[];
+	readonly series: readonly ChartSeries[];
+	/** Numeric x positions of a line or the x measure of a scatter, one per category. */
+	readonly x?: {
+		readonly name: string;
+		readonly dim: Dimension;
+		readonly unit: string;
+		readonly values: readonly number[];
+	};
+	/** Total/summary rows, printed under the chart instead of skewing its scale. */
+	readonly caption?: string;
+	/** Name of the category axis (the label column's header). */
+	readonly axis: string;
+}
+
+const BEFORE =
+	/\b(?:before|old|baseline|base|main|master|prev|previous|original|orig|cold|was|from|v1|stock|default|unpatched|without)\b/i;
+const AFTER = /\b(?:after|new|patched|optimi[sz]ed|fixed|warm|now|to|v2|with|proposed|branch|pr|ours)\b/i;
+const DELTA = /(?:Δ|delta|change|diff|improvement|speedup|reduction|savings|saved|gain|regression|% chg)/i;
+/** Aggregate columns that restate the others; dropped when enough same-unit series remain. */
+const AGGREGATE = /^(?:total|sum|cumulative|cum\.?|running total|avg|average|mean)\b/i;
+/** Row labels that name an ordered step (`Run 3`, `Day 2`, `N=1000`, `Q3`). */
+const SEQUENCE_LABEL =
+	/^(?:run|day|week|month|iter(?:ation)?|round|step|phase|epoch|v|version|n\s*=|wave|attempt|pass|batch|q[1-4]|#)\s*\d/i;
+const MONTH = /^(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\b/i;
+/** Most panels a small-multiples grid stays legible with. */
+const MAX_PANELS = 6;
+/** Most lines one line chart keeps apart. */
+const MAX_LINES = 6;
+
+/** The local best guess at a chart for `table`, or `undefined` when no chart fits. */
+export function planChart(table: TableAnalysis): ChartPlan | undefined {
+	const { rows } = table;
+	let label = table.label;
+	let measures = dropAggregates(table.measures);
+	if (measures.length === 0 || rows.length < 2) return undefined;
+
+	let order = axisOrder(table, label);
+	// Without a name column, a monotonic leading measure (`Workers | p50 | p99`) is the
+	// x axis of the rest; beside one it is just a sorted measure (`% | Self | Function`).
+	if (!order && label?.role !== "label" && measures.length >= 2 && measures[0]!.index === 0 && rows.length >= 4) {
+		const xs = columnValues(measures[0]!, rows);
+		if (xs.length === rows.length && isMonotonic(xs)) {
+			label = measures[0];
+			measures = measures.slice(1);
+			order = "numeric";
+		}
+	}
+	const plan = (kind: ChartKind, series: readonly TableColumn[], transpose = false): ChartPlan => ({
+		kind,
+		label: label?.index,
+		series: series.map(column => column.index),
+		transpose,
+	});
+
+	const mixed = measures.filter(column => column.mixed);
+	if (mixed.length > 0 && mixed.length * 2 >= measures.length) return plan("multiples", measures, true);
+	if (measures.length === 1 && measures[0]!.arrowShare >= 0.6) return plan("paired", measures);
+
+	const dims = new Set(measures.map(column => column.dim));
+	if (dims.size === 1 && measures.length >= 2 && measures.length <= 4) {
+		const before = measures.find(column => BEFORE.test(column.header));
+		const after = measures.find(column => column !== before && AFTER.test(column.header));
+		if (before && after) return plan("paired", [before, after]);
+	}
+	if (rows.length === 2 && measures.length === 1) return undefined;
+	if (order && rows.length >= 4) {
+		const lead = measures[0]!.dim;
+		return plan("line", measures.filter(column => column.dim === lead).slice(0, MAX_LINES));
+	}
+	if (measures.length <= 2) {
+		const delta = measures.find(
+			column =>
+				(column.signedShare >= 0.6 || DELTA.test(column.header)) &&
+				columnValues(column, rows).some(value => value < 0),
+		);
+		if (delta) return plan("diverging", [delta]);
+	}
+	const share = measures.find(column => column.dim === "percent");
+	if (share && rows.length <= 10 && (measures.length === 1 || (measures.length === 2 && dims.size === 2))) {
+		const values = columnValues(share, rows);
+		const sum = values.reduce((total, value) => total + value, 0);
+		if (values.every(value => value >= 0) && sum >= 97 && sum <= 103) return plan("share", [share]);
+	}
+	if (dims.size === 1 && measures.length >= 4 && rows.length >= 3) return plan("heatmap", measures);
+	if (!label && measures.length === 2 && rows.length >= 6) return plan("scatter", measures);
+	if (dims.size >= 2) return plan("multiples", measures.slice(0, MAX_PANELS));
+	if (measures.length === 2) return plan("paired", measures);
+	if (measures.length >= 3) return plan("grouped", measures);
+	return plan("bar", measures);
+}
+
+/**
+ * The data `plan` draws from `table`, or `undefined` when it leaves fewer than
+ * two categories or no series with two values. The kind is fitted to the
+ * series it ends up with ({@link fitKind}), so any plan — a model's pick
+ * included — draws as something the renderer supports.
+ */
+export function buildChart(table: TableAnalysis, plan: ChartPlan): ChartSpec | undefined {
+	const label = plan.label === undefined ? undefined : table.columns[plan.label];
+	const columns = plan.series.map(index => table.columns[index]).filter(column => column !== undefined);
+	if (columns.length === 0) return undefined;
+	const rowName = (row: number, at: number) => (label ? label.cells[row]!.text : "") || `#${at + 1}`;
+
+	let categories: string[];
+	let series: ChartSeries[];
+	if (plan.transpose) {
+		categories = columns.map(column => column.header);
+		series = table.rows.map((row, at) => rowSeries(rowName(row, at), columns, row));
+	} else if (plan.kind === "paired" && columns.length === 1) {
+		// `a → b` cells: the column splits into its from and to values.
+		const column = columns[0]!;
+		const [from, to] = column.header.split(/\s*(?:→|->|⇒)\s*/);
+		const before = columnSeries(column, table.rows, from && to ? from : "before");
+		const after: ChartSeries = {
+			...before,
+			name: from && to ? to : "after",
+			points: table.rows.map(row => {
+				const cell = column.cells[row];
+				return isNumber(cell) && cell.to !== undefined
+					? { value: cell.to, text: cell.toFigure ?? "", emphasis: cell.emphasis }
+					: null;
+			}),
+		};
+		categories = table.rows.map(rowName);
+		series = [before, after];
+	} else {
+		categories = table.rows.map(rowName);
+		series = columns.map(column => columnSeries(column, table.rows, column.header));
+	}
+
+	let x: ChartSpec["x"];
+	if (plan.kind === "scatter" && series.length >= 2) {
+		const xs = series[0]!;
+		x = { name: xs.name, dim: xs.dim, unit: xs.unit, values: xs.points.map(entry => entry?.value ?? Number.NaN) };
+		series = [series[1]!];
+	} else if (plan.kind === "line" && label && !plan.transpose) {
+		const values = table.rows.map(row => label.cells[row]).map(cell => (isNumber(cell) ? cell.value : Number.NaN));
+		if (values.every(Number.isFinite) && isMonotonic(values)) {
+			const first = label.cells[table.rows[0]!];
+			x = {
+				name: label.header,
+				dim: isNumber(first) ? first.dim : "count",
+				unit: label.unit,
+				values,
+			};
+		}
+	}
+
+	series = series.filter(entry => entry.points.filter(point => point !== null).length >= 2);
+	if (categories.length < 2 || series.length === 0) return undefined;
+	const kind = plan.transpose ? "multiples" : fitKind(plan.kind, series, x !== undefined);
+	// A share or a delta reads one series; the rest would overdraw it.
+	if (kind === "share" || kind === "diverging") series = series.slice(0, 1);
+	return {
+		kind,
+		categories,
+		series,
+		x,
+		caption: totalsCaption(table, label, columns, plan.transpose),
+		axis: label?.header ?? "",
+	};
+}
+
+/**
+ * Whether a chart of `spec` reads faster than its table: at least four
+ * categories, and either nine plotted values or a 3× spread within a series.
+ * On a model-judged sample of assistant tables this gate kept 85% of the
+ * tables a chart clearly helped while rejecting most two- and three-row ones.
+ */
+export function worthCharting(spec: ChartSpec): boolean {
+	if (spec.categories.length < 4) return false;
+	let points = 0;
+	let spread = 1;
+	for (const entry of spec.series) {
+		const positive: number[] = [];
+		for (const point of entry.points) {
+			if (!point) continue;
+			points++;
+			if (point.value > 0) positive.push(point.value);
+		}
+		if (positive.length >= 2) spread = Math.max(spread, Math.max(...positive) / Math.min(...positive));
+	}
+	return points >= 9 || spread >= 3;
+}
+
+/**
+ * The nearest kind `kind` draws as for `series`: a shared axis needs one unit
+ * (else small multiples), bars take one series, a dumbbell two, grouped bars
+ * up to four (more become a heatmap), and a scatter needs its x measure.
+ */
+function fitKind(kind: ChartKind, series: readonly ChartSeries[], hasX: boolean): ChartKind {
+	if (kind === "multiples") return kind;
+	if (kind === "scatter" && hasX) return kind;
+	if (new Set(series.map(entry => `${entry.dim}:${entry.unit}`)).size > 1) return "multiples";
+	if (kind === "share" || kind === "diverging" || kind === "line" || kind === "heatmap") return kind;
+	const count = series.length;
+	return count === 1 ? "bar" : count === 2 ? "paired" : count <= 4 ? "grouped" : "heatmap";
+}
+
+/** Same-unit aggregate columns (`Total`, `avg`) restate the series beside them. */
+function dropAggregates(measures: readonly TableColumn[]): readonly TableColumn[] {
+	return measures.filter(
+		column =>
+			!AGGREGATE.test(column.header) ||
+			measures.filter(other => other !== column && other.dim === column.dim).length < 2,
+	);
+}
+
+/** How the label column orders the rows: by time, by step, by a numeric size — or not at all. */
+function axisOrder(
+	table: TableAnalysis,
+	label: TableColumn | undefined,
+): "temporal" | "sequence" | "numeric" | undefined {
+	if (!label) return undefined;
+	if (label.role === "temporal") return "temporal";
+	if (label.role === "sequence") return "sequence";
+	const names = table.rows.map(row => label.cells[row]!.text);
+	const mostly = (pattern: RegExp) => names.filter(name => pattern.test(name)).length >= names.length * 0.8;
+	if (mostly(SEQUENCE_LABEL)) return "sequence";
+	if (mostly(MONTH)) return "temporal";
+	const values = columnValues(label, table.rows);
+	if (values.length === names.length && values.length >= 3 && isMonotonic(values)) return "numeric";
+	return undefined;
+}
+
+function columnValues(column: TableColumn, rows: readonly number[]): number[] {
+	const values: number[] = [];
+	for (const row of rows) {
+		const cell = column.cells[row];
+		if (isNumber(cell)) values.push(cell.value);
+	}
+	return values;
+}
+
+/** A column as a series: its cells of the column's dimension, other cells as gaps (status words kept as notes). */
+function columnSeries(column: TableColumn, rows: readonly number[], name: string): ChartSeries {
+	const points: (ChartPoint | null)[] = [];
+	const notes: (string | undefined)[] = [];
+	for (const row of rows) {
+		const cell = column.cells[row]!;
+		const fits = isNumber(cell) && cell.dim === column.dim;
+		points.push(fits ? point(cell) : null);
+		notes.push(!fits && cell.kind !== "missing" && !isNumber(cell) ? cell.text : undefined);
+	}
+	return { name, dim: column.dim ?? "count", unit: column.unit, points, notes };
+}
+
+/** One row of a metric-per-row table as a series over the plotted columns, in the row's dominant dimension. */
+function rowSeries(name: string, columns: readonly TableColumn[], row: number): ChartSeries {
+	const cells = columns.map(column => column.cells[row]);
+	const tally = new Map<Dimension, number>();
+	for (const cell of cells) if (isNumber(cell)) tally.set(cell.dim, (tally.get(cell.dim) ?? 0) + 1);
+	let dim: Dimension = "count";
+	for (const [key, count] of tally) if (count > (tally.get(dim) ?? 0)) dim = key;
+	const unitCell = cells.find(cell => isNumber(cell) && cell.dim === dim);
+	return {
+		name,
+		dim,
+		unit: isNumber(unitCell) && (dim === "currency" || dim === "rate") ? unitCell.unit : "",
+		points: cells.map(cell => (isNumber(cell) && cell.dim === dim ? point(cell) : null)),
+		notes: cells.map(cell => (cell && !isNumber(cell) && cell.kind !== "missing" ? cell.text : undefined)),
+	};
+}
+
+/** A numeric cell as a plotted point labelled with its written figure. */
+function point(cell: NumberCell): ChartPoint {
+	return { value: cell.value, text: cell.figure, emphasis: cell.emphasis, upper: cell.upper };
+}
+
+/** `Total: 2,964 · 2,310` for each summary row, over the plotted columns. */
+function totalsCaption(
+	table: TableAnalysis,
+	label: TableColumn | undefined,
+	columns: readonly TableColumn[],
+	transpose: boolean,
+): string | undefined {
+	if (transpose || !label || table.totals.length === 0) return undefined;
+	const lines = table.totals.slice(0, 2).flatMap(row => {
+		const values = columns.map(column => column.cells[row]?.text ?? "").filter(Boolean);
+		return values.length ? [`${label.cells[row]!.text}: ${values.join(" · ")}`] : [];
+	});
+	return lines.length ? lines.join("   ") : undefined;
+}