@pellux/goodvibes-tui 0.18.4

package/src/renderer/help-overlay.ts

@@ -0,0 +1,247 @@
+/**
+ * renderHelpOverlay — renders the help overlay with keyboard shortcuts and slash commands.
+ *
+ * Toggle with `?` key or `/help` command.
+ */
+
+import { type Line } from '@pellux/goodvibes-sdk/platform/types/grid';
+import { ModalFactory } from './modal-factory.ts';
+import type { SlashCommand } from '../input/command-registry.ts';
+import type { KeybindingsManager } from '../input/keybindings.ts';
+import { getOverlaySurfaceMetrics } from './overlay-viewport.ts';
+import { getVisibleWindow } from './surface-layout.ts';
+
+function toModalSections(rows: readonly string[]): import('./modal-factory.ts').ModalSection[] {
+  return rows.map((row) => {
+    if (row === '') return { type: 'spacer' as const };
+    if (row.startsWith('  ') && !row.slice(2).includes('  ')) {
+      return { type: 'title' as const, content: row.trim() };
+    }
+    if (row.startsWith('  \u2500')) return { type: 'separator' as const };
+    return { type: 'text' as const, content: row };
+  });
+}
+
+/**
+ * Render the help overlay as Line[].
+ * Shows keyboard shortcuts summary and slash commands.
+ *
+ * @param width      Terminal width.
+ * @param commands   List of registered slash commands.
+ * @param scrollOffset  Number of lines scrolled (for navigation).
+ */
+export function renderHelpOverlay(
+  width: number,
+  keybindingsManager: KeybindingsManager,
+  commands?: SlashCommand[],
+  scrollOffset = 0,
+  viewportHeight = process.stdout.rows || 24,
+): Line[] {
+  const kb = (action: Parameters<typeof keybindingsManager.getComboLabel>[0]) => keybindingsManager.getComboLabel(action);
+
+  const hasCommand = (name: string): boolean => Boolean(commands?.some((command) => command.name === name || (command.aliases ?? []).includes(name)));
+
+  // Keyboard shortcut sections
+  const shortcutRows: string[] = [
+    '  Core Navigation',
+    '  ' + '\u2500'.repeat(40),
+    `  ${'Up / Down'.padEnd(20)}  Scroll / history recall`,
+    `  ${'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`,
+    `  ${'Shift+Enter'.padEnd(20)}  Insert newline`,
+    `  ${kb('paste').padEnd(20)}  Paste (image priority)`,
+    `  ${(kb('undo') + ' / ' + kb('redo')).padEnd(20)}  Undo / redo`,
+    '',
+    '  Overlays And Panels',
+    '  ' + '\u2500'.repeat(40),
+    `  ${'?'.padEnd(20)}  Toggle help`,
+    `  ${'/shortcuts'.padEnd(20)}  Full keyboard shortcuts`,
+    `  ${kb('panel-picker').padEnd(20)}  Open or focus the panel workspace`,
+    '',
+  ];
+
+  const commandRows: string[] = [
+    '  Quick Start',
+    '  ' + '\u2500'.repeat(40),
+    '  /setup onboarding     Guided first-run review and environment posture',
+    '  /cockpit              Unified runtime control room',
+    '  /settings             Settings and config browser',
+    '',
+    '  Build And Operate',
+    '  ' + '\u2500'.repeat(40),
+    '  /provider             Choose provider or model family',
+    '  /subscription         Review provider logins and subscriptions',
+    '  /marketplace open     Browse plugins, skills, and packs',
+    '  /remote setup         Review remote, bridge, and tunnel flows',
+    '  /sandbox review       Inspect secure execution posture',
+    '',
+    '  Review And Govern',
+    '  ' + '\u2500'.repeat(40),
+    '  /security             Security review workspace',
+    '  /policy               Simulation, lint, and preflight review',
+    '  /incident             Incident workspace and export flows',
+    '  /knowledge            Durable knowledge and review queue',
+    '',
+    '  Power Surfaces',
+    '  ' + '\u2500'.repeat(40),
+    '  /hooks                Hook workbench and runtime activity',
+    '  /orchestration        Graph and recursive-agent control room',
+    '  /communication        Structured agent communication workspace',
+    '  /tasks                Task surface for list/show/pause/resume/output',
+  ];
+
+  if (commands && commands.length > 0) {
+    commandRows.push('', '  Available Slash Commands', '  ' + '\u2500'.repeat(40));
+    const preferred = ['setup', 'cockpit', 'settings', 'provider', 'subscription', 'marketplace', 'remote', 'sandbox', 'security', 'policy', 'incident', 'knowledge', 'hooks', 'orchestration', 'communication', 'tasks'];
+    const seen = new Set<string>();
+    for (const name of preferred) {
+      const cmd = commands.find((entry) => entry.name === name);
+      if (!cmd) continue;
+      seen.add(cmd.name);
+      const nameCol = `/${cmd.name}`.padEnd(18);
+      commandRows.push(`  ${nameCol}  ${cmd.description}`);
+    }
+    const remainder = [...commands]
+      .filter((cmd) => !seen.has(cmd.name))
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .slice(0, 24);
+    if (remainder.length > 0) {
+      commandRows.push('', '  More Commands', '  ' + '\u2500'.repeat(40));
+      for (const cmd of remainder) {
+        const nameCol = `/${cmd.name}`.padEnd(18);
+        commandRows.push(`  ${nameCol}  ${cmd.description}`);
+      }
+    }
+  } else if (!hasCommand('help')) {
+    commandRows.push('', '  Essentials', '  ' + '\u2500'.repeat(40));
+    commandRows.push('  /help               Show this help overlay');
+    commandRows.push('  /shortcuts          Keyboard shortcut reference');
+    commandRows.push('  /model              Select LLM model');
+    commandRows.push('  /clear              Clear conversation');
+  }
+
+  const allRows = [...shortcutRows, ...commandRows];
+
+  // Apply scroll offset — show a window of rows
+  const metrics = getOverlaySurfaceMetrics(width, viewportHeight, {
+    chromeRows: 4,
+    minContentRows: 8,
+    maxContentRows: 12,
+  });
+  const maxVisible = metrics.contentRows;
+  const clampedOffset = Math.max(0, Math.min(scrollOffset, Math.max(0, allRows.length - maxVisible)));
+  const visibleRows = allRows.slice(clampedOffset, clampedOffset + maxVisible);
+  const window = getVisibleWindow(allRows.length, clampedOffset, maxVisible);
+
+  return ModalFactory.createModal(
+    {
+      title: 'Help',
+      width: metrics.boxWidth,
+      margin: metrics.margin,
+      targetContentRows: metrics.contentRows,
+      tabs: [
+        { label: 'Overview', active: true },
+        { label: 'Commands' },
+      ],
+      sections: toModalSections(visibleRows),
+      helpers: allRows.length > maxVisible
+        ? [{ content: `[${window.start + 1}-${Math.min(allRows.length, clampedOffset + visibleRows.length)} of ${allRows.length}]` }]
+        : undefined,
+      hints: ['? or Esc Close', 'Up/Down Scroll'],
+    },
+    width,
+  );
+}
+
+/**
+ * renderShortcutsOverlay — renders keyboard shortcuts as Line[].
+ * Accessed via /shortcuts command. Reflects live keybindings (user overrides included).
+ */
+export function renderShortcutsOverlay(
+  width: number,
+  keybindingsManager: KeybindingsManager,
+  scrollOffset = 0,
+  viewportHeight = process.stdout.rows || 24,
+): Line[] {
+  function row(key: string, desc: string): string {
+    const keyCol = key.length > 20 ? key.slice(0, 19) + '\u2026' : key.padEnd(20);
+    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);
+
+  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('Mouse wheel', 'Scroll conversation'),
+    '',
+    '  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'),
+    '',
+    '  Actions',
+    '  ' + '\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', 'Process monitor'),
+    row('?', 'Help overlay'),
+    row(`${kb('clear-cancel')} x2`, 'Exit'),
+    '',
+    '  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'),
+    '',
+    `  Config: /keybindings to list and customize`,
+  ];
+
+  const metrics = getOverlaySurfaceMetrics(width, viewportHeight, {
+    chromeRows: 4,
+    minContentRows: 8,
+    maxContentRows: 12,
+  });
+  const maxVisible = metrics.contentRows;
+  const clampedOffset = Math.max(0, Math.min(scrollOffset, Math.max(0, allRows.length - maxVisible)));
+  const visibleRows = allRows.slice(clampedOffset, clampedOffset + maxVisible);
+  const window = getVisibleWindow(allRows.length, clampedOffset, maxVisible);
+
+  return ModalFactory.createModal(
+    {
+      title: 'Keyboard Shortcuts',
+      width: metrics.boxWidth,
+      margin: metrics.margin,
+      targetContentRows: metrics.contentRows,
+      tabs: [{ label: 'Shortcuts', active: true }],
+      sections: toModalSections(visibleRows),
+      helpers: allRows.length > maxVisible
+        ? [{ content: `[${window.start + 1}-${Math.min(allRows.length, clampedOffset + visibleRows.length)} of ${allRows.length}]` }]
+        : undefined,
+      hints: ['Esc Close', 'Up/Down Scroll'],
+    },
+    width,
+  );
+}

package/src/renderer/history-search-overlay.ts

@@ -0,0 +1,73 @@
+import type { Line } from '@pellux/goodvibes-sdk/platform/types/grid';
+import { getDisplayWidth } from '@pellux/goodvibes-sdk/platform/utils/terminal-width';
+import type { HistorySearch } from '../input/input-history.ts';
+import { createBottomBarLine, writeBottomBarText } from './bottom-bar.ts';
+
+/**
+ * Truncate `text` to at most `maxWidth` display columns, then pad with spaces
+ * to exactly `maxWidth` columns. CJK/emoji wide characters count as 2 columns.
+ */
+function truncateToWidth(text: string, maxWidth: number): string {
+  let usedWidth = 0;
+  let result = '';
+  let i = 0;
+  while (i < text.length) {
+    const code = text.codePointAt(i)!;
+    const charLen = code > 0xFFFF ? 2 : 1;
+    const charWidth = getDisplayWidth(text.slice(i, i + charLen));
+    if (usedWidth + charWidth > maxWidth) break;
+    result += text.slice(i, i + charLen);
+    usedWidth += charWidth;
+    i += charLen;
+  }
+  // Pad to exactly maxWidth columns with spaces
+  return result + ' '.repeat(maxWidth - usedWidth);
+}
+
+/**
+ * Render the reverse-i-search bar as a single Line[] overlay at the bottom of the viewport.
+ * Format: (reverse-i-search)`query': matched-command-text
+ *
+ * - The matched command text is shown in dim grey over the teal bar.
+ * - If no match, shows "(failed reverse-i-search)" prefix.
+ */
+export function renderHistorySearchOverlay(
+  historySearch: HistorySearch,
+  width: number
+): Line[] {
+  if (width <= 0) return [];
+
+  const match = historySearch.currentMatch;
+  const hasMatch = match !== null && historySearch.query.length > 0;
+  const noMatch = historySearch.query.length > 0 && !hasMatch;
+
+  const prefix = noMatch
+    ? '(failed reverse-i-search)`'
+    : '(reverse-i-search)`';
+  const queryPart = historySearch.query + "': ";
+  const matchText = hasMatch ? match?.entry ?? '' : '';
+
+  // Build the display string
+  const label = prefix + queryPart;
+  const full = truncateToWidth(label + matchText, width);
+
+  const line = createBottomBarLine(width, { fg: '#000000', bg: '#00ffcc' });
+  writeBottomBarText(line, 0, width, full, { fg: '#000000', bg: '#00ffcc' });
+
+  // Highlight the matched region in the match text with dim styling
+  if (hasMatch && match) {
+    const labelW = getDisplayWidth(label);
+    const matchStartCol = labelW + match.matchStart;
+    const matchEndCol = matchStartCol + match.matchLength;
+    const highlightWidth = Math.max(0, matchEndCol - matchStartCol);
+    const matchedSlice = truncateToWidth(match.entry.slice(match.matchStart, match.matchStart + match.matchLength), highlightWidth);
+    writeBottomBarText(line, matchStartCol, highlightWidth, matchedSlice, {
+      fg: '#000000',
+      bg: '#00ffcc',
+      bold: true,
+      underline: true,
+    });
+  }
+
+  return [line];
+}

package/src/renderer/layout-engine.ts

@@ -0,0 +1,97 @@
+export interface ShellLayoutRequest {
+  readonly width: number;
+  readonly height: number;
+  readonly headerHeight: number;
+  readonly footerHeight: number;
+  readonly panelWidth?: number;
+}
+
+export interface Rect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface ShellLayout {
+  readonly screen: Rect;
+  readonly header: Rect;
+  readonly body: Rect;
+  readonly footer: Rect;
+  readonly conversation: Rect;
+  readonly panel?: Rect;
+  readonly separatorX?: number;
+}
+
+export interface SplitPaneLayout {
+  readonly totalRows: number;
+  readonly topTabRows: number;
+  readonly bottomTabRows: number;
+  readonly separatorRows: number;
+  readonly topContentRows: number;
+  readonly bottomContentRows: number;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+export function createShellLayout(request: ShellLayoutRequest): ShellLayout {
+  const width = Math.max(1, request.width);
+  const height = Math.max(1, request.height);
+  const headerHeight = clamp(request.headerHeight, 0, height);
+  const footerHeight = clamp(request.footerHeight, 0, Math.max(0, height - headerHeight));
+  const bodyHeight = Math.max(0, height - headerHeight - footerHeight);
+
+  const hasPanel = typeof request.panelWidth === 'number' && request.panelWidth > 0;
+  const safePanelWidth = hasPanel
+    ? clamp(request.panelWidth as number, 1, Math.max(1, width - 2))
+    : 0;
+  const separatorWidth = hasPanel ? 1 : 0;
+  const conversationWidth = hasPanel ? Math.max(1, width - safePanelWidth - separatorWidth) : width;
+
+  return {
+    screen: { x: 0, y: 0, width, height },
+    header: { x: 0, y: 0, width, height: headerHeight },
+    body: { x: 0, y: headerHeight, width, height: bodyHeight },
+    footer: { x: 0, y: headerHeight + bodyHeight, width, height: footerHeight },
+    conversation: { x: 0, y: headerHeight, width: conversationWidth, height: bodyHeight },
+    panel: hasPanel
+      ? {
+          x: conversationWidth + separatorWidth,
+          y: headerHeight,
+          width: safePanelWidth,
+          height: bodyHeight,
+        }
+      : undefined,
+    separatorX: hasPanel ? conversationWidth : undefined,
+  };
+}
+
+export function createSplitPaneLayout(
+  totalRows: number,
+  ratio: number,
+  options: {
+    readonly topTabRows?: number;
+    readonly bottomTabRows?: number;
+    readonly separatorRows?: number;
+  } = {},
+): SplitPaneLayout {
+  const topTabRows = options.topTabRows ?? 1;
+  const bottomTabRows = options.bottomTabRows ?? 1;
+  const separatorRows = options.separatorRows ?? 1;
+  const chromeRows = topTabRows + bottomTabRows + separatorRows;
+  const contentRows = Math.max(0, totalRows - chromeRows);
+  const normalizedRatio = clamp(ratio, 0.2, 0.8);
+  const topContentRows = contentRows <= 1 ? contentRows : Math.max(1, Math.floor(contentRows * normalizedRatio));
+  const bottomContentRows = contentRows <= 1 ? 0 : Math.max(1, contentRows - topContentRows);
+
+  return {
+    totalRows,
+    topTabRows,
+    bottomTabRows,
+    separatorRows,
+    topContentRows,
+    bottomContentRows,
+  };
+}

package/src/renderer/layout.ts

@@ -0,0 +1,32 @@
+import { GLYPHS } from './ui-primitives.ts';
+
+/**
+ * Layout constants — single source of truth for margins and content width.
+ * All renderers import these instead of hardcoding indent values.
+ */
+export const LAYOUT = {
+  LEFT_MARGIN: 4,
+  RIGHT_MARGIN: 2,
+  contentWidth: (termWidth: number) => termWidth - LAYOUT.LEFT_MARGIN - LAYOUT.RIGHT_MARGIN,
+  /** Used by createMessageBar in ui-factory.ts for user message ghost boxes. */
+  USER_BOX_MARGIN: 2,
+} as const;
+
+export const TOOL_STATUS = {
+  SUCCESS_ICON: GLYPHS.status.success,
+  SPINNER_FRAMES: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  FAIL_ICON: GLYPHS.status.failure,
+  PENDING_ICON: GLYPHS.status.pending,
+  TOOL_NAME_PAD: 8,
+} as const;
+
+export const COLORS = {
+  DIM_TEXT: '244',
+} as const;
+
+export const BORDERS = {
+  THINKING: { char: '▌', color: '#9945FF' },
+  ERROR:    { char: '▌', color: '#ef4444' },
+  WARNING:  { char: '▌', color: '#eab308' },
+  INFO:     { char: '▌', color: '#22d3ee' },
+} as const;

package/src/renderer/live-tail-modal.ts

@@ -0,0 +1,156 @@
+import { type Line } from '@pellux/goodvibes-sdk/platform/types/grid';
+import { ModalFactory } from './modal-factory.ts';
+import type { ProcessManager } from '@pellux/goodvibes-sdk/platform/tools/shared/process-manager';
+import type { AgentManager } from '../tools/agent/index.ts';
+import type { ProcessEntry } from './process-modal.ts';
+import { getOverlaySurfaceMetrics, getStableOverlayContentRows } from './overlay-viewport.ts';
+
+export interface LiveTailModalDeps {
+  readonly agentManager: Pick<AgentManager, 'cancel' | 'getStatus'>;
+  readonly processManager: Pick<ProcessManager, 'stop' | 'getOutput'>;
+}
+
+// ─── LiveTailModal ────────────────────────────────────────────────────────────
+
+/**
+ * LiveTailModal — manages state for the live output peek modal.
+ *
+ * Shows streaming stdout/stderr from a selected background process or agent
+ * progress notes. Auto-scrolls to the bottom unless the user scrolled up.
+ */
+export class LiveTailModal {
+  public active = false;
+  public entry: ProcessEntry | null = null;
+
+  /** Number of lines scrolled up from the bottom (0 = at bottom). */
+  public scrollOffset = 0;
+
+  constructor(private readonly deps: LiveTailModalDeps) {}
+
+  open(entry: ProcessEntry): void {
+    this.entry = entry;
+    this.scrollOffset = 0;
+    this.active = true;
+  }
+
+  close(): void {
+    this.active = false;
+    this.entry = null;
+    this.scrollOffset = 0;
+  }
+
+  scrollUp(): void {
+    this.scrollOffset++;
+  }
+
+  scrollDown(): void {
+    this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+  }
+
+  /**
+   * Kill the current process.
+   * Returns true if the process was found and stopped.
+   */
+  killProcess(): boolean {
+    if (!this.entry) return false;
+
+    if (this.entry.type === 'exec') {
+      return this.deps.processManager.stop(this.entry.id);
+    } else {
+      return this.deps.agentManager.cancel(this.entry.id);
+    }
+  }
+
+  /** Retrieve the current output text for the watched process. */
+  getOutput(): string {
+    if (!this.entry) return '';
+
+    if (this.entry.type === 'exec') {
+      const out = this.deps.processManager.getOutput(this.entry.id);
+      if (!out) return '';
+      const combined = [out.stdout, out.stderr].filter(Boolean).join('\n').trim();
+      return combined || '(no output yet)';
+    } else {
+      // For agents, show progress note and status
+      const rec = this.deps.agentManager.getStatus(this.entry.id);
+      if (!rec) return '(process not found)';
+      const parts: string[] = [
+        `Task: ${rec.task}`,
+        `Status: ${rec.status}`,
+        `Tool calls: ${rec.toolCallCount}`,
+      ];
+      if (rec.progress) parts.push(`Progress: ${rec.progress}`);
+      if (rec.error) parts.push(`Error: ${rec.error}`);
+      return parts.join('\n');
+    }
+  }
+}
+
+// ─── renderLiveTailModal ──────────────────────────────────────────────────────
+
+/**
+ * Render the live-tail peek modal as Line[] for overlay in the viewport.
+ *
+ * Shows a scrollable view of the process output. scrollOffset=0 means the
+ * bottom of the output is visible (auto-scroll behaviour).
+ *
+ * @param modal  LiveTailModal state
+ * @param width  Terminal width
+ * @param maxOutputLines  Maximum lines to show inside the box (default: 16)
+ */
+export function renderLiveTailModal(
+  modal: LiveTailModal,
+  width: number,
+  viewportHeight = 24,
+): Line[] {
+  const entry = modal.entry;
+  if (!entry) return [];
+  const metrics = getOverlaySurfaceMetrics(width, viewportHeight, {
+    chromeRows: 4,
+    minContentRows: 6,
+    maxContentRows: 10,
+  });
+  const maxOutputLines = metrics.contentRows;
+  const targetContentRows = getStableOverlayContentRows(metrics.contentRows, 8);
+
+  const output = modal.getOutput();
+  const allLines = output.split('\n');
+
+  // Apply scroll: scrollOffset=0 → show tail; larger → scroll toward head
+  const totalLines = allLines.length;
+  // Clamp scrollOffset so we never scroll past the top of the content
+  const maxScroll = Math.max(0, totalLines - maxOutputLines);
+  const clampedOffset = Math.min(modal.scrollOffset, maxScroll);
+  const endIdx = Math.max(maxOutputLines, totalLines - clampedOffset);
+  const startIdx = Math.max(0, endIdx - maxOutputLines);
+  const visibleLines = allLines.slice(startIdx, endIdx);
+
+  const typeTag = entry.type === 'agent' ? '[agent]' : '[exec]';
+  const maxLabelW = Math.max(20, width - 30);
+  const title = `${typeTag} ${entry.label.slice(0, maxLabelW)}`;
+
+  // Build scroll indicator for text section header
+  const scrollInfo = totalLines > maxOutputLines
+    ? `  Lines ${startIdx + 1}-${Math.min(endIdx, totalLines)} of ${totalLines}  [Up/Down] Scroll`
+    : '';
+
+  const contentText = visibleLines.join('\n') || '(no output yet)';
+
+  const sections: import('./modal-factory.ts').ModalSection[] = [];
+
+  if (scrollInfo) {
+    sections.push({ type: 'text', content: scrollInfo });
+    sections.push({ type: 'separator' });
+  }
+
+  sections.push({ type: 'text', content: contentText });
+
+  return ModalFactory.createModal({
+    title,
+    width: metrics.boxWidth,
+    margin: 2,
+    targetContentRows,
+    sections,
+    hints: ['[Up/Down] Scroll', '[k] Kill', '[Esc] Back'],
+  }, width);
+}