@pellux/goodvibes-agent 0.1.0

package/src/renderer/fullscreen-workspace.ts

@@ -0,0 +1,199 @@
+import type { Line } from '../types/grid.ts';
+import { GLYPHS } from './ui-primitives.ts';
+import {
+  borderLine,
+  clamp,
+  contentLine,
+  drawHorizontalRule,
+  drawVerticalRule,
+  fillRange,
+  FULLSCREEN_PALETTE,
+  makeLine,
+  writeText,
+} from './fullscreen-primitives.ts';
+
+export {
+  borderLine,
+  clamp,
+  contentLine,
+  fillRange,
+  makeLine,
+  padDisplay,
+  stableWindow,
+  writeText,
+} from './fullscreen-primitives.ts';
+export { FULLSCREEN_PALETTE as WORKSPACE_PALETTE } from './fullscreen-primitives.ts';
+
+const WORKSPACE_PALETTE = FULLSCREEN_PALETTE;
+
+export interface WorkspaceRow {
+  readonly text: string;
+  readonly selected?: boolean;
+  readonly bold?: boolean;
+  readonly dim?: boolean;
+  readonly fg?: string;
+  readonly bg?: string;
+  readonly kind?: 'group' | 'item' | 'more' | 'empty';
+}
+
+export interface FullscreenWorkspaceRenderOptions {
+  readonly width: number;
+  readonly height: number;
+  readonly title: string;
+  readonly stateLabel?: string;
+  readonly leftHeader: string;
+  readonly mainHeader: string;
+  readonly leftRows: readonly WorkspaceRow[];
+  readonly contextRows: readonly WorkspaceRow[];
+  readonly controlRows: readonly WorkspaceRow[];
+  readonly footer: string;
+  readonly leftWidth?: number;
+  readonly contextRatio?: number;
+  readonly minContextRows?: number;
+}
+
+export interface FullscreenWorkspaceMetrics {
+  readonly safeWidth: number;
+  readonly safeHeight: number;
+  readonly leftWidth: number;
+  readonly centerWidth: number;
+  readonly bodyRows: number;
+  readonly contextWidth: number;
+  readonly contextRows: number;
+  readonly controlRows: number;
+}
+
+export function drawVertical(line: Line, x: number, bg = ''): void {
+  if (x <= 0 || x >= line.length - 1) return;
+  drawVerticalRule(line, x, WORKSPACE_PALETTE.border, bg);
+}
+
+export function drawHorizontalRange(line: Line, startX: number, endX: number, bg = ''): void {
+  drawHorizontalRule(line, Math.max(1, startX), Math.min(line.length - 2, endX), WORKSPACE_PALETTE.border, bg);
+}
+
+function leftWidthFor(width: number, explicit?: number): number {
+  if (explicit !== undefined) return clamp(explicit, 14, Math.max(14, width - 24));
+  return width < 80
+    ? clamp(Math.round(width * 0.32), 14, Math.max(14, width - 24))
+    : clamp(Math.round(width * 0.22), 24, 34);
+}
+
+export function getFullscreenWorkspaceMetrics(options: Pick<
+  FullscreenWorkspaceRenderOptions,
+  'width' | 'height' | 'leftWidth' | 'contextRatio' | 'minContextRows'
+>): FullscreenWorkspaceMetrics {
+  const safeWidth = Math.max(1, options.width);
+  const safeHeight = Math.max(12, options.height);
+  const leftWidth = leftWidthFor(safeWidth, options.leftWidth);
+  const centerWidth = Math.max(20, safeWidth - leftWidth - 3);
+  const bodyTop = 3;
+  const footerY = safeHeight - 2;
+  const bodyRows = Math.max(4, footerY - bodyTop);
+  const contextWidth = Math.max(10, centerWidth - 2);
+  const maxContextRows = Math.max(3, bodyRows - 4);
+  const minContextRows = clamp(options.minContextRows ?? 10, 3, maxContextRows);
+  const contextRows = clamp(
+    Math.round(bodyRows * (options.contextRatio ?? 0.4)),
+    Math.min(minContextRows, maxContextRows),
+    maxContextRows,
+  );
+  const controlRows = Math.max(3, bodyRows - contextRows - 1);
+  return { safeWidth, safeHeight, leftWidth, centerWidth, bodyRows, contextWidth, contextRows, controlRows };
+}
+
+function rowFg(row: WorkspaceRow, fallback: string): string {
+  if (row.fg) return row.fg;
+  if (row.kind === 'group') return WORKSPACE_PALETTE.subtitle;
+  if (row.kind === 'more') return WORKSPACE_PALETTE.dim;
+  return fallback;
+}
+
+export function renderFullscreenWorkspace(options: FullscreenWorkspaceRenderOptions): Line[] {
+  const { safeWidth, safeHeight, leftWidth, centerWidth, bodyRows, contextWidth, contextRows } = getFullscreenWorkspaceMetrics(options);
+  const leftStart = 1;
+  const dividerX = leftWidth + 1;
+  const centerStart = dividerX + 1;
+  const centerEnd = safeWidth - 2;
+  const bodyTop = 3;
+  const separatorY = bodyTop + contextRows;
+  const lines: Line[] = [];
+
+  const top = borderLine(safeWidth, GLYPHS.frame.topLeft, GLYPHS.frame.horizontal, GLYPHS.frame.topRight);
+  writeText(top, 2, safeWidth - 4, ` ${options.title} `, { fg: WORKSPACE_PALETTE.title, bold: true });
+  if (options.stateLabel) {
+    writeText(top, Math.max(2, safeWidth - options.stateLabel.length - 4), options.stateLabel.length, options.stateLabel, {
+      fg: WORKSPACE_PALETTE.subtitle,
+    });
+  }
+  lines.push(top);
+
+  const header = contentLine(safeWidth, WORKSPACE_PALETTE.footerBg);
+  drawVertical(header, dividerX, WORKSPACE_PALETTE.footerBg);
+  writeText(header, leftStart + 1, leftWidth - 2, options.leftHeader, {
+    fg: WORKSPACE_PALETTE.subtitle,
+    bold: true,
+    bg: WORKSPACE_PALETTE.footerBg,
+  });
+  writeText(header, centerStart + 1, centerWidth - 2, options.mainHeader, {
+    fg: WORKSPACE_PALETTE.subtitle,
+    bold: true,
+    bg: WORKSPACE_PALETTE.footerBg,
+  });
+  lines.push(header);
+
+  const headerSep = contentLine(safeWidth, '');
+  drawVertical(headerSep, dividerX);
+  drawHorizontalRange(headerSep, 1, safeWidth - 2);
+  lines.push(headerSep);
+
+  for (let row = 0; row < bodyRows; row += 1) {
+    const y = bodyTop + row;
+    const inContext = y < separatorY;
+    const inSeparator = y === separatorY;
+    const bg = inSeparator ? '' : inContext ? WORKSPACE_PALETTE.contextBg : WORKSPACE_PALETTE.controlsBg;
+    const line = contentLine(safeWidth, bg);
+    fillRange(line, 1, dividerX - 1, WORKSPACE_PALETTE.categoryBg);
+    drawVertical(line, dividerX, bg);
+
+    const leftRow = options.leftRows[row] ?? { text: '', kind: 'empty' as const };
+    if (leftRow.selected) fillRange(line, leftStart, dividerX - 1, WORKSPACE_PALETTE.selectedBg);
+    writeText(line, leftStart + 1, leftWidth - 3, leftRow.text, {
+      fg: leftRow.selected ? WORKSPACE_PALETTE.text : rowFg(leftRow, WORKSPACE_PALETTE.muted),
+      bg: leftRow.selected ? WORKSPACE_PALETTE.selectedBg : WORKSPACE_PALETTE.categoryBg,
+      bold: leftRow.bold ?? (leftRow.selected || leftRow.kind === 'group'),
+      dim: leftRow.dim,
+    });
+
+    if (inSeparator) {
+      drawHorizontalRange(line, centerStart, centerEnd);
+    } else if (inContext) {
+      const contextRow = options.contextRows[row] ?? { text: '', kind: 'empty' as const };
+      writeText(line, centerStart + 1, contextWidth, contextRow.text, {
+        fg: rowFg(contextRow, WORKSPACE_PALETTE.text),
+        bg,
+        bold: contextRow.bold,
+        dim: contextRow.dim ?? contextRow.text.length === 0,
+      });
+    } else {
+      const controlRow = options.controlRows[row - contextRows - 1] ?? { text: '', kind: 'empty' as const };
+      if (controlRow.selected) fillRange(line, centerStart, centerEnd, WORKSPACE_PALETTE.selectedBg);
+      writeText(line, centerStart + 1, contextWidth, controlRow.text, {
+        fg: controlRow.selected ? WORKSPACE_PALETTE.text : rowFg(controlRow, WORKSPACE_PALETTE.text),
+        bg: controlRow.selected ? WORKSPACE_PALETTE.selectedBg : bg,
+        bold: controlRow.bold ?? controlRow.selected,
+        dim: controlRow.dim ?? controlRow.text.length === 0,
+      });
+    }
+
+    lines.push(line);
+  }
+
+  const footer = contentLine(safeWidth, WORKSPACE_PALETTE.footerBg);
+  writeText(footer, 2, safeWidth - 4, options.footer, { fg: WORKSPACE_PALETTE.muted, bg: WORKSPACE_PALETTE.footerBg });
+  lines.push(footer);
+  lines.push(borderLine(safeWidth, GLYPHS.frame.bottomLeft, GLYPHS.frame.horizontal, GLYPHS.frame.bottomRight));
+
+  while (lines.length < safeHeight) lines.unshift(makeLine(safeWidth));
+  return lines.slice(-safeHeight);
+}

package/src/renderer/git-status.ts

@@ -0,0 +1,89 @@
+import { GitService } from '@pellux/goodvibes-sdk/platform/git';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+/** Git state shown in the header bar. */
+export interface GitHeaderInfo {
+  branch: string;
+  dirty: boolean;
+  ahead: number;
+  behind: number;
+}
+
+const FALLBACK: GitHeaderInfo = { branch: '?', dirty: false, ahead: 0, behind: 0 };
+
+/**
+ * GitStatusProvider — Fetches git state for the header bar.
+ *
+ * Results are cached for 2 seconds (TTL). The next call after expiry triggers
+ * a fresh fetch and returns the cached value immediately (stale-while-revalidate).
+ * Never throws — returns FALLBACK on any error.
+ */
+export class GitStatusProvider {
+  private cache: GitHeaderInfo = { ...FALLBACK };
+  private lastFetch = 0;
+  private readonly ttlMs = 2000;
+  private fetching = false;
+
+  constructor(private readonly workingDirectory: string) {}
+
+  /** Returns cached info immediately; refreshes in background if TTL expired. */
+  async getStatus(): Promise<GitHeaderInfo> {
+    const now = Date.now();
+    if (now - this.lastFetch < this.ttlMs) {
+      return this.cache;
+    }
+    // Fetch synchronously on first call (no cache yet), otherwise return stale
+    if (this.lastFetch === 0) {
+      await this._fetch().catch(() => {
+        // Ensure fallback is set if _fetch failed before setting lastFetch
+        if (this.lastFetch === 0) {
+          this.lastFetch = Date.now();
+        }
+      });
+    } else if (!this.fetching) {
+      this._fetch().catch(err => { logger.debug('GitStatusProvider: background refresh failed', { error: summarizeError(err) }); });
+    }
+    return this.cache;
+  }
+
+  /** Force a fresh fetch and update the cache. Returns updated info. */
+  async refresh(): Promise<GitHeaderInfo> {
+    await this._fetch();
+    return this.cache;
+  }
+
+  private async _fetch(): Promise<void> {
+    if (this.fetching) return;
+    this.fetching = true;
+    try {
+      const git = new GitService(this.workingDirectory);
+      const [statusResult, branchResult] = await Promise.all([
+        git.status(),
+        git.branch(),
+      ]);
+      const dirty =
+        statusResult.modified.length > 0 ||
+        statusResult.created.length > 0 ||
+        statusResult.deleted.length > 0 ||
+        statusResult.renamed.length > 0 ||
+        statusResult.conflicted.length > 0 ||
+        statusResult.not_added.length > 0;
+      this.cache = {
+        branch: branchResult.current || '?',
+        dirty,
+        ahead: statusResult.ahead ?? 0,
+        behind: statusResult.behind ?? 0,
+      };
+      this.lastFetch = Date.now();
+    } catch {
+      // Never throw — return fallback
+      if (this.lastFetch === 0) {
+        this.cache = { ...FALLBACK };
+        this.lastFetch = Date.now();
+      }
+    } finally {
+      this.fetching = false;
+    }
+  }
+}

package/src/renderer/help-overlay.ts

@@ -0,0 +1,267 @@
+/**
+ * renderHelpOverlay — renders the help overlay with keyboard shortcuts and slash commands.
+ *
+ * Toggle with `?` key or `/help` command.
+ */
+
+import { type Line } from '../types/grid.ts';
+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';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+
+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`,
+    '',
+  ];
+
+  // Featured commands shown in the Quick Start section.
+  // Each entry is [commandName, subcommandOrArgHint, description].
+  // Commands not registered in the live registry are omitted at render time.
+  const FEATURED_COMMANDS: Array<[name: string, argHint: string, desc: string]> = [
+    ['onboarding',   '',           'Open the onboarding wizard with current settings preloaded'],
+    ['cockpit',      '',           'Unified runtime control room'],
+    ['settings',     '',           'Settings and config browser'],
+    ['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'],
+    ['security',     '',           'Security review workspace'],
+    ['policy',       '',           'Simulation, lint, and preflight review'],
+    ['incident',     '',           'Incident workspace and export flows'],
+    ['knowledge',    '',           'Durable knowledge and review queue'],
+    ['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'],
+  ];
+
+  // Build command rows from featured list, filtering out unregistered commands.
+  function featuredRow(name: string, argHint: string, desc: string): string {
+    const invocation = argHint ? `/${name} ${argHint}` : `/${name}`;
+    return `  ${invocation.padEnd(23)}  ${desc}`;
+  }
+
+  const quickStartRows: string[] = [];
+  try {
+    for (const [name, argHint, desc] of FEATURED_COMMANDS) {
+      if (!hasCommand(name)) continue; // omit if not in live registry
+      quickStartRows.push(featuredRow(name, argHint, desc));
+    }
+  } catch (err) {
+    // A plugin command getter threw during registry traversal. Fall back to an
+    // unfiltered quick-start list so /help remains reachable.
+    logger.warn(`[help-overlay] registry traversal error during command filter; using unfiltered list: ${err}`);
+    quickStartRows.length = 0;
+    for (const [name, argHint, desc] of FEATURED_COMMANDS) {
+      quickStartRows.push(featuredRow(name, argHint, desc));
+    }
+  }
+
+  const commandRows: string[] = [];
+  if (quickStartRows.length > 0) {
+    commandRows.push('  Quick Start', '  ' + '\u2500'.repeat(40), ...quickStartRows, '');
+  }
+
+  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 or hovered panel'),
+    '',
+    '  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 '../types/grid.ts';
+import { getDisplayWidth } from '../utils/terminal-width.ts';
+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];
+}