@pellux/goodvibes-tui 2.0.21 → 2.1.0

package/src/renderer/layout-engine.ts

@@ -3,7 +3,6 @@ export interface ShellLayoutRequest {
   readonly height: number;
   readonly headerHeight: number;
   readonly footerHeight: number;
-  readonly panelWidth?: number;
 }
 
 export interface Rect {
@@ -19,23 +18,13 @@ export interface ShellLayout {
   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));
 }
 
+/** The screen's rows: header, the conversation body (full width), footer. */
 export function createShellLayout(request: ShellLayoutRequest): ShellLayout {
   const width = Math.max(1, request.width);
   const height = Math.max(1, request.height);
@@ -43,55 +32,11 @@ export function createShellLayout(request: ShellLayoutRequest): ShellLayout {
   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,
+    conversation: { x: 0, y: headerHeight, width, height: bodyHeight },
   };
 }

package/src/renderer/layout.ts

@@ -1,4 +1,5 @@
-import { GLYPHS, SPINNER_FRAMES, UI_TONES } from './ui-primitives.ts';
+import { GLYPHS, SPINNER_FRAMES } from './ui-primitives.ts';
+import { activeUiTones } from './theme.ts';
 
 /**
  * Layout constants, single source of truth for margins and content width.
@@ -9,17 +10,10 @@ import { GLYPHS, SPINNER_FRAMES, UI_TONES } from './ui-primitives.ts';
  */
 export { TRANSCRIPT_LAYOUT as LAYOUT } from '@pellux/goodvibes-terminal-shell';
 
-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;
-
+// `color` is a getter so it always reads the active theme.
 export const BORDERS = {
-  THINKING: { char: '▌', color: UI_TONES.state.reasoning },
-  ERROR:    { char: '▌', color: UI_TONES.state.bad },
-  WARNING:  { char: '▌', color: UI_TONES.state.warn },
-  INFO:     { char: '▌', color: UI_TONES.state.info },
+  THINKING: { char: '▌', get color(): string { return activeUiTones().state.reasoning; } },
+  ERROR:    { char: '▌', get color(): string { return activeUiTones().state.bad; } },
+  WARNING:  { char: '▌', get color(): string { return activeUiTones().state.warn; } },
+  INFO:     { char: '▌', get color(): string { return activeUiTones().state.info; } },
 } as const;

package/src/renderer/markdown-inline.ts

@@ -9,6 +9,7 @@
  */
 
 import type { Cell } from '@pellux/goodvibes-sdk/platform/types';
+import { activeTheme } from './theme.ts';
 
 /** Module-level set of inline markdown special characters (hoisted out of hot loop). */
 const INLINE_SPECIAL_CHARS = new Set(['[', '`', '*', '_', '~']);
@@ -102,7 +103,7 @@ export function renderInlineMarkdown(text: string): InlineToken[] {
     if (text.slice(i, i + 2) === '~~') {
       const end = text.indexOf('~~', i + 2);
       if (end !== -1) {
-        tokens.push({ type: 'text', text: text.slice(i + 2, end), style: { strikethrough: true, fg: '244' } });
+        tokens.push({ type: 'text', text: text.slice(i + 2, end), style: { strikethrough: true, fg: activeTheme().strikethrough } });
         i = end + 2;
         continue;
       }

package/src/renderer/markdown-table.ts

@@ -41,7 +41,7 @@
 import { type Line, type Cell, createStyledCell } from '@pellux/goodvibes-sdk/platform/types';
 import { UIFactory } from './ui-factory.ts';
 import { getDisplayWidth } from '../utils/terminal-width.ts';
-import { activeTheme } from './theme.ts';
+import { activeTheme, activeTokens } from './theme.ts';
 import { renderInlineMarkdown } from './markdown-inline.ts';
 
 /** Width a column is given when the budget allows, even if its content is narrower. */
@@ -111,7 +111,7 @@ function flattenCellChars(raw: string, isHdr: boolean): StyledChar[] {
   for (const token of renderInlineMarkdown(raw)) {
     let style: Partial<Cell>;
     if (token.type === 'code') {
-      style = { fg: T.inlineCodeFg, bold: true };
+      style = { fg: activeTokens().markdownCode };
     } else if (token.type === 'link') {
       style = { fg: T.link, underline: true };
     } else {
@@ -121,7 +121,7 @@ function flattenCellChars(raw: string, isHdr: boolean): StyledChar[] {
       style.fg = style.fg || T.heading1;
       style.bold = true;
     } else {
-      style.fg = style.fg || '252';
+      style.fg = style.fg || activeTokens().text;
     }
     for (const ch of token.text) out.push({ char: ch, style });
   }
@@ -203,7 +203,7 @@ function padLineToCells(lineChars: readonly StyledChar[], maxW: number, isHdr: b
     w += cw;
   }
   while (w < maxW) {
-    cells.push(createStyledCell(' ', isHdr ? { fg: T.heading1 } : { fg: '252' }));
+    cells.push(createStyledCell(' ', isHdr ? { fg: T.heading1 } : { fg: activeTokens().text }));
     w++;
   }
   return cells;
@@ -315,16 +315,17 @@ function renderStackedTable(
   hasSeparator: boolean,
   width: number,
   indent: number,
+  rightGutter: number,
 ): Line[] {
   const lines: Line[] = [];
-  const availW = Math.max(1, width - indent);
+  const availW = Math.max(1, width - rightGutter - indent);
   const headerRow = hasSeparator ? parsedRows[0] : undefined;
   const bodyRows = hasSeparator ? parsedRows.slice(1) : [...parsedRows];
   // A header-only table still has to show its headers, so it renders as one
   // record with empty values rather than as nothing at all.
   const records: readonly string[][] = bodyRows.length > 0 ? bodyRows : [[]];
-  const separatorStyle: Partial<Cell> = { fg: '240' };
-  const rule = UIFactory.stringToLine(' '.repeat(indent) + '─'.repeat(availW), width, { fg: '240' });
+  const separatorStyle: Partial<Cell> = { fg: activeTokens().textFaint };
+  const rule = UIFactory.stringToLine(' '.repeat(indent) + '─'.repeat(availW), width, { fg: activeTokens().textFaint });
 
   for (let r = 0; r < records.length; r++) {
     if (r > 0) lines.push(rule);
@@ -348,7 +349,11 @@ function renderStackedTable(
  * Render a markdown table with box-drawing borders. Cells wrap to as many
  * physical lines as their content needs; nothing is ever truncated.
  */
-export function renderTable(rows: string[], width: number, indent: number): Line[] {
+/**
+ * `rightGutter` columns on the right stay clear: the table (boxed or stacked)
+ * ends at width - rightGutter - 1 or earlier.
+ */
+export function renderTable(rows: string[], width: number, indent: number, rightGutter = 0): Line[] {
   const lines: Line[] = [];
 
   // Parse rows into cells, skip separator
@@ -367,7 +372,7 @@ export function renderTable(rows: string[], width: number, indent: number): Line
   if (parsedRows.length === 0) return lines;
 
   const colCount = Math.max(...parsedRows.map((r) => r.length));
-  const availW = width - indent;
+  const availW = width - rightGutter - indent;
 
   // Measure using stripped text (no markdown markers), both the natural width
   // and the widest single word, the latter is what a column needs before it
@@ -391,11 +396,11 @@ export function renderTable(rows: string[], width: number, indent: number): Line
   // the end of the line buffer and silently dropped, so the box is abandoned
   // for the stacked layout instead.
   const boxWidth = indent + 1 + colWidths.reduce((sum, w) => sum + w + 3, 0);
-  if (boxWidth > width) {
-    return renderStackedTable(parsedRows, colCount, hasSeparator, width, indent);
+  if (boxWidth > width - rightGutter) {
+    return renderStackedTable(parsedRows, colCount, hasSeparator, width, indent, rightGutter);
   }
 
-  const bc = '240'; // border color
+  const bc = activeTokens().textFaint; // border color
 
   const makeBorder = (left: string, mid: string, right: string, horiz: string): Line => {
     let s = ' '.repeat(indent) + left;

package/src/renderer/markdown.ts

@@ -2,8 +2,7 @@ import { type Line, type Cell, createStyledCell } from '@pellux/goodvibes-sdk/pl
 import { UIFactory } from './ui-factory.ts';
 import { renderCodeBlock } from './code-block.ts';
 import { getDisplayWidth } from '../utils/terminal-width.ts';
-import { LAYOUT } from './layout.ts';
-import { activeTheme } from './theme.ts';
+import { activeTheme, activeTokens } from './theme.ts';
 import { renderInlineMarkdown, type InlineToken } from './markdown-inline.ts';
 import { isLikelyTableHeaderRow, isLikelyTableSeparatorRow, renderTable } from './markdown-table.ts';
 
@@ -25,6 +24,11 @@ export interface MarkdownRenderOptions {
  * renderMarkdown - Parse markdown text into styled Line[].
  * Thin wrapper over renderMarkdownTracked for callers that don't need code-block metadata.
  */
+/** Column where markdown prose starts (the Measurements table's text column). */
+export const MARKDOWN_TEXT_COL = 5;
+/** Columns kept clear on the right: wrapped prose ends at width-6 or earlier. */
+const MARKDOWN_RIGHT_GUTTER = 5;
+
 export function renderMarkdown(text: string, width: number, options: MarkdownRenderOptions = {}): Line[] {
   return renderMarkdownTracked(text, width, options).lines;
 }
@@ -58,14 +62,39 @@ export function renderMarkdownTracked(
   let codeBlockLines: string[] = [];
   let fenceChar = '`';
   let fenceIndent = 0;
-  const indent = LAYOUT.LEFT_MARGIN;
-  const contentWidth = LAYOUT.contentWidth(width);
+  // Prose starts at column 5 (the Measurements table's text column, the
+  // same column user-message and composer text use) and wraps before
+  // width-5, so the right edge never reaches a fill's padding band.
+  const indent = MARKDOWN_TEXT_COL;
+  const contentWidth = Math.max(1, width - MARKDOWN_RIGHT_GUTTER - indent);
+  const tk = activeTokens();
+
+  // Code blocks, tables, block quotes and rules get exactly one blank row
+  // above and below, whatever the source had. `openBlock` trims the blank
+  // rows already emitted to one; `blankAfter` owes one blank row to whatever
+  // comes next (and swallows extra source blanks until then).
+  const isBlankLine = (line: Line): boolean => line.every((c) => c.char === ' ' || c.char === '');
+  let blankAfter = false;
+  let inQuote = false;
+  const openBlock = (): void => {
+    blankAfter = false;
+    while (lines.length > 0 && isBlankLine(lines[lines.length - 1]!)) lines.pop();
+    if (lines.length > 0) lines.push(UIFactory.stringToLine('', width));
+  };
+  const closeBlock = (): void => { blankAfter = true; };
+  const beforeContent = (): void => {
+    if (blankAfter) {
+      lines.push(UIFactory.stringToLine('', width));
+      blankAfter = false;
+    }
+  };
 
   for (let i = 0; i < rawLines.length; i++) {
     const raw = rawLines[i];
 
     const fenceMatch = raw.match(/^(\s*)(```|~~~)\s*([\w-]*)/);
     if (fenceMatch && !inCodeBlock) {
+      if (inQuote) { inQuote = false; closeBlock(); }
       inCodeBlock = true;
       fenceIndent = fenceMatch[1].length;
       fenceChar = fenceMatch[2][0]; // '`' or '~'
@@ -77,6 +106,7 @@ export function renderMarkdownTracked(
       // Close fence: same char, same or less indentation, at least 3 of that char
       const closeFenceRe = new RegExp(`^\\s{0,${fenceIndent}}${fenceChar === '`' ? '```' : '~~~'}`);
       if (closeFenceRe.test(raw)) {
+        openBlock();
         const blockStart = lines.length;
         const rendered = renderCodeBlock(codeBlockLines, codeBlockLang, width, {
           showLineNumbers: options.codeBlockLineNumbers ?? true,
@@ -88,6 +118,7 @@ export function renderMarkdownTracked(
           rawContent: codeBlockLines.join('\n'),
         });
         lines.push(...rendered);
+        closeBlock();
         inCodeBlock = false;
         codeBlockLang = '';
         codeBlockLines = [];
@@ -100,25 +131,32 @@ export function renderMarkdownTracked(
     }
 
     if (raw.trim() === '') {
+      if (inQuote) { inQuote = false; closeBlock(); }
+      if (blankAfter) continue; // the owed blank row is emitted before the next content
       lines.push(UIFactory.stringToLine('', width));
       continue;
     }
 
+    const isQuoteLine = /^> ?/.test(raw);
+    if (inQuote && !isQuoteLine) { inQuote = false; closeBlock(); }
+    const isRule = /^[-*_]{3,}$/.test(raw.trim());
+    const isTableStart = raw.includes('|') && i + 1 < rawLines.length && isLikelyTableHeaderRow(raw) && isLikelyTableSeparatorRow(rawLines[i + 1]);
+    if (!isQuoteLine && !isRule && !isTableStart) beforeContent();
+
     const h3 = raw.match(/^### (.+)/);
     const h2 = raw.match(/^## (.+)/);
     const h1 = raw.match(/^# (.+)/);
-    if (h1) {
-      lines.push(UIFactory.stringToLine(' '.repeat(indent) + h1[1].toUpperCase(), width, { fg: T.heading1, bold: true }));
-      lines.push(UIFactory.stringToLine(' '.repeat(indent) + '━'.repeat(Math.min(getDisplayWidth(h1[1]), contentWidth)), width, { fg: '244' }));
-      continue;
-    }
-    if (h2) {
-      lines.push(UIFactory.stringToLine(' '.repeat(indent) + h2[1], width, { fg: T.heading2, bold: true }));
-      lines.push(UIFactory.stringToLine(' '.repeat(indent) + '─'.repeat(Math.min(getDisplayWidth(h2[1]), contentWidth)), width, { fg: '240' }));
-      continue;
-    }
-    if (h3) {
-      lines.push(UIFactory.stringToLine(' '.repeat(indent) + h3[1], width, { fg: T.heading3, bold: true }));
+    // Headings keep their own case and carry no rule rows; the heading
+    // color and weight are what mark them.
+    const heading = h1?.[1] ?? h2?.[1] ?? h3?.[1];
+    if (heading !== undefined) {
+      // A heading is a block: one blank row above (unless it opens the
+      // message) and one below.
+      openBlock();
+      lines.push(...compositeInlineLine(' '.repeat(indent), renderInlineMarkdown(heading).map((tok) => (
+        tok.type === 'text' ? { ...tok, style: { ...tok.style, fg: tk.markdownHeading, bold: true } } : tok
+      )), width, {}, indent));
+      closeBlock();
       continue;
     }
 
@@ -131,8 +169,8 @@ export function renderMarkdownTracked(
       const checkbox = checked ? '\u2611 ' : '\u2610 ';
       const rendered = renderInlineMarkdown(taskMatch[3]);
       const prefix = ' '.repeat(bulletX) + checkbox;
-      const style = checked ? { fg: '244', strikethrough: true } : {};
-      lines.push(...compositeInlineLine(prefix, rendered, width, { fg: checked ? T.checkboxChecked : '252', ...style }, textStartX));
+      const style = checked ? { fg: activeTokens().textMuted, strikethrough: true } : {};
+      lines.push(...compositeInlineLine(prefix, rendered, width, { fg: checked ? T.checkboxChecked : activeTokens().text, ...style }, textStartX));
       continue;
     }
 
@@ -143,7 +181,7 @@ export function renderMarkdownTracked(
       const textStartX = bulletX + 2;
       const rendered = renderInlineMarkdown(ulMatch[2]);
       const prefix = ' '.repeat(bulletX) + '• ';
-      lines.push(...compositeInlineLine(prefix, rendered, width, { fg: '135', bold: false }, textStartX));
+      lines.push(...compositeInlineLine(prefix, rendered, width, { fg: tk.textMuted, bold: false }, textStartX));
       continue;
     }
 
@@ -155,24 +193,32 @@ export function renderMarkdownTracked(
       const textStartX = bulletX + numStr.length;
       const rendered = renderInlineMarkdown(olMatch[3]);
       const prefix = ' '.repeat(bulletX) + numStr;
-      lines.push(...compositeInlineLine(prefix, rendered, width, { fg: '135', bold: false }, textStartX));
+      lines.push(...compositeInlineLine(prefix, rendered, width, { fg: tk.textMuted, bold: false }, textStartX));
       continue;
     }
 
-    if (/^[-*_]{3,}$/.test(raw.trim())) {
-      lines.push(UIFactory.stringToLine(' '.repeat(indent) + '─'.repeat(contentWidth), width, { fg: '240' }));
+    if (isRule) {
+      openBlock();
+      lines.push(UIFactory.stringToLine(' '.repeat(indent) + '─'.repeat(contentWidth), width, { fg: tk.markdownHorizontalRule }));
+      closeBlock();
       continue;
     }
 
-    const bqMatch = raw.match(/^> (.*)/);
+    const bqMatch = raw.match(/^> ?(.*)/);
     if (bqMatch) {
-      const rendered = renderInlineMarkdown(bqMatch[1]);
-      const prefix = ' '.repeat(indent) + '┃ ';
-      lines.push(...compositeInlineLine(prefix, rendered, width, { fg: '244', italic: true }, indent + 3));
+      if (!inQuote) { openBlock(); inQuote = true; }
+      // The thin bar runs down every wrapped row of the quote, and the text
+      // keeps the quote color and italic on every row.
+      const rendered = renderInlineMarkdown(bqMatch[1]).map((tok) => (
+        tok.type === 'text' ? { ...tok, style: { fg: tk.markdownBlockQuote, italic: true, ...tok.style } } : tok
+      ));
+      const prefix = ' '.repeat(indent) + '│ ';
+      lines.push(...compositeInlineLine(prefix, rendered, width, { fg: tk.markdownBlockQuote }, indent + 2, prefix));
       continue;
     }
 
-    if (raw.includes('|') && i + 1 < rawLines.length && isLikelyTableHeaderRow(raw) && isLikelyTableSeparatorRow(rawLines[i + 1])) {
+    if (isTableStart) {
+      openBlock();
       const tableRows: string[] = [];
       let j = i;
       while (j < rawLines.length && rawLines[j].includes('|')) {
@@ -180,7 +226,8 @@ export function renderMarkdownTracked(
         j++;
       }
       i = j - 1;
-      lines.push(...renderTable(tableRows, width, indent));
+      lines.push(...renderTable(tableRows, width, indent, MARKDOWN_RIGHT_GUTTER));
+      closeBlock();
       continue;
     }
 
@@ -189,6 +236,7 @@ export function renderMarkdownTracked(
   }
 
   if (inCodeBlock && codeBlockLines.length > 0) {
+    openBlock();
     const blockStart = lines.length;
     const rendered = renderCodeBlock(codeBlockLines, codeBlockLang, width, {
       showLineNumbers: options.codeBlockLineNumbers ?? true,
@@ -214,9 +262,12 @@ function compositeInlineLine(
   tokens: InlineToken[],
   width: number,
   prefixStyle: Partial<Cell>,
-  textStartX: number
+  textStartX: number,
+  /** Drawn on every wrapped row after the first (a block quote's bar); blank when omitted. */
+  continuationPrefix?: string,
 ): Line[] {
   const T = activeTheme();
+  const tk = activeTokens();
   const lines: Line[] = [];
 
   // Flatten tokens to [char, style] pairs
@@ -227,7 +278,7 @@ function compositeInlineLine(
     if (token.type === 'text') {
       for (const ch of token.text) chars.push({ char: ch, style: token.style });
     } else if (token.type === 'code') {
-      for (const ch of token.text) chars.push({ char: ch, style: { fg: T.inlineCodeFg, bold: true } });
+      for (const ch of token.text) chars.push({ char: ch, style: { fg: tk.markdownCode } });
     } else if (token.type === 'link') {
       // Resolve URL: if url is empty or relative, treat as text; if it's a file path, use file:// protocol
       let resolvedUrl = token.url;
@@ -238,8 +289,8 @@ function compositeInlineLine(
     }
   }
 
-  // Render with simple line-breaking at width
-  const availW = width - textStartX;
+  // Wrap before the right gutter so text keeps clear of the screen edge.
+  const availW = width - MARKDOWN_RIGHT_GUTTER - textStartX;
   if (availW <= 0) return lines;
 
   let lineChars: StyledChar[] = [];
@@ -248,9 +299,10 @@ function compositeInlineLine(
   const flushLine = (isFirst: boolean) => {
     const line = new Array(width).fill(null).map(() => createStyledCell(' ')) as Cell[];
     // Write prefix on first line
-    if (isFirst) {
+    const rowPrefix = isFirst ? prefix : continuationPrefix;
+    if (rowPrefix !== undefined) {
       let px = 0;
-      for (const ch of prefix) {
+      for (const ch of rowPrefix) {
         if (px >= width) break;
         const cw = getDisplayWidth(ch);
         line[px] = createStyledCell(ch, { fg: prefixStyle.fg, bg: prefixStyle.bg, bold: prefixStyle.bold, dim: prefixStyle.dim, underline: prefixStyle.underline, italic: prefixStyle.italic, strikethrough: prefixStyle.strikethrough });
@@ -313,9 +365,15 @@ function compositeInlineLine(
       // Space: flush current word, then add the space
       flushWord();
       if (lineW + cw > availW && lineW > 0) {
+        // The row is full: this space is the break itself and is consumed by
+        // it, so the next row starts at the text column, not one to the right.
         flushLine(isFirstLine);
         isFirstLine = false;
+        continue;
       }
+      // A wrapped row never opens with a break space (a run of spaces that
+      // straddles a break). The first row keeps its leading spaces.
+      if (!isFirstLine && lineW === 0) continue;
       lineChars.push(sc);
       lineW += cw;
     } else {

package/src/renderer/masked-entry-modal.ts

@@ -0,0 +1,78 @@
+/**
+ * renderMaskedEntryModal, the local-auth password prompt.
+ *
+ *   ✦ Rotate password  alice                                           esc
+ *
+ *   The password is typed here and never shown, stored in history, or
+ *   written to the transcript.
+ *
+ *   Password   ●●●●●●●●▏
+ *
+ *   ⏎ save   esc cancel
+ *
+ * The password row shows one dot per character; the characters themselves
+ * never reach a cell. Adding a user first asks for the username (plain text,
+ * usernames are not secret) when none was given.
+ */
+
+import { activeTokens } from './theme.ts';
+import { beginModal, finishModal, clipText, type KitHint, type SurfaceLayer } from './surface-kit.ts';
+import { drawTextBlock, modalHeightFor, modalTextWidth, textBlockHeight } from './surface-kit-extra.ts';
+
+/** What the renderer reads from the modal (never the password itself). */
+export interface MaskedEntryView {
+  readonly kind: 'add-user' | 'rotate-password';
+  /** The username (typed or given). */
+  readonly username: string;
+  /** Which field is being typed. */
+  readonly step: 'username' | 'password';
+  /** Characters typed into the password field (only the count is drawn). */
+  readonly passwordLength: number;
+  /** An error from the last attempt, or null. */
+  readonly error: string | null;
+}
+
+const MODAL_WIDTH = 72;
+
+function intro(view: MaskedEntryView): string {
+  return view.step === 'username'
+    ? 'Type the username for the new local user, then its password on the next step.'
+    : 'The password is typed here and never shown, kept in history, or written to the transcript.';
+}
+
+export function renderMaskedEntryModal(view: MaskedEntryView, screenWidth: number, screenHeight: number): SurfaceLayer {
+  const t = activeTokens();
+  const hints: KitHint[] = [['⏎', view.step === 'username' ? 'next' : 'save'], ['esc', 'cancel']];
+  const width = modalTextWidth(screenWidth, screenHeight, MODAL_WIDTH);
+  const introRows = textBlockHeight([{ text: intro(view) }], width);
+  const errorRows = view.error ? textBlockHeight([{ text: view.error }], width) + 1 : 0;
+  const fieldRows = view.kind === 'add-user' ? 2 : 1;
+  const height = modalHeightFor(screenWidth, screenHeight, { width: MODAL_WIDTH, hints }, introRows + 1 + fieldRows + errorRows);
+  const f = beginModal(screenWidth, screenHeight, {
+    title: view.kind === 'add-user' ? 'Add local user' : 'Rotate password',
+    sub: view.step === 'password' ? view.username : undefined,
+    width: MODAL_WIDTH,
+    height,
+    center: true,
+    cap: 'warning',
+    hints,
+  });
+  let y = drawTextBlock(f.canvas, f.l, f.top, width, [{ text: intro(view), style: { fg: t.textMuted } }], f.bottom) + 1;
+  const labelW = 11;
+  const valueX = f.l + labelW;
+  const room = Math.max(1, f.r - valueX);
+  if (view.kind === 'add-user' && y <= f.bottom) {
+    f.canvas.put(f.l, y, 'Username', { fg: t.textMuted });
+    const end = f.canvas.put(valueX, y, clipText(view.username, room), { fg: t.text });
+    if (view.step === 'username') f.canvas.put(end, y, '▏', { fg: t.brand });
+    y++;
+  }
+  if (view.step === 'password' && y <= f.bottom) {
+    f.canvas.put(f.l, y, 'Password', { fg: t.textMuted });
+    const end = f.canvas.put(valueX, y, '●'.repeat(Math.min(view.passwordLength, room)), { fg: t.text });
+    f.canvas.put(end, y, '▏', { fg: t.brand });
+    y++;
+  }
+  if (view.error) drawTextBlock(f.canvas, f.l, y + 1, width, [{ text: view.error, style: { fg: t.error } }], f.bottom);
+  return finishModal(f);
+}