@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/extensions/bytefly/panel/settings.ts

@@ -9,7 +9,7 @@
  * The catalogue is the shortlist a session changes, not the whole document: every
  * row is one a workflow differs on, and each states its own rule so a value the
  * screen accepts is a value the loader keeps. The catalogue order is the screen's
- * order, and it is capped so the section fits a 24-row terminal (`panel.test.ts`
+ * order, and it is capped so the section fits a 24-row terminal (`settings.test.ts`
  * holds the ceiling); a new row has to displace one. Everything else stays
  * `bytefly.json` — a list (`doctor.skip`), a table (`price.rates`), a schedule
  * (`price.peak`), and the tuning numbers and labels this screen deliberately does
@@ -25,13 +25,14 @@
  */
 
 import { configSection, configValueAt } from "../../../lib/config.ts";
-import { SPLIT_KEY, SPLIT_SECTION, SPLIT_SETTING_ID, SPLIT_SETTING_LABEL } from "../../../lib/plans/setting.ts";
 import { DEFAULT_CONFIG as DEFAULT_DOCTOR_CONFIG, normalizeConfig as normalizeDoctorConfig } from "../doctor/config.ts";
 import {
 	CURRENCY_DEFAULTS,
+	CURRENCY_SYMBOLS,
 	DEFAULT_BYTEFLY_CONFIG,
 	DEFAULT_CURRENCY,
 	MAX_BUDGET,
+	MAX_DECIMALS,
 	normalizeByteflyConfig,
 } from "../footer/price/config.ts";
 import type { CurrencyCode } from "../footer/price/types.ts";
@@ -39,7 +40,7 @@ import { DEFAULT_NOTIFY_CONFIG, normalizeNotifyConfig } from "../notify/config.t
 import type { Settings, WriteScope } from "../picker/types.ts";
 
 /** Where a preference is stored. */
-type SettingSource = "app" | "bytefly" | "plan";
+type SettingSource = "app" | "bytefly";
 
 /** The row control a preference uses. */
 type SettingKind = "boolean" | "enum" | "text";
@@ -47,6 +48,13 @@ type SettingKind = "boolean" | "enum" | "text";
 /** Where the effective value came from. */
 type SettingOrigin = "default" | "global" | "project" | "inherited";
 
+/**
+ * The heading a row sits under. The screen draws one heading per group, so twelve
+ * rows read as four short lists: what a session starts with, what it tells you
+ * about, what it keeps, and what it costs.
+ */
+export type SettingGroup = "Startup" | "Notifications" | "Session" | "Price";
+
 /** One curated value a row can take. */
 interface SettingOption {
 	value: string;
@@ -62,7 +70,7 @@ interface TextRule {
 }
 
 /** The `bytefly.json` sections a row still reaches. */
-export type ConfigSectionName = "notify" | "doctor" | "price" | "rewind" | "job" | "plan";
+export type ConfigSectionName = "notify" | "doctor" | "price" | "rewind" | "job";
 
 /** Where a `bytefly.json` row lives: a section, and the path to its leaf. */
 interface SettingConfig {
@@ -81,6 +89,8 @@ interface SettingLeaf {
 export interface SettingDescriptor {
 	/** Stable identity, also the focus key. */
 	id: string;
+	/** The heading this row is listed under. */
+	group: SettingGroup;
 	label: string;
 	description: string;
 	source: SettingSource;
@@ -125,8 +135,6 @@ const ON_OFF: readonly SettingOption[] = [
 	{ value: "true", label: "On" },
 ];
 
-/** The notify section's delivery methods, labeled by the surface each reaches. */
-
 /**
  * A text rule for a money amount inside an inclusive range: a whole number or a
  * decimal with up to four places, matching the loader's clamp for `price.budget`.
@@ -148,15 +156,17 @@ function amountRule(min: number, max: number): TextRule {
 /**
  * The catalogue, in screen order.
  *
- * Global scope lists all thirteen; Project lists the eleven `bytefly.json` rows,
+ * Global scope lists all twelve; Project lists the ten `bytefly.json` rows,
  * because Pi's setters write the personal `settings.json` only. The list is
  * capped so the screen keeps fitting a 24-row terminal.
  */
 export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	{
 		id: "byteflyUi",
-		label: "Bytefly startup TUI",
-		description: "Use bytefly's startup header in place of Pi's startup TUI.",
+		group: "Startup",
+		label: "Startup screen",
+		description:
+			"Show bytefly's header in place of Pi's own, so a session opens on the versions, the help keys, and the update marker.",
 		source: "app",
 		kind: "boolean",
 		fallback: "false",
@@ -165,9 +175,10 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "theme",
+		group: "Startup",
 		label: "Theme",
 		description:
-			"Pi's color theme, chosen from the palettes this package ships; `system` follows the terminal's colors. Takes effect after reload.",
+			"The palette every bytefly surface is drawn with; `system` follows Pi's own colors. Takes effect after reload.",
 		source: "app",
 		kind: "enum",
 		fallback: "system",
@@ -176,8 +187,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.enabled",
+		group: "Notifications",
 		label: "Desktop notifications",
-		description: "Raise an OS notification when a run or job finishes, or the agent asks for input.",
+		description: "The master switch for OS notifications; with it off, none of the four below is raised.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "false",
@@ -187,8 +199,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.turnFinished",
-		label: "Turn finished",
-		description: "Announce it when a full agent run settles.",
+		group: "Notifications",
+		label: "When a turn ends",
+		description: "Raise a notification once the agent has finished a reply.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -198,8 +211,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.needsInput",
-		label: "Needs input",
-		description: "Announce it when the agent opens a prompt and waits for an answer.",
+		group: "Notifications",
+		label: "When the agent needs you",
+		description: "Raise a notification when a question or a permission prompt is waiting.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -209,8 +223,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.jobFinished",
-		label: "Job finished",
-		description: "Announce it when a background job or watcher settles.",
+		group: "Notifications",
+		label: "When a job ends",
+		description: "Raise a notification when a background job or a watcher settles.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -220,8 +235,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.matchFound",
-		label: "Watcher matched",
-		description: "Announce it when a `watch` whose `wake` is on matches, once the agent is idle.",
+		group: "Notifications",
+		label: "When a watcher matches",
+		description: "Raise a notification when a watched pattern appears, once the agent is idle.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -231,8 +247,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "job.wakeOnFinish",
-		label: "Wake when a job finishes",
-		description: "Start one agent turn when any background job finishes.",
+		group: "Session",
+		label: "Resume after a job",
+		description: "Wake the agent once a background job finishes, so it can read the output.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "false",
@@ -242,8 +259,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "rewind.autoSnapshots",
-		label: "Automatic snapshots",
-		description: "Take one rewind snapshot per prompt, before the first mutating tool call.",
+		group: "Session",
+		label: "Snapshot before a turn",
+		description: "Keep one rewind point per prompt, so `/rewind` can take you back.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -253,8 +271,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "doctor.proactive",
-		label: "Proactive health check",
-		description: "Probe enabled extensions at session start and warn about a missing requirement.",
+		group: "Session",
+		label: "Health check at startup",
+		description: "Probe what the extensions need before the first turn and say what is missing.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -264,9 +283,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "price.currency.code",
+		group: "Price",
 		label: "Currency",
-		description:
-			"CNY prices DeepSeek from its yuan rates; USD from its published dollars, falling back to Pi's recorded cost.",
+		description: "The currency the footer prices a session in, at that currency's published rates.",
 		source: "bytefly",
 		kind: "enum",
 		fallback: DEFAULT_CURRENCY.code,
@@ -286,8 +305,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "price.budget",
+		group: "Price",
 		label: "Session budget",
-		description: "Warn once when the session's cost reaches this amount; 0 is off. It never stops a turn.",
+		description: "Where the footer's `spent/limit` warns: one notice and one notification at the limit; 0 is off.",
 		source: "bytefly",
 		kind: "text",
 		fallback: "0",
@@ -296,20 +316,6 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		text: amountRule(0, MAX_BUDGET),
 		config: { section: "price", path: ["budget"] },
 	},
-	{
-		// The split's switch, with the label, id, and default taken from the module
-		// that reads it, so this row cannot describe a key nothing honours.
-		id: SPLIT_SETTING_ID,
-		label: SPLIT_SETTING_LABEL,
-		description:
-			"Let an approved plan carry a team of slices, which separate sessions join by name. Off keeps every plan one flow.",
-		source: "plan",
-		kind: "boolean",
-		fallback: "false",
-		json: "boolean",
-		options: ON_OFF,
-		config: { section: SPLIT_SECTION, path: [SPLIT_KEY] },
-	},
 ];
 
 /** The one refusal for a Project write while the project is untrusted. */
@@ -346,6 +352,31 @@ function themeOptions(themes: readonly string[]): readonly SettingOption[] {
 	return names.map((name) => ({ value: name, label: name }));
 }
 
+/** The currency and precision a session prices in, through the price reader. */
+function currencyOf(snapshot: SettingsSnapshot, scope: WriteScope): { code: CurrencyCode; decimals: number } {
+	const reader = SECTION_READERS.price;
+	const globalRaw = configSection(snapshot.global, "price");
+	const projectRaw = scope === "project" ? configSection(snapshot.project, "price") : undefined;
+	const code = reader?.(globalRaw, projectRaw, ["currency", "code"]);
+	const decimals = reader?.(globalRaw, projectRaw, ["currency", "decimals"]);
+	return {
+		code: typeof code === "string" && code in CURRENCY_SYMBOLS ? (code as CurrencyCode) : DEFAULT_CURRENCY.code,
+		decimals: typeof decimals === "number" ? Math.min(decimals, MAX_DECIMALS) : DEFAULT_CURRENCY.decimals,
+	};
+}
+
+/**
+ * The budget's display value: `Off` for zero, otherwise the amount in the currency
+ * the session prices in. A reader thinks in `¥5`, not in `5`, and in `Off` rather
+ * than in `0`.
+ */
+function budgetLabel(raw: string, snapshot: SettingsSnapshot, scope: WriteScope): string {
+	const amount = Number(raw);
+	if (!Number.isFinite(amount) || amount <= 0) return "Off";
+	const { code, decimals } = currencyOf(snapshot, scope);
+	return `${CURRENCY_SYMBOLS[code]}${amount.toFixed(decimals)}`;
+}
+
 /** The display label for `raw`, or the raw value when it is a valid custom one. */
 function labelFor(row: SettingDescriptor, raw: string): string {
 	const option = row.options.find((entry) => entry.value === raw);
@@ -445,7 +476,8 @@ export function settingViews(snapshot: SettingsSnapshot, scope: WriteScope): Set
 		const options = row.id === "theme" ? themeOptions(snapshot.themes) : row.options;
 		const { value, origin } = row.source === "app" ? appValue(snapshot, row) : byteflyValue(snapshot, row, scope);
 		const view = { ...row, options, value };
-		return { ...view, valueLabel: labelFor(view, value), origin };
+		const valueLabel = row.id === "price.budget" ? budgetLabel(value, snapshot, scope) : labelFor(view, value);
+		return { ...view, valueLabel, origin };
 	});
 }
 

package/extensions/bytefly/panel/tui/entries.ts

@@ -1,10 +1,12 @@
 /**
- * The panel's entry model: one flat list of selectable rows per section.
+ * The panel's entry model: one flat list of display entries per section, made of
+ * group headings interleaved with the selectable rows under them.
  *
- * Extensions interleaves group headings with rows — a source group says where a
- * resource came from, which the row cannot — while Settings is flat, in catalogue
- * order. Both are built from a model or a set of views, so the component only has
- * to keep one cursor per section.
+ * Every section groups. A resource list groups by source — where an extension came
+ * from is something its row cannot say — and Settings groups by what the
+ * preference does, so twelve rows read as four short lists instead of one long
+ * one. Both are built from a model or a set of views, so the component only has to
+ * keep one cursor per section.
  *
  * Pure: the list is rebuilt from a model or a set of views, and navigation is
  * index arithmetic.
@@ -76,9 +78,25 @@ export function entriesOf(model: PanelModel): PanelEntry[] {
 }
 
 /**
- * The Settings entries: one row per view, in catalogue order, with no group
- * headings — the list is short enough to read whole.
+ * The Settings entries: one heading per group, in catalogue order, then its rows.
+ * The group key names the heading so a filter cannot collide a setting id with it.
  */
 export function settingEntries(views: readonly SettingView[]): PanelEntry[] {
-	return views.map((setting) => ({ kind: "setting", setting }));
+	const entries: PanelEntry[] = [];
+	for (const [group, settings] of groupSettings(views)) {
+		entries.push({ kind: "group", key: `setting:${group}`, label: group, count: settings.length });
+		for (const setting of settings) entries.push({ kind: "setting", setting });
+	}
+	return entries;
+}
+
+/** The views by their group, in catalogue order of first appearance. */
+function groupSettings(views: readonly SettingView[]): Map<string, SettingView[]> {
+	const groups = new Map<string, SettingView[]>();
+	for (const view of views) {
+		const list = groups.get(view.group) ?? [];
+		list.push(view);
+		groups.set(view.group, list);
+	}
+	return groups;
 }

package/extensions/bytefly/panel/tui/frame.ts

@@ -1,13 +1,17 @@
 /**
- * The chrome around the panel's body: the layout constants, the section bar with
- * its counts, a group heading, the hint row that a transient notice replaces, and
- * the frame the two sections share.
+ * The chrome around the panel's body: the header rule with the screen's
+ * attention, the section tabs with their counts and the write scope, a group
+ * heading, the hint row that a transient notice replaces, and the frame all three
+ * sections share.
  *
- * Every section draws its body through these, so the two views cannot drift on
- * spacing, roles, or the width arithmetic.
+ * Every section draws its body through {@link panelFrame}, so the three cannot
+ * drift on spacing, roles, width arithmetic, or height: the body is padded to one
+ * target measured across all three sections, which is what keeps the dock from
+ * resizing when the tabs change.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../../../lib/format.ts";
 import {
 	detailBlockRows,
@@ -17,51 +21,86 @@ import {
 	type ViewportRowsSource,
 } from "../../../../lib/tui/chrome.ts";
 import { clip, fitCells, splitRow } from "../../../../lib/tui/columns.ts";
-import { fitRows, formatRange, type ListCursor } from "../../../../lib/tui/cursor.ts";
+import { formatRange, type ListCursor } from "../../../../lib/tui/cursor.ts";
+import { SEPARATORS } from "../../../../lib/tui/glyphs.ts";
 import { BODY_INDENT } from "../../../../lib/tui/indent.ts";
 import { emptyState } from "../../../../lib/tui/rows.ts";
+import { titleRule } from "../../../../lib/tui/rules.ts";
 import { paint } from "../../../../lib/tui/tokens.ts";
-import { sectionSegments, type SummarySegment } from "../format.ts";
+import { sectionLabel, type SummarySegment } from "../format.ts";
 import type { PanelSection } from "../types.ts";
 import { selectableRange, type PanelEntry } from "./entries.ts";
+import { composeRows } from "./panes.ts";
 
 /** Body rows when the terminal height is unknown. */
 export const SCREEN_DEFAULT_ROWS = 16;
-/** Fixed rows around the body: header, summary, blank, blank, hint, closing rule. */
+/** Fixed rows around the body: header, tabs, blank, blank, hint, closing rule. */
 export const FRAME_ROWS = 6;
-/** Detail rows reserved for the focused row: its head, one description line, and its origin. */
+/** Detail rows reserved for the focused row in the single-column layout. */
 export const DETAIL_ROWS = 3;
-/** Body rows that must survive before the detail pane collapses to its title. */
+/** Body rows that must survive before the bottom pane collapses to nothing. */
 export const MIN_BODY_ROWS = 3;
 /** Detail rows when the terminal height is unknown and the focused row is expanded. */
 export const EXPANDED_DETAIL_FALLBACK = 8;
-/** Fixed body offset in the frame: header, summary, blank line. */
+/** Fixed body offset in the frame: header, tabs, blank line. */
 export const BODY_START = 3;
 
-/** The body indent, shared by the note and the detail pane. */
+/** The body indent, shared by the note and any focused-row block. */
 export const INDENT = " ".repeat(BODY_INDENT);
 
-/** The themed section bar: both section names, the active one accented. */
-export function sectionBar(theme: Theme, width: number, active: PanelSection, counts: string): string {
-	const separator = paint(theme, "faint", " · ");
-	const left = `  ${sectionSegments(active)
-		.map((segment) => paint(theme, segment.color, segment.text))
-		.join(separator)}`;
-	return clip(splitRow(left, counts, width), width);
+/**
+ * The header rule: the screen's name first, the attention it found at the right
+ * edge. The right side is dropped whole on a narrow terminal rather than clipped
+ * into half a word; the tabs below carry the same facts.
+ */
+export function headerLine(theme: Theme, width: number, title: string, right: readonly SummarySegment[]): string {
+	const w = Math.max(1, width);
+	const separator = paint(theme, "faint", SEPARATORS.item);
+	const text = right.map((segment) => paint(theme, segment.color, segment.text)).join(separator);
+	const rightWidth = visibleWidth(text);
+	if (text === "" || rightWidth + title.length + 4 > w) return titleRule(theme, w, title);
+	return `${titleRule(theme, w - rightWidth - 1, title)} ${text}`;
+}
+
+/**
+ * The tab row: every section with how many rows it holds, then any filter chips,
+ * and the scope a change is written to at the right edge. The active tab takes the
+ * accent; the counts stay faint so the names read first.
+ */
+export function tabsLine(
+	theme: Theme,
+	width: number,
+	active: PanelSection,
+	counts: Record<PanelSection, number>,
+	options: { chips?: readonly SummarySegment[]; scope?: string } = {},
+): string {
+	const separator = paint(theme, "faint", SEPARATORS.item);
+	const tabs = (["extensions", "skills", "settings"] as const).map(
+		(section) =>
+			paint(theme, section === active ? "accent" : "faint", sectionLabel(section)) +
+			paint(theme, "faint", ` ${counts[section]}`),
+	);
+	const chips = options.chips ?? [];
+	const left = [
+		`  ${tabs.join(separator)}`,
+		...(chips.length > 0 ? [`  ${chips.map((chip) => paint(theme, chip.color, chip.text)).join(separator)}`] : []),
+	].join("");
+	const right = options.scope === undefined ? "" : paint(theme, "meta", `writes ${options.scope}`);
+	return clip(splitRow(left, right, width), width);
 }
 
 /** One section's counts as whole segments, so a narrow screen drops a count. */
 export function countsLine(theme: Theme, width: number, segments: readonly SummarySegment[]): string {
-	const separator = paint(theme, "faint", " · ");
+	const separator = paint(theme, "faint", SEPARATORS.item);
 	const styled = segments.map((segment) => paint(theme, segment.color, segment.text));
 	return fitCells(styled, Math.max(1, width - 2), separator);
 }
 
-/** One group heading: its label and how many rows sit under it. */
+/** One group heading: its label, and how many rows sit under it. */
 export function groupLine(theme: Theme, width: number, entry: { label: string; count: number }): string {
 	const label = paint(theme, "meta", sanitizeLine(entry.label));
-	const count = paint(theme, "faint", `(${entry.count})`);
-	return clip(`  ${label} ${count}`, width);
+	const count = entry.count > 0 ? paint(theme, "faint", ` (${entry.count})`) : "";
+	return clip(`  ${label}${count}`, width);
 }
 
 /** The key-hint row, or a section's notice that replaces it. */
@@ -74,7 +113,7 @@ export function noticeLine(theme: Theme, width: number, notice: string): string
 	return clip(`${INDENT}${paint(theme, "meta", sanitizeLine(notice))}`, width);
 }
 
-/** The saved-then-reload marker, shared by both detail panes. */
+/** The saved-then-reload marker, shared by every focused-row block. */
 export function savedLine(theme: Theme, width: number, dirty: boolean): string[] {
 	if (!dirty) return [];
 	return [clip(`${INDENT}${paint(theme, "warn", "Saved · reload to apply")}`, width)];
@@ -87,50 +126,18 @@ export function totalRows(source: ViewportRowsSource | undefined): number | unde
 }
 
 /**
- * Detail rows the focused row gets: the fixed pane, or the free height when
- * expanded. Zero when there is no free row for a pane at all, so a short
- * terminal keeps its body; the caller then drops optional rows if needed.
+ * The rows the bottom pane gets in the single-column layout: the fixed pane, or
+ * the free height when expanded. Zero when there is no free row for a pane at all,
+ * so a short terminal keeps its body.
  */
 export function detailRows(expanded: boolean, viewportRows: ViewportRowsSource | undefined): number {
 	const total = totalRows(viewportRows);
 	if (total === undefined) return expanded ? EXPANDED_DETAIL_FALLBACK : DETAIL_ROWS;
-	// One row pays for the blank line the frame puts above the pane.
 	const available = total - FRAME_ROWS - MIN_BODY_ROWS - 1;
 	if (available < 1) return 0;
 	return expanded ? available : Math.min(DETAIL_ROWS, available);
 }
 
-/**
- * Drop optional rows until the frame fits the viewport: the range row first,
- * then the project note, then the blank above the detail pane, then the pane.
- * The header, summary, one body row, and the hint always survive; a terminal
- * shorter than those is left to the host.
- */
-export function fitOptionalLines(options: {
-	viewportRows: ViewportRowsSource | undefined;
-	body: string[];
-	note: string | undefined;
-	range: string | undefined;
-	detail: string[];
-}): { body: string[]; range: string | undefined; detail: string[]; noteShown: boolean; detailBlank: boolean } {
-	const total = totalRows(options.viewportRows);
-	let { body, range, detail } = options;
-	let noteShown = options.note !== undefined && body[0] === options.note;
-	if (total === undefined) return { body, range, detail, noteShown, detailBlank: true };
-	const fits = (blank: boolean): boolean =>
-		FRAME_ROWS + body.length + (range === undefined ? 0 : 1) + detailBlockRows(detail, blank) <= total;
-	if (!fits(true)) range = undefined;
-	if (!fits(true) && noteShown) {
-		body = body.slice(1);
-		noteShown = false;
-	}
-	// The separator goes before the pane does: the focused row's findings are
-	// worth more than the blank above them.
-	const detailBlank = fits(true) || !fits(false);
-	if (!fits(false)) detail = [];
-	return { body, range, detail, noteShown, detailBlank };
-}
-
 /** What {@link panelFrame} draws: the window, the body, and the chrome around it. */
 export interface PanelFrameInput {
 	theme: Theme;
@@ -138,59 +145,89 @@ export interface PanelFrameInput {
 	cursor: ListCursor;
 	width: number;
 	header: string;
-	summary: string;
+	tabs: string;
 	entries: readonly PanelEntry[];
 	note?: string;
+	/** The focused row's block, drawn under the list below the pane breakpoint. */
 	detail: string[];
 	hint: string;
 	/** The line a section shows in place of its body when it has no entries. */
 	emptyLabel?: string;
+	/**
+	 * The tallest section's row count. The body is padded to it (bounded by the
+	 * viewport), so every section draws the same height.
+	 */
+	tallest: number;
+	/** The side pane's rows, in the wide layout only. */
+	side?: (rows: number) => string[];
 	draw: (entry: PanelEntry, index: number) => string | undefined;
 }
 
+/** The frame both sections share, and the state the caller has to remember. */
+export interface PanelFrameResult {
+	lines: string[];
+	/** Whether the project note survived the row budget, for the click mapping. */
+	noteShown: boolean;
+	/** Body rows drawn, so a caller can map a click to a row. */
+	bodyRows: number;
+}
+
 /**
- * The frame both sections share: the cursor window, the visible body rows, the
- * range row, the optional rows that give way on a short terminal, and the
- * chrome around them. Each section supplies its summary, its detail pane, its
- * hint row, and how one entry is drawn.
+ * The frame every section draws: the cursor window, the padded body, the range
+ * row when the list scrolls, the optional rows that give way on a short terminal,
+ * and the chrome around them.
+ *
+ * The height comes from one place. With a side pane the body is the whole free
+ * height, capped by the tallest section; without one the bottom pane is paid for
+ * first and the body gets what is left. Either way `target` is the same for all
+ * three sections at a given terminal size.
  */
-export function panelFrame(input: PanelFrameInput): { lines: string[]; noteShown: boolean } {
-	const { theme, viewportRows, cursor, width, entries, note, detail, hint, draw } = input;
-	cursor.visible = fitRows(
-		viewportRows,
-		entries.length,
-		FRAME_ROWS + detailBlockRows(detail) + (note ? 1 : 0),
-		SCREEN_DEFAULT_ROWS,
-	);
+export function panelFrame(input: PanelFrameInput): PanelFrameResult {
+	const { theme, viewportRows, cursor, width, entries, note, hint } = input;
+	const total = totalRows(viewportRows);
+	const wide = input.side !== undefined;
+
+	// Costs that a short terminal can shed, in the order they go: the bottom pane
+	// first (its facts move nowhere, but the list matters more), then the note.
+	let detail = wide ? [] : input.detail;
+	let noteShown = note !== undefined;
+	const budgetFor = (): number => {
+		if (total === undefined) return Math.max(MIN_BODY_ROWS, input.tallest);
+		return total - FRAME_ROWS - detailBlockRows(wide ? [] : detail) - (noteShown ? 1 : 0);
+	};
+	if (budgetFor() < MIN_BODY_ROWS && !wide) detail = [];
+	if (budgetFor() < MIN_BODY_ROWS && noteShown) noteShown = false;
+
+	const target = Math.max(1, Math.min(budgetFor(), Math.max(1, input.tallest)));
+	const capacity = Math.max(1, target - (noteShown && note !== undefined ? 1 : 0));
+	const scrolling = entries.length > capacity;
+	cursor.visible = Math.max(1, capacity - (scrolling ? 1 : 0));
 	cursor.sync(entries.length);
 	const { start, end } = cursor.window(entries.length);
 
 	const body: string[] = [];
-	if (note) body.push(note);
+	if (note !== undefined && noteShown) body.push(note);
 	if (entries.length === 0 && input.emptyLabel !== undefined) {
 		body.push(...emptyState(theme, width, { label: input.emptyLabel }));
 	}
 	for (let index = start; index < end; index += 1) {
-		const line = draw(entries[index], index);
+		const line = input.draw(entries[index], index);
 		if (line !== undefined) body.push(line);
 	}
-
-	const range = cursor.clipped(entries.length)
-		? formatRange(theme, width, selectableRange(entries, { start, end }))
-		: undefined;
-	const fitted = fitOptionalLines({ viewportRows, body, note, range, detail });
-	return {
-		lines: dockListFrame({
-			theme,
-			width,
-			header: input.header,
-			summary: input.summary,
-			body: fitted.body,
-			range: fitted.range,
-			detail: fitted.detail.length > 0 ? fitted.detail : undefined,
-			detailBlank: fitted.detailBlank,
-			hint,
-		}),
-		noteShown: fitted.noteShown,
-	};
+	if (scrolling) {
+		body.push(formatRange(theme, width, selectableRange(entries, { start, end })));
+	}
+	while (body.length < target) body.push("");
+
+	const side = input.side === undefined ? undefined : input.side(target);
+	const lines = dockListFrame({
+		theme,
+		width,
+		header: input.header,
+		summary: input.tabs,
+		body: side === undefined ? body : composeRows(theme, width, body, side),
+		detail: detail.length > 0 ? detail : undefined,
+		hint,
+	});
+	return { lines, noteShown, bodyRows: target };
 }