@pellux/goodvibes-tui 2.0.21 → 2.1.0

package/src/renderer/agents-modal.ts

@@ -0,0 +1,310 @@
+/**
+ * renderAgentsModal, every agent, chain, workflow, hosted session and
+ * background process in one list (replaces the Fleet view and its aliases).
+ *
+ *   ✦ Agents  3 running · 1 failed · you $0.25 · fleet $0.47             esc
+ *
+ *   ▏Type / to filter agents                                         6 shown
+ *
+ *   ✦ running                                  ┌ element inset ─────────────┐
+ *   ◐ engineer  Add a maxDelayMs cap  2m · $0.12   engineer
+ *   ◐ └ tester  Edit test/retry.test.ts   48s      claude-sonnet · worktree
+ *   ✦ finished                                     → Read src/net/retry.ts
+ *   ✕ researcher  verify: 2 tests failing          ◐ Edit test/retry.test.ts
+ *
+ *   ⏎ open full screen   s steer   x stop   n new agent
+ *
+ * Levels (Esc goes back one, and never interrupts anything): the list, a
+ * full-height view of one agent's transcript, the host-an-agent picker, and
+ * the best-of-N candidate picker.
+ */
+
+import type { Line } from '@pellux/goodvibes-sdk/platform/types';
+import { activeTokens } from './theme.ts';
+import { beginModal, finishModal, clipText, scrollCountText, searchRow, wrapLines, type KitHint, type ModalFrame, type SurfaceCanvas, type SurfaceLayer } from './surface-kit.ts';
+import { drawList, type KitRow } from './surface-kit-list.ts';
+import { inset, type KitInset } from './surface-kit-parts.ts';
+import { drawTextBlock, splitListDetail } from './surface-kit-extra.ts';
+
+export type AgentsTone = 'text' | 'muted' | 'faint' | 'brand' | 'success' | 'warning' | 'error';
+
+/** A line of plain text in a tone. */
+export interface AgentsText {
+  readonly text: string;
+  readonly tone: AgentsTone;
+  readonly bold?: boolean;
+  /** A marker drawn in front (→ ← ◐ …). */
+  readonly glyph?: string;
+}
+
+/** Content for the detail inset or the full view: text, or prebuilt lines (fleet detail, transcripts). */
+export type AgentsBlock =
+  | { readonly kind: 'text'; readonly lines: readonly AgentsText[] }
+  /** Prebuilt lines for a width (the fleet's detail block). */
+  | { readonly kind: 'lines'; readonly build: (width: number) => readonly Line[] };
+
+export interface AgentsDetail {
+  readonly title: string;
+  readonly meta: string;
+  /** Drawn from the top. */
+  readonly blocks: readonly AgentsBlock[];
+  /** The live tail, drawn from the bottom up (newest last). */
+  readonly tail: readonly AgentsText[];
+}
+
+/** One option in a sub-level picker (host an agent, pick a winner). */
+export interface AgentsOption {
+  readonly label: string;
+  readonly detail: string;
+  readonly selected: boolean;
+}
+
+/** What the renderer reads from the modal. */
+export interface AgentsModalView {
+  readonly level: 'list' | 'full' | 'picker';
+  readonly crumbs: readonly string[];
+  readonly sub: string;
+  readonly hints: readonly KitHint[];
+  readonly status: AgentsText | null;
+  /** An inline input being typed (steer), or null. */
+  readonly input: { readonly label: string; readonly draft: string } | null;
+  // list
+  readonly filter: { readonly query: string; readonly active: boolean; readonly count: string };
+  readonly rows: readonly KitRow[];
+  readonly detail: AgentsDetail | null;
+  // full
+  readonly full: {
+    readonly meta: string;
+    readonly header: readonly AgentsText[];
+    /** The transcript for a body of this width and height (newest at the bottom). */
+    readonly body: (width: number, height: number) => readonly Line[];
+  } | null;
+  // picker
+  readonly picker: { readonly intro: string; readonly options: readonly AgentsOption[]; readonly side: readonly AgentsText[] } | null;
+  readonly scrollOwner: object;
+}
+
+function toneColor(tone: AgentsTone): string {
+  const t = activeTokens();
+  switch (tone) {
+    case 'text': return t.text;
+    case 'muted': return t.textMuted;
+    case 'faint': return t.textFaint;
+    case 'brand': return t.brand;
+    case 'success': return t.success;
+    case 'warning': return t.warning;
+    case 'error': return t.error;
+  }
+}
+
+/** Copy prebuilt cells onto the canvas; cells on the terminal's own background take `bg`. */
+function blitLine(canvas: SurfaceCanvas, x: number, y: number, line: Line, width: number, bg: string): void {
+  const row = canvas.lines[y];
+  if (!row) return;
+  for (let q = 0; q < width && q < line.length; q++) {
+    const cell = line[q]!;
+    const cx = x + q;
+    if (cx < 0 || cx >= canvas.width) continue;
+    // Never leave half of a wide glyph at the right edge.
+    if (q === width - 1 && cell.char && line[q + 1]?.char === '') {
+      row[cx] = { ...cell, char: ' ', bg: cell.bg || bg };
+      continue;
+    }
+    row[cx] = { ...cell, bg: cell.bg || bg };
+  }
+}
+
+/** Width the prebuilt detail lines are built at before they are wrapped to the inset. */
+const DETAIL_BUILD_WIDTH = 400;
+
+/**
+ * Wrap one prebuilt cell row to `width`: trailing blanks dropped, breaks at
+ * the last space that fits (a hard break only for a word longer than the
+ * row), continuation rows indented two past the row's own leading spaces, and
+ * a wide glyph never split from its continuation cell. Nothing is cut off.
+ */
+function wrapCellLine(line: Line, width: number): Line[] {
+  let end = line.length;
+  while (end > 0 && line[end - 1]!.char === ' ') end--;
+  const cells = line.slice(0, end);
+  if (cells.length <= width) return [cells];
+  let lead = 0;
+  while (lead < cells.length && cells[lead]!.char === ' ') lead++;
+  const indent = Math.min(lead + 2, Math.floor(width / 3));
+  const blank = { ...cells[0]!, char: ' ' };
+  const rows: Line[] = [];
+  let start = 0;
+  let first = true;
+  while (start < cells.length) {
+    const avail = first ? width : width - indent;
+    const prefix: Line = first ? [] : Array.from({ length: indent }, () => ({ ...blank }));
+    if (cells.length - start <= avail) {
+      rows.push([...prefix, ...cells.slice(start)]);
+      break;
+    }
+    let cut = start + avail;
+    let space = -1;
+    for (let q = cut; q > start; q--) if (cells[q]?.char === ' ') { space = q; break; }
+    if (space > start) cut = space;
+    else if (cells[cut]?.char === '') cut--; // keep a wide glyph whole
+    rows.push([...prefix, ...cells.slice(start, cut)]);
+    start = cut;
+    while (start < cells.length && cells[start]!.char === ' ') start++;
+    first = false;
+  }
+  return rows;
+}
+
+/** Draw text lines (wrapped) from row y; returns the row after them. */
+function drawTexts(canvas: SurfaceCanvas, x: number, y: number, width: number, lines: readonly AgentsText[], maxY: number, bg?: string): number {
+  let yy = y;
+  for (const line of lines) {
+    const indent = line.glyph ? 2 : 0;
+    const parts = wrapLines(line.text, Math.max(1, width - indent));
+    for (let k = 0; k < parts.length; k++) {
+      if (yy > maxY) return yy;
+      if (k === 0 && line.glyph) canvas.put(x, yy, line.glyph, { fg: toneColor(line.tone), bg });
+      canvas.put(x + indent, yy, parts[k]!, { fg: toneColor(line.tone), bold: line.bold, bg });
+      yy++;
+    }
+  }
+  return yy;
+}
+
+/** Rows a list of texts takes when wrapped to `width`. */
+function textRows(lines: readonly AgentsText[], width: number): number {
+  return lines.reduce((n, line) => n + wrapLines(line.text, Math.max(1, width - (line.glyph ? 2 : 0))).length, 0);
+}
+
+function drawDetail(canvas: SurfaceCanvas, p: KitInset, detail: AgentsDetail): void {
+  const t = activeTokens();
+  const width = p.r - p.l + 1;
+  let y = p.top;
+  canvas.put(p.l, y, clipText(detail.title, width), { fg: t.text, bold: true, bg: p.bg });
+  y++;
+  if (detail.meta) y = drawTexts(canvas, p.l, y, width, [{ text: detail.meta, tone: 'faint' }], p.bottom, p.bg);
+  y++;
+  // The tail keeps its newest rows; the detail above it gets what is left.
+  const tailRows = Math.min(textRows(detail.tail, width), Math.max(0, p.bottom - y + 1 - 2));
+  const detailBottom = detail.tail.length > 0 ? p.bottom - tailRows - 1 : p.bottom;
+  for (const block of detail.blocks) {
+    if (y > detailBottom) break;
+    if (block.kind === 'text') y = drawTexts(canvas, p.l, y, width, block.lines, detailBottom, p.bg);
+    else for (const built of block.build(DETAIL_BUILD_WIDTH)) {
+      for (const line of wrapCellLine(built, width)) {
+        if (y > detailBottom) break;
+        blitLine(canvas, p.l, y, line, width, p.bg);
+        y++;
+      }
+    }
+  }
+  if (detail.tail.length === 0 || tailRows <= 0) return;
+  // Draw the tail into a scratch run of rows, keeping only the last tailRows.
+  const wrapped: AgentsText[] = [];
+  for (const line of detail.tail) {
+    const parts = wrapLines(line.text, Math.max(1, width - (line.glyph ? 2 : 0)));
+    parts.forEach((part, k) => wrapped.push({ text: part, tone: line.tone, bold: line.bold, glyph: k === 0 ? line.glyph : line.glyph ? ' ' : undefined }));
+  }
+  const shown = wrapped.slice(-tailRows);
+  let ty = p.bottom - shown.length + 1;
+  for (const line of shown) {
+    if (line.glyph && line.glyph !== ' ') canvas.put(p.l, ty, line.glyph, { fg: toneColor(line.tone), bg: p.bg });
+    canvas.put(p.l + (line.glyph ? 2 : 0), ty, line.text, { fg: toneColor(line.tone), bold: line.bold, bg: p.bg });
+    ty++;
+  }
+}
+
+/** The inline input and the status line, at the bottom of the body. Returns the rows they take. */
+function bottomRows(view: AgentsModalView, width: number): number {
+  let rows = 0;
+  if (view.input) rows += wrapLines(`${view.input.label}${view.input.draft}`, width).length;
+  if (view.status) rows += wrapLines(view.status.text, width).length;
+  return rows > 0 ? rows + 1 : 0;
+}
+
+function drawBottom(f: ModalFrame, view: AgentsModalView): void {
+  const t = activeTokens();
+  const width = f.r - f.l + 1;
+  const rows = bottomRows(view, width);
+  if (rows === 0) return;
+  let y = f.bottom - rows + 2;
+  if (view.input) {
+    const parts = wrapLines(`${view.input.label}${view.input.draft}`, width);
+    parts.forEach((part, k) => {
+      const end = f.canvas.put(f.l, y, part, { fg: t.text });
+      if (k === parts.length - 1) f.canvas.put(end, y, '▏', { fg: t.brand });
+      y++;
+    });
+  }
+  if (view.status) y = drawTexts(f.canvas, f.l, y, width, [view.status], f.bottom);
+}
+
+function drawListLevel(f: ModalFrame, view: AgentsModalView): void {
+  const t = activeTokens();
+  searchRow(f, f.top, view.filter.query, view.filter.active ? '' : 'Type / to filter agents', view.filter.count);
+  const bottom = f.bottom - bottomRows(view, f.r - f.l + 1);
+  const top = f.top + 2;
+  if (view.rows.length === 0) {
+    drawTextBlock(f.canvas, f.l, top, f.r - f.l + 1, [{
+      text: view.filter.query
+        ? `Nothing matches "${view.filter.query}".`
+        : 'Nothing is running. Agents, WRFC chains, workflows, hosted sessions and background processes appear here as they start; n hosts a third-party agent. This list starts empty on each launch; every agent\'s event log stays on disk under .goodvibes/tui/sessions.',
+      style: { fg: t.textMuted },
+    }], bottom);
+    drawBottom(f, view);
+    return;
+  }
+  const split = splitListDetail(f.l, f.r, top, bottom, 0.5, 6);
+  const result = drawList(f.canvas, { rows: view.rows, top: split.top, bottom: split.bottom, x0: split.x0, x1: split.x1, scrollKey: { owner: view.scrollOwner, name: 'list' } });
+  f.hintRight = scrollCountText(result.above, result.below);
+  if (view.detail && split.detailH >= 4) {
+    const p = inset(f.canvas, split.detailX, split.detailY, split.detailW, split.detailH);
+    drawDetail(f.canvas, p, view.detail);
+  }
+  drawBottom(f, view);
+}
+
+function drawFullLevel(f: ModalFrame, view: AgentsModalView): void {
+  const full = view.full!;
+  const width = f.r - f.l + 1;
+  let y = f.top;
+  if (full.meta) y = drawTexts(f.canvas, f.l, y, width, [{ text: full.meta, tone: 'faint' }], f.bottom);
+  if (full.header.length > 0) y = drawTexts(f.canvas, f.l, y, width, full.header, f.bottom);
+  y++;
+  const bottom = f.bottom - bottomRows(view, width);
+  const height = bottom - y + 1;
+  if (height > 0) {
+    // The transcript is drawn by the conversation renderer at the width of the
+    // fill minus 2 columns per side, so its own bars and fills keep their measurements.
+    const bodyWidth = width + 4;
+    const lines = full.body(bodyWidth, height);
+    const start = Math.max(0, lines.length - height);
+    for (let k = start; k < lines.length; k++) blitLine(f.canvas, f.l - 2, y + (k - start), lines[k]!, bodyWidth, activeTokens().backgroundPanel);
+  }
+  drawBottom(f, view);
+}
+
+function drawPickerLevel(f: ModalFrame, view: AgentsModalView): void {
+  const t = activeTokens();
+  const picker = view.picker!;
+  const width = f.r - f.l + 1;
+  const y = drawTextBlock(f.canvas, f.l, f.top, width, [{ text: picker.intro, style: { fg: t.textMuted } }], f.bottom) + 1;
+  const bottom = f.bottom - bottomRows(view, width);
+  const rows: KitRow[] = picker.options.map((option) => ({ label: option.label, desc: option.detail, selected: option.selected }));
+  const split = picker.side.length > 0 ? splitListDetail(f.l, f.r, y, bottom, 0.5, 6) : null;
+  const result = drawList(f.canvas, { rows, top: y, bottom: split ? split.bottom : bottom, x0: f.l, x1: split ? split.x1 : f.r, scrollKey: { owner: view.scrollOwner, name: 'picker' } });
+  f.hintRight = scrollCountText(result.above, result.below);
+  if (split && split.detailH >= 4) {
+    const p = inset(f.canvas, split.detailX, split.detailY, split.detailW, split.detailH);
+    drawTexts(f.canvas, p.l, p.top, p.r - p.l + 1, picker.side, p.bottom, p.bg);
+  }
+  drawBottom(f, view);
+}
+
+export function renderAgentsModal(view: AgentsModalView, screenWidth: number, screenHeight: number): SurfaceLayer {
+  const f = beginModal(screenWidth, screenHeight, { title: 'Agents', crumbs: view.crumbs, sub: view.sub, hints: view.hints });
+  if (view.level === 'full' && view.full) drawFullLevel(f, view);
+  else if (view.level === 'picker' && view.picker) drawPickerLevel(f, view);
+  else drawListLevel(f, view);
+  return finishModal(f);
+}

package/src/renderer/autocomplete-overlay.ts

@@ -1,44 +1,27 @@
-import { type Line } from '@pellux/goodvibes-sdk/platform/types';
-import { fitDisplay, getDisplayWidth, truncateDisplay } from '../utils/terminal-width.ts';
-import { wrapWithHangingIndent } from './text-layout.ts';
-import type { AutocompleteEngine } from '../input/autocomplete.ts';
-import {
-  createOverlayBorderLine,
-  createOverlayBoxLayout,
-  createOverlayContentLine,
-  DEFAULT_OVERLAY_PALETTE,
-  putOverlayText,
-} from './overlay-box.ts';
-import { getOverlaySurfaceMetrics } from './overlay-viewport.ts';
-
-const BORDER_FG = DEFAULT_OVERLAY_PALETTE.borderFg;
-const TITLE_FG = DEFAULT_OVERLAY_PALETTE.titleFg;
-const BODY_FG = DEFAULT_OVERLAY_PALETTE.bodyFg;
-const MUTED_FG = DEFAULT_OVERLAY_PALETTE.mutedFg;
-const SELECTED_BG = DEFAULT_OVERLAY_PALETTE.selectedBg;
+/**
+ * renderAutocompleteOverlay, the slash-command popup.
+ *
+ * Anchored to the composer with no dimming (you are still typing): the same
+ * width as the composer, a ┃ bar on its left edge, the surface fill, and no
+ * frame or hint rows. Command names line up in one column with their
+ * descriptions beside them; a description that does not fit on its row is
+ * left out rather than cut, and the selected row always shows its full
+ * description (wrapped) with "tab complete" on the right. When the list is
+ * longer than the popup, its last row carries a muted "12 more ↓" count.
+ */
 
-interface CellStyle {
-  fg: string;
-  bg?: string;
-  bold?: boolean;
-  dim?: boolean;
-}
+import type { Line } from '@pellux/goodvibes-sdk/platform/types';
+import { getDisplayWidth } from '../utils/terminal-width.ts';
+import type { AutocompleteEngine } from '../input/autocomplete.ts';
+import { activeTokens } from './theme.ts';
+import { renderPopup, POPUP_BAR_X } from './surface-kit-parts.ts';
+import type { KitRow } from './surface-kit-list.ts';
 
-function putText(line: Line, startX: number, maxWidth: number, text: string, style: CellStyle): void {
-  putOverlayText(line, startX, maxWidth, text, style);
+/** Rows the popup may use at most (it shrinks to its content). */
+function popupRows(viewportHeight: number): number {
+  return Math.max(3, Math.min(12, Math.floor(viewportHeight * 0.5)));
 }
 
-/**
- * Render the slash command autocomplete dropdown as Line[] for overlay in the viewport.
- *
- * A row's description renders inline only when it genuinely fits beside the
- * command name; otherwise the FULL description wraps onto its own line(s)
- * below the command name, with no line cap, descriptive text is never
- * clipped (same fix as selection-modal-overlay.ts's modal rule). Item
- * visibility is row-budget aware (a wrapped description can cost more than
- * one physical row), always showing the selected item in full and falling
- * back to the existing position counter rather than losing text.
- */
 export function renderAutocompleteOverlay(
   autocomplete: AutocompleteEngine,
   width: number,
@@ -46,188 +29,27 @@ export function renderAutocompleteOverlay(
 ): Line[] {
   const state = autocomplete.getState();
   if (!state.active || state.results.length === 0) return [];
-
-  const lines: Line[] = [];
-  const chromeRows = 4;
-  const metrics = getOverlaySurfaceMetrics(width, viewportHeight, {
-    margin: 2,
-    maxWidth: 88,
-    chromeRows,
-    minContentRows: 6,
-    // Rows grow with wrapped descriptions (never clipped) rather than
-    // staying pinned at a small constant, still bounded by the viewport.
-    maxContentRows: Math.max(10, viewportHeight - chromeRows - 4),
+  const t = activeTokens();
+  // Text columns inside the popup: fill starts right of the bar, text 2 in.
+  const x0 = POPUP_BAR_X + 3;
+  const x1 = width - 5;
+  const nameW = Math.min(20, Math.max(...state.results.map((r) => getDisplayWidth(r.command.name) + 1)));
+  const tabHint = 'tab complete';
+  const rows: KitRow[] = state.results.map((result, index) => {
+    const selected = index === state.selectedIndex;
+    const name = `/${result.command.name}`;
+    const pad = ' '.repeat(Math.max(2, nameW + 2 - getDisplayWidth(name)));
+    const room = x1 - x0 + 1 - getDisplayWidth(name) - pad.length - (selected ? getDisplayWidth(tabHint) + 2 : 0);
+    const description = result.command.description;
+    const showDesc = selected || getDisplayWidth(description) <= room;
+    return {
+      spans: [
+        { text: name, fg: t.text, bold: selected },
+        ...(showDesc && description ? [{ text: `${pad}${description}`, fg: t.textMuted }] : []),
+      ],
+      right: selected ? tabHint : undefined,
+      selected,
+    };
   });
-  const layout = createOverlayBoxLayout(width, metrics.margin, metrics.boxWidth);
-
-  lines.push(createOverlayBorderLine(width, layout, '┌', '─', '┐', BORDER_FG));
-
-  const titleLine = createOverlayContentLine(width, layout);
-  const titleText = ' Commands';
-  const queryText = state.query ? `/${state.query}` : '/';
-  const queryWidth = Math.min(Math.floor(layout.innerWidth / 2), Math.max(8, layout.innerWidth - getDisplayWidth(titleText) - 2));
-  const leftText = fitDisplay(titleText, Math.max(0, layout.innerWidth - queryWidth));
-  const rightText = truncateDisplay(queryText, queryWidth);
-  putText(titleLine, layout.margin + 2, layout.innerWidth - queryWidth, leftText, { fg: TITLE_FG, bold: true });
-  putText(
-    titleLine,
-    layout.margin + 2 + layout.innerWidth - queryWidth,
-    queryWidth,
-    fitDisplay(rightText, queryWidth),
-    { fg: TITLE_FG, dim: true },
-  );
-  lines.push(titleLine);
-
-  const results = state.results;
-  const total = results.length;
-  const rowBudget = Math.max(1, metrics.contentRows);
-
-  const indicatorWidth = 2;
-  const maxCommandWidth = Math.min(18, Math.max(10, Math.floor(layout.innerWidth * 0.28)));
-  const gapWidth = 2;
-  const descWidth = Math.max(0, layout.innerWidth - indicatorWidth - maxCommandWidth - gapWidth);
-  const wrapWidth = Math.max(8, layout.innerWidth - indicatorWidth);
-
-  // palette curation (item 4): on a bare '/' (query === ''), the results
-  // list is "common tier" (score 2) followed by "alphabetical rest" (score
-  // 1), see CommandRegistry.fuzzyMatch. commonCount marks that boundary;
-  // a one-row separator draws there when it falls inside the visible window.
-  const hasCommonSeparator = state.query === '' && state.commonCount > 0 && state.commonCount < total;
-
-  function descriptionFitsInline(description: string): boolean {
-    return descWidth >= 12 && getDisplayWidth(description) <= descWidth;
-  }
-
-  /** Physical rows a result occupies: 1 for the command-name row, plus one more per wrapped description line when it doesn't fit inline, plus 1 more when the common/rest separator sits immediately before it. */
-  function rowCostFor(index: number): number {
-    const { command } = results[index];
-    const rows = descriptionFitsInline(command.description)
-      ? 1
-      : 1 + wrapWithHangingIndent(command.description, wrapWidth, '').length;
-    const separatorCost = hasCommonSeparator && index === state.commonCount ? 1 : 0;
-    return rows + separatorCost;
-  }
-
-  // Row-budget-aware windowing (mirrors selection-modal-overlay.ts's fix): a
-  // window of results is chosen by their REAL rendered height rather than
-  // assuming one row per item, always including the selected item in full,
-  // growing outward (roughly centered) until the budget is spent.
-  const selectedIdx = Math.max(0, Math.min(state.selectedIndex, total - 1));
-  let startIdx = selectedIdx;
-  let endIdx = selectedIdx + 1;
-  let usedRows = rowCostFor(selectedIdx);
-  let growBefore = true;
-  while (startIdx > 0 || endIdx < total) {
-    const canGrowBefore = growBefore && startIdx > 0;
-    const canGrowAfter = !growBefore && endIdx < total;
-    if (canGrowBefore) {
-      const cost = rowCostFor(startIdx - 1);
-      if (usedRows + cost > rowBudget) break;
-      startIdx -= 1;
-      usedRows += cost;
-    } else if (canGrowAfter) {
-      const cost = rowCostFor(endIdx);
-      if (usedRows + cost > rowBudget) break;
-      endIdx += 1;
-      usedRows += cost;
-    } else if (startIdx > 0) {
-      const cost = rowCostFor(startIdx - 1);
-      if (usedRows + cost > rowBudget) break;
-      startIdx -= 1;
-      usedRows += cost;
-    } else if (endIdx < total) {
-      const cost = rowCostFor(endIdx);
-      if (usedRows + cost > rowBudget) break;
-      endIdx += 1;
-      usedRows += cost;
-    } else {
-      break;
-    }
-    growBefore = !growBefore;
-  }
-
-  for (let i = startIdx; i < endIdx; i++) {
-    if (hasCommonSeparator && i === state.commonCount) {
-      const sepLine = createOverlayContentLine(width, layout);
-      putText(sepLine, layout.margin + 2, layout.innerWidth, '─'.repeat(layout.innerWidth), { fg: BORDER_FG, dim: true });
-      lines.push(sepLine);
-    }
-
-    const { command } = results[i];
-    const isSelected = i === state.selectedIndex;
-    const bg = isSelected ? SELECTED_BG : '';
-    const indicator = isSelected ? '▸ ' : '  ';
-    const commandText = fitDisplay(
-      truncateDisplay(`/${command.name}`, maxCommandWidth),
-      maxCommandWidth,
-    );
-
-    const line = createOverlayContentLine(width, layout, BORDER_FG, bg);
-    let x = layout.margin + 2;
-    putText(line, x, indicatorWidth, indicator, {
-      fg: isSelected ? TITLE_FG : MUTED_FG,
-      bg,
-      bold: isSelected,
-    });
-    x += indicatorWidth;
-    putText(line, x, maxCommandWidth, commandText, {
-      fg: isSelected ? TITLE_FG : BODY_FG,
-      bg,
-      bold: isSelected,
-    });
-    x += maxCommandWidth;
-
-    if (descriptionFitsInline(command.description)) {
-      putText(line, x, gapWidth, '  ', { fg: BODY_FG, bg });
-      x += gapWidth;
-      putText(line, x, descWidth, fitDisplay(command.description, descWidth), {
-        fg: isSelected ? BODY_FG : MUTED_FG,
-        bg,
-        bold: false,
-      });
-      lines.push(line);
-    } else {
-      // Doesn't fit beside the command name, wrap the FULL description onto
-      // its own line(s) below at the full row width, rather than clipping it.
-      lines.push(line);
-      for (const wrapped of wrapWithHangingIndent(command.description, wrapWidth, '')) {
-        const descLine = createOverlayContentLine(width, layout, BORDER_FG, bg);
-        putText(descLine, layout.margin + 2 + indicatorWidth, wrapWidth, fitDisplay(wrapped, wrapWidth), {
-          fg: isSelected ? BODY_FG : MUTED_FG,
-          bg,
-        });
-        lines.push(descLine);
-      }
-    }
-  }
-
-  if (startIdx > 0 || endIdx < total) {
-    const scrollLine = createOverlayContentLine(width, layout);
-    const scrollText = `${state.selectedIndex + 1}/${total}`;
-    putText(
-      scrollLine,
-      layout.margin + 2 + Math.max(0, layout.innerWidth - getDisplayWidth(scrollText)),
-      getDisplayWidth(scrollText),
-      scrollText,
-      { fg: MUTED_FG, dim: true },
-    );
-    lines.push(scrollLine);
-  }
-
-  const footerLine = createOverlayContentLine(width, layout);
-  // vocab unification: "Run"/"Close" match the /help selection modal's
-  // hint bar (selection-modal-overlay.ts), both surfaces execute a command
-  // on Enter, so they now say so the same way.
-  const hints = '[Tab] Complete  [Up/Down] Navigate  [Enter] Run  [Esc] Close';
-  putText(
-    footerLine,
-    layout.margin + 2,
-    layout.innerWidth,
-    fitDisplay(truncateDisplay(hints, layout.innerWidth), layout.innerWidth),
-    { fg: MUTED_FG, dim: true },
-  );
-  lines.push(footerLine);
-
-  lines.push(createOverlayBorderLine(width, layout, '└', '─', '┘', BORDER_FG));
-  return lines;
+  return renderPopup({ width, rows, maxRows: popupRows(viewportHeight), scrollOwner: autocomplete }).lines;
 }

package/src/renderer/back-to-bottom.ts

@@ -0,0 +1,80 @@
+/**
+ * back-to-bottom.ts, the pill that shows while the output is scrolled away
+ * from its live bottom, centered just above the input area:
+ *
+ *        ▐  ↓ Back to bottom   esc  ▌   (drawn as one filled row)
+ *
+ *   fill      the element surface, 2 columns of padding inside each end so
+ *             the text never touches the fill's edge
+ *   ↓         the brand color, bold
+ *   words     "Back to bottom" in the text color
+ *   keycap    ` esc ` on the keycap fill, 2 columns after the words, drawn
+ *             only while the next Esc really goes back to the bottom (an
+ *             empty composer, the keyboard in the input area); otherwise the
+ *             pill names the place without a key, since the status line says
+ *             what that Esc does instead
+ *
+ * It is a fill row, so it keeps one full empty row from any text above it
+ * (the output, or the throbber); the input area's ▄ cap gives the half row
+ * below it (shell-surface.ts builds that stack). Gone at the bottom.
+ */
+
+import { type Line, createEmptyLine } from '@pellux/goodvibes-sdk/platform/types';
+import { getDisplayWidth } from '../utils/terminal-width.ts';
+import { activeTokens } from './theme.ts';
+
+/** What the pill shows. */
+export interface BackToBottomState {
+  /** The next Esc goes back to the live bottom: the pill carries the esc keycap. */
+  readonly escKey: boolean;
+}
+
+const ARROW = '↓';
+const WORDS = 'Back to bottom';
+const KEY = 'esc';
+/** Columns of fill between the pill's edge and its text. */
+const PAD = 2;
+/** Columns between the words and the keycap. */
+const KEY_GAP = 2;
+
+/** The pill's width in cells (with or without its keycap). */
+function backToBottomWidth(state: BackToBottomState): number {
+  const words = getDisplayWidth(ARROW) + 1 + getDisplayWidth(WORDS);
+  return PAD + words + (state.escKey ? KEY_GAP + getDisplayWidth(KEY) + 2 : 0) + PAD;
+}
+
+/** The pill row, centered on a `width`-cell line (terminal background around it). */
+export function renderBackToBottomPill(width: number, state: BackToBottomState): Line {
+  const t = activeTokens();
+  const line = createEmptyLine(width);
+  for (const cell of line) cell.bg = '';
+  // The keycap goes first when the row is short; the pill never runs past
+  // the screen's 3-column margins (fills from column 3 to width-3).
+  const withKey = state.escKey && backToBottomWidth(state) <= width - 6;
+  const shape: BackToBottomState = { escKey: withKey };
+  const pillW = Math.min(backToBottomWidth(shape), Math.max(0, width - 6));
+  if (pillW < PAD * 2 + 1) return line;
+  const x0 = Math.max(3, Math.floor((width - pillW) / 2));
+  const x1 = x0 + pillW; // exclusive
+  const bg = t.backgroundElement;
+  for (let x = x0; x < x1; x++) line[x] = { ...line[x]!, char: ' ', bg };
+  let cx = x0 + PAD;
+  const put = (text: string, style: { fg: string; bg: string; bold?: boolean }): void => {
+    for (const ch of text) {
+      const w = getDisplayWidth(ch);
+      if (w <= 0) continue;
+      if (cx + w > x1 - PAD) return;
+      line[cx] = { char: ch, fg: style.fg, bg: style.bg, bold: style.bold ?? false, dim: false, underline: false, italic: false, strikethrough: false };
+      if (w === 2 && cx + 1 < line.length) line[cx + 1] = { ...line[cx]!, char: '' };
+      cx += w;
+    }
+  };
+  put(ARROW, { fg: t.brand, bg, bold: true });
+  cx += 1;
+  put(WORDS, { fg: t.text, bg });
+  if (withKey) {
+    cx += KEY_GAP;
+    put(` ${KEY} `, { fg: t.text, bg: t.border, bold: true });
+  }
+  return line;
+}