@pellux/goodvibes-tui 1.19.6 → 1.20.1

package/src/renderer/context-status-hint.ts

@@ -12,34 +12,77 @@
  *  - compacting      → shows in-progress text so the user knows something is running
  *  - watch           → no hint (not yet actionable)
  *  - stable/unknown  → no hint
+ *
+ * Evidence policy (why the guards below exist)
+ * ────────────────────────────────────────────
+ * A fresh boot printed "Context high (0% used) — auto-compact will run before
+ * the next turn." before a single token had been counted. The evaluator was
+ * not at fault: `evaluateSessionMaintenance` reaches 'suggest-compact' when
+ * `remainingTokens <= 15_000`, and at boot the resolved window is still the
+ * SDK's DEFAULT_CONTEXT_WINDOW fallback (8,192 — the "8.2k" the footer meter
+ * shows before the real window arrives), so 8,192 free tokens tripped that
+ * rule instantly. Arithmetically consistent; factually false. No context had
+ * been consumed and no auto-compact was imminent.
+ *
+ * So a pressure claim here has to be backed by evidence, not merely by a
+ * level:
+ *   1. Usage has actually been measured. At zero tokens consumed there is no
+ *      pressure to report, whatever the window says.
+ *   2. The window is one the provider vouched for, not the fallback constant.
+ *      A model whose real window happens to equal the fallback is
+ *      indistinguishable from "not resolved yet", and in that ambiguity
+ *      staying quiet is the honest choice — the Tokens panel and /context
+ *      still show the real numbers either way.
+ * Neither guard touches 'compacting', which reports work that is provably
+ * running rather than a prediction about headroom.
  */
 
+import { DEFAULT_CONTEXT_WINDOW } from '@pellux/goodvibes-sdk/platform/providers';
 import type { PanelSessionMaintenanceLevel } from '../panels/session-maintenance.ts';
 
-export interface ContextStatusHintOptions {
+interface ContextStatusHintOptions {
   /** Maintenance level from evaluateSessionMaintenance. */
   readonly level: PanelSessionMaintenanceLevel;
   /** Whether auto-compaction is active (threshold > 0 in config). */
   readonly autoCompactEnabled: boolean;
   /** Current usage percent 0–100. */
   readonly usagePct: number;
+  /** Tokens actually counted so far this session (orchestrator.lastInputTokens). */
+  readonly currentTokens: number;
+  /** The resolved context window the usage percent was computed against. */
+  readonly contextWindow: number;
+}
+
+/**
+ * Whether the numbers backing a pressure claim are real yet: usage has been
+ * counted, and the window is not the provider fallback the app boots with.
+ */
+function hasRealContextNumbers(
+  options: Pick<ContextStatusHintOptions, 'currentTokens' | 'contextWindow' | 'usagePct'>,
+): boolean {
+  if (options.currentTokens <= 0 || options.usagePct <= 0) return false;
+  if (options.contextWindow <= 0 || options.contextWindow === DEFAULT_CONTEXT_WINDOW) return false;
+  return true;
 }
 
 /**
  * Build the passive status-line hint text for context pressure.
  *
- * Returns null when no hint is warranted (stable / watch / unknown).
- * The caller renders this as a dim informational line — no prompts, no
- * blocking, no confirmation required.
+ * Returns null when no hint is warranted (stable / watch / unknown), and also
+ * when a pressure level is not yet backed by real numbers — see the evidence
+ * policy above. The caller renders this as a dim informational line — no
+ * prompts, no blocking, no confirmation required.
  */
-export function buildContextStatusHint(options: ContextStatusHintOptions): string | null {
+function buildContextStatusHint(options: ContextStatusHintOptions): string | null {
   const { level, autoCompactEnabled, usagePct } = options;
 
   switch (level) {
     case 'needs-repair':
+      if (!hasRealContextNumbers(options)) return null;
       return `  Context pressure critical (${usagePct}% used) — compaction needs attention. Run /compact or /health review.`;
 
     case 'suggest-compact':
+      if (!hasRealContextNumbers(options)) return null;
       if (autoCompactEnabled) {
         return `  Context high (${usagePct}% used) — auto-compact will run before the next turn.`;
       }
@@ -52,3 +95,28 @@ export function buildContextStatusHint(options: ContextStatusHintOptions): strin
       return null;
   }
 }
+
+/**
+ * Evaluate session maintenance and turn it into the footer hint in one call.
+ * The ONE public seam of this module, deliberately: the guards above need the
+ * exact `currentTokens` / `contextWindow` the evaluator was handed, and a
+ * caller free to pass different values to each half is how they drift apart.
+ */
+export function resolveContextStatusHint(input: {
+  readonly evaluate: (args: { readonly currentTokens: number; readonly contextWindow: number }) => {
+    readonly level: PanelSessionMaintenanceLevel;
+    readonly autoCompactEnabled: boolean;
+    readonly usagePct: number;
+  };
+  readonly currentTokens: number;
+  readonly contextWindow: number;
+}): string | null {
+  const status = input.evaluate({ currentTokens: input.currentTokens, contextWindow: input.contextWindow });
+  return buildContextStatusHint({
+    level: status.level,
+    autoCompactEnabled: status.autoCompactEnabled,
+    usagePct: status.usagePct,
+    currentTokens: input.currentTokens,
+    contextWindow: input.contextWindow,
+  });
+}

package/src/renderer/conversation-layout.ts

@@ -38,6 +38,22 @@ export function buildConversationViewport(
   };
 }
 
+/**
+ * Absolute history-line index of the bottom-most visible row of the
+ * conversation viewport. The buffer bottom-aligns content shorter than the
+ * viewport (InfiniteBuffer.getSnapshot pads with blank lines at the TOP, not
+ * the bottom — see history.ts), so the naive `scrollTop + viewportHeight - 1`
+ * overshoots past the real last line whenever the whole transcript already
+ * fits on screen. Clamping to `lineCount - 1` handles both cases with one
+ * formula: when scrollLocked at the true bottom (the common case), this is
+ * exactly the last rendered content line — the block the user is actually
+ * looking at, not whatever sits at the TOP of the viewport (scrollTop alone).
+ */
+export function getViewportBottomLine(scrollTop: number, viewportHeight: number, lineCount: number): number {
+  if (lineCount <= 0) return 0;
+  return Math.max(0, Math.min(scrollTop + viewportHeight - 1, lineCount - 1));
+}
+
 export function overlayViewportBottom(
   viewport: readonly Line[],
   overlay: readonly Line[],

package/src/renderer/conversation-overlays.ts

@@ -16,6 +16,7 @@ import { renderSessionPickerModal } from './session-picker-modal.ts';
 import { renderProfilePickerModal } from './profile-picker-modal.ts';
 import { renderBookmarkModal } from './bookmark-modal.ts';
 import { renderHelpOverlay, renderShortcutsOverlay } from './help-overlay.ts';
+import { renderBlockActionsMenu } from './block-actions-overlay.ts';
 import { renderAutocompleteOverlay } from './autocomplete-overlay.ts';
 import { renderOnboardingWizard } from './onboarding/onboarding-wizard.ts';
 import { overlayViewportBottom, replaceViewportWithOverlay } from './conversation-layout.ts';
@@ -118,6 +119,11 @@ export function applyConversationOverlays(
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
+  if (!fullscreenClaimed && input.blockActionsMenu.active) {
+    const lines = renderBlockActionsMenu(input.blockActionsMenu, conversationWidth, viewportHeight);
+    next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
+  }
+
   if (input.helpOverlayActive) {
     const lines = renderHelpOverlay(conversationWidth, keybindingsManager, commandRegistry.getAll(), input.helpScrollOffset, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);

package/src/renderer/header-line.ts

@@ -0,0 +1,146 @@
+/**
+ * header-line.ts — the top-of-screen header row: brand, version, optional
+ * conversation title, optional git segment, and the right-hand model/provider
+ * pair.
+ *
+ * Extracted from ui-factory.ts (which sits on the 800-line source gate) when
+ * the header gained the failover divergence marker. `UIFactory.createHeader`
+ * remains the call name everywhere and delegates here.
+ *
+ * The model/provider pair rendered here is the SERVING backend, resolved by
+ * core/active-model-identity.ts — the same resolution the footer uses, so the
+ * two surfaces can no longer disagree about who is answering. `note` carries
+ * the divergence marker naming the user's configured selection when serving
+ * has moved off it.
+ */
+
+import { type Line, createEmptyLine } from '../types/grid.ts';
+import { VERSION } from '../version.ts';
+import { getDisplayWidth } from '../utils/terminal-width.ts';
+import type { GitHeaderInfo } from './git-status.ts';
+import { activeUiTones } from './theme.ts';
+
+/** Build the git segment string and its display width. Single source of truth for header layout. */
+function buildGitSegment(gitInfo: GitHeaderInfo): { text: string; width: number } {
+  const branch = ` git:${gitInfo.branch}`;
+  if (gitInfo.dirty) {
+    const text = `${branch} * `;
+    return { text, width: getDisplayWidth(text) };
+  }
+  if (gitInfo.ahead > 0 || gitInfo.behind > 0) {
+    const arrows = (gitInfo.ahead > 0 ? ` +${gitInfo.ahead}` : '') + (gitInfo.behind > 0 ? ` -${gitInfo.behind}` : '');
+    const text = `${branch}${arrows} `;
+    return { text, width: getDisplayWidth(text) };
+  }
+  const text = `${branch} `;
+  return { text, width: getDisplayWidth(text) };
+}
+
+/**
+ * Pick the widest divergence marker that still fits beside the brand and the
+ * model/provider pair.
+ *
+ * Graded, never truncated mid-word: the full marker (which names the
+ * configured selection) is preferred; a bare "divergent" keyword is the
+ * fallback on a narrow terminal; on a very narrow terminal the marker is
+ * dropped entirely. Dropping it is safe — what remains is still the SERVING
+ * backend, so the header never claims the configured backend is answering.
+ * The footer carries the full marker with far more room (see ui-factory's
+ * prioritized context segments).
+ */
+function fitHeaderNote(note: string, usedWidth: number, width: number): string {
+  if (!note) return '';
+  const full = `· ${note} `;
+  if (usedWidth + getDisplayWidth(full) <= width) return full;
+  const short = '· divergent ';
+  return usedWidth + getDisplayWidth(short) <= width ? short : '';
+}
+
+/**
+ * Render the header row plus its underline.
+ *
+ * @param width    - Terminal columns.
+ * @param model    - Serving model id (already resolved; see file doc).
+ * @param provider - Serving provider id.
+ * @param title    - Optional conversation title, truncated to fit.
+ * @param gitInfo  - Optional git branch/dirty/ahead-behind segment.
+ * @param version  - Defaults to the live build VERSION; tests pass a pinned
+ *                   fixture so golden snapshots survive release bumps.
+ * @param note     - Divergence marker naming the configured selection when the
+ *                   serving backend is not the one the user chose; '' otherwise.
+ */
+export function renderHeaderLine(
+  width: number,
+  model: string,
+  provider: string,
+  title?: string,
+  gitInfo?: GitHeaderInfo,
+  version: string = VERSION,
+  note: string = '',
+): Line[] {
+  const lines: Line[] = [];
+  // Header/footer/thinking paint on the transparent terminal background, so
+  // they read chrome.* (light-terminal-aware) — NOT fg.*/state.*, which stay
+  // tuned for the opaque dark modal/panel boxes. Read live per render so a
+  // mode flip re-resolves without any module reload (see theme.ts).
+  const t = activeUiTones();
+  const CYAN = t.accent.brand;
+  const GREY = t.chrome.faint;
+  const TITLE_COLOR = t.chrome.label;
+  const brand = ` GoodVibes `;
+  const ver = `v${version} `;
+  const stats = ` ${model} `;
+  const prov = `(${provider}) `;
+  const gitWidth = gitInfo ? buildGitSegment(gitInfo).width : 0;
+  // Resolve the marker before the title so the title's fit calculation
+  // reserves room for it too.
+  const noteStr = fitHeaderNote(note, getDisplayWidth(brand + ver + stats + prov) + gitWidth, width);
+  const line = createEmptyLine(width);
+  let curX = 0;
+  for (const char of brand) { line[curX++] = { char, fg: CYAN, bg: '', bold: true, dim: false, underline: false, italic: false, strikethrough: false }; }
+  for (const char of ver) { line[curX++] = { char, fg: GREY, bg: '', bold: false, dim: true, underline: false, italic: false, strikethrough: false }; }
+  // Optional conversation title — shown after brand/ver, truncated to fit
+  if (title) {
+    const titleStr = `│ ${title} `;
+    // Reserve space for git info (if present) + model/provider + marker on the right
+    const rightReserved = getDisplayWidth(stats + prov + noteStr) + gitWidth;
+    const maxTitleW = width - curX - rightReserved - 1;
+    let displayTitle: string;
+    if (getDisplayWidth(titleStr) <= maxTitleW) {
+      displayTitle = titleStr;
+    } else {
+      let truncated = '';
+      let w = 0;
+      for (const ch of titleStr) {
+        const cw = getDisplayWidth(ch);
+        if (w + cw > maxTitleW - 3) { truncated += '...'; break; }
+        truncated += ch;
+        w += cw;
+      }
+      displayTitle = truncated;
+    }
+    for (const char of displayTitle) { if (curX < width) line[curX++] = { char, fg: TITLE_COLOR, bg: '', bold: false, dim: true, underline: false, italic: false, strikethrough: false }; }
+  }
+  // Build git info segment
+  let gitStr = '';
+  let gitFg: string = t.chrome.faint;
+  if (gitInfo) {
+    gitStr = buildGitSegment(gitInfo).text;
+    if (gitInfo.dirty || gitInfo.ahead > 0 || gitInfo.behind > 0) {
+      gitFg = t.chrome.warn; // yellow when dirty or out-of-sync
+    }
+  }
+  const rightSideW = getDisplayWidth(stats + prov + noteStr) + getDisplayWidth(gitStr);
+  let rightX = width - rightSideW;
+  for (const char of gitStr) { if (rightX >= 0 && rightX < width) line[rightX++] = { char, fg: gitFg, bg: '', bold: false, dim: !gitInfo?.dirty && !(gitInfo?.ahead || gitInfo?.behind), underline: false, italic: false, strikethrough: false }; }
+  for (const char of stats) { if (rightX < width) line[rightX++] = { char, fg: CYAN, bg: '', bold: true, dim: false, underline: false, italic: false, strikethrough: false }; }
+  for (const char of prov) { if (rightX < width) line[rightX++] = { char, fg: GREY, bg: '', bold: false, dim: true, underline: false, italic: false, strikethrough: false }; }
+  // The marker reads as a warning, not as chrome: serving has left the
+  // selection the user made and that is worth noticing.
+  for (const char of noteStr) { if (rightX >= 0 && rightX < width) line[rightX++] = { char, fg: t.chrome.warn, bg: '', bold: false, dim: false, underline: false, italic: false, strikethrough: false }; }
+  lines.push(line);
+  const underline = createEmptyLine(width);
+  for (let x = 0; x < width; x++) underline[x] = { char: '━', fg: t.chrome.faint, bg: '', bold: false, dim: false, underline: false, italic: false, strikethrough: false };
+  lines.push(underline);
+  return lines;
+}

package/src/renderer/help-overlay.ts

@@ -1,7 +1,9 @@
 /**
  * renderHelpOverlay — renders the help overlay with keyboard shortcuts and slash commands.
  *
- * Toggle with `?` key or `/help` command.
+ * Opened via `/commands`. `?` and `/help` open the searchable command
+ * browser (a selection modal that runs the picked command) instead — they
+ * are a different, complementary surface, not this one.
  */
 
 import { type Line } from '../types/grid.ts';
@@ -68,22 +70,27 @@ export function renderHelpOverlay(
   const shortcutRows: string[] = [
     '  Core Navigation',
     '  ' + '\u2500'.repeat(40),
-    `  ${'Up / Down'.padEnd(20)}  Scroll / history recall`,
+    `  ${'Up / Down'.padEnd(20)}  Recall input history; Down at bottom focuses the process indicator`,
     `  ${'PageUp / PageDn'.padEnd(20)}  Scroll by full page`,
     `  ${kb('search').padEnd(20)}  Search conversation (Ctrl+F)`,
     '',
     '  Prompt And Editing',
     '  ' + '\u2500'.repeat(40),
-    `  ${'Enter'.padEnd(20)}  Submit message`,
+    `  ${'Enter'.padEnd(20)}  Submit message (composer empty: open the block-actions menu)`,
     `  ${'Shift+Enter'.padEnd(20)}  Insert newline`,
     `  ${kb('paste').padEnd(20)}  Paste (image priority)`,
     `  ${(kb('undo') + ' / ' + kb('redo')).padEnd(20)}  Undo / redo`,
+    shortcutLine('(paste >8 lines)', 'Folds to [TEXT: pN, M lines] — /pastes previews it before you submit'),
     '',
     '  Overlays And Panels',
     '  ' + '\u2500'.repeat(40),
-    shortcutLine('?', 'Toggle help'),
-    shortcutLine('/shortcuts', 'Full keyboard shortcuts'),
-    shortcutLine('Tab', 'Swap focus between input and workspace'),
+    shortcutLine('?  or  /help', 'Open the command browser (search & run any command)'),
+    shortcutLine('/commands', 'This reference: keyboard shortcuts + full command list'),
+    shortcutLine('/shortcuts', 'Keyboard-shortcuts-only reference (a separate, generated overlay)'),
+    // Precedence (highest first): a visible panel workspace claims Tab for
+    // focus-swap; failing that, a partial path under the cursor claims it for
+    // completion; only then does it fall through to collapse/expand.
+    shortcutLine('Tab', 'Panel focus-swap, else path-complete, else collapse/expand block'),
     ...panelBindingRows,
     '',
     // The shared in-panel contract every workspace panel honors. These are not
@@ -149,7 +156,7 @@ export function renderHelpOverlay(
     ['sessions',    'Browse and resume saved sessions'],
     ['save',        'Save the current session'],
     ['compact',     'Compact the conversation history'],
-    ['clear',       'Clear the conversation'],
+    ['clear',       'Clear the conversation display (keeps LLM context)'],
     ['keybindings', 'List and customize key bindings'],
     ['panel',       'Open, focus, or manage panels'],
   ];
@@ -197,10 +204,11 @@ export function renderHelpOverlay(
     }
   } else if (!hasCommand('help')) {
     commandRows.push('', '  Essentials', '  ' + '\u2500'.repeat(40));
-    commandRows.push('  /help               Show this help overlay');
+    commandRows.push('  /commands           Show this help overlay');
+    commandRows.push('  /help               Browse & run any command');
     commandRows.push('  /shortcuts          Keyboard shortcut reference');
     commandRows.push('  /model              Select LLM model');
-    commandRows.push('  /clear              Clear conversation');
+    commandRows.push('  /clear              Clear the conversation display (keeps LLM context)');
   }
 
   const allRows = [...shortcutRows, ...commandRows];
@@ -255,61 +263,69 @@ export function renderShortcutsOverlay(
     return `  ${keyCol}  ${desc}`;
   }
 
-  // Helper: get the label for a bindable action, falling back to literal string.
-  const kb = (action: Parameters<typeof keybindingsManager.getComboLabel>[0]) => keybindingsManager.getComboLabel(action);
+  // Keys that are real, but not KeyAction entries in keybindingsManager
+  // (context-dependent chords, or literal characters rather than bindable
+  // actions) \u2014 a maintained table rather than hand-picked getAll() calls, so
+  // adding a new KeyAction automatically shows up below without anyone
+  // remembering to also add a row for it here.
+  const HARDCODED_ROWS: ReadonlyArray<[key: string, desc: string]> = [
+    ['Up / Down', 'Recall input history; Down at bottom focuses the process indicator'],
+    ['PageUp / PageDn', 'Scroll by full page'],
+    ['Home / End', 'Jump to start / end of line'],
+    ['n / N (search)', 'Next / previous match'],
+    ['Mouse wheel', 'Scroll conversation or hovered panel'],
+    ['Enter', 'Submit message (composer empty: open the block-actions menu)'],
+    ['Shift+Enter', 'Insert newline'],
+    ['@', 'Open file picker'],
+    ['/', 'Slash command mode'],
+    ['Esc', 'Close overlay / cancel generation / clear prompt (context-dependent)'],
+    ['Shift+Tab', 'Cycle permission mode (auto-approve / prompt / manual)'],
+    ['F2', 'Open the Fleet panel'],
+    ['?  or  /help', 'Open the command browser (search & run any command)'],
+    // Precedence (highest first): panel focus-swap, else path-completion,
+    // else collapse/expand \u2014 see the Panels section's Tab row below for the
+    // full chain; this row is the "what does it do here" short form.
+    ['Tab', 'Collapse/expand block (composer empty \u2014 see Panels: Tab for full precedence)'],
+  ];
+
+  const IN_PANEL_ROWS: ReadonlyArray<[key: string, desc: string]> = [
+    ['j / k', 'Move selection down / up'],
+    ['g / G', 'Jump to top / bottom'],
+    ['/', 'Filter the list'],
+  ];
+
+  // Generated from the live keybindings table (default bindings AND any user
+  // overrides) so this listing can never drift from what a key actually
+  // does \u2014 no action is hand-picked, none can be silently missed.
+  const allBindings = keybindingsManager.getAll();
+  const panelActionRows = allBindings
+    .filter((entry) => entry.action.startsWith('panel-'))
+    .map((entry) => row(entry.combos.map((c) => keybindingsManager.formatCombo(c)).join(', '), entry.description));
+  const otherActionRows = allBindings
+    .filter((entry) => !entry.action.startsWith('panel-'))
+    .map((entry) => row(entry.combos.map((c) => keybindingsManager.formatCombo(c)).join(', '), entry.description));
 
   const allRows: string[] = [
-    '  Navigation',
-    '  ' + '\u2500'.repeat(40),
-    row('Up / Down', 'Scroll / history recall'),
-    row('PageUp / PageDn', 'Scroll by full page'),
-    row('Home / End', 'Jump to start / end of line'),
-    row(kb('search'), 'Search conversation'),
-    row('n / N (search)', 'Next / previous match'),
-    row('Mouse wheel', 'Scroll conversation or hovered panel'),
-    '',
-    '  Editing',
+    '  Navigation & Editing',
     '  ' + '\u2500'.repeat(40),
-    row('Enter', 'Submit message'),
-    row('Shift+Enter', 'Insert newline'),
-    row('@', 'Open file picker'),
-    row('/', 'Slash command mode'),
-    row(kb('paste'), 'Paste (image priority)'),
-    row(`${kb('undo')} / ${kb('redo')}`, 'Undo / redo'),
-    row(kb('clear-prompt'), 'Clear prompt'),
-    row(kb('delete-word'), 'Delete word backward'),
-    row(kb('kill-line'), 'Kill to end of line'),
-    row(kb('apply-diff-line-start'), 'Apply diff / line start'),
-    row(kb('next-error-line-end'), 'Next error / line end'),
+    ...HARDCODED_ROWS.map(([key, desc]) => row(key, desc)),
     '',
-    '  Actions',
+    '  Actions & Shortcuts (customize via /keybindings)',
     '  ' + '\u2500'.repeat(40),
-    row('Tab', 'Collapse/expand block'),
-    row(kb('bookmark'), 'Bookmark block'),
-    row(kb('block-copy'), 'Copy block to clipboard'),
-    row(kb('block-save'), 'Save block to file'),
-    row(kb('copy-selection'), 'Copy selection'),
-    row('F2', 'Open the Fleet panel'),
-    row('?', 'Help overlay'),
-    row(`${kb('clear-cancel')} x2`, 'Exit'),
+    ...otherActionRows,
     '',
     '  Panels',
     '  ' + '\u2500'.repeat(40),
-    row('Tab', 'Swap focus between input and panel workspace'),
-    row(kb('panel-picker'), 'Open / focus / hide panel workspace'),
-    row(kb('panel-tab-next'), 'Next workspace panel tab'),
-    row(kb('panel-tab-prev'), 'Previous workspace panel tab'),
-    row(`${kb('panel-tab-1')}\u2026${kb('panel-tab-9')}`, 'Jump to workspace tab 1-9'),
-    row(kb('panel-focus-toggle'), 'Swap focus between top / bottom pane'),
-    row(kb('panel-close'), 'Close active panel'),
-    row(kb('panel-close-all'), 'Close all panels'),
-    row(kb('panel-ops'), 'Open and focus the Fleet panel'),
+    // Full Tab precedence, stated once here as the authoritative chain: a
+    // visible panel workspace claims Tab for focus-swap first; failing that,
+    // a partial path under the cursor claims it for completion; only then
+    // does it fall through to collapse/expand (the Actions section's row).
+    row('Tab', 'Panel focus-swap (1st) > path-complete (2nd) > collapse/expand block (3rd)'),
+    ...panelActionRows,
     '',
     '  In-Panel Controls',
     '  ' + '\u2500'.repeat(40),
-    row('j / k', 'Move selection down / up'),
-    row('g / G', 'Jump to top / bottom'),
-    row('/', 'Filter the list'),
+    ...IN_PANEL_ROWS.map(([key, desc]) => row(key, desc)),
     '',
     `  Config: /keybindings to list and customize`,
   ];

package/src/renderer/selection-modal-overlay.ts

@@ -69,6 +69,41 @@ function rowCostFor(item: SelectionItem, remaining: number): number {
   return 1 + (computeDetailLayout(item, remaining).wrappedDetail?.length ?? 0);
 }
 
+const MODAL_MARGIN = 4;
+const MODAL_MAX_WIDTH = 72;
+const INDICATOR_WIDTH = 2;
+/** Rows kept clear between the box and the top/bottom of the terminal. */
+const VIEWPORT_INSET_ROWS = 2;
+
+/**
+ * Rows the box spends on its own frame, counted as they are actually pushed
+ * below: top and bottom border, the title, the section row (a search label,
+ * search input and divider when the modal searches), the "Results" header and
+ * the footer hint. `chromeRows` is the budget-math constant the surface
+ * metrics subtract from a total; this is the physical count, and it is what
+ * decides how tall the box may really grow.
+ */
+function frameRowsFor(modal: SelectionModal): number {
+  return modal.allowSearch ? 8 : 6;
+}
+
+/**
+ * Physical rows every row of the list needs, category headers included — the
+ * height the box would have to give the list for nothing to be scrolled away.
+ */
+function totalContentRowsFor(modal: SelectionModal, remaining: number): number {
+  let rows = 0;
+  let lastCategory: string | undefined;
+  for (const item of modal.filteredItems) {
+    if (item.category && item.category !== lastCategory) {
+      lastCategory = item.category;
+      rows += 1;
+    }
+    rows += rowCostFor(item, remaining);
+  }
+  return rows;
+}
+
 /**
  * Render the selection modal as Line[] for overlay in the viewport.
  */
@@ -79,9 +114,29 @@ export function renderSelectionModalOverlay(
 ): Line[] {
   const lines: Line[] = [];
   const chromeRows = modal.allowSearch ? 5 : 4;
+  // Width does not depend on the row budget, so the box layout is settled
+  // first: the list's real height can only be measured once the wrap width is
+  // known. `createOverlayBoxLayout` resolves the requested max width the same
+  // way `getOverlaySurfaceMetrics` does, so both agree on the box.
+  const layout = createOverlayBoxLayout(width, MODAL_MARGIN, MODAL_MAX_WIDTH);
+  const remaining = layout.innerWidth - INDICATOR_WIDTH;
+
+  // Size to content before falling back to the viewport's height ratio. When
+  // every row (and its wrapped detail) fits in the space the terminal
+  // actually has, ask for exactly that many rows, so a short list is never
+  // split behind a "(n below)" hint with screen still empty below the box —
+  // a two-item question in particular must always show both its answers. A
+  // list genuinely taller than the terminal keeps the ratio-derived budget
+  // and scrolls as before.
+  const neededContentRows = totalContentRowsFor(modal, remaining);
+  const fittableContentRows = viewportHeight - VIEWPORT_INSET_ROWS - frameRowsFor(modal);
+  const growToFitTotalRows = neededContentRows > 0 && neededContentRows <= fittableContentRows
+    ? neededContentRows + chromeRows
+    : undefined;
+
   const metrics = getOverlaySurfaceMetrics(width, viewportHeight, {
-    margin: 4,
-    maxWidth: 72,
+    margin: MODAL_MARGIN,
+    maxWidth: MODAL_MAX_WIDTH,
     chromeRows,
     minContentRows: 6,
     // Modals size to content: items whose detail wraps onto extra lines can
@@ -89,8 +144,11 @@ export function renderSelectionModalOverlay(
     // ceiling grows with the viewport rather than staying pinned at a small
     // constant (still bounded — never larger than the terminal can show).
     maxContentRows: Math.max(10, viewportHeight - chromeRows - 4),
+    // A floor only. The shared budget keeps its own target and ceiling, so a
+    // modal whose content is shorter than that target is unaffected: this can
+    // raise the budget to fit the list, never lower it.
+    minTotalRows: growToFitTotalRows,
   });
-  const layout = createOverlayBoxLayout(width, metrics.margin, metrics.boxWidth);
 
   lines.push(createOverlayFilledBorderLine(width, layout, OVERLAY_GLYPHS.topLeft, OVERLAY_GLYPHS.horizontal, OVERLAY_GLYPHS.topRight, BORDER_FG, DEFAULT_OVERLAY_PALETTE.titleBg));
 
@@ -143,8 +201,6 @@ export function renderSelectionModalOverlay(
     putText(line, layout.margin + 2, layout.innerWidth, fitDisplay(message, layout.innerWidth), { fg: MUTED_FG, dim: true });
     lines.push(line);
   } else {
-    const indicatorWidth = 2;
-    const remaining = layout.innerWidth - indicatorWidth;
     const rowBudget = Math.max(1, metrics.contentRows);
 
     // Row-budget-aware windowing: rather than assuming one physical row per
@@ -210,12 +266,12 @@ export function renderSelectionModalOverlay(
       const detailLayout = computeDetailLayout(item, remaining);
       const labelWidth = detailLayout.labelWidth;
       const labelLine = createOverlayContentLine(width, layout, BORDER_FG, isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg);
-        putText(labelLine, layout.margin + 2, indicatorWidth, indicator, {
+        putText(labelLine, layout.margin + 2, INDICATOR_WIDTH, indicator, {
           fg: isSelected ? TITLE_FG : MUTED_FG,
           bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
           bold: isSelected,
         });
-      putText(labelLine, layout.margin + 2 + indicatorWidth, labelWidth, fitDisplay(truncateDisplay(item.label, labelWidth), labelWidth), {
+      putText(labelLine, layout.margin + 2 + INDICATOR_WIDTH, labelWidth, fitDisplay(truncateDisplay(item.label, labelWidth), labelWidth), {
         fg: labelColor,
         bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
         bold: isSelected,
@@ -223,11 +279,11 @@ export function renderSelectionModalOverlay(
       if (item.detail) {
         if (detailLayout.wrappedDetail === null) {
           // Fits beside the label at a readable width — no truncation needed.
-          putText(labelLine, layout.margin + 2 + indicatorWidth + labelWidth, 2, '  ', {
+          putText(labelLine, layout.margin + 2 + INDICATOR_WIDTH + labelWidth, 2, '  ', {
             fg: BODY_FG,
             bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
           });
-          putText(labelLine, layout.margin + 2 + indicatorWidth + labelWidth + 2, detailLayout.detailWidth, fitDisplay(item.detail, detailLayout.detailWidth), {
+          putText(labelLine, layout.margin + 2 + INDICATOR_WIDTH + labelWidth + 2, detailLayout.detailWidth, fitDisplay(item.detail, detailLayout.detailWidth), {
             fg: detailColor,
             bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
           });
@@ -238,7 +294,7 @@ export function renderSelectionModalOverlay(
           lines.push(labelLine);
           for (const detailLineText of detailLayout.wrappedDetail) {
             const detailLine = createOverlayContentLine(width, layout, BORDER_FG, isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg);
-            putText(detailLine, layout.margin + 2 + indicatorWidth, remaining, fitDisplay(detailLineText, remaining), {
+            putText(detailLine, layout.margin + 2 + INDICATOR_WIDTH, remaining, fitDisplay(detailLineText, remaining), {
               fg: detailColor,
               bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
               dim: !isSelected,