@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/widgets/text-input.js

@@ -3,10 +3,12 @@
  *
  * Two modes:
  *   - single-line (default): Enter submits; newlines in value are rendered
- *                            as a literal `↵` glyph if they ever appear.
+ *                            as a literal `↵` glyph if they ever appear, and
+ *                            any other glyph of zero cells as `◌`.
  *   - multi-line  (`multiline: true`): Enter inserts a `\n`; `value` may
  *                            contain logical line breaks; Up/Down navigate
  *                            between logical lines preserving column intent.
+ *                            A glyph of zero cells is drawn as `◌` here too.
  *
  * [LAW:dataflow-not-control-flow] cursor and value are observable data; the
  * keymap dispatches to small `@action` mutators that all flow through the
@@ -97,7 +99,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 import { observable, action, observableRef, runInAction } from "mobx";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
-import { cellLen, setCellSize, splitText, cellStepFrom, cellColToCodeUnitOffset, asCellCol, asCodePoint, asCodeUnit, graphemeBoundary, graphemes, nextGrapheme, prevGrapheme, } from "../core/cells.js";
+import { cellLen, setCellSize, splitText, cellFitEnd, cellStepFrom, asCellCol, asCodePoint, asCodeUnit, graphemeBoundary, graphemes, nextGrapheme, prevGrapheme, } from "../core/cells.js";
 import { drawable } from "../core/protocol.js";
 import { ThemedWidget } from "./themed-widget.js";
 import { ink } from "./ink.js";
@@ -113,7 +115,7 @@ import { ink } from "./ink.js";
  */
 export const charGreedyWrap = (line, { firstWidth, continuationWidth }) => {
     if (line.length === 0)
-        return [{ content: "", start: asCodePoint(0) }];
+        return [{ start: asCodePoint(0), end: asCodePoint(0) }];
     const rows = [];
     let pos = asCodePoint(0);
     let isFirst = true;
@@ -122,19 +124,29 @@ export const charGreedyWrap = (line, { firstWidth, continuationWidth }) => {
         if (cap <= 0)
             break;
         const end = cellStepFrom(line, pos, cap);
-        rows.push({ content: line.slice(pos, end), start: pos });
+        rows.push({ start: pos, end });
         pos = end;
         isFirst = false;
     }
     return rows;
 };
 const MIN_CONTENT_WIDTH = 8;
-// Each glyph and its ASCII stand-in are one code unit and one cell, so the
-// display string maps 1:1 onto `value` and hit-testing needs no render options.
+// [LAW:one-source-of-truth] The cells single-line content takes: its text and,
+// past the text's end, the cell the cursor stands on there — never fewer than
+// the floor. The render sizes and scrolls the field by it; `measure` asks it
+// with the cursor at the end, the widest a value draws.
+function singleLineExtent(textCells, cursorCell) {
+    return asCellCol(Math.max(MIN_CONTENT_WIDTH, textCells, cursorCell + 1));
+}
+// What one line shows in place of a glyph of `value`; each is one cell.
 const NEWLINE_GLYPH = "↵";
 const ASCII_NEWLINE_GLYPH = "~";
 const MASK_GLYPH = "•";
 const ASCII_MASK_GLYPH = "*";
+// The dotted circle Unicode draws for a mark with no base to sit on; `?` is the
+// ASCII replacement character.
+const ZERO_CELL_GLYPH = "◌";
+const ASCII_ZERO_CELL_GLYPH = "?";
 // Text a key may insert: anything but the C0 controls, DEL and the C1
 // controls, which a terminal reads as escape sequences (U+009B is CSI).
 const PRINTABLE = /^[^\x00-\x1f\x7f-\x9f]+$/u;
@@ -336,7 +348,9 @@ let TextInput = (() => {
         // single-line renderer. Captured by _renderSingleLine and read by
         // handleMouse so the hit-test uses the same visual origin the user sees.
         _singleLineViewportStart = asCellCol(0);
-        _singleLineAsciiOnly = false;
+        // How the last render could draw, so the hit-test and vertical motion
+        // measure `value` as it was shown.
+        _drawn = { asciiOnly: false };
         multiline;
         constructor(options = {}) {
             super(options.theme);
@@ -556,7 +570,7 @@ let TextInput = (() => {
                 // Continuation rows start after the marker; non-continuation rows start at column 0.
                 const contentXOff = asCellCol(row.isContinuation ? this._markerWidth : 0);
                 const relX = asCellCol(Math.max(0, event.x - contentXOff));
-                this.cursorPosition = asCodeUnit(row.valueStart + cellColToCodeUnitOffset(row.content, relX));
+                this.cursorPosition = asCodeUnit(row.valueStart + this._offsetAtShownCell(row.content, relX));
             }
             else {
                 // [LAW:types-are-the-program] relX is a cell-column offset into the full
@@ -564,19 +578,7 @@ let TextInput = (() => {
                 // by _renderSingleLine) so a click on a scrolled viewport maps to the
                 // correct code-unit in the underlying value.
                 const relX = asCellCol(Math.max(0, event.x - 1) + this._singleLineViewportStart);
-                // The glyphs of `value` whose shown cells lie wholly left of the click,
-                // shown as the last render showed them.
-                const drawn = { asciiOnly: this._singleLineAsciiOnly };
-                let at = 0;
-                let col = 0;
-                for (const g of graphemes(this.value)) {
-                    const w = cellLen(this._shown(g, drawn));
-                    if (col + w > relX)
-                        break;
-                    col += w;
-                    at += g.length;
-                }
-                this.cursorPosition = asCodeUnit(at);
+                this.cursorPosition = this._offsetAtShownCell(this.value, relX);
             }
             this._preferredColumn = null;
         }
@@ -610,13 +612,13 @@ let TextInput = (() => {
             if (lineStart === 0)
                 return;
             // Fallback: no render cache yet; use cell-space arithmetic for wide-char correctness.
-            const col = this._preferredColumn ?? asCellCol(cellLen(this.value.slice(lineStart, this.cursorPosition)));
+            const col = this._preferredColumn ?? this._shownCells(this.value.slice(lineStart, this.cursorPosition));
             const prevLineEnd = lineStart - 1;
             let prevLineStart = prevLineEnd;
             while (prevLineStart > 0 && this.value[prevLineStart - 1] !== "\n")
                 prevLineStart--;
             const prevLineContent = this.value.slice(prevLineStart, prevLineEnd);
-            this.cursorPosition = asCodeUnit(prevLineStart + cellColToCodeUnitOffset(prevLineContent, asCellCol(Math.min(col, cellLen(prevLineContent)))));
+            this.cursorPosition = asCodeUnit(prevLineStart + this._offsetAtShownCell(prevLineContent, col));
             this._preferredColumn = col;
         }
         moveLineDown() {
@@ -634,13 +636,13 @@ let TextInput = (() => {
                 return;
             const lineStart = this._lineStart();
             // Fallback: no render cache yet; use cell-space arithmetic for wide-char correctness.
-            const col = this._preferredColumn ?? asCellCol(cellLen(this.value.slice(lineStart, this.cursorPosition)));
+            const col = this._preferredColumn ?? this._shownCells(this.value.slice(lineStart, this.cursorPosition));
             const nextLineStart = lineEnd + 1;
             let nextLineEnd = nextLineStart;
             while (nextLineEnd < this.value.length && this.value[nextLineEnd] !== "\n")
                 nextLineEnd++;
             const nextLineContent = this.value.slice(nextLineStart, nextLineEnd);
-            this.cursorPosition = asCodeUnit(nextLineStart + cellColToCodeUnitOffset(nextLineContent, asCellCol(Math.min(col, cellLen(nextLineContent)))));
+            this.cursorPosition = asCodeUnit(nextLineStart + this._offsetAtShownCell(nextLineContent, col));
             this._preferredColumn = col;
         }
         // Clamp `col` (a cell column) to the target visual row's content, returning
@@ -659,11 +661,11 @@ let TextInput = (() => {
             const rows = this._visualRows;
             const target = rows[targetIdx];
             const nextIsContinuation = targetIdx + 1 < rows.length && rows[targetIdx + 1].isContinuation;
-            const contentCellWidth = asCellCol(cellLen(target.content));
+            const contentCellWidth = this._shownCells(target.content);
             const capCells = nextIsContinuation
                 ? asCellCol(Math.max(0, contentCellWidth - 1))
                 : contentCellWidth;
-            return cellColToCodeUnitOffset(target.content, asCellCol(Math.min(col, capCells)));
+            return this._offsetAtShownCell(target.content, asCellCol(Math.min(col, capCells)));
         }
         // Locate which cached visual row the cursor sits on. Returns the row index
         // for use in `moveLineUp`/`moveLineDown`; caller must guard `_visualRows`.
@@ -683,7 +685,7 @@ let TextInput = (() => {
             const rows = this._visualRows;
             const idx = this._cursorVisualRow();
             const row = rows[idx];
-            return asCellCol(cellLen(row.content.slice(0, this.cursorPosition - row.valueStart)));
+            return this._shownCells(row.content.slice(0, this.cursorPosition - row.valueStart));
         }
         moveLineStart() {
             this.cursorPosition = this._lineStart();
@@ -908,40 +910,67 @@ let TextInput = (() => {
                 : this.contentStyleOverride ?? super.ground;
         }
         draw(options) {
+            this._drawn = { asciiOnly: options.asciiOnly ?? false };
             if (this._multiline)
                 return this._renderMultiline(options);
             return this._renderSingleLine(options);
         }
         // [LAW:dataflow-not-control-flow] How a stretch of `value` is shown in one
-        // line derives from mode: one mask cell per glyph, or `\n` as a visible
-        // glyph. The render and the click hit-test both read it.
+        // line derives glyph by glyph from mode: a mask cell in password mode, else
+        // the glyph itself — or, for a glyph of zero cells, a stand-in of one cell.
+        // Every glyph then has a column of its own, so each cursor stop draws the
+        // cursor somewhere new. The render and the click hit-test both read it.
+        _shownAs(options) {
+            const mask = drawable(options, MASK_GLYPH, ASCII_MASK_GLYPH);
+            const newline = drawable(options, NEWLINE_GLYPH, ASCII_NEWLINE_GLYPH);
+            const zeroCell = drawable(options, ZERO_CELL_GLYPH, ASCII_ZERO_CELL_GLYPH);
+            return (g) => this._password ? mask
+                : cellLen(g) > 0 ? g
+                    : g === "\n" ? newline : zeroCell;
+        }
         _shown(text, options) {
-            return this._password
-                ? drawable(options, MASK_GLYPH, ASCII_MASK_GLYPH).repeat(graphemes(text).length)
-                : text.replace(/\n/g, drawable(options, NEWLINE_GLYPH, ASCII_NEWLINE_GLYPH));
+            return graphemes(text).map(this._shownAs(options)).join("");
+        }
+        // The cells a stretch of `value` took in the last render.
+        _shownCells(text) {
+            return asCellCol(cellLen(this._shown(text, this._drawn)));
+        }
+        // The end of the glyphs of `text` whose cells in the last render lie wholly
+        // left of `col`, so a column inside a wide glyph lands before it.
+        _offsetAtShownCell(text, col) {
+            const shownAs = this._shownAs(this._drawn);
+            let at = 0;
+            let cells = 0;
+            for (const g of graphemes(text)) {
+                cells += cellLen(shownAs(g));
+                if (cells > col)
+                    break;
+                at += g.length;
+            }
+            return asCodePoint(at);
         }
         _renderSingleLine(options) {
             const showPlaceholder = this.focused && this.value.length === 0 && this.placeholder.length > 0;
             // The cursor's column is the width of the shown text before it, whatever
             // the mode — a placeholder is shown only over an empty value.
-            this._singleLineAsciiOnly = options.asciiOnly ?? false;
             const shown = (text) => this._shown(text, options);
             const rawDisplay = showPlaceholder ? this.placeholder : shown(this.value);
             const rawCellWidth = asCellCol(cellLen(rawDisplay));
-            const cursorCellCol = asCellCol(cellLen(shown(this.value.slice(0, this.cursorPosition))));
+            const beforeCursor = shown(this.value.slice(0, this.cursorPosition));
+            const cursorCellCol = asCellCol(cellLen(beforeCursor));
+            // The cursor's glyph, or the one cell past the text's end.
+            const cursorCells = Math.max(1, cellLen(shown(this.value.slice(this.cursorPosition, nextGrapheme(this.value, this.cursorPosition)))));
             const maxAvailable = asCellCol(Math.max(MIN_CONTENT_WIDTH, options.maxWidth - 2));
-            const desiredWidth = asCellCol(Math.max(MIN_CONTENT_WIDTH, rawCellWidth, cursorCellCol + 1));
-            const contentWidth = asCellCol(Math.min(maxAvailable, desiredWidth));
-            // Slide viewport (in cells) to keep cursor visible when content overflows.
-            const startCell = asCellCol(Math.max(0, Math.min(rawCellWidth - contentWidth, cursorCellCol - contentWidth + 1)));
+            const contentWidth = asCellCol(Math.min(maxAvailable, singleLineExtent(rawCellWidth, cursorCellCol)));
+            // The viewport (in cells) starts where the most of the text before the
+            // cursor that fits beside the cursor's glyph begins: a glyph boundary, so
+            // a wide glyph is never cut, and the cursor's glyph always in view.
+            const startCell = asCellCol(cursorCellCol - cellLen(cellFitEnd(beforeCursor, asCellCol(contentWidth - cursorCells))));
+            this._singleLineViewportStart = startCell;
             const [, afterStart] = splitText(rawDisplay, startCell);
-            // splitText snaps backward when startCell falls mid-wide-char, so afterStart
-            // may start 1 cell earlier than requested. actualStartCell is the real offset.
-            const actualStartCell = asCellCol(rawCellWidth - cellLen(afterStart));
-            this._singleLineViewportStart = actualStartCell;
             const [visible] = splitText(afterStart, contentWidth);
             const display = setCellSize(visible, contentWidth);
-            const cursorDisplayCellCol = asCellCol(cursorCellCol - actualStartCell);
+            const cursorDisplayCellCol = asCellCol(cursorCellCol - startCell);
             const bracketStyle = this.disabled
                 ? new Style(this.disabledInk)
                 : new Style(ink(this.theme, "foreground", "background"));
@@ -950,7 +979,7 @@ let TextInput = (() => {
                 : this.ground;
             const cursorStyle = this.cursorStyleOverride ?? new Style(ink(this.theme, "on-primary", "primary"));
             const segments = [new Segment("[", bracketStyle)];
-            if (this.focused && !this.disabled && cursorDisplayCellCol >= 0 && cursorDisplayCellCol < contentWidth) {
+            if (this.focused && !this.disabled) {
                 const [before, rest] = splitText(display, cursorDisplayCellCol);
                 const firstCh = rest.slice(0, nextGrapheme(rest, asCodePoint(0)));
                 const at = firstCh || " ";
@@ -973,7 +1002,7 @@ let TextInput = (() => {
             // *and* cursor projection from the same array. Vertical motion reads
             // from the cache so Up/Down step through whatever the user actually
             // sees, including soft-wrap continuations.
-            const visualRows = this._computeVisualRows(options.maxWidth);
+            const visualRows = this._computeVisualRows(options);
             this._visualRows = visualRows;
             // Scroll window: keep `_scrollStart` (the viewport's top row) stable
             // across renders, adjusting only when the cursor would leave the
@@ -1014,10 +1043,9 @@ let TextInput = (() => {
             // collides with the arrow. Only emitted in `"arrows"` mode; other modes
             // leave the content area untouched and rely on the host to surface scroll
             // state externally (e.g. Panel border accessory).
-            const scrollable = this._maxRows !== undefined && total > this._maxRows;
-            const arrowsMode = this._scrollIndicator === "arrows";
-            const canScrollUp = arrowsMode && scrollable && this._scrollStart > 0;
-            const canScrollDown = arrowsMode && scrollable && this._scrollStart + this._maxRows < total;
+            const arrows = this._drawsArrows(total);
+            const canScrollUp = arrows && this._scrollStart > 0;
+            const canScrollDown = arrows && this._scrollStart + this._maxRows < total;
             const indicatorStyle = this.indicatorStyleOverride ?? new Style(ink(this.theme, "text-primary", "background"));
             const segments = [];
             const showCursor = this.focused && !this.disabled;
@@ -1044,7 +1072,7 @@ let TextInput = (() => {
                 const rowPrintWidth = row.isContinuation
                     ? asCellCol(Math.max(0, options.maxWidth - this._markerWidth))
                     : asCellCol(options.maxWidth);
-                this._emitRowContent(segments, row, rowIdx === cursorRow && showCursor, contentStyle, cursorStyle, indicator, rowPrintWidth);
+                this._emitRowContent(segments, options, row, rowIdx === cursorRow && showCursor, contentStyle, cursorStyle, indicator, rowPrintWidth);
             }
             // Trailing empty rows for minRows padding (no cursor, no marker).
             // Emit a whitespace segment of the full content width so Segment.splitLines
@@ -1056,44 +1084,29 @@ let TextInput = (() => {
             }
             return segments;
         }
-        _emitRowContent(out, row, cursorOnRow, contentStyle, cursorStyle, indicator, rowPrintWidth) {
-            const content = row.content;
-            // cursorCol is a code-unit offset into row.content; both cursorPosition
-            // and valueStart are CodePoint, so their difference lands on a code-point
-            // boundary within content and is safe for string slicing.
-            const cursorCol = cursorOnRow ? this.cursorPosition - row.valueStart : -1;
-            // Fast path: no indicator on this row. Let the wrapper pad to width.
-            if (indicator === undefined) {
-                if (!cursorOnRow) {
-                    if (content.length > 0)
-                        out.push(new Segment(content, contentStyle));
-                    return;
-                }
-                const before = content.slice(0, cursorCol);
-                const nextCp = nextGrapheme(content, asCodePoint(cursorCol));
-                const at = content.slice(cursorCol, nextCp) || " ";
-                const after = content.slice(nextCp);
-                if (before.length > 0)
-                    out.push(new Segment(before, contentStyle));
-                out.push(new Segment(at, cursorStyle));
-                if (after.length > 0)
-                    out.push(new Segment(after, contentStyle));
-                return;
-            }
-            // Indicator path: reserve the indicator's cells at the end of the row so
-            // wide characters never collide with it. Content fills [0, contentCellWidth)
-            // cells; the indicator occupies the remaining cells.
-            const indicatorWidth = asCellCol(cellLen(indicator.ch));
-            const contentCellWidth = asCellCol(Math.max(0, rowPrintWidth - indicatorWidth));
-            // Clip row content to the non-indicator region and pad to exact cell width.
-            const [visibleContent] = splitText(content, contentCellWidth);
-            const paddedContent = setCellSize(visibleContent, contentCellWidth);
-            // Map the code-unit cursor offset to a cell column within this row.
-            const cursorCellColInRow = cursorOnRow && cursorCol >= 0
-                ? cellLen(content.slice(0, cursorCol))
+        // Whether `rows` visual rows draw a scroll arrow in the last cell of a row.
+        _drawsArrows(rows) {
+            return this._scrollIndicator === "arrows" && this._maxRows !== undefined && rows > this._maxRows;
+        }
+        _emitRowContent(out, options, row, cursorOnRow, contentStyle, cursorStyle, indicator, rowPrintWidth) {
+            const shown = this._shown(row.content, options);
+            // An indicator's cells are reserved at the end of the row, so wide glyphs
+            // never collide with it: the content is cut to the cells before it and
+            // padded out to them. With no indicator the wrapper pads the row.
+            const contentCellWidth = indicator === undefined
+                ? Infinity
+                : Math.max(0, rowPrintWidth - cellLen(indicator.ch));
+            const display = indicator === undefined
+                ? shown
+                : setCellSize(splitText(shown, asCellCol(contentCellWidth))[0], asCellCol(contentCellWidth));
+            // cursorPosition and valueStart are both cluster boundaries, so the
+            // cursor's offset into the row is one too, and the shown cells before it
+            // are its column.
+            const cursorCell = cursorOnRow
+                ? cellLen(this._shown(row.content.slice(0, this.cursorPosition - row.valueStart), options))
                 : -1;
-            if (cursorCellColInRow >= 0 && cursorCellColInRow < contentCellWidth) {
-                const [before, rest] = splitText(paddedContent, asCellCol(cursorCellColInRow));
+            if (cursorCell >= 0 && cursorCell < contentCellWidth) {
+                const [before, rest] = splitText(display, asCellCol(cursorCell));
                 const firstCh = rest.slice(0, nextGrapheme(rest, asCodePoint(0)));
                 const at = firstCh || " ";
                 const after = rest.slice(firstCh.length);
@@ -1103,31 +1116,48 @@ let TextInput = (() => {
                 if (after.length > 0)
                     out.push(new Segment(after, contentStyle));
             }
-            else {
-                if (paddedContent.length > 0)
-                    out.push(new Segment(paddedContent, contentStyle));
+            else if (display.length > 0) {
+                out.push(new Segment(display, contentStyle));
             }
-            out.push(new Segment(indicator.ch, indicator.style));
+            if (indicator !== undefined)
+                out.push(new Segment(indicator.ch, indicator.style));
         }
-        _computeVisualRows(maxWidth) {
-            const firstWidth = asCellCol(Math.max(1, maxWidth));
+        _computeVisualRows(options) {
+            const firstWidth = asCellCol(Math.max(1, options.maxWidth));
             const continuationWidth = asCellCol(Math.max(1, firstWidth - this._markerWidth));
+            const shownAs = this._shownAs(options);
             const rows = [];
             const lines = this.value.split("\n");
             let pos = 0;
             for (let li = 0; li < lines.length; li++) {
                 const line = lines[li];
                 if (this._wrap !== undefined) {
-                    const wrapRows = this._wrap(line, { firstWidth, continuationWidth });
+                    // `lineOffset[s]` is where offset `s` of the line as shown falls in
+                    // `line`: a glyph shown as itself maps code unit for code unit, and
+                    // every offset inside a stand-in falls at the start of its glyph, so
+                    // a row the strategy ends there draws the glyph on the next row.
+                    let shownLine = "";
+                    const lineOffset = [];
+                    let at = 0;
+                    for (const g of graphemes(line)) {
+                        const s = shownAs(g);
+                        for (let i = 0; i < s.length; i++)
+                            lineOffset.push(s === g ? at + i : at);
+                        shownLine += s;
+                        at += g.length;
+                    }
+                    lineOffset.push(at);
+                    const wrapRows = this._wrap(shownLine, { firstWidth, continuationWidth });
                     if (wrapRows.length === 0) {
                         rows.push({ content: "", valueStart: asCodePoint(pos), isContinuation: false });
                     }
                     else {
                         for (let ri = 0; ri < wrapRows.length; ri++) {
                             const wr = wrapRows[ri];
+                            const start = lineOffset[wr.start];
                             rows.push({
-                                content: wr.content,
-                                valueStart: asCodePoint(pos + wr.start),
+                                content: line.slice(start, lineOffset[wr.end]),
+                                valueStart: asCodePoint(pos + start),
                                 isContinuation: ri > 0,
                             });
                         }
@@ -1140,17 +1170,30 @@ let TextInput = (() => {
             }
             return rows;
         }
-        measure(_options) {
+        measure(options) {
             const minimum = MIN_CONTENT_WIDTH + 2;
-            const maximum = Math.max(minimum, Math.max(cellLen(this.value), cellLen(this.placeholder)) + 2);
-            return { minimum, maximum };
+            const shownCells = (line) => cellLen(this._shown(line, options));
+            // The widest the value draws, its cursor at the end of a line included. A
+            // multi-line value draws each logical line on rows of its own, with no
+            // brackets and no placeholder, and a scroll arrow's cell past each line
+            // when its lines outnumber the rows.
+            if (this._multiline) {
+                const lines = this.value.split("\n");
+                const arrowCells = this._drawsArrows(lines.length) ? 1 : 0;
+                return { minimum, maximum: lines.reduce((w, line) => Math.max(w, shownCells(line) + 1 + arrowCells), minimum) };
+            }
+            // A single-line value draws its breaks as glyphs between brackets, and its
+            // placeholder over an empty value.
+            const valueCells = shownCells(this.value);
+            return { minimum, maximum: singleLineExtent(this.value === "" ? cellLen(this.placeholder) : valueCells, valueCells) + 2 };
         }
         /**
          * `[X/Y]` scroll-position string when there's actually something to
          * scroll, else `undefined`. X is the cursor's 1-indexed visual row; Y is
          * the total visual row count. Reads cached state populated by the most
          * recent `render()` — call from a `Panel.bottomRightAccessory` thunk so
-         * it evaluates after content has been rendered for the current frame.
+         * it evaluates after content has been rendered for the current frame;
+         * `BorderAccessory` names the widths where it has not.
          *
          * Returns `undefined` when:
          *   - `scrollIndicator` is not `"indices"`, or

package/dist/widgets/widget-app.d.ts

@@ -7,8 +7,10 @@
  * `Table` cell — and nothing lays it out a second time. Everything added here
  * reads the frame the view drew:
  *
- * - Focus moves in document order: the order widgets start to render in
- *   (`RenderOptions.onDraw`), among those with a cell on the frame on screen.
+ * - Focus moves in document order: the order the view reports its widgets in
+ *   (`RenderOptions.onPresent`), among those with a cell on the frame on screen.
+ *   A widget its container hands no column is reported held, not drawn: it is
+ *   in the view, so it keeps focus, and it has no cell, so Tab passes it.
  *   Not reading order — in a `Layout` split into columns, reading order
  *   zigzags between the columns row by row.
  * - Overlays are painted over the view's frame, in document order, directly
@@ -24,10 +26,12 @@
  * hear the input.
  */
 import { Segment } from "../core/segment.js";
+import type { Presence } from "../core/protocol.js";
 import type { Unsubscribe } from "../core/subscription.js";
 import { type AppOptions, type AppPhase, type Wheel } from "../host/app.js";
 import type { FocusManager, FrameSource, KeyEvent, KeyHandlerOptions } from "./types.js";
 import type { AppMouseEvent } from "../host/app.js";
+import { WidgetBase } from "./widget-base.js";
 export interface WidgetAppOptions extends AppOptions {
     /**
      * Whether a left-button press focuses the widget under it, before it hears the
@@ -35,15 +39,27 @@ export interface WidgetAppOptions extends AppOptions {
      */
     readonly focusOnClick?: boolean;
 }
+/** A widget the view reported for a frame, and whether it was drawn or held. */
+export interface WidgetPresence {
+    readonly widget: WidgetBase;
+    readonly presence: Presence;
+}
 export declare class WidgetApp implements FrameSource {
     readonly focusManager: FocusManager;
     private readonly focus;
     private readonly app;
     private readonly router;
     private readonly reaction;
-    private drawn;
+    private _present;
     constructor(options: WidgetAppOptions);
     get phase(): AppPhase;
+    /**
+     * The widgets the view reported for the frame on screen, in document order,
+     * each drawn or held (`RenderOptions.onPresent`). A held widget is one its
+     * container handed no column: in the view, with no cell on the frame.
+     */
+    get present(): readonly WidgetPresence[];
+    private get widgets();
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame(): readonly (readonly Segment[])[];
     /**

package/dist/widgets/widget-app.js

@@ -7,8 +7,10 @@
  * `Table` cell — and nothing lays it out a second time. Everything added here
  * reads the frame the view drew:
  *
- * - Focus moves in document order: the order widgets start to render in
- *   (`RenderOptions.onDraw`), among those with a cell on the frame on screen.
+ * - Focus moves in document order: the order the view reports its widgets in
+ *   (`RenderOptions.onPresent`), among those with a cell on the frame on screen.
+ *   A widget its container hands no column is reported held, not drawn: it is
+ *   in the view, so it keeps focus, and it has no cell, so Tab passes it.
  *   Not reading order — in a `Layout` split into columns, reading order
  *   zigzags between the columns row by row.
  * - Overlays are painted over the view's frame, in document order, directly
@@ -25,6 +27,7 @@
  */
 import { Reaction } from "mobx";
 import { Segment } from "../core/segment.js";
+import { render } from "../core/protocol.js";
 import { App } from "../host/app.js";
 import { DefaultFocusManager } from "./focus-manager.js";
 import { EventRouter } from "./event-router.js";
@@ -38,8 +41,7 @@ export class WidgetApp {
     router;
     // Paints the next frame when anything the last one read changes.
     reaction;
-    // The widgets the view drew for the frame on screen, in document order.
-    drawn = [];
+    _present = [];
     constructor(options) {
         const { view, focusOnClick = true } = options;
         this.reaction = new Reaction("WidgetApp", () => this.app.refresh());
@@ -47,9 +49,12 @@ export class WidgetApp {
             ...options,
             view: (t) => ({ render: (renderOptions) => this.compose(() => view(t), renderOptions) }),
         });
-        this.focus = new DefaultFocusManager(() => {
-            const owners = ownersOn(this.app.frame);
-            return this.drawn.filter((widget) => owners.has(widget));
+        this.focus = new DefaultFocusManager({
+            present: () => this.widgets,
+            onScreen: () => {
+                const owners = ownersOn(this.app.frame);
+                return this.widgets.filter((widget) => owners.has(widget));
+            },
         });
         this.focusManager = this.focus;
         this.router = new EventRouter({ source: this, focusOnClick });
@@ -59,7 +64,7 @@ export class WidgetApp {
         this.app.onMouse((event) => this.router.mouse(event));
         this.app.onWheel((wheel) => this.router.wheel(wheel));
         this.app.onPaint(() => {
-            this.focus.settle(this.drawn);
+            this.focus.settle();
             this.router.framePainted();
         });
         // [LAW:single-enforcer] `settle` judges every focus move, so every move
@@ -69,6 +74,17 @@ export class WidgetApp {
     get phase() {
         return this.app.phase;
     }
+    /**
+     * The widgets the view reported for the frame on screen, in document order,
+     * each drawn or held (`RenderOptions.onPresent`). A held widget is one its
+     * container handed no column: in the view, with no cell on the frame.
+     */
+    get present() {
+        return this._present;
+    }
+    get widgets() {
+        return this._present.map(({ widget }) => widget);
+    }
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame() {
         return this.app.frame;
@@ -131,26 +147,28 @@ export class WidgetApp {
         return this.app.onWheel(handler);
     }
     compose(view, options) {
-        const drawn = new Set();
-        // [LAW:parse-dont-validate] An owner is any object; only a `WidgetBase`
-        // reports itself as a widget, so this is where `object` becomes one.
-        const onDraw = (owner) => {
-            if (owner instanceof WidgetBase)
-                drawn.add(owner);
+        // Each widget once, where it was first reported; drawn anywhere, it is drawn.
+        const present = new Map();
+        // [LAW:parse-dont-validate] What the view reports is any renderable; only
+        // a `WidgetBase` is a widget, so this is where a renderable becomes one.
+        const onPresent = (renderable, presence) => {
+            if (renderable instanceof WidgetBase)
+                present.set(renderable, present.get(renderable) === "drawn" ? "drawn" : presence);
         };
         // The view, its render and the overlays are all tracked, so an observable
         // any of them reads — a label, `focused`, the state that picks what the
         // view shows — paints the next frame when it changes.
-        // An overlay reports what it draws too: a widget in it is on the frame,
-        // and visiting `drawn` in insertion order paints its overlay in turn.
-        const render = { ...options, onDraw };
+        // An overlay reports what it draws too: a widget in it is in the view,
+        // and visiting `present` in report order paints its overlay in turn. A
+        // held widget has no footprint on the frame, and so paints none.
+        const drawing = { ...options, onPresent };
         const lines = tracked(this.reaction, () => {
-            const base = Segment.splitLines(view().render(render));
-            for (const widget of drawn)
-                paintOverlay(base, widget, render);
+            const base = Segment.splitLines(render(view(), drawing));
+            for (const widget of present.keys())
+                paintOverlay(base, widget, drawing);
             return base;
         });
-        this.drawn = [...drawn];
+        this._present = [...present].map(([widget, presence]) => ({ widget, presence }));
         return lines.flatMap((line) => [...line, Segment.line()]);
     }
 }

package/dist/widgets/widget-base.js

@@ -153,10 +153,7 @@ let WidgetBase = (() => {
         // and a click past the end of a short row still reaches it; every row ends
         // in a newline, so a blank last row survives the next `splitLines`. The
         // padding stands on `ground`, whatever the widget draws its own cells on.
-        // Reporting itself before it draws is what puts a widget ahead of the
-        // widgets nested in it in document order — the order focus traverses.
         render(options) {
-            options.onDraw?.(this);
             const drawn = Segment.splitLines(this.draw(options));
             const [width] = Segment.getShape(drawn);
             const lines = Segment.anchorLines(drawn.map((line) => Segment.adjustLineLength(line, width, this.ground)), this);