@pellux/goodvibes-tui 2.0.21 → 2.1.1

package/src/renderer/surface-kit-extra.ts

@@ -0,0 +1,303 @@
+/**
+ * surface-kit-extra.ts, small shared helpers layered on the modal surface kit
+ * (surface-kit.ts, surface-kit-list.ts, surface-kit-parts.ts) for surfaces
+ * converted from the old ModalFactory / overlay-box frames:
+ *
+ *   - legacy hint strings ("r refresh", "Enter repair", "←/→ tab") become
+ *     KitHint keycaps; strings that are not a key plus an action (for example
+ *     "/health for latency & routes") are returned as notes to show as text
+ *   - tab rows that wrap onto a second row instead of dropping tabs
+ *   - content-sized modal heights (small dialogs grow to fit their body)
+ *   - measuring a kit list's height, group spacing included
+ *
+ * Colors come only from the active theme's tokens.
+ */
+
+import { createEmptyLine, type Line } from '@pellux/goodvibes-sdk/platform/types';
+import { getDisplayWidth } from '../utils/terminal-width.ts';
+import { activeTokens } from './theme.ts';
+import {
+  MODAL_PAD_X,
+  layoutHintRows,
+  hintLayoutWidth,
+  maxModalHeight,
+  modalGeometry,
+  wrapLines,
+  type KitHint,
+  type KitStyle,
+  type ModalGeometryOptions,
+  type SurfaceCanvas,
+  type SurfaceLayer,
+} from './surface-kit.ts';
+import { isHeader, measureRow, type KitRow } from './surface-kit-list.ts';
+
+// ---------------------------------------------------------------------------
+// Hints
+// ---------------------------------------------------------------------------
+
+const NAMED_KEYS: Readonly<Record<string, string>> = {
+  enter: '⏎',
+  return: '⏎',
+  esc: 'esc',
+  escape: 'esc',
+  tab: 'tab',
+  'shift+tab': 'shift+tab',
+  space: 'space',
+  ' ': 'space',
+  backspace: 'bksp',
+  delete: 'del',
+  del: 'del',
+  pageup: 'pgup',
+  pagedown: 'pgdn',
+  pgup: 'pgup',
+  pgdn: 'pgdn',
+  up: '↑',
+  down: '↓',
+  left: '←',
+  right: '→',
+  'up/down': '↑↓',
+  'left/right': '←→',
+  '←/→': '←→',
+  '↑/↓': '↑↓',
+  '↑↓': '↑↓',
+  '←→': '←→',
+};
+
+/** The keycap text for a key name ("enter" → "⏎", "Up/Down" → "↑↓", "d" → "d"). */
+function keycapLabel(key: string): string {
+  const lower = key.toLowerCase();
+  const named = NAMED_KEYS[lower] ?? NAMED_KEYS[key];
+  if (named) return named;
+  if (/^(ctrl|shift|alt|meta)\+/i.test(key)) return lower;
+  return key;
+}
+
+/** True when `token` reads as a key (a single character, a named key, a range like 1-6, a chord). */
+function isKeyToken(token: string): boolean {
+  if ([...token].length === 1) return true;
+  const lower = token.toLowerCase();
+  if (NAMED_KEYS[lower] !== undefined || NAMED_KEYS[token] !== undefined) return true;
+  if (/^\d-\d$/.test(token)) return true;
+  if (/^(ctrl|shift|alt|meta)\+\S+$/i.test(token)) return true;
+  if (/^f\d{1,2}$/i.test(token)) return true;
+  return false;
+}
+
+/** One legacy hint string as a keycap hint, or null when it is prose (a note). */
+function hintFromString(text: string): KitHint | null {
+  const trimmed = text.trim();
+  // Legacy "[Enter] Load" style.
+  const bracket = /^\[([^\]]+)\]\s+(.+)$/.exec(trimmed);
+  if (bracket) return [keycapLabel(bracket[1]!), bracket[2]!];
+  const space = trimmed.indexOf(' ');
+  if (space <= 0) return null;
+  const key = trimmed.slice(0, space);
+  const action = trimmed.slice(space + 1).trim();
+  if (!action || !isKeyToken(key)) return null;
+  return [keycapLabel(key), action];
+}
+
+/**
+ * Convert legacy hint strings into keycap hints plus notes. Hints whose key is
+ * already present (earlier in `base` or the list) are dropped, so a surface
+ * hint and the matching action hint show once.
+ */
+export function kitHintsFromStrings(
+  strings: readonly string[],
+  base: readonly KitHint[] = [],
+): { readonly hints: KitHint[]; readonly notes: string[] } {
+  const hints: KitHint[] = [...base];
+  const notes: string[] = [];
+  const seen = new Set(base.map(([key]) => key));
+  for (const text of strings) {
+    if (!text.trim()) continue;
+    const hint = hintFromString(text);
+    if (!hint) {
+      if (!notes.includes(text.trim())) notes.push(text.trim());
+      continue;
+    }
+    if (seen.has(hint[0])) continue;
+    seen.add(hint[0]);
+    hints.push(hint);
+  }
+  return { hints, notes };
+}
+
+// ---------------------------------------------------------------------------
+// Heights
+// ---------------------------------------------------------------------------
+
+/** Rows a kit list needs, the blank row above each group but the first included. */
+export function listHeight(rows: readonly KitRow[], x0: number, x1: number): number {
+  let total = 0;
+  rows.forEach((row, k) => {
+    total += measureRow(row, x0, x1);
+    if (k > 0 && isHeader(row)) total += 1;
+  });
+  return total;
+}
+
+/**
+ * The fill height a modal needs for `bodyRows` rows of body (from frame.top to
+ * frame.bottom), given its hints, clamped to what the screen allows. Pass the
+ * result as `height` to beginModal.
+ */
+export function modalHeightFor(
+  screenW: number,
+  screenH: number,
+  options: ModalGeometryOptions & { readonly hints?: readonly KitHint[] },
+  bodyRows: number,
+): number {
+  const g = modalGeometry(screenW, screenH, { width: options.width });
+  const inner = Math.max(1, g.w - 2 * MODAL_PAD_X);
+  const hintRows = options.hints && options.hints.length > 0
+    ? layoutHintRows(options.hints, hintLayoutWidth(inner)).length
+    : 0;
+  // Fill rows: padding, title, blank, body..., [blank, hints...], padding.
+  const need = hintRows > 0 ? bodyRows + hintRows + 5 : bodyRows + 4;
+  return Math.max(5, Math.min(need, maxModalHeight(screenH)));
+}
+
+/** Text width between a modal's inner padding for a screen width (and optional preferred width). */
+export function modalTextWidth(screenW: number, screenH: number, width?: number): number {
+  const g = modalGeometry(screenW, screenH, { width });
+  return Math.max(1, g.w - 2 * MODAL_PAD_X);
+}
+
+// ---------------------------------------------------------------------------
+// Tabs that wrap
+// ---------------------------------------------------------------------------
+
+/** Rows `labels` take when laid out as tabs from x to maxX. */
+export function tabRowCount(labels: readonly string[], x: number, maxX: number): number {
+  return layoutTabs(labels, x, maxX).rows;
+}
+
+function layoutTabs(labels: readonly string[], x: number, maxX: number): { rows: number; at: Array<{ x: number; row: number }> } {
+  const at: Array<{ x: number; row: number }> = [];
+  let cx = x;
+  let row = 0;
+  labels.forEach((label, k) => {
+    const w = getDisplayWidth(label);
+    if (k > 0 && cx + w - 1 > maxX) {
+      row++;
+      cx = x;
+    }
+    at.push({ x: cx, row });
+    cx += w + 4;
+  });
+  return { rows: labels.length === 0 ? 0 : row + 1, at };
+}
+
+/**
+ * Tabs across one or more rows (a tab that does not fit moves to the next
+ * row; none is dropped). The active tab carries the gradient with dark bold
+ * text, the rest are muted. Returns the number of rows used.
+ */
+export function drawTabRows(canvas: SurfaceCanvas, x: number, y: number, labels: readonly string[], active: number, maxX: number): number {
+  const t = activeTokens();
+  const layout = layoutTabs(labels, x, maxX);
+  labels.forEach((label, k) => {
+    const pos = layout.at[k]!;
+    const text = wrapLines(label, Math.max(1, maxX - pos.x + 1))[0] ?? label;
+    const w = getDisplayWidth(text);
+    if (k === active) {
+      canvas.grad(pos.x - 1, y + pos.row, w + 2, t.brand, t.brandEnd);
+      canvas.put(pos.x, y + pos.row, text, { fg: t.selectedListItemText, bold: true });
+    } else {
+      canvas.put(pos.x, y + pos.row, text, { fg: t.textMuted });
+    }
+  });
+  return layout.rows;
+}
+
+// ---------------------------------------------------------------------------
+// Text blocks
+// ---------------------------------------------------------------------------
+
+/** A block of text lines, each wrapped in full, with its own style. */
+export interface TextLine {
+  readonly text: string;
+  readonly style?: KitStyle;
+}
+
+/** Wrapped row count of a text block. */
+export function textBlockHeight(lines: readonly TextLine[], width: number): number {
+  return lines.reduce((n, line) => n + (line.text === '' ? 1 : wrapLines(line.text, width).length), 0);
+}
+
+/** Draw a text block from row y (wrapping each line in full); returns the row after it. */
+export function drawTextBlock(canvas: SurfaceCanvas, x: number, y: number, width: number, lines: readonly TextLine[], maxY = Number.POSITIVE_INFINITY): number {
+  const t = activeTokens();
+  let yy = y;
+  for (const line of lines) {
+    if (line.text === '') { yy++; continue; }
+    for (const part of wrapLines(line.text, width)) {
+      if (yy > maxY) return yy;
+      canvas.put(x, yy, part, { fg: t.text, ...line.style });
+      yy++;
+    }
+  }
+  return yy;
+}
+
+// ---------------------------------------------------------------------------
+// List and detail: a list on the left, an element inset on the right
+// ---------------------------------------------------------------------------
+
+/** Text width below which list-and-detail modals stack the inset under the list. */
+const LIST_DETAIL_MIN_WIDTH = 60;
+
+export interface ListDetailSplit {
+  /** The list's text span and rows (inclusive). */
+  readonly x0: number;
+  readonly x1: number;
+  readonly top: number;
+  readonly bottom: number;
+  /** The inset fill rectangle (text inside it keeps 2 columns of padding and a padding row). */
+  readonly detailX: number;
+  readonly detailY: number;
+  readonly detailW: number;
+  readonly detailH: number;
+  readonly stacked: boolean;
+}
+
+/**
+ * Split a modal body (rows top..bottom between text columns l..r) into a list
+ * and an element inset. Wide bodies put the list on the left (`ratio` of the
+ * width) and the inset on the right, reaching 2 columns from the fill's edge
+ * like the concept's palette preview; narrow bodies stack the inset under the
+ * list (`listRows` rows for the list, at least a third of the body).
+ */
+export function splitListDetail(l: number, r: number, top: number, bottom: number, ratio = 0.45, listRows?: number): ListDetailSplit {
+  const inner = r - l + 1;
+  if (inner >= LIST_DETAIL_MIN_WIDTH) {
+    const x1 = l + Math.max(20, Math.floor(inner * ratio)) - 1;
+    return { x0: l, x1, top, bottom, detailX: x1 + 3, detailY: top, detailW: r - x1, detailH: bottom - top + 1, stacked: false };
+  }
+  const body = bottom - top + 1;
+  const rows = Math.max(3, Math.min(listRows ?? Math.floor(body / 2), body - 5));
+  const listBottom = top + rows - 1;
+  return { x0: l, x1: r, top, bottom: listBottom, detailX: l - 2, detailY: listBottom + 2, detailW: inner + 4, detailH: bottom - listBottom - 1, stacked: true };
+}
+
+// ---------------------------------------------------------------------------
+// Layers as plain lines
+// ---------------------------------------------------------------------------
+
+/**
+ * A layer's cells placed on `height` blank lines of `width` columns, with no
+ * dimming (for a surface that owns the whole viewport, such as onboarding).
+ */
+export function layerToLines(layer: SurfaceLayer, width: number, height: number): Line[] {
+  const lines: Line[] = Array.from({ length: height }, () => createEmptyLine(width));
+  layer.lines.forEach((row, r) => {
+    const target = lines[layer.y + r];
+    if (!target) return;
+    row.forEach((cell, c) => {
+      const x = layer.x + c;
+      if (x >= 0 && x < width) target[x] = { ...cell };
+    });
+  });
+  return lines;
+}

package/src/renderer/surface-kit-list.ts

@@ -0,0 +1,366 @@
+/**
+ * surface-kit-list.ts, list rows and group headers for the modal surface kit.
+ *
+ *   ✦ group header         lowercase, accent (violet), bold; a blank row above
+ *                          every group except the first (dropped when a
+ *                          narrow or short list does not fit)
+ *   ● Label  description             right metadata
+ *     wrapped continuation of a long label or description
+ *
+ * The selected row is the one loud element: a brand → brandEnd gradient inset 2
+ * columns from each side of the fill, with dark bold text
+ * (selectedListItemText). Long labels and descriptions wrap onto continuation
+ * rows; nothing is clipped. When the list does not fit, group spacing collapses
+ * first (always when that makes it fit; on a narrow screen or a short list
+ * area in every case), then the list scrolls around the selected row and reports how many
+ * rows are hidden above and below (drawn as a muted "12 more ↓" count).
+ */
+
+import { getDisplayWidth } from '../utils/terminal-width.ts';
+import { activeTokens } from './theme.ts';
+import { MODAL_MARK_INSET, SurfaceCanvas, scrollCountText, type KitStyle } from './surface-kit.ts';
+
+/** A run of text with one style (used for custom labels such as fuzzy-match highlights). */
+export interface KitSpan {
+  readonly text: string;
+  readonly fg?: string;
+  readonly bold?: boolean;
+  readonly italic?: boolean;
+  readonly strikethrough?: boolean;
+}
+
+/** One list row: a group header when `header` is set, an item otherwise. */
+export interface KitRow {
+  readonly header?: string;
+  readonly headerRight?: string;
+  readonly label?: string;
+  /** Custom label spans; replaces `label` when set. */
+  readonly spans?: readonly KitSpan[];
+  /** Muted text after the label (wraps with it). */
+  readonly desc?: string;
+  /** Muted metadata right-aligned on the row's first line. */
+  readonly right?: string;
+  readonly rightFg?: string;
+  /** A marker 2 columns in from the fill edge (● ✓ ◐ ✕ …). */
+  readonly mark?: string;
+  readonly markFg?: string;
+  readonly selected?: boolean;
+  /** The active choice: label in the brand color when not selected. */
+  readonly current?: boolean;
+  /** A destructive / armed row: label in the error color; a red fill instead of the gradient when selected. */
+  readonly danger?: boolean;
+  readonly labelFg?: string;
+  readonly bold?: boolean;
+  /** Rows shown dimmer (unavailable entries). */
+  readonly muted?: boolean;
+}
+
+export function isHeader(row: KitRow): boolean {
+  return row.header !== undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Wrapping styled spans
+// ---------------------------------------------------------------------------
+
+interface Piece { text: string; style: KitStyle }
+
+/** Greedy word wrap over styled spans; each output row is a list of pieces. */
+function wrapSpans(spans: readonly Piece[], width: number): Piece[][] {
+  const rows: Piece[][] = [[]];
+  let used = 0;
+  const pushText = (text: string, style: KitStyle): void => {
+    const row = rows[rows.length - 1]!;
+    const last = row[row.length - 1];
+    if (last && last.style === style) last.text += text;
+    else row.push({ text, style });
+    used += getDisplayWidth(text);
+  };
+  const newRow = (): void => { rows.push([]); used = 0; };
+  for (const span of spans) {
+    // Split into words keeping the separating spaces attached to the front.
+    const words = span.text.split(/(?= )/);
+    for (const raw of words) {
+      let word = raw;
+      const w = getDisplayWidth(word);
+      if (used > 0 && used + w > width) {
+        newRow();
+        word = word.replace(/^ +/, '');
+      } else if (used === 0) {
+        word = word.replace(/^ +/, '');
+      }
+      // A word longer than the row: hard-split it.
+      while (getDisplayWidth(word) > width) {
+        let cut = '';
+        let cw = 0;
+        for (const ch of word) {
+          const chw = getDisplayWidth(ch);
+          if (used + cw + chw > width) break;
+          cut += ch;
+          cw += chw;
+        }
+        if (cut.length === 0) { newRow(); continue; }
+        pushText(cut, span.style);
+        word = word.slice(cut.length);
+        newRow();
+      }
+      if (word.length > 0) pushText(word, span.style);
+    }
+  }
+  return rows.filter((row, k) => row.length > 0 || k === 0);
+}
+
+// ---------------------------------------------------------------------------
+// Rows
+// ---------------------------------------------------------------------------
+
+interface RowLayout {
+  readonly lines: Piece[][];
+  readonly right?: string;
+}
+
+function rowPieces(row: KitRow): Piece[] {
+  const t = activeTokens();
+  const sel = row.selected === true;
+  const ink = t.selectedListItemText;
+  const labelFg = sel ? ink
+    : row.danger ? t.error
+    : row.current ? t.brand
+    : row.muted ? t.textFaint
+    : row.labelFg ?? t.text;
+  const pieces: Piece[] = [];
+  if (row.spans) {
+    for (const span of row.spans) {
+      pieces.push({ text: span.text, style: { fg: sel ? ink : span.fg ?? labelFg, bold: sel || span.bold === true, italic: span.italic, strikethrough: span.strikethrough } });
+    }
+  } else {
+    pieces.push({ text: row.label ?? '', style: { fg: labelFg, bold: sel || row.bold === true } });
+  }
+  if (row.desc) pieces.push({ text: `  ${row.desc}`, style: { fg: sel ? ink : t.textMuted } });
+  return pieces;
+}
+
+function layoutRow(row: KitRow, x0: number, x1: number): RowLayout {
+  const width = Math.max(1, x1 - x0 + 1);
+  if (isHeader(row)) return { lines: [[{ text: row.header!.toLowerCase(), style: {} }]], right: row.headerRight };
+  const rightW = row.right ? getDisplayWidth(row.right) + 2 : 0;
+  const textW = Math.max(4, width - rightW);
+  const lines = wrapSpans(rowPieces(row), textW);
+  return { lines, right: row.right };
+}
+
+/** Rows a list row takes at the given text span. */
+export function measureRow(row: KitRow, x0: number, x1: number): number {
+  return layoutRow(row, x0, x1).lines.length;
+}
+
+/**
+ * Draw one row (header or item) with its text starting at x0 and right
+ * metadata ending at x1. Returns the number of canvas rows used.
+ */
+export function drawRow(canvas: SurfaceCanvas, y: number, row: KitRow, x0: number, x1: number, maxY = Number.POSITIVE_INFINITY): number {
+  const t = activeTokens();
+  const layout = layoutRow(row, x0, x1);
+  if (isHeader(row)) {
+    canvas.put(x0 - MODAL_MARK_INSET, y, '✦', { fg: t.brandEnd });
+    canvas.put(x0, y, row.header!.toLowerCase(), { fg: t.accent, bold: true });
+    if (row.headerRight) canvas.right(x1, y, row.headerRight, { fg: t.textFaint });
+    return 1;
+  }
+  const sel = row.selected === true;
+  const ink = t.selectedListItemText;
+  const used = Math.min(layout.lines.length, Math.max(1, maxY - y + 1));
+  if (sel) {
+    // An armed (danger) row is red, not the gradient: it is about to do something destructive.
+    const span = x1 - x0 + 1 + 2 * MODAL_MARK_INSET;
+    for (let k = 0; k < used; k++) {
+      if (row.danger) canvas.tint(x0 - MODAL_MARK_INSET, y + k, span, t.error);
+      else canvas.grad(x0 - MODAL_MARK_INSET, y + k, span, t.brand, t.brandEnd);
+    }
+  }
+  if (row.mark) canvas.put(x0 - MODAL_MARK_INSET, y, row.mark, { fg: sel ? ink : row.markFg ?? t.brand, bold: sel });
+  for (let k = 0; k < used; k++) {
+    let cx = x0;
+    for (const piece of layout.lines[k]!) cx = canvas.put(cx, y + k, piece.text, piece.style);
+  }
+  if (layout.right) canvas.right(x1, y, layout.right, { fg: sel ? ink : row.rightFg ?? t.textFaint, bold: false });
+  return used;
+}
+
+// ---------------------------------------------------------------------------
+// Lists
+// ---------------------------------------------------------------------------
+
+export interface KitListOptions {
+  readonly rows: readonly KitRow[];
+  /** First and last canvas rows the list may use (inclusive). */
+  readonly top: number;
+  readonly bottom: number;
+  readonly x0: number;
+  readonly x1: number;
+  /** Row index to start from when scrolling (clamped so the selected row stays visible). */
+  readonly scrollStart?: number;
+  /**
+   * Remember this list's scroll position between renders (keyed by an owner
+   * object, usually the modal's state, and a list name), so the window only
+   * moves when the selection leaves it instead of re-anchoring every frame.
+   */
+  readonly scrollKey?: { readonly owner: object; readonly name: string };
+}
+
+const scrollMemory = new WeakMap<object, Map<string, number>>();
+
+/** The remembered first row of a list (see KitListOptions.scrollKey). */
+export function rememberedStart(key: KitListOptions['scrollKey']): number | undefined {
+  return key ? scrollMemory.get(key.owner)?.get(key.name) : undefined;
+}
+
+/** Record a list's first row for the next render. */
+export function rememberStart(key: KitListOptions['scrollKey'], start: number): void {
+  if (!key) return;
+  let names = scrollMemory.get(key.owner);
+  if (!names) {
+    names = new Map();
+    scrollMemory.set(key.owner, names);
+  }
+  names.set(key.name, start);
+}
+
+export interface KitListResult {
+  /** Item rows (headers excluded) hidden above / below the window. */
+  readonly above: number;
+  readonly below: number;
+  /** Index of the first row drawn. */
+  readonly start: number;
+  /** Canvas row after the last row drawn. */
+  readonly endY: number;
+}
+
+interface ListPlan {
+  readonly capacity: number;
+  readonly heights: readonly number[];
+  /** Whether the blank row above each group header (but the first) is drawn. */
+  readonly gaps: boolean;
+  /** True when the rows do not all fit and the list scrolls. */
+  readonly scrolls: boolean;
+  /** Canvas rows that rows from..to take, spacing included when `gaps` is on. */
+  readonly spanOf: (from: number, to: number) => number;
+}
+
+/** Heights, group spacing and whether the list scrolls, by the rules drawList documents. */
+function planList(canvas: SurfaceCanvas, options: KitListOptions): ListPlan {
+  const { rows, top, bottom, x0, x1 } = options;
+  const capacity = Math.max(1, bottom - top + 1);
+  const heights = rows.map((row) => measureRow(row, x0, x1));
+  // Prefix sums keep every span query O(1): catalogs run to thousands of rows.
+  const heightPre = [0];
+  const headerPre = [0];
+  for (let i = 0; i < rows.length; i++) {
+    heightPre.push(heightPre[i]! + heights[i]!);
+    headerPre.push(headerPre[i]! + (isHeader(rows[i]!) ? 1 : 0));
+  }
+  const span = (from: number, to: number, withGaps: boolean): number => {
+    if (to < from) return 0;
+    const base = heightPre[to + 1]! - heightPre[from]!;
+    // A blank row above every header after the first row of the span.
+    return withGaps ? base + (headerPre[to + 1]! - headerPre[from + 1]!) : base;
+  };
+  const last = rows.length - 1;
+  if (rows.length === 0 || span(0, last, true) <= capacity) {
+    return { capacity, heights, gaps: true, scrolls: false, spanOf: (from, to) => span(from, to, true) };
+  }
+  // Spacing collapses before anything is cut; when the list scrolls anyway it
+  // stays on a wide screen with room, and goes on a narrow screen or a short list.
+  const scrolls = span(0, last, false) > capacity;
+  const gaps = scrolls && !canvas.compact && capacity >= SHORT_LIST_ROWS;
+  return { capacity, heights, gaps, scrolls, spanOf: (from, to) => span(from, to, gaps) };
+}
+
+/**
+ * The furthest first row a list can scroll to and still fill its area: for
+ * callers that track their own scroll position (drawList's scrollStart) and
+ * need to know where the end is, by the same spacing rules drawList uses.
+ */
+export function listScrollEnd(canvas: SurfaceCanvas, options: KitListOptions): number {
+  const plan = planList(canvas, options);
+  if (!plan.scrolls) return 0;
+  const last = options.rows.length - 1;
+  let start = last;
+  while (start > 0 && plan.spanOf(start - 1, last) <= plan.capacity) start--;
+  return start;
+}
+
+/**
+ * A list shorter than this many rows drops its group spacing as soon as it
+ * scrolls: on a short screen every row of content is worth more than the gap.
+ */
+const SHORT_LIST_ROWS = 10;
+
+/**
+ * Draw a list of rows between `top` and `bottom`, keeping the selected row in
+ * view. Group spacing (the blank row above each header but the first) stays
+ * while the list scrolls on a wide screen. It collapses before any row is cut
+ * when everything would fit without it, and it is dropped whenever the list
+ * does not fit on a narrow screen (below 90 columns) or a short list area.
+ */
+export function drawList(canvas: SurfaceCanvas, options: KitListOptions): KitListResult {
+  const { rows, top, bottom, x0, x1 } = options;
+  const plan = planList(canvas, options);
+  const { gaps, heights } = plan;
+  let start = 0;
+  const last = rows.length - 1;
+  if (plan.scrolls) {
+    const { capacity, spanOf } = plan;
+    const selected = rows.findIndex((row) => row.selected === true);
+    start = Math.max(0, Math.min(rememberedStart(options.scrollKey) ?? options.scrollStart ?? 0, last));
+    if (selected >= 0) {
+      if (selected < start) start = selected;
+      while (start < selected && spanOf(start, selected) > capacity) start++;
+      // Show the selected row's group header when there is room for it.
+      if (start > 0 && start === selected && isHeader(rows[start - 1]!) && spanOf(start - 1, selected) <= capacity) start--;
+    }
+    // Do not leave empty space at the end when scrolled down.
+    while (start > 0 && spanOf(start - 1, last) <= capacity) start--;
+  }
+
+  rememberStart(options.scrollKey, start);
+  let y = top;
+  let lastDrawn = start - 1;
+  for (let i = start; i < rows.length; i++) {
+    const gap = gaps && i > start && isHeader(rows[i]!) ? 1 : 0;
+    if (y + gap > bottom) break;
+    // A header with no room for an item under it is left for the next page.
+    if (isHeader(rows[i]!) && y + gap + 1 > bottom && i < rows.length - 1) break;
+    y += gap;
+    const used = drawRow(canvas, y, rows[i]!, x0, x1, bottom);
+    y += used;
+    lastDrawn = i;
+    if (used < heights[i]!) break;
+  }
+  const countItems = (from: number, to: number): number => {
+    let n = 0;
+    for (let i = from; i <= to; i++) if (!isHeader(rows[i]!)) n++;
+    return n;
+  };
+  return {
+    above: countItems(0, start - 1),
+    below: countItems(lastDrawn + 1, last),
+    start,
+    endY: y,
+  };
+}
+
+/**
+ * drawList for a list that has no hint row of its own: when rows are hidden,
+ * the list's last row carries the muted scroll count ("3 more ↑ · 12 more ↓").
+ */
+export function drawScrollingList(canvas: SurfaceCanvas, options: KitListOptions): KitListResult {
+  const scratch = new SurfaceCanvas(canvas.width, canvas.height);
+  scratch.compact = canvas.compact;
+  const trial = drawList(scratch, options);
+  if (trial.above === 0 && trial.below === 0) return drawList(canvas, options);
+  const result = drawList(canvas, { ...options, bottom: options.bottom - 1 });
+  const text = scrollCountText(result.above, result.below);
+  if (text) canvas.right(options.x1, options.bottom, text, { fg: activeTokens().textFaint });
+  return result;
+}