@promptctl/rich-js 0.2.0 → 0.3.0

package/dist/widgets/text-input.js

@@ -1,16 +1,59 @@
 /**
- * TextInput widget — single-line editable text field with cursor.
- * [LAW:dataflow-not-control-flow] cursor is a data position; when focused,
- * exactly one cell is rendered with reverse-video styling on every frame.
- * [LAW:one-type-per-behavior] shared infrastructure inherited from WidgetBase.
+ * TextInput widget — editable text field with cursor.
  *
- * Visual states:
- *   normal      — "[value______]" with brackets bracketing fixed-width content
- *   focused     — same width with cursor cell (reverse video) at cursorPosition
- *   placeholder — focused + empty value: dimmed placeholder text shown,
- *                 cursor at position 0
- *   password    — every value char rendered as "•"
- *   disabled    — entire segment dimmed
+ * Two modes:
+ *   - single-line (default): Enter submits; newlines in value are rendered
+ *                            as a literal `↵` glyph if they ever appear.
+ *   - multi-line  (`multiline: true`): Enter inserts a `\n`; `value` may
+ *                            contain logical line breaks; Up/Down navigate
+ *                            between logical lines preserving column intent.
+ *
+ * [LAW:dataflow-not-control-flow] cursor and value are observable data; the
+ * keymap dispatches to small `@action` mutators that all flow through the
+ * same value/cursor update path. There is no per-key bespoke branch in the
+ * render loop or the change-emit path.
+ *
+ * [LAW:one-source-of-truth] The cursor's logical line — and therefore "what
+ * Home/End/Up/Down mean" — is derived from `value` and `cursorPosition` via
+ * `_lineStart()` / `_lineEnd()`. Multi-line behavior is the same code path
+ * as single-line; with no `\n` in `value`, line bounds collapse to value
+ * bounds, so single-line semantics are recovered without a special case.
+ *
+ * [LAW:types-are-the-program] Three integer spaces coexist: `CellCol` (terminal
+ * cell columns), `CodeUnit` (JS UTF-16 indices), and `CodePoint` (code-unit
+ * offsets that are additionally on a Unicode code-point boundary — a subtype of
+ * `CodeUnit`). `cursorPosition` is `CodePoint`; it is never inside a surrogate
+ * pair by construction. Visual positions are `CellCol`. The three are never
+ * interchangeable — the type system enforces this at every crossing point.
+ *
+ * Keymap (readline / emacs compatible):
+ *
+ *   ─── motion ───
+ *   left | Ctrl+B               char left
+ *   right | Ctrl+F              char right
+ *   up | Ctrl+P                 line up   (preserves preferred column)
+ *   down | Ctrl+N               line down (preserves preferred column)
+ *   home | Ctrl+A               line start
+ *   end | Ctrl+E                line end
+ *   Ctrl+Home                   document start
+ *   Ctrl+End                    document end
+ *   Ctrl+Left | Alt+Left | Alt+B   word left
+ *   Ctrl+Right | Alt+Right | Alt+F word right
+ *
+ *   ─── editing ───
+ *   backspace | Ctrl+H          delete char back
+ *   delete | Ctrl+D             delete char forward
+ *   Ctrl+W | Alt+Backspace      delete word back  (whitespace-bounded; readline parity)
+ *   Alt+D                       delete word forward
+ *   Ctrl+U                      kill to line start (stores in kill buffer)
+ *   Ctrl+K                      kill to line end   (stores in kill buffer)
+ *   Ctrl+Y                      yank kill buffer at cursor
+ *   Ctrl+T                      transpose chars (swap pre-cursor/at-cursor, advance)
+ *   enter                       submit (single-line) or insert `\n` (multiline)
+ *
+ * Motion and editing primitives are also exposed as public methods
+ * (`moveCharLeft`, `killLineForward`, etc.) so a host can bind custom keys
+ * or invoke them programmatically.
  */
 var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
     var useValue = arguments.length > 2;
@@ -50,11 +93,59 @@ import { observable, action } from "mobx";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { ColorSpec } from "../core/color.js";
+import { cellLen, setCellSize, splitText, cellFitFrom, cellColToCodeUnitOffset, asCellCol, asCodePoint, nextCodePoint, prevCodePoint, } from "../core/cells.js";
 import { DEFAULT_TERMINAL_THEME } from "../themes/terminalThemes.js";
 import { WidgetBase } from "./widget-base.js";
+/**
+ * Character-greedy soft wrap. Breaks at any character once `firstWidth`
+ * (or `continuationWidth` for continuation rows) cells are exhausted. The
+ * textarea default when a consumer says "wrap, I don't care how" — no syntax
+ * awareness, just fits the line to the width.
+ *
+ * Wide characters (CJK, emoji) are treated as atomic: a char that would
+ * straddle the budget is moved to the next row rather than split. When the
+ * budget is too narrow to fit even one character, that character is
+ * force-taken to guarantee progress (avoids an infinite loop).
+ */
+export const charGreedyWrap = (line, { firstWidth, continuationWidth }) => {
+    if (line.length === 0)
+        return [{ content: "", start: asCodePoint(0) }];
+    const rows = [];
+    let pos = asCodePoint(0);
+    let isFirst = true;
+    while (pos < line.length) {
+        const cap = isFirst ? firstWidth : continuationWidth;
+        if (cap <= 0)
+            break;
+        let end = cellFitFrom(line, pos, cap);
+        if (end === pos) {
+            // Leading character exceeds cap — force-take one code point to guarantee
+            // progress when the terminal is extremely narrow.
+            end = nextCodePoint(line, pos);
+            if (end === pos)
+                break;
+        }
+        rows.push({ content: line.slice(pos, end), start: pos });
+        pos = end;
+        isFirst = false;
+    }
+    return rows;
+};
 const MIN_CONTENT_WIDTH = 8;
+const NEWLINE_GLYPH = "↵";
+// Word-character regex used by Alt+B/F and Ctrl+Left/Right. Matches the
+// readline default (alphanumeric + underscore), which is what users typing
+// shell commands or code identifiers expect.
+const WORD_CHAR_RE = /[A-Za-z0-9_]/;
+const WHITESPACE_RE = /\s/;
+function isWordChar(c) {
+    return c !== undefined && WORD_CHAR_RE.test(c);
+}
+function isWhitespace(c) {
+    return c !== undefined && WHITESPACE_RE.test(c);
+}
 let TextInput = (() => {
-    var _a;
+    var _a, _b, _c, _d;
     let _classSuper = WidgetBase;
     let _instanceExtraInitializers = [];
     let _value_decorators;
@@ -66,24 +157,96 @@ let TextInput = (() => {
     let _placeholder_decorators;
     let _placeholder_initializers = [];
     let _placeholder_extraInitializers = [];
+    let _indicatorStyleOverride_decorators;
+    let _indicatorStyleOverride_initializers = [];
+    let _indicatorStyleOverride_extraInitializers = [];
+    let _cursorStyleOverride_decorators;
+    let _cursorStyleOverride_initializers = [];
+    let _cursorStyleOverride_extraInitializers = [];
+    let _contentStyleOverride_decorators;
+    let _contentStyleOverride_initializers = [];
+    let _contentStyleOverride_extraInitializers = [];
     let _handleKey_decorators;
     let _handleMouse_decorators;
     let _setHovered_decorators;
+    let _moveCharLeft_decorators;
+    let _moveCharRight_decorators;
+    let _moveLineUp_decorators;
+    let _moveLineDown_decorators;
+    let _moveLineStart_decorators;
+    let _moveLineEnd_decorators;
+    let _moveDocStart_decorators;
+    let _moveDocEnd_decorators;
+    let _moveWordLeft_decorators;
+    let _moveWordRight_decorators;
+    let _deleteCharBack_decorators;
+    let _deleteCharForward_decorators;
+    let _deleteWordBack_decorators;
+    let _deleteWordForward_decorators;
+    let _killLineBack_decorators;
+    let _killLineForward_decorators;
+    let _yank_decorators;
+    let _transposeChars_decorators;
+    let __insertText_decorators;
     return class TextInput extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             _value_decorators = [observable];
             _cursorPosition_decorators = [observable];
             _placeholder_decorators = [(_a = observable).ref.bind(_a)];
+            _indicatorStyleOverride_decorators = [(_b = observable).ref.bind(_b)];
+            _cursorStyleOverride_decorators = [(_c = observable).ref.bind(_c)];
+            _contentStyleOverride_decorators = [(_d = observable).ref.bind(_d)];
             _handleKey_decorators = [action];
             _handleMouse_decorators = [action];
             _setHovered_decorators = [action];
+            _moveCharLeft_decorators = [action];
+            _moveCharRight_decorators = [action];
+            _moveLineUp_decorators = [action];
+            _moveLineDown_decorators = [action];
+            _moveLineStart_decorators = [action];
+            _moveLineEnd_decorators = [action];
+            _moveDocStart_decorators = [action];
+            _moveDocEnd_decorators = [action];
+            _moveWordLeft_decorators = [action];
+            _moveWordRight_decorators = [action];
+            _deleteCharBack_decorators = [action];
+            _deleteCharForward_decorators = [action];
+            _deleteWordBack_decorators = [action];
+            _deleteWordForward_decorators = [action];
+            _killLineBack_decorators = [action];
+            _killLineForward_decorators = [action];
+            _yank_decorators = [action];
+            _transposeChars_decorators = [action];
+            __insertText_decorators = [action];
             __esDecorate(this, null, _value_decorators, { kind: "accessor", name: "value", static: false, private: false, access: { has: obj => "value" in obj, get: obj => obj.value, set: (obj, value) => { obj.value = value; } }, metadata: _metadata }, _value_initializers, _value_extraInitializers);
             __esDecorate(this, null, _cursorPosition_decorators, { kind: "accessor", name: "cursorPosition", static: false, private: false, access: { has: obj => "cursorPosition" in obj, get: obj => obj.cursorPosition, set: (obj, value) => { obj.cursorPosition = value; } }, metadata: _metadata }, _cursorPosition_initializers, _cursorPosition_extraInitializers);
             __esDecorate(this, null, _placeholder_decorators, { kind: "accessor", name: "placeholder", static: false, private: false, access: { has: obj => "placeholder" in obj, get: obj => obj.placeholder, set: (obj, value) => { obj.placeholder = value; } }, metadata: _metadata }, _placeholder_initializers, _placeholder_extraInitializers);
+            __esDecorate(this, null, _indicatorStyleOverride_decorators, { kind: "accessor", name: "indicatorStyleOverride", static: false, private: false, access: { has: obj => "indicatorStyleOverride" in obj, get: obj => obj.indicatorStyleOverride, set: (obj, value) => { obj.indicatorStyleOverride = value; } }, metadata: _metadata }, _indicatorStyleOverride_initializers, _indicatorStyleOverride_extraInitializers);
+            __esDecorate(this, null, _cursorStyleOverride_decorators, { kind: "accessor", name: "cursorStyleOverride", static: false, private: false, access: { has: obj => "cursorStyleOverride" in obj, get: obj => obj.cursorStyleOverride, set: (obj, value) => { obj.cursorStyleOverride = value; } }, metadata: _metadata }, _cursorStyleOverride_initializers, _cursorStyleOverride_extraInitializers);
+            __esDecorate(this, null, _contentStyleOverride_decorators, { kind: "accessor", name: "contentStyleOverride", static: false, private: false, access: { has: obj => "contentStyleOverride" in obj, get: obj => obj.contentStyleOverride, set: (obj, value) => { obj.contentStyleOverride = value; } }, metadata: _metadata }, _contentStyleOverride_initializers, _contentStyleOverride_extraInitializers);
             __esDecorate(this, null, _handleKey_decorators, { kind: "method", name: "handleKey", static: false, private: false, access: { has: obj => "handleKey" in obj, get: obj => obj.handleKey }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _handleMouse_decorators, { kind: "method", name: "handleMouse", static: false, private: false, access: { has: obj => "handleMouse" in obj, get: obj => obj.handleMouse }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setHovered_decorators, { kind: "method", name: "setHovered", static: false, private: false, access: { has: obj => "setHovered" in obj, get: obj => obj.setHovered }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveCharLeft_decorators, { kind: "method", name: "moveCharLeft", static: false, private: false, access: { has: obj => "moveCharLeft" in obj, get: obj => obj.moveCharLeft }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveCharRight_decorators, { kind: "method", name: "moveCharRight", static: false, private: false, access: { has: obj => "moveCharRight" in obj, get: obj => obj.moveCharRight }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveLineUp_decorators, { kind: "method", name: "moveLineUp", static: false, private: false, access: { has: obj => "moveLineUp" in obj, get: obj => obj.moveLineUp }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveLineDown_decorators, { kind: "method", name: "moveLineDown", static: false, private: false, access: { has: obj => "moveLineDown" in obj, get: obj => obj.moveLineDown }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveLineStart_decorators, { kind: "method", name: "moveLineStart", static: false, private: false, access: { has: obj => "moveLineStart" in obj, get: obj => obj.moveLineStart }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveLineEnd_decorators, { kind: "method", name: "moveLineEnd", static: false, private: false, access: { has: obj => "moveLineEnd" in obj, get: obj => obj.moveLineEnd }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveDocStart_decorators, { kind: "method", name: "moveDocStart", static: false, private: false, access: { has: obj => "moveDocStart" in obj, get: obj => obj.moveDocStart }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveDocEnd_decorators, { kind: "method", name: "moveDocEnd", static: false, private: false, access: { has: obj => "moveDocEnd" in obj, get: obj => obj.moveDocEnd }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveWordLeft_decorators, { kind: "method", name: "moveWordLeft", static: false, private: false, access: { has: obj => "moveWordLeft" in obj, get: obj => obj.moveWordLeft }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _moveWordRight_decorators, { kind: "method", name: "moveWordRight", static: false, private: false, access: { has: obj => "moveWordRight" in obj, get: obj => obj.moveWordRight }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _deleteCharBack_decorators, { kind: "method", name: "deleteCharBack", static: false, private: false, access: { has: obj => "deleteCharBack" in obj, get: obj => obj.deleteCharBack }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _deleteCharForward_decorators, { kind: "method", name: "deleteCharForward", static: false, private: false, access: { has: obj => "deleteCharForward" in obj, get: obj => obj.deleteCharForward }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _deleteWordBack_decorators, { kind: "method", name: "deleteWordBack", static: false, private: false, access: { has: obj => "deleteWordBack" in obj, get: obj => obj.deleteWordBack }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _deleteWordForward_decorators, { kind: "method", name: "deleteWordForward", static: false, private: false, access: { has: obj => "deleteWordForward" in obj, get: obj => obj.deleteWordForward }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _killLineBack_decorators, { kind: "method", name: "killLineBack", static: false, private: false, access: { has: obj => "killLineBack" in obj, get: obj => obj.killLineBack }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _killLineForward_decorators, { kind: "method", name: "killLineForward", static: false, private: false, access: { has: obj => "killLineForward" in obj, get: obj => obj.killLineForward }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _yank_decorators, { kind: "method", name: "yank", static: false, private: false, access: { has: obj => "yank" in obj, get: obj => obj.yank }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _transposeChars_decorators, { kind: "method", name: "transposeChars", static: false, private: false, access: { has: obj => "transposeChars" in obj, get: obj => obj.transposeChars }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, __insertText_decorators, { kind: "method", name: "_insertText", static: false, private: false, access: { has: obj => "_insertText" in obj, get: obj => obj._insertText }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         id = __runInitializers(this, _instanceExtraInitializers);
@@ -100,66 +263,255 @@ let TextInput = (() => {
         _theme = __runInitializers(this, _placeholder_extraInitializers);
         _maxLength;
         _password;
+        _multiline;
+        _wrap;
+        _continuationMarker;
+        _markerWidth;
+        _maxRows;
+        _minRows;
+        _scrollIndicator;
+        #indicatorStyleOverride_accessor_storage = __runInitializers(this, _indicatorStyleOverride_initializers, void 0);
+        get indicatorStyleOverride() { return this.#indicatorStyleOverride_accessor_storage; }
+        set indicatorStyleOverride(value) { this.#indicatorStyleOverride_accessor_storage = value; }
+        #cursorStyleOverride_accessor_storage = (__runInitializers(this, _indicatorStyleOverride_extraInitializers), __runInitializers(this, _cursorStyleOverride_initializers, void 0));
+        get cursorStyleOverride() { return this.#cursorStyleOverride_accessor_storage; }
+        set cursorStyleOverride(value) { this.#cursorStyleOverride_accessor_storage = value; }
+        #contentStyleOverride_accessor_storage = (__runInitializers(this, _cursorStyleOverride_extraInitializers), __runInitializers(this, _contentStyleOverride_initializers, void 0));
+        get contentStyleOverride() { return this.#contentStyleOverride_accessor_storage; }
+        set contentStyleOverride(value) { this.#contentStyleOverride_accessor_storage = value; }
+        /**
+         * Last computed visual-row decomposition. Cached at the end of `render()`
+         * so vertical motion (Up/Down) can step row-by-row without re-running the
+         * wrap strategy. Null before the first render — vertical motion falls
+         * back to logical-line motion in that case.
+         *
+         * [LAW:dataflow-not-control-flow] One source of truth for "what does Up
+         * mean right now": the row table the renderer just produced. No parallel
+         * "where would the cursor go" math; both the renderer and the keymap
+         * read from the same array.
+         */
+        _visualRows = (__runInitializers(this, _contentStyleOverride_extraInitializers), null);
+        // [LAW:types-are-the-program] `_preferredColumn` is a cell column (not a
+        // code-unit index) — vertical motion navigates the visual surface, not the
+        // string's byte layout. Reset to null on every non-vertical motion or edit
+        // so the next Up/Down captures a fresh intent. Without this, Down through a
+        // short line then back Up would land at the short-line column instead of the
+        // original.
+        _preferredColumn = null;
+        // Single-slot kill buffer used by Ctrl+U / Ctrl+K → Ctrl+Y. Not a full
+        // kill ring (no Alt+Y rotation) — sufficient for the common cut/paste
+        // pattern that's the readline 90% case.
+        _killBuffer = "";
+        // [LAW:one-source-of-truth] Top visual row of the scroll viewport.
+        // Persisted across renders so the cursor can move *within* the viewport
+        // without dragging it along — the viewport scrolls only when the cursor
+        // would leave it. Without this, recomputing scroll from cursor position
+        // alone pins the cursor to the viewport's bottom edge whenever
+        // `cursorRow >= maxRows`, making every subsequent Up/Down scroll in
+        // lockstep with the cursor.
+        _scrollStart = 0;
+        // [LAW:one-source-of-truth] Viewport scroll offset in cells for the
+        // 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);
+        multiline;
         constructor(options = {}) {
             super();
             this.id = options.id ?? `text-input-${Math.random().toString(36).slice(2, 8)}`;
             this.value = options.value ?? "";
             this.placeholder = options.placeholder ?? "";
-            this.cursorPosition = this.value.length;
+            // [LAW:dataflow-not-control-flow] Initial cursor position is data, not
+            // a render-time branch. Single-line inputs follow the pre-filled-form
+            // convention (cursor at end — typing continues the value). Multiline
+            // inputs follow the textarea convention (cursor at start — pre-loaded
+            // content is read top-to-bottom, and the viewport's "scroll into view"
+            // logic does nothing because row 0 is already inside the initial window).
+            this.cursorPosition = (options.multiline ?? false) ? asCodePoint(0) : asCodePoint(this.value.length);
             this.disabled = options.disabled ?? false;
             this._theme = options.theme ?? DEFAULT_TERMINAL_THEME;
             this._maxLength = options.maxLength;
             this._password = options.password ?? false;
+            this._multiline = options.multiline ?? false;
+            this._wrap = options.wrap;
+            this._continuationMarker = options.continuationMarker ?? "↳ ";
+            this._markerWidth = asCellCol(cellLen(this._continuationMarker));
+            this._maxRows = options.maxRows;
+            this._minRows = options.minRows;
+            this._scrollIndicator = options.scrollIndicator ?? "arrows";
+            this.indicatorStyleOverride = options.indicatorStyle;
+            this.cursorStyleOverride = options.cursorStyle;
+            this.contentStyleOverride = options.contentStyle;
+            this.multiline = this._multiline;
         }
         setTheme(theme) { this._theme = theme; }
         // --- Event handlers ---
         handleKey(event) {
             if (this.disabled)
                 return;
-            switch (event.key) {
-                case "left":
-                    this.cursorPosition = Math.max(0, this.cursorPosition - 1);
-                    return;
-                case "right":
-                    this.cursorPosition = Math.min(this.value.length, this.cursorPosition + 1);
-                    return;
-                case "home":
-                    this.cursorPosition = 0;
-                    return;
-                case "end":
-                    this.cursorPosition = this.value.length;
-                    return;
-                case "backspace":
-                    if (this.cursorPosition > 0) {
-                        this.value = this.value.slice(0, this.cursorPosition - 1) + this.value.slice(this.cursorPosition);
-                        this.cursorPosition -= 1;
-                        this.emitChange();
-                    }
-                    return;
-                case "delete":
-                    if (this.cursorPosition < this.value.length) {
-                        this.value = this.value.slice(0, this.cursorPosition) + this.value.slice(this.cursorPosition + 1);
-                        this.emitChange();
-                    }
-                    return;
-                case "enter":
+            // ─── editing keys (modifier-conscious) ───
+            if (event.key === "backspace") {
+                if (event.meta || event.ctrl)
+                    this.deleteWordBack();
+                else
+                    this.deleteCharBack();
+                event.stop();
+                return;
+            }
+            if (event.key === "delete") {
+                this.deleteCharForward();
+                event.stop();
+                return;
+            }
+            if (event.key === "enter") {
+                if (this._multiline && !event.ctrl)
+                    this._insertText("\n");
+                else
                     this.emitSubmit();
-                    return;
+                event.stop();
+                return;
+            }
+            // Escape is intentionally ignored — text-input does not stop it so
+            // higher-level UI (dialogs, modals) can react to it.
+            if (event.key === "escape")
+                return;
+            // ─── unmodified motion ───
+            if (!event.ctrl && !event.meta) {
+                switch (event.key) {
+                    case "left":
+                        this.moveCharLeft();
+                        event.stop();
+                        return;
+                    case "right":
+                        this.moveCharRight();
+                        event.stop();
+                        return;
+                    case "up":
+                        this.moveLineUp();
+                        event.stop();
+                        return;
+                    case "down":
+                        this.moveLineDown();
+                        event.stop();
+                        return;
+                    case "home":
+                        this.moveLineStart();
+                        event.stop();
+                        return;
+                    case "end":
+                        this.moveLineEnd();
+                        event.stop();
+                        return;
+                }
+            }
+            // ─── Ctrl-modified motion + readline editing ───
+            if (event.ctrl && !event.meta) {
+                switch (event.key) {
+                    case "left":
+                        this.moveWordLeft();
+                        event.stop();
+                        return;
+                    case "right":
+                        this.moveWordRight();
+                        event.stop();
+                        return;
+                    case "home":
+                        this.moveDocStart();
+                        event.stop();
+                        return;
+                    case "end":
+                        this.moveDocEnd();
+                        event.stop();
+                        return;
+                    case "a":
+                        this.moveLineStart();
+                        event.stop();
+                        return;
+                    case "e":
+                        this.moveLineEnd();
+                        event.stop();
+                        return;
+                    case "b":
+                        this.moveCharLeft();
+                        event.stop();
+                        return;
+                    case "f":
+                        this.moveCharRight();
+                        event.stop();
+                        return;
+                    case "p":
+                        this.moveLineUp();
+                        event.stop();
+                        return;
+                    case "n":
+                        this.moveLineDown();
+                        event.stop();
+                        return;
+                    case "d":
+                        this.deleteCharForward();
+                        event.stop();
+                        return;
+                    case "h":
+                        this.deleteCharBack();
+                        event.stop();
+                        return;
+                    case "w":
+                        this.deleteWordBack();
+                        event.stop();
+                        return;
+                    case "u":
+                        this.killLineBack();
+                        event.stop();
+                        return;
+                    case "k":
+                        this.killLineForward();
+                        event.stop();
+                        return;
+                    case "y":
+                        this.yank();
+                        event.stop();
+                        return;
+                    case "t":
+                        this.transposeChars();
+                        event.stop();
+                        return;
+                }
             }
-            // Printable insertion: single-character event.character with no modifier.
+            // ─── Alt-modified (meta) motion + editing ───
+            if (event.meta && !event.ctrl) {
+                switch (event.key) {
+                    case "left":
+                        this.moveWordLeft();
+                        event.stop();
+                        return;
+                    case "right":
+                        this.moveWordRight();
+                        event.stop();
+                        return;
+                    case "b":
+                        this.moveWordLeft();
+                        event.stop();
+                        return;
+                    case "f":
+                        this.moveWordRight();
+                        event.stop();
+                        return;
+                    case "d":
+                        this.deleteWordForward();
+                        event.stop();
+                        return;
+                }
+            }
+            // ─── printable insertion ───
+            // A single-char `event.character` with no command modifiers is text to
+            // insert. Ctrl/meta-modified keys produce empty `character` from the
+            // router (see event-router.ts) so they never reach this branch.
             if (event.character.length === 1 &&
                 !event.ctrl &&
                 !event.meta &&
                 event.character >= " " &&
                 event.character !== "\x7f") {
-                if (this._maxLength !== undefined && this.value.length >= this._maxLength)
-                    return;
-                this.value =
-                    this.value.slice(0, this.cursorPosition) +
-                        event.character +
-                        this.value.slice(this.cursorPosition);
-                this.cursorPosition += 1;
-                this.emitChange();
+                this._insertText(event.character);
+                event.stop();
             }
         }
         handleMouse(event) {
@@ -170,30 +522,400 @@ let TextInput = (() => {
             const b = this.bounds;
             if (!b)
                 return;
-            // Click position relative to the content area (skip the leading "[" bracket).
-            const relX = event.x - b.x - 1;
-            this.cursorPosition = Math.max(0, Math.min(this.value.length, relX));
+            if (this._multiline) {
+                // Multiline has no brackets; rows may have a leading continuation marker.
+                // Use event.y to pick the visual row, then project event.x into its content.
+                const rows = this._visualRows;
+                if (!rows || rows.length === 0)
+                    return;
+                const relY = event.y - b.y;
+                const rawRowIdx = this._scrollStart + relY;
+                // Clicks on minRows-padded empty rows (beyond the last real row) snap to end.
+                if (rawRowIdx >= rows.length) {
+                    this.cursorPosition = asCodePoint(this.value.length);
+                    this._preferredColumn = null;
+                    return;
+                }
+                const rowIdx = Math.max(0, rawRowIdx);
+                const row = rows[rowIdx];
+                // 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 - b.x - contentXOff));
+                const pos = cellColToCodeUnitOffset(row.content, relX);
+                const absPos = row.valueStart + pos;
+                const chu = absPos < this.value.length ? this.value.charCodeAt(absPos) : 0;
+                const prevChu = absPos > 0 ? this.value.charCodeAt(absPos - 1) : 0;
+                this.cursorPosition = asCodePoint(chu >= 0xDC00 && chu <= 0xDFFF && prevChu >= 0xD800 && prevChu <= 0xDBFF
+                    ? absPos + 1
+                    : absPos);
+            }
+            else {
+                // [LAW:types-are-the-program] relX is a cell-column offset into the full
+                // display string. Add _singleLineViewportStart (the scroll offset captured
+                // 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 - b.x - 1) + this._singleLineViewportStart);
+                const displayForHitTest = this._password
+                    ? "•".repeat(this.value.length)
+                    : this.value.indexOf("\n") >= 0
+                        ? this.value.replace(/\n/g, NEWLINE_GLYPH)
+                        : this.value;
+                const pos = cellColToCodeUnitOffset(displayForHitTest, relX);
+                // Snap forward only when pos lands on a valid surrogate pair, never on a
+                // lone low surrogate (malformed string). Verify the preceding code unit is
+                // the high-surrogate half before advancing.
+                const chu = pos < this.value.length ? this.value.charCodeAt(pos) : 0;
+                const prevChu = pos > 0 ? this.value.charCodeAt(pos - 1) : 0;
+                this.cursorPosition = asCodePoint(chu >= 0xDC00 && chu <= 0xDFFF && prevChu >= 0xD800 && prevChu <= 0xDBFF
+                    ? pos + 1
+                    : pos);
+            }
+            this._preferredColumn = null;
         }
         // --- Hover mutator (router fast-path) ---
         setHovered(value) { this.hovered = value; }
+        // ─── Public motion primitives ───────────────────────────────────────────
+        moveCharLeft() {
+            this.cursorPosition = prevCodePoint(this.value, this.cursorPosition);
+            this._preferredColumn = null;
+        }
+        moveCharRight() {
+            this.cursorPosition = nextCodePoint(this.value, this.cursorPosition);
+            this._preferredColumn = null;
+        }
+        moveLineUp() {
+            // Prefer the on-screen visual decomposition when it exists — wraps,
+            // marker offsets, and scroll alignment are all already accounted for.
+            // Fall back to logical-line motion only when no render has occurred yet
+            // (e.g. cursor motion before mount).
+            if (this._visualRows !== null && this._visualRows.length > 1) {
+                const rowIdx = this._cursorVisualRow();
+                if (rowIdx === 0)
+                    return;
+                const col = this._preferredColumn ?? this._cursorVisualCol();
+                const target = this._visualRows[rowIdx - 1];
+                this.cursorPosition = asCodePoint(target.valueStart + this._clampColForRow(col, rowIdx - 1));
+                this._preferredColumn = col;
+                return;
+            }
+            const lineStart = this._lineStart();
+            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 prevLineEnd = lineStart - 1;
+            let prevLineStart = prevLineEnd;
+            while (prevLineStart > 0 && this.value[prevLineStart - 1] !== "\n")
+                prevLineStart--;
+            const prevLineContent = this.value.slice(prevLineStart, prevLineEnd);
+            this.cursorPosition = asCodePoint(prevLineStart + cellColToCodeUnitOffset(prevLineContent, asCellCol(Math.min(col, cellLen(prevLineContent)))));
+            this._preferredColumn = col;
+        }
+        moveLineDown() {
+            if (this._visualRows !== null && this._visualRows.length > 1) {
+                const rowIdx = this._cursorVisualRow();
+                if (rowIdx === this._visualRows.length - 1)
+                    return;
+                const col = this._preferredColumn ?? this._cursorVisualCol();
+                this.cursorPosition = asCodePoint(this._visualRows[rowIdx + 1].valueStart + this._clampColForRow(col, rowIdx + 1));
+                this._preferredColumn = col;
+                return;
+            }
+            const lineEnd = this._lineEnd();
+            if (lineEnd === this.value.length)
+                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 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 = asCodePoint(nextLineStart + cellColToCodeUnitOffset(nextLineContent, asCellCol(Math.min(col, cellLen(nextLineContent)))));
+            this._preferredColumn = col;
+        }
+        // Clamp `col` (a cell column) to the target visual row's content, returning
+        // the code-unit offset within that row. When the row IS followed by a
+        // continuation of the same logical line, we clamp to the last valid
+        // code-point boundary strictly inside the row (which may be more than
+        // one cell before the visual end when the last code point is wide) so the
+        // cursor stays strictly inside the target row — landing at the boundary
+        // would cause `_cursorVisualRow` to resolve to the *later* row, making
+        // every subsequent Up/Down stick at the boundary.
+        //
+        // For rows NOT followed by a continuation (last wrap row, or any unwrapped
+        // logical line), the end-of-line position is valid — there is no adjacent
+        // continuation row to collide with.
+        _clampColForRow(col, targetIdx) {
+            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 capCells = nextIsContinuation
+                ? asCellCol(Math.max(0, contentCellWidth - 1))
+                : contentCellWidth;
+            return cellColToCodeUnitOffset(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`.
+        _cursorVisualRow() {
+            const rows = this._visualRows;
+            let idx = 0;
+            for (let i = rows.length - 1; i >= 0; i--) {
+                if (rows[i].valueStart <= this.cursorPosition) {
+                    idx = i;
+                    break;
+                }
+            }
+            return idx;
+        }
+        // Returns the cursor's cell column within its current visual row.
+        _cursorVisualCol() {
+            const rows = this._visualRows;
+            const idx = this._cursorVisualRow();
+            const row = rows[idx];
+            return asCellCol(cellLen(row.content.slice(0, this.cursorPosition - row.valueStart)));
+        }
+        moveLineStart() {
+            this.cursorPosition = this._lineStart();
+            this._preferredColumn = null;
+        }
+        moveLineEnd() {
+            this.cursorPosition = this._lineEnd();
+            this._preferredColumn = null;
+        }
+        moveDocStart() {
+            this.cursorPosition = asCodePoint(0);
+            this._preferredColumn = null;
+        }
+        moveDocEnd() {
+            this.cursorPosition = asCodePoint(this.value.length);
+            this._preferredColumn = null;
+        }
+        moveWordLeft() {
+            let p = this.cursorPosition;
+            while (p > 0) {
+                const prev = prevCodePoint(this.value, p);
+                if (isWordChar(this.value.slice(prev, p)))
+                    break;
+                p = prev;
+            }
+            while (p > 0) {
+                const prev = prevCodePoint(this.value, p);
+                if (!isWordChar(this.value.slice(prev, p)))
+                    break;
+                p = prev;
+            }
+            this.cursorPosition = p;
+            this._preferredColumn = null;
+        }
+        moveWordRight() {
+            let p = this.cursorPosition;
+            while (p < this.value.length) {
+                const next = nextCodePoint(this.value, p);
+                if (isWordChar(this.value.slice(p, next)))
+                    break;
+                p = next;
+            }
+            while (p < this.value.length) {
+                const next = nextCodePoint(this.value, p);
+                if (!isWordChar(this.value.slice(p, next)))
+                    break;
+                p = next;
+            }
+            this.cursorPosition = p;
+            this._preferredColumn = null;
+        }
+        // ─── Public editing primitives ──────────────────────────────────────────
+        deleteCharBack() {
+            if (this.cursorPosition === 0)
+                return;
+            const newPos = prevCodePoint(this.value, this.cursorPosition);
+            this.value = this.value.slice(0, newPos) + this.value.slice(this.cursorPosition);
+            this.cursorPosition = newPos;
+            this._preferredColumn = null;
+            this.emitChange();
+        }
+        deleteCharForward() {
+            if (this.cursorPosition >= this.value.length)
+                return;
+            const nextPos = nextCodePoint(this.value, this.cursorPosition);
+            this.value = this.value.slice(0, this.cursorPosition) + this.value.slice(nextPos);
+            this._preferredColumn = null;
+            this.emitChange();
+        }
+        deleteWordBack() {
+            // Readline `unix-word-rubout` semantics: delete back to nearest whitespace,
+            // skipping trailing whitespace first so successive Ctrl+W at "foo bar |"
+            // → "foo |" → "|" rather than getting stuck on the trailing space.
+            let p = this.cursorPosition;
+            while (p > 0) {
+                const prev = prevCodePoint(this.value, p);
+                if (!isWhitespace(this.value.slice(prev, p)))
+                    break;
+                p = prev;
+            }
+            while (p > 0) {
+                const prev = prevCodePoint(this.value, p);
+                if (isWhitespace(this.value.slice(prev, p)))
+                    break;
+                p = prev;
+            }
+            if (p === this.cursorPosition)
+                return;
+            this._killBuffer = this.value.slice(p, this.cursorPosition);
+            this.value = this.value.slice(0, p) + this.value.slice(this.cursorPosition);
+            this.cursorPosition = p;
+            this._preferredColumn = null;
+            this.emitChange();
+        }
+        deleteWordForward() {
+            let p = this.cursorPosition;
+            while (p < this.value.length) {
+                const next = nextCodePoint(this.value, p);
+                if (isWordChar(this.value.slice(p, next)))
+                    break;
+                p = next;
+            }
+            while (p < this.value.length) {
+                const next = nextCodePoint(this.value, p);
+                if (!isWordChar(this.value.slice(p, next)))
+                    break;
+                p = next;
+            }
+            if (p === this.cursorPosition)
+                return;
+            this._killBuffer = this.value.slice(this.cursorPosition, p);
+            this.value = this.value.slice(0, this.cursorPosition) + this.value.slice(p);
+            this._preferredColumn = null;
+            this.emitChange();
+        }
+        killLineBack() {
+            const start = this._lineStart();
+            if (start === this.cursorPosition)
+                return;
+            this._killBuffer = this.value.slice(start, this.cursorPosition);
+            this.value = this.value.slice(0, start) + this.value.slice(this.cursorPosition);
+            this.cursorPosition = start;
+            this._preferredColumn = null;
+            this.emitChange();
+        }
+        killLineForward() {
+            const end = this._lineEnd();
+            if (end > this.cursorPosition) {
+                this._killBuffer = this.value.slice(this.cursorPosition, end);
+                this.value = this.value.slice(0, this.cursorPosition) + this.value.slice(end);
+                this._preferredColumn = null;
+                this.emitChange();
+                return;
+            }
+            // Already at line end → kill the trailing `\n` (join next line).
+            if (this.cursorPosition < this.value.length) {
+                this._killBuffer = "\n";
+                this.value = this.value.slice(0, this.cursorPosition) + this.value.slice(this.cursorPosition + 1);
+                this._preferredColumn = null;
+                this.emitChange();
+            }
+        }
+        yank() {
+            if (this._killBuffer.length === 0)
+                return;
+            this._insertText(this._killBuffer);
+        }
+        transposeChars() {
+            // Readline `transpose-chars`: swap the char before the cursor with the
+            // char at the cursor and advance. At end-of-value, swap the trailing
+            // two chars without advancing. At position 0, no-op.
+            const len = this.value.length;
+            if (len < 2 || this.cursorPosition === 0)
+                return;
+            const p = this.cursorPosition;
+            if (p === len) {
+                // End-of-value: swap the trailing two code points; cursor stays.
+                const cp2 = prevCodePoint(this.value, p);
+                const cp1 = prevCodePoint(this.value, cp2);
+                this.value = this.value.slice(0, cp1) + this.value.slice(cp2) + this.value.slice(cp1, cp2);
+                this._preferredColumn = null;
+                this.emitChange();
+                return;
+            }
+            // Normal case: find full code-point substrings for the char before and at cursor.
+            const cpBefore = prevCodePoint(this.value, p);
+            const cpAfter = nextCodePoint(this.value, p);
+            const charBefore = this.value.slice(cpBefore, p);
+            const charAt = this.value.slice(p, cpAfter);
+            this.value = this.value.slice(0, cpBefore) + charAt + charBefore + this.value.slice(cpAfter);
+            this.cursorPosition = asCodePoint(cpAfter);
+            this._preferredColumn = null;
+            this.emitChange();
+        }
+        // ─── Internal helpers ───────────────────────────────────────────────────
+        _lineStart() {
+            let p = this.cursorPosition;
+            while (p > 0 && this.value[p - 1] !== "\n")
+                p--;
+            return asCodePoint(p);
+        }
+        _lineEnd() {
+            let p = this.cursorPosition;
+            while (p < this.value.length && this.value[p] !== "\n")
+                p++;
+            return asCodePoint(p);
+        }
+        _insertText(text) {
+            let toInsert = text;
+            if (this._maxLength !== undefined) {
+                const room = this._maxLength - this.value.length;
+                if (room <= 0)
+                    return;
+                if (toInsert.length > room)
+                    toInsert = toInsert.slice(0, room);
+            }
+            this.value =
+                this.value.slice(0, this.cursorPosition) +
+                    toInsert +
+                    this.value.slice(this.cursorPosition);
+            this.cursorPosition = asCodePoint(this.cursorPosition + toInsert.length);
+            this._preferredColumn = null;
+            this.emitChange();
+        }
         // --- Rendering ---
         render(options) {
+            if (this._multiline)
+                return this._renderMultiline(options);
+            return this._renderSingleLine(options);
+        }
+        _renderSingleLine(options) {
             const showPlaceholder = this.focused && this.value.length === 0 && this.placeholder.length > 0;
+            // [LAW:dataflow-not-control-flow] Single rawDisplay value derives from
+            // mode (password / placeholder / plain). NEWLINE_GLYPH substitution maps
+            // every code unit in value 1:1 to rawDisplay so cursorPosition (a code-
+            // unit index) is a valid index into rawDisplay regardless of mode.
             const rawDisplay = showPlaceholder
                 ? this.placeholder
                 : this._password
                     ? "•".repeat(this.value.length)
-                    : this.value;
-            // [LAW:dataflow-not-control-flow] content width is data — derived from
-            // value/placeholder length, MIN_CONTENT_WIDTH floor, maxWidth ceiling.
-            const maxAvailable = Math.max(MIN_CONTENT_WIDTH, options.maxWidth - 2);
-            const desiredWidth = Math.max(MIN_CONTENT_WIDTH, rawDisplay.length, this.cursorPosition + 1);
-            const contentWidth = Math.min(maxAvailable, desiredWidth);
-            // Slide window to keep cursor visible when content overflows.
-            const startIdx = Math.max(0, Math.min(rawDisplay.length - contentWidth, this.cursorPosition - contentWidth + 1));
-            const sliced = rawDisplay.slice(Math.max(0, startIdx), Math.max(0, startIdx) + contentWidth);
-            const display = sliced.padEnd(contentWidth, " ");
-            const cursorDisplayIdx = this.cursorPosition - Math.max(0, startIdx);
+                    : this.value.indexOf("\n") >= 0
+                        ? this.value.replace(/\n/g, NEWLINE_GLYPH)
+                        : this.value;
+            // Measure in cell space — cursorPosition is a code-unit index; convert to
+            // cell column for all viewport arithmetic.
+            const rawCellWidth = asCellCol(cellLen(rawDisplay));
+            const cursorCellCol = asCellCol(cellLen(rawDisplay.slice(0, 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 [, 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 bracketStyle = this.disabled
                 ? new Style({ color: "#666666", bgcolor: "#333333", dim: true })
                 : new Style({ color: this.resolvePalette("foreground") });
@@ -201,21 +923,24 @@ let TextInput = (() => {
                 ? new Style({ color: "#666666", bgcolor: "#333333", dim: true })
                 : showPlaceholder
                     ? new Style({ color: this.resolvePalette("foreground"), dim: true })
-                    : new Style({ color: this.resolvePalette("foreground") });
-            // Cursor cell paints on a full primary bg → use on-primary for fg so
-            // contrast is WCAG-correct across all themes, not theme-bg-dependent.
-            const cursorStyle = new Style({
+                    : this.contentStyleOverride ?? new Style({ color: this.resolvePalette("foreground") });
+            const cursorStyle = this.cursorStyleOverride ?? new Style({
                 color: this.resolvePalette("on-primary"),
                 bgcolor: this.resolvePalette("primary"),
             });
             const segments = [new Segment("[", bracketStyle)];
-            if (this.focused && !this.disabled && cursorDisplayIdx >= 0 && cursorDisplayIdx < contentWidth) {
-                const before = display.slice(0, cursorDisplayIdx);
-                const at = display.slice(cursorDisplayIdx, cursorDisplayIdx + 1);
-                const after = display.slice(cursorDisplayIdx + 1);
+            if (this.focused && !this.disabled && cursorDisplayCellCol >= 0 && cursorDisplayCellCol < contentWidth) {
+                const [before, rest] = splitText(display, cursorDisplayCellCol);
+                let firstCh = "";
+                for (const ch of rest) {
+                    firstCh = ch;
+                    break;
+                }
+                const at = firstCh || " ";
+                const after = rest.slice(firstCh.length);
                 if (before.length > 0)
                     segments.push(new Segment(before, contentStyle));
-                segments.push(new Segment(at.length > 0 ? at : " ", cursorStyle));
+                segments.push(new Segment(at, cursorStyle));
                 if (after.length > 0)
                     segments.push(new Segment(after, contentStyle));
             }
@@ -225,11 +950,216 @@ let TextInput = (() => {
             segments.push(new Segment("]", bracketStyle));
             return segments;
         }
+        _renderMultiline(options) {
+            // [LAW:dataflow-not-control-flow] Decompose `value` into visual rows
+            // exactly once per render, cache the result, then drive both display
+            // *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);
+            this._visualRows = visualRows;
+            // Scroll window: keep `_scrollStart` (the viewport's top row) stable
+            // across renders, adjusting only when the cursor would leave the
+            // viewport. This is the textarea-conventional "viewport follows cursor
+            // when it has to" behavior — cursor moves freely *within* the visible
+            // rows; the window scrolls only at the edges. When `maxRows` is unset,
+            // render every row.
+            const total = visualRows.length;
+            const cursorRow = this._cursorVisualRow();
+            let scrollStart = 0;
+            let visibleCount = total;
+            if (this._maxRows !== undefined && total > this._maxRows) {
+                const maxStart = total - this._maxRows;
+                if (cursorRow < this._scrollStart) {
+                    this._scrollStart = cursorRow;
+                }
+                else if (cursorRow >= this._scrollStart + this._maxRows) {
+                    this._scrollStart = cursorRow - this._maxRows + 1;
+                }
+                this._scrollStart = Math.max(0, Math.min(maxStart, this._scrollStart));
+                scrollStart = this._scrollStart;
+                visibleCount = this._maxRows;
+            }
+            else {
+                this._scrollStart = 0;
+            }
+            // Pad with empty rows when the value is shorter than `minRows`.
+            let padRows = 0;
+            if (this._minRows !== undefined && total < this._minRows && this._maxRows === undefined) {
+                padRows = this._minRows - total;
+            }
+            const contentStyle = this.disabled
+                ? new Style({ color: "#666666", bgcolor: "#333333", dim: true })
+                : this.contentStyleOverride ?? new Style({ color: this.resolvePalette("foreground") });
+            const markerStyle = new Style({ color: this.resolvePalette("foreground"), dim: true });
+            const cursorStyle = this.cursorStyleOverride ?? new Style({
+                color: this.resolvePalette("on-primary"),
+                bgcolor: this.resolvePalette("primary"),
+            });
+            // Scroll-direction arrows appear in the rightmost cell of the first/last
+            // visible row, *only* when scroll is actually possible in that direction.
+            // _emitRowContent reserves the indicator's cells so content never
+            // 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 indicatorStyle = this.indicatorStyleOverride ?? new Style({ color: this.resolvePalette("primary") });
+            const segments = [];
+            const showCursor = this.focused && !this.disabled;
+            for (let i = 0; i < visibleCount; i++) {
+                const rowIdx = scrollStart + i;
+                const row = visualRows[rowIdx];
+                if (i > 0)
+                    segments.push(new Segment("\n"));
+                if (row.isContinuation) {
+                    segments.push(new Segment(this._continuationMarker, markerStyle));
+                }
+                let indicator;
+                if (i === 0 && canScrollUp) {
+                    indicator = { ch: "▲", style: indicatorStyle };
+                }
+                else if (i === visibleCount - 1 && canScrollDown) {
+                    indicator = { ch: "▼", style: indicatorStyle };
+                }
+                // When a continuation marker was emitted, the row's printable width is
+                // reduced by the marker width — the indicator column is still at
+                // `options.maxWidth - 1` in the panel's view, which is
+                // `options.maxWidth - markerWidth - 1` columns past the marker.
+                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);
+            }
+            // Trailing empty rows for minRows padding (no cursor, no marker).
+            // Emit a whitespace segment of the full content width so Segment.splitLines
+            // does not drop the row — an empty segment before a newline would produce
+            // an invisible row that the renderer discards.
+            for (let i = 0; i < padRows; i++) {
+                segments.push(new Segment("\n"));
+                segments.push(new Segment(setCellSize("", asCellCol(options.maxWidth)), contentStyle));
+            }
+            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 = nextCodePoint(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))
+                : -1;
+            if (cursorCellColInRow >= 0 && cursorCellColInRow < contentCellWidth) {
+                const [before, rest] = splitText(paddedContent, asCellCol(cursorCellColInRow));
+                let firstCh = "";
+                for (const ch of rest) {
+                    firstCh = ch;
+                    break;
+                }
+                const at = firstCh || " ";
+                const after = rest.slice(firstCh.length);
+                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));
+            }
+            else {
+                if (paddedContent.length > 0)
+                    out.push(new Segment(paddedContent, contentStyle));
+            }
+            out.push(new Segment(indicator.ch, indicator.style));
+        }
+        _computeVisualRows(maxWidth) {
+            const firstWidth = asCellCol(Math.max(1, maxWidth));
+            const continuationWidth = asCellCol(Math.max(1, firstWidth - this._markerWidth));
+            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 });
+                    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];
+                            rows.push({
+                                content: wr.content,
+                                valueStart: asCodePoint(pos + wr.start),
+                                isContinuation: ri > 0,
+                            });
+                        }
+                    }
+                }
+                else {
+                    rows.push({ content: line, valueStart: asCodePoint(pos), isContinuation: false });
+                }
+                pos += line.length + 1; // +1 for the \n separator
+            }
+            return rows;
+        }
         measure(_options) {
             const minimum = MIN_CONTENT_WIDTH + 2;
-            const maximum = Math.max(minimum, Math.max(this.value.length, this.placeholder.length) + 2);
+            const maximum = Math.max(minimum, Math.max(cellLen(this.value), cellLen(this.placeholder)) + 2);
             return { minimum, maximum };
         }
+        /**
+         * `[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.
+         *
+         * Returns `undefined` when:
+         *   - `scrollIndicator` is not `"indices"`, or
+         *   - `maxRows` is unset, or total visual rows ≤ maxRows (nothing to
+         *     scroll), or
+         *   - no render has happened yet (cache is empty).
+         */
+        get scrollIndicatorText() {
+            if (this._scrollIndicator !== "indices")
+                return undefined;
+            if (this._maxRows === undefined)
+                return undefined;
+            const rows = this._visualRows;
+            if (rows === null || rows.length <= this._maxRows)
+                return undefined;
+            const cursorRow1 = this._cursorVisualRow() + 1;
+            return `[${cursorRow1}/${rows.length}]`;
+        }
         // --- Palette resolution ---
         resolvePalette(key) {
             const rgba = this._theme.palette.get(key);