@zergai/ztc 0.2.6-dev.36101352252 → 0.2.7-dev.36236183737

package/dist/ui/widgets/select.js

@@ -3,6 +3,7 @@
  *
  * Extracted from cli_ratatui.ts to reduce file size.
  */
+import { displayWidth } from '../core/text_width.js';
 export class SelectWidget {
     host;
     active = null;
@@ -10,6 +11,15 @@ export class SelectWidget {
     checked = new Set();
     otherMode = false;
     otherValue = '';
+    /**
+     * Columns the option gutter claims before the label: the `❯ `/`  ` pointer
+     * plus the state marker and its separator. Every body row (question, label,
+     * description, Other hint) is indented by this, so the card has one left edge.
+     */
+    static labelColumn(type) {
+        const marker = type === 'multiselect' ? '[✓]' : '○';
+        return ' '.repeat(displayWidth('  ') + displayWidth(marker) + 1);
+    }
     constructor(host) {
         this.host = host;
     }
@@ -250,26 +260,51 @@ export class SelectWidget {
         const { title, question, type, options, allowOther } = this.active;
         const lines = [];
         const width = Math.min(Math.max(cols - 4, 40), 72);
+        // `pad` sizes to the full interior by default. Rows that carry a leading
+        // gutter pass an explicit width so the indent does not eat into the text
+        // budget (which would clip a line that still had room).
         const pad = (s, w = width - 4) => {
-            if (s.length > w)
-                return s.slice(0, w - 1) + '…';
-            return s.padEnd(w);
+            if (displayWidth(s) > w) {
+                // Slice on visible width, not code units: the gutter holds wide glyphs
+                // (❯, ○, [✓]) and a code-unit slice would cut them in half.
+                let clipped = '';
+                for (const ch of s) {
+                    if (displayWidth(clipped + ch) > w - 1)
+                        break;
+                    clipped += ch;
+                }
+                return clipped + '…';
+            }
+            return s + ' '.repeat(Math.max(0, w - displayWidth(s)));
         };
         // Top border with title
         const titlePart = title ? ` ${title} ` : '';
-        const topLine = '╭─' + titlePart + '─'.repeat(Math.max(0, width - 4 - titlePart.length)) + '╮';
+        // Body rows reserve 4 fixed cells ('│ ' + ' │'). The title border reserves
+        // only 3 ('╭─' + '╮'), so it was drawn one column short of every other row
+        // and the right edge did not line up. Fill to the same interior width.
+        const titleFill = Math.max(0, width - 3 - displayWidth(titlePart));
+        const topLine = '╭─' + titlePart + '─'.repeat(titleFill) + '╮';
         lines.push(topLine);
         // Question (word-wrap if longer than available width)
         const maxQWidth = width - 4;
-        if (question.length <= maxQWidth) {
-            lines.push('│ ' + pad(question) + ' │');
+        // Both branches indent to the option label column. Fixing only the wrapped
+        // branch left short questions flush at column 1 while their labels started
+        // at the gutter, so the two disagreed for the commonest case.
+        const questionGutter = SelectWidget.labelColumn(type);
+        if (displayWidth(questionGutter + question) <= maxQWidth) {
+            lines.push('│ ' + pad(questionGutter + question, maxQWidth) + ' │');
         }
         else {
+            // Indent the question to the option label column so the card has one left
+            // edge. Deriving it from the real gutter keeps the two in step for both
+            // the select radio and the wider multiselect checkbox.
+            const gutter = questionGutter;
+            const innerQ = Math.max(1, maxQWidth - displayWidth(gutter));
             const words = question.split(' ');
             let line = '';
             for (const word of words) {
-                if ((line + word).length > maxQWidth && line.length > 0) {
-                    lines.push('│ ' + pad(line.trimEnd()) + ' │');
+                if (displayWidth(line + word) > innerQ && line.length > 0) {
+                    lines.push('│ ' + pad(gutter + line.trimEnd(), maxQWidth) + ' │');
                     line = word + ' ';
                 }
                 else {
@@ -277,7 +312,7 @@ export class SelectWidget {
                 }
             }
             if (line.trimEnd().length > 0) {
-                lines.push('│ ' + pad(line.trimEnd()) + ' │');
+                lines.push('│ ' + pad(gutter + line.trimEnd(), maxQWidth) + ' │');
             }
         }
         lines.push('│' + ' '.repeat(width - 2) + '│');
@@ -328,8 +363,8 @@ export class SelectWidget {
             }
             // Description (if selected and has description) - word-wrap instead of truncate
             if (isSelected && opt.description) {
-                const indent = '     ';
-                const maxDescWidth = width - 8; // borders + padding
+                const indent = SelectWidget.labelColumn(type);
+                const maxDescWidth = width - 3 - displayWidth(indent); // borders + padding
                 const words = opt.description.split(' ');
                 let line = indent;
                 for (const word of words) {
@@ -354,7 +389,7 @@ export class SelectWidget {
             const labelLine = `${pointer}${radio} Other...`;
             lines.push('│ ' + pad(labelLine) + ' │');
             if (isSelected) {
-                lines.push('│ ' + pad('     Enter a custom value') + ' │');
+                lines.push('│ ' + pad(SelectWidget.labelColumn(type) + 'Enter a custom value') + ' │');
             }
         }
         // Bottom separator and instructions

package/dist/ui/widgets/settings_panel.d.ts

@@ -9,6 +9,10 @@ export interface SettingsPanelSurface {
 export interface SettingsPanelData {
     title?: string;
     categories: SettingCategory[];
+    layout?: 'page';
+    notice?: string;
+    initialSetting?: string;
+    initialCategory?: string;
     initialFilter?: string;
     onSettingChange: (setting: string, value: string) => void | Promise<void>;
     /**
@@ -18,6 +22,33 @@ export interface SettingsPanelData {
     onCaptureStateChange?: (capturing: boolean) => void;
     onClose?: () => void;
 }
+/**
+ * Columns between the longest label and the value column.
+ *
+ * Two blank columns read as a deliberate gap: one is indistinguishable from a
+ * label that happens to end one cell early, which is what made the value column
+ * look ragged across rows of different label lengths.
+ */
+export declare const SETTINGS_VALUE_COLUMN_GAP = 2;
+/**
+ * Floor on the label column, in cells.
+ *
+ * Clipping a label is worse than a wide gap: the label is what identifies the
+ * row, and the two-column table has nothing else to name it. This is the
+ * smallest column that still shows a label like "Notifications" whole on the
+ * narrowest pane the panel supports, so it stays a fixed cell count rather than
+ * a share of a width that can shrink below it.
+ */
+export declare const SETTINGS_LABEL_COLUMN_MIN = 14;
+/**
+ * Cells the `› ` cursor claims before a label.
+ *
+ * Every body row in the pane indents by this — the label, its description, the
+ * captured-key notice, and the option list — so the pane has one content
+ * column. Exported so a test can assert the rows agree instead of pinning the
+ * number twice.
+ */
+export declare const SETTINGS_ROW_INDENT = 2;
 export declare class SettingsPanelWidget {
     private host;
     private active;
@@ -48,7 +79,17 @@ export declare class SettingsPanelWidget {
     private categoryBand;
     private settingsBand;
     private lastBodyRows;
+    /**
+     * Column the painted frame starts on, in surface coordinates.
+     *
+     * Zero when the frame fills the width. On a terminal wide enough to trigger
+     * the cap it is the centring margin, and the wheel bands have to add it back:
+     * a click lands in terminal columns, so without it a capped page would scroll
+     * from a pane that is no longer under the pointer.
+     */
+    private frameInset;
     constructor(host: WidgetHost);
+    private isPage;
     show(data: SettingsPanelData): void;
     cancel(): void;
     isActive(): boolean;
@@ -96,10 +137,44 @@ export declare class SettingsPanelWidget {
     private notifyCaptureState;
     private commitSettingValue;
     handleInput(input: string, key: KeyEvent): void;
+    /**
+     * A value that always reads the same for a given setting, so a row can show
+     * it without consulting live state.
+     *
+     * The rows the settings panel paints come from `buildSettingRows`, which
+     * needs a value before it has decided anything else. A row that overrides
+     * `formatValue` is the exception: it renders from state the panel holds (the
+     * caret in an edit field, a recorded chord), so those rows still ask.
+     */
     private displayValue;
     private visibleSettings;
     private categorySettings;
     private categorySummaries;
+    /**
+     * The label column, sized once from the labels the pane currently shows
+     * rather than per row, so the value column is straight down the pane.
+     *
+     * The width comes from the current category, not from every setting the
+     * surface holds: a column sized by a category the user is not looking at
+     * would squeeze the values of the one they are.
+     *
+     * The column is the longest label plus the gap, capped so the value keeps
+     * its reserve. Deriving it from the labels means a short-label page
+     * gets a short column — the old fixed 14-cell floor padded every label out and
+     * pushed the values far from their own text.
+     */
+    private labelColumnWidth;
+    /**
+     * One settings row: the cursor, the label in its own column, then the value.
+     *
+     * The value is flush left rather than right-aligned, because pushing it to
+     * the far edge is what separates a label from its own value on a wide frame.
+     * A frame too narrow for both columns keeps the label whole and lets the
+     * value clip, since the label is what identifies the row.
+     */
+    private composeRow;
+    /** One content column: a body row indented to where labels start. */
+    private indented;
     private buildSettingRows;
     private visibleSettingWindow;
     private categoryWindow;

package/dist/ui/widgets/settings_panel.js

@@ -1,7 +1,7 @@
 import { box, text } from '../core/index.js';
 import { displayWidth, padEndDisplay, sanitizeTerminalText } from '../core/text_width.js';
 import { TERMINAL_THEME } from '../views/theme.js';
-import { bodyBand, isInsideBand, sideBySideBands, } from './panel_frame.js';
+import { bodyBand, isInsideBand, sideBySideBands, widgetFrameGeometry, } from './panel_frame.js';
 const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
 /**
  * Labels a checkbox row spells out before it counts the rest. These rows sit in
@@ -9,6 +9,44 @@ const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
  * full list is one Enter away on the page that owns it.
  */
 const CHECKBOX_SUMMARY_LABELS = 3;
+/**
+ * Columns between the longest label and the value column.
+ *
+ * Two blank columns read as a deliberate gap: one is indistinguishable from a
+ * label that happens to end one cell early, which is what made the value column
+ * look ragged across rows of different label lengths.
+ */
+export const SETTINGS_VALUE_COLUMN_GAP = 2;
+/**
+ * Cells the label column always leaves for the value.
+ *
+ * The cap on the label column comes from the pane, not from a fixed share of
+ * it: a label may use everything except this reserve, so one long label cannot
+ * push every value off the pane, yet a medium pane still shows a label such as
+ * "Compact threshold (% of window)" whole instead of clipping it at half width.
+ * Six cells fit a number, a percent or on/off; a longer value clips before the
+ * label does, because the label is what names the row.
+ */
+const SETTINGS_VALUE_COLUMN_MIN = 6;
+/**
+ * Floor on the label column, in cells.
+ *
+ * Clipping a label is worse than a wide gap: the label is what identifies the
+ * row, and the two-column table has nothing else to name it. This is the
+ * smallest column that still shows a label like "Notifications" whole on the
+ * narrowest pane the panel supports, so it stays a fixed cell count rather than
+ * a share of a width that can shrink below it.
+ */
+export const SETTINGS_LABEL_COLUMN_MIN = 14;
+/**
+ * Cells the `› ` cursor claims before a label.
+ *
+ * Every body row in the pane indents by this — the label, its description, the
+ * captured-key notice, and the option list — so the pane has one content
+ * column. Exported so a test can assert the rows agree instead of pinning the
+ * number twice.
+ */
+export const SETTINGS_ROW_INDENT = 2;
 /**
  * Subsequence match, so "ctx" finds "Context left" and "stln" finds
  * "Status Line". Every whitespace-separated token must land somewhere in one of
@@ -165,12 +203,29 @@ export class SettingsPanelWidget {
     categoryBand = null;
     settingsBand = null;
     lastBodyRows = 1;
+    /**
+     * Column the painted frame starts on, in surface coordinates.
+     *
+     * Zero when the frame fills the width. On a terminal wide enough to trigger
+     * the cap it is the centring margin, and the wheel bands have to add it back:
+     * a click lands in terminal columns, so without it a capped page would scroll
+     * from a pane that is no longer under the pointer.
+     */
+    frameInset = 0;
     constructor(host) {
         this.host = host;
     }
+    isPage() {
+        return this.active?.layout === 'page';
+    }
     show(data) {
+        if (data.layout === 'page' && data.categories.length !== 1) {
+            throw new Error('A settings interaction page needs exactly one category.');
+        }
         this.active = data;
-        this.filterText = data.initialFilter || '';
+        // Category deep links keep the full rail navigable. The filter still goes
+        // to the web mirror, where it selects that Settings section.
+        this.filterText = data.initialCategory ? '' : data.initialFilter || '';
         this.filterMode = false;
         this.cursorIndex = 0;
         this.expandedSetting = null;
@@ -182,7 +237,12 @@ export class SettingsPanelWidget {
         this.captureNotice = null;
         this.scrollOffset = 0;
         this.buildFlatList();
-        this.applyFilter();
+        this.applyFilter(data.initialSetting);
+        if (data.initialCategory && !data.initialSetting) {
+            const categoryIndex = this.visibleRows.findIndex(row => (row.type === 'setting' && row.categoryName.toLowerCase() === data.initialCategory?.toLowerCase()));
+            if (categoryIndex >= 0)
+                this.cursorIndex = categoryIndex;
+        }
         this.host.render();
     }
     cancel() {
@@ -272,7 +332,7 @@ export class SettingsPanelWidget {
         const fields = [
             row.setting.label,
             row.setting.name,
-            row.setting.value,
+            row.setting.secret ? '' : row.setting.value,
             row.categoryName,
             optionLabels,
         ];
@@ -489,21 +549,27 @@ export class SettingsPanelWidget {
     commitSettingValue(setting, value) {
         if (!this.active)
             return;
+        const page = this.active;
         const previousValue = setting.value;
         setting.value = value;
         try {
-            void Promise.resolve(this.active.onSettingChange(setting.name, value)).then(() => this.refreshRows(setting.name), (error) => {
+            void Promise.resolve(page.onSettingChange(setting.name, value)).then(() => {
+                if (this.active === page)
+                    this.refreshRows(setting.name);
+            }, (error) => {
                 if (setting.value === value)
                     setting.value = previousValue;
                 this.host.addSystemMessage(`Setting failed: ${error.message}`);
-                this.refreshRows(setting.name);
+                if (this.active === page)
+                    this.refreshRows(setting.name);
             });
         }
         catch (error) {
             setting.value = previousValue;
             const message = error instanceof Error ? error.message : String(error);
             this.host.addSystemMessage(`Setting failed: ${message}`);
-            this.refreshRows(setting.name);
+            if (this.active === page)
+                this.refreshRows(setting.name);
         }
     }
     handleInput(input, key) {
@@ -590,7 +656,7 @@ export class SettingsPanelWidget {
                 this.host.render();
                 return;
             }
-            if (input === '/' && !key.ctrl && !key.meta) {
+            if (input === '/' && !this.isPage() && !key.ctrl && !key.meta) {
                 this.filterMode = true;
                 this.host.render();
                 return;
@@ -625,7 +691,7 @@ export class SettingsPanelWidget {
             this.host.render();
             return;
         }
-        if (input === '/') {
+        if (input === '/' && !this.isPage()) {
             this.filterMode = true;
             this.host.render();
             return;
@@ -679,6 +745,15 @@ export class SettingsPanelWidget {
         }
         this.host.render();
     }
+    /**
+     * A value that always reads the same for a given setting, so a row can show
+     * it without consulting live state.
+     *
+     * The rows the settings panel paints come from `buildSettingRows`, which
+     * needs a value before it has decided anything else. A row that overrides
+     * `formatValue` is the exception: it renders from state the panel holds (the
+     * caret in an edit field, a recorded chord), so those rows still ask.
+     */
     displayValue(setting) {
         if (setting.secret)
             return setting.value ? '••••' : '(not set)';
@@ -722,6 +797,49 @@ export class SettingsPanelWidget {
             .map(category => ({ name: category.name, count: counts.get(category.name) || 0 }))
             .filter(category => category.count > 0);
     }
+    /**
+     * The label column, sized once from the labels the pane currently shows
+     * rather than per row, so the value column is straight down the pane.
+     *
+     * The width comes from the current category, not from every setting the
+     * surface holds: a column sized by a category the user is not looking at
+     * would squeeze the values of the one they are.
+     *
+     * The column is the longest label plus the gap, capped so the value keeps
+     * its reserve. Deriving it from the labels means a short-label page
+     * gets a short column — the old fixed 14-cell floor padded every label out and
+     * pushed the values far from their own text.
+     */
+    labelColumnWidth(innerWidth) {
+        const labels = this.categorySettings(this.currentCategoryName())
+            .map(row => row.setting.label);
+        const longest = labels.reduce((widest, label) => Math.max(widest, displayWidth(label)), 0);
+        const room = Math.max(1, innerWidth - SETTINGS_ROW_INDENT);
+        const ceiling = room - SETTINGS_VALUE_COLUMN_GAP - SETTINGS_VALUE_COLUMN_MIN;
+        // The column is the longest label, kept between the floor and the ceiling.
+        // The floor wins over the ceiling: clipping a label costs more than a wide
+        // gap, because the label is the only thing naming the row.
+        return Math.min(Math.max(longest, SETTINGS_LABEL_COLUMN_MIN), Math.max(ceiling, SETTINGS_LABEL_COLUMN_MIN));
+    }
+    /**
+     * One settings row: the cursor, the label in its own column, then the value.
+     *
+     * The value is flush left rather than right-aligned, because pushing it to
+     * the far edge is what separates a label from its own value on a wide frame.
+     * A frame too narrow for both columns keeps the label whole and lets the
+     * value clip, since the label is what identifies the row.
+     */
+    composeRow(label, value, width, focused) {
+        const cursor = `${focused ? '›' : ' '} `.padEnd(SETTINGS_ROW_INDENT);
+        const labelWidth = Math.min(this.labelColumnWidth(width), Math.max(1, width - SETTINGS_ROW_INDENT));
+        const padded = padEndDisplay(clipText(label, labelWidth), labelWidth);
+        const gap = ' '.repeat(SETTINGS_VALUE_COLUMN_GAP);
+        return clipText(`${cursor}${padded}${gap}${value}`, width);
+    }
+    /** One content column: a body row indented to where labels start. */
+    indented(text, width) {
+        return clipText(`${' '.repeat(SETTINGS_ROW_INDENT)}${text}`, width);
+    }
     buildSettingRows(innerWidth) {
         const categoryName = this.currentCategoryName();
         const rows = categoryName ? this.categorySettings(categoryName) : [];
@@ -735,7 +853,7 @@ export class SettingsPanelWidget {
         for (const row of rows) {
             const current = row.setting.name === this.currentSetting()?.name;
             rendered.push({
-                text: joinColumns(`${current ? '›' : ' '} ${row.setting.label}`, this.displayValue(row.setting), innerWidth),
+                text: this.composeRow(row.setting.label, this.displayValue(row.setting), innerWidth, current),
                 focus: current && !this.expandedSetting && !this.editMode,
                 style: current
                     ? { bold: true, inverse: true }
@@ -743,16 +861,16 @@ export class SettingsPanelWidget {
             });
             // A typed row has nowhere else to explain itself, so the focused row
             // carries its own one-line note. The option list explains itself instead.
-            if (current && row.setting.description && this.expandedSetting !== row.setting.name && !this.editMode) {
+            if (!this.isPage() && current && row.setting.description && this.expandedSetting !== row.setting.name && !this.editMode) {
                 rendered.push({
-                    text: clipText(`    ${row.setting.description}`, innerWidth),
+                    text: this.indented(row.setting.description, innerWidth),
                     focus: true,
                     style: { color: TERMINAL_THEME.muted, dimColor: true },
                 });
             }
             if (current && this.captureSetting === row.setting.name) {
                 rendered.push({
-                    text: clipText(`    ${this.captureNotice ?? 'Press a key…'}`, innerWidth),
+                    text: this.indented(this.captureNotice ?? 'Press a key…', innerWidth),
                     focus: true,
                     style: this.captureNotice
                         ? { color: TERMINAL_THEME.attention }
@@ -764,8 +882,13 @@ export class SettingsPanelWidget {
                     const option = row.setting.options[optionIndex];
                     const highlighted = optionIndex === this.expandedOptionIndex;
                     const selected = option.value === row.setting.value || option.label === row.setting.value;
+                    // The marker row and its description share one column: the option
+                    // label sits after `› ● `, and the description lines up under it
+                    // rather than two cells to its left.
+                    const optionGutter = ' '.repeat(SETTINGS_ROW_INDENT);
+                    const optionMarker = `${highlighted ? '›' : ' '} ${selected ? '●' : '○'} `;
                     rendered.push({
-                        text: clipText(`  ${highlighted ? '›' : ' '} ${selected ? '●' : '○'} ${option.label}`, innerWidth),
+                        text: this.indented(`${optionGutter}${optionMarker}${option.label}`, innerWidth),
                         focus: highlighted && !option.description,
                         style: highlighted
                             ? { bold: true, inverse: true }
@@ -773,7 +896,7 @@ export class SettingsPanelWidget {
                     });
                     if (highlighted && option.description) {
                         rendered.push({
-                            text: clipText(`      ${option.description}`, innerWidth),
+                            text: this.indented(`${optionGutter}${' '.repeat(displayWidth(optionMarker))}${option.description}`, innerWidth),
                             focus: true,
                             style: { color: TERMINAL_THEME.muted, dimColor: true },
                         });
@@ -784,7 +907,7 @@ export class SettingsPanelWidget {
                 const value = row.setting.secret ? '•'.repeat(this.editValue.length) : this.editValue;
                 const fallback = !value && row.setting.placeholder ? row.setting.placeholder : '';
                 rendered.push({
-                    text: clipText(`  › ${value || fallback}█`, innerWidth),
+                    text: this.indented(`› ${value || fallback}█`, innerWidth),
                     focus: true,
                     style: { color: TERMINAL_THEME.info, bold: true },
                 });
@@ -839,9 +962,15 @@ export class SettingsPanelWidget {
         if (this.filterMode)
             return 'Type to search · ↵ done · Esc keep · Ctrl+U clear';
         if (this.editMode)
-            return 'Type a value · ↵ save · Esc cancel · Ctrl+U clear';
+            return this.isPage()
+                ? 'Type · ↵ save · Esc cancel'
+                : 'Type a value · ↵ save · Esc cancel · Ctrl+U clear';
         if (this.expandedSetting)
-            return '↑↓ choose · PgUp/PgDn page · ↵ apply · Esc back';
+            return this.isPage()
+                ? '↑↓ choose · ↵ apply · Esc back'
+                : '↑↓ choose · PgUp/PgDn page · ↵ apply · Esc back';
+        if (this.isPage())
+            return '↑↓ move · ↵ edit/select · Esc back';
         return '↑↓ navigate · ←→ category · PgUp/PgDn page · ↵ change · / search · Esc close';
     }
     contextLabel(hiddenAbove, hiddenBelow) {
@@ -868,8 +997,18 @@ export class SettingsPanelWidget {
         // The host embeds the surface in a `paddingX: 1` column, so `cols - 2` is
         // the full usable width. No cap: wide terminals get a wider settings pane
         // rather than dead space beside the frame.
-        const width = Math.max(1, termCols - 2);
-        const desiredRows = Math.max(10, Math.min(22, this.visibleRows.length + 4));
+        const page = this.isPage();
+        // One frame width for every full-page surface, so the settings page lines up
+        // with the pickers: they are opened and dismissed constantly and the user
+        // sees one at a time, so a page drawn at a different width from its
+        // neighbour would shift the frame sideways on every switch. The frame is
+        // flush left, so the spare columns all sit to its right. The cap also keeps
+        // this page's label and value columns close enough to read as one row.
+        const { width, inset } = widgetFrameGeometry(termCols);
+        this.frameInset = inset;
+        const desiredRows = page
+            ? Math.min(22, this.settingIndices().length + 4 + (this.active.notice ? 1 : 0))
+            : Math.max(10, Math.min(22, this.visibleRows.length + 4));
         const height = Math.max(1, Math.floor(maxRows ?? desiredRows));
         const innerWidth = Math.max(0, width - 4);
         const settings = this.settingIndices();
@@ -880,12 +1019,14 @@ export class SettingsPanelWidget {
             return lines;
         if (height === 2)
             return [...lines, bottomBorder(width)];
-        const showUtility = height >= 5;
-        const fixedRows = showUtility ? 4 : 3;
+        const showUtility = !page && height >= 5;
+        const showNotice = page && Boolean(this.active.notice) && height >= 5;
+        const showDetail = page && height >= (showNotice ? 6 : 5);
+        const fixedRows = page ? 3 + Number(showNotice) + Number(showDetail) : showUtility ? 4 : 3;
         const bodyRows = Math.max(0, height - fixedRows);
-        const settingCapacity = Math.max(0, bodyRows - 1);
+        const settingCapacity = Math.max(0, bodyRows - (page ? 0 : 1));
         this.lastBodyRows = Math.max(1, bodyRows);
-        const wide = width >= 70 && bodyRows >= 4;
+        const wide = !page && width >= 70 && bodyRows >= 4;
         const categoryWidth = wide
             ? Math.max(20, Math.min(28, Math.floor(innerWidth * 0.3)))
             : 0;
@@ -906,13 +1047,17 @@ export class SettingsPanelWidget {
                         : { color: TERMINAL_THEME.muted },
                 }], width, TERMINAL_THEME.bgElevated));
         }
+        if (showNotice) {
+            lines.push(framedLine([{ text: clipText(this.active.notice || '', innerWidth),
+                    style: { color: TERMINAL_THEME.error, bold: true } }], width, TERMINAL_THEME.bgElevated));
+        }
         if (bodyRows > 0) {
             const categoryName = this.currentCategoryName();
             const categoryCount = categoryName ? this.categorySettings(categoryName).length : 0;
             const heading = categoryName
                 ? `${categoryName.toUpperCase()} · ${categoryCount} setting${categoryCount === 1 ? '' : 's'}`
                 : (this.filterText ? 'NO MATCHES' : 'SETTINGS');
-            const bodyTop = lines.length - 1;
+            const bodyTop = page ? lines.length : lines.length - 1;
             if (wide) {
                 const categoryOverflow = `${categoryWindow.hiddenAbove > 0 ? `↑${categoryWindow.hiddenAbove}` : ''}${categoryWindow.hiddenBelow > 0 ? `↓${categoryWindow.hiddenBelow}` : ''}`;
                 lines.push(framedLine([
@@ -921,7 +1066,7 @@ export class SettingsPanelWidget {
                     { text: padEndDisplay(clipText(heading, settingsWidth), settingsWidth), style: { color: TERMINAL_THEME.text, bold: true } },
                 ], width, TERMINAL_THEME.bgPanel));
             }
-            else {
+            else if (!page) {
                 lines.push(framedLine([{ text: heading, style: { color: TERMINAL_THEME.text, bold: true } }], width, TERMINAL_THEME.bgPanel));
             }
             for (let index = 0; index < settingCapacity; index++) {
@@ -944,8 +1089,8 @@ export class SettingsPanelWidget {
             // Wide: two columns sharing the body's rows. Narrow: one list, so only
             // the settings band exists.
             const bands = wide
-                ? sideBySideBands(bodyTop, lines.length - 1, categoryWidth, settingsWidth)
-                : { list: null, preview: bodyBand(bodyTop, lines.length - 1, settingsWidth) };
+                ? sideBySideBands(bodyTop, lines.length - 1, categoryWidth, settingsWidth, inset)
+                : { list: null, preview: bodyBand(bodyTop, lines.length - 1, settingsWidth, inset) };
             this.categoryBand = bands.list;
             this.settingsBand = bands.preview;
         }
@@ -954,6 +1099,12 @@ export class SettingsPanelWidget {
             this.categoryBand = null;
             this.settingsBand = null;
         }
+        if (showDetail) {
+            lines.push(framedLine([{
+                    text: clipText(this.currentSetting()?.description || '', innerWidth),
+                    style: { color: TERMINAL_THEME.muted, dimColor: true },
+                }], width, TERMINAL_THEME.bgElevated));
+        }
         while (lines.length < height - 2)
             lines.push(framedLine([], width));
         lines.push(framedLine([{
@@ -996,19 +1147,26 @@ export class SettingsPanelWidget {
     }
     buildSurface(cols, maxRows) {
         const lines = this.buildSurfaceLines(cols, maxRows);
+        // `buildSurfaceLines` records the centring margin as a side effect; the
+        // view re-emits it as a real margin so the painted frame and the wheel
+        // bands agree on which column the surface starts at.
+        const inset = this.frameInset;
+        const frame = box(lines.map(line => box(line.segments.map(segment => text(segment.text, segment.style)), {
+            flexDirection: 'row',
+            height: 1,
+            flexShrink: 0,
+            backgroundColor: line.backgroundColor,
+        })), {
+            flexDirection: 'column',
+            height: lines.length,
+            flexShrink: 0,
+            backgroundColor: TERMINAL_THEME.bg,
+        });
         return {
             content: lines.map(lineText).join('\n'),
-            view: box(lines.map(line => box(line.segments.map(segment => text(segment.text, segment.style)), {
-                flexDirection: 'row',
-                height: 1,
-                flexShrink: 0,
-                backgroundColor: line.backgroundColor,
-            })), {
-                flexDirection: 'column',
-                height: lines.length,
-                flexShrink: 0,
-                backgroundColor: TERMINAL_THEME.bg,
-            }),
+            view: inset > 0
+                ? box([frame], { flexDirection: 'column', marginLeft: inset, flexShrink: 0 })
+                : frame,
             lineCount: lines.length,
         };
     }

package/dist/ui/widgets/status_line_panel.d.ts

@@ -51,6 +51,15 @@ export interface StatusLinePanelSurface {
 export declare class StatusLinePanelWidget {
     private host;
     private active;
+    /**
+     * Column the painted frame starts on, in surface coordinates.
+     *
+     * Zero unless the terminal is wide enough to trigger the shared cap, in which
+     * case it is that centring margin. The wheel bands add it back: a notch lands
+     * in terminal columns, so without it a capped page would scroll from a pane
+     * that is no longer under the pointer.
+     */
+    private frameInset;
     private draft;
     private side;
     private focus;