@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/widgets/slider.js

@@ -0,0 +1,270 @@
+/**
+ * Slider widget — numeric value within [min, max] with step increments.
+ * [LAW:dataflow-not-control-flow] every render emits exactly `width`
+ * track cells; the marker cell index is data, not a branch.
+ * [LAW:one-type-per-behavior] shared infrastructure inherited from
+ * WidgetBase.
+ *
+ * Visual:
+ *   track    — `width` cells of "─" (ASCII fallback "-")
+ *   marker   — "●" (ASCII fallback "*") at round((value - min) / range * (width - 1))
+ *   filled   — cells left of and including the marker use primary fg
+ *              on the default terminal bg
+ *   unfilled — cells right of the marker use surface fg on the default
+ *              terminal bg (no explicit bgcolor — the unfilled track
+ *              should sit transparently against whatever the panel /
+ *              parent paints underneath)
+ *   focused  — underline on the segments
+ *   disabled — dim
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { observable, action, observableRef } from "mobx";
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import { ColorSpec } from "../core/color.js";
+import { DEFAULT_TERMINAL_THEME } from "../themes/terminalThemes.js";
+import { drawable } from "../core/protocol.js";
+import { WidgetBase } from "./widget-base.js";
+const DEFAULT_WIDTH = 20;
+let Slider = (() => {
+    let _classSuper = WidgetBase;
+    let _instanceExtraInitializers = [];
+    let _value_decorators;
+    let _value_initializers = [];
+    let _value_extraInitializers = [];
+    let _min_decorators;
+    let _min_initializers = [];
+    let _min_extraInitializers = [];
+    let _max_decorators;
+    let _max_initializers = [];
+    let _max_extraInitializers = [];
+    let _step_decorators;
+    let _step_initializers = [];
+    let _step_extraInitializers = [];
+    let _width_decorators;
+    let _width_initializers = [];
+    let _width_extraInitializers = [];
+    let __theme_decorators;
+    let __theme_initializers = [];
+    let __theme_extraInitializers = [];
+    let _setTheme_decorators;
+    let _handleKey_decorators;
+    let _handleMouse_decorators;
+    let _setValue_decorators;
+    return class Slider extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _value_decorators = [observable];
+            _min_decorators = [observableRef];
+            _max_decorators = [observableRef];
+            _step_decorators = [observableRef];
+            _width_decorators = [observableRef];
+            __theme_decorators = [observableRef];
+            _setTheme_decorators = [action];
+            _handleKey_decorators = [action];
+            _handleMouse_decorators = [action];
+            _setValue_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, _min_decorators, { kind: "accessor", name: "min", static: false, private: false, access: { has: obj => "min" in obj, get: obj => obj.min, set: (obj, value) => { obj.min = value; } }, metadata: _metadata }, _min_initializers, _min_extraInitializers);
+            __esDecorate(this, null, _max_decorators, { kind: "accessor", name: "max", static: false, private: false, access: { has: obj => "max" in obj, get: obj => obj.max, set: (obj, value) => { obj.max = value; } }, metadata: _metadata }, _max_initializers, _max_extraInitializers);
+            __esDecorate(this, null, _step_decorators, { kind: "accessor", name: "step", static: false, private: false, access: { has: obj => "step" in obj, get: obj => obj.step, set: (obj, value) => { obj.step = value; } }, metadata: _metadata }, _step_initializers, _step_extraInitializers);
+            __esDecorate(this, null, _width_decorators, { kind: "accessor", name: "width", static: false, private: false, access: { has: obj => "width" in obj, get: obj => obj.width, set: (obj, value) => { obj.width = value; } }, metadata: _metadata }, _width_initializers, _width_extraInitializers);
+            __esDecorate(this, null, __theme_decorators, { kind: "accessor", name: "_theme", static: false, private: false, access: { has: obj => "_theme" in obj, get: obj => obj._theme, set: (obj, value) => { obj._theme = value; } }, metadata: _metadata }, __theme_initializers, __theme_extraInitializers);
+            __esDecorate(this, null, _setTheme_decorators, { kind: "method", name: "setTheme", static: false, private: false, access: { has: obj => "setTheme" in obj, get: obj => obj.setTheme }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __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, _setValue_decorators, { kind: "method", name: "setValue", static: false, private: false, access: { has: obj => "setValue" in obj, get: obj => obj.setValue }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        id = __runInitializers(this, _instanceExtraInitializers);
+        focusable = true;
+        #value_accessor_storage = __runInitializers(this, _value_initializers, void 0);
+        get value() { return this.#value_accessor_storage; }
+        set value(value) { this.#value_accessor_storage = value; }
+        #min_accessor_storage = (__runInitializers(this, _value_extraInitializers), __runInitializers(this, _min_initializers, void 0));
+        get min() { return this.#min_accessor_storage; }
+        set min(value) { this.#min_accessor_storage = value; }
+        #max_accessor_storage = (__runInitializers(this, _min_extraInitializers), __runInitializers(this, _max_initializers, void 0));
+        get max() { return this.#max_accessor_storage; }
+        set max(value) { this.#max_accessor_storage = value; }
+        #step_accessor_storage = (__runInitializers(this, _max_extraInitializers), __runInitializers(this, _step_initializers, void 0));
+        get step() { return this.#step_accessor_storage; }
+        set step(value) { this.#step_accessor_storage = value; }
+        #width_accessor_storage = (__runInitializers(this, _step_extraInitializers), __runInitializers(this, _width_initializers, void 0));
+        get width() { return this.#width_accessor_storage; }
+        set width(value) { this.#width_accessor_storage = value; }
+        #_theme_accessor_storage = (__runInitializers(this, _width_extraInitializers), __runInitializers(this, __theme_initializers, void 0));
+        // [LAW:types-are-the-program] @observableRef so setTheme() triggers a
+        // re-render — render() reads _theme.palette, so the theme reference must
+        // participate in MobX reactivity for Screen's autorun to fire on swap.
+        get _theme() { return this.#_theme_accessor_storage; }
+        set _theme(value) { this.#_theme_accessor_storage = value; }
+        _dragging = (__runInitializers(this, __theme_extraInitializers), false);
+        constructor(options = {}) {
+            super();
+            this.id = options.id ?? `slider-${Math.random().toString(36).slice(2, 8)}`;
+            this.min = options.min ?? 0;
+            this.max = options.max ?? 100;
+            this.step = options.step ?? 1;
+            // [LAW:types-are-the-program] `width` is a `number` in the option shape,
+            // but rendering and mouse math require a positive integer. This is a
+            // construction-time trust boundary — guard once so every downstream call
+            // (`trackChar.repeat(width)`, `width - 1` denominator) can assume validity.
+            const width = options.width ?? DEFAULT_WIDTH;
+            if (!Number.isInteger(width) || width < 1) {
+                throw new RangeError(`Slider width must be a positive integer; got ${width}`);
+            }
+            this.width = width;
+            this.value = clampSnap(options.value ?? this.min, this.min, this.max, this.step);
+            this.disabled = options.disabled ?? false;
+            this._theme = options.theme ?? DEFAULT_TERMINAL_THEME;
+        }
+        setTheme(theme) { this._theme = theme; }
+        // --- Event handlers ---
+        handleKey(event) {
+            if (this.disabled)
+                return;
+            switch (event.key) {
+                case "left":
+                    this.setValue(this.value - this.step);
+                    event.stop();
+                    return;
+                case "right":
+                    this.setValue(this.value + this.step);
+                    event.stop();
+                    return;
+                case "home":
+                    this.setValue(this.min);
+                    event.stop();
+                    return;
+                case "end":
+                    this.setValue(this.max);
+                    event.stop();
+                    return;
+            }
+        }
+        handleMouse(event) {
+            if (this.disabled)
+                return;
+            if (event.type === "mouse_down") {
+                this._dragging = true;
+                this.setValueFromMouseX(event.x);
+                return;
+            }
+            if (event.type === "mouse_move") {
+                if (this._dragging)
+                    this.setValueFromMouseX(event.x);
+                return;
+            }
+            if (event.type === "mouse_up") {
+                const wasDragging = this._dragging;
+                this._dragging = false;
+                if (wasDragging) {
+                    this.setValueFromMouseX(event.x);
+                    this.emitSubmit();
+                }
+                return;
+            }
+        }
+        // --- Value mutation ---
+        setValue(next) {
+            const snapped = clampSnap(next, this.min, this.max, this.step);
+            if (snapped === this.value)
+                return;
+            this.value = snapped;
+            this.emitChange();
+        }
+        // `x` is a column of this slider's own track, and runs outside 0..width
+        // when a drag carries the pointer past either end.
+        setValueFromMouseX(x) {
+            const cellsAvailable = Math.max(1, this.width - 1);
+            const clamped = Math.max(0, Math.min(this.width - 1, x));
+            const fraction = clamped / cellsAvailable;
+            const next = this.min + fraction * (this.max - this.min);
+            this.setValue(next);
+        }
+        // --- Rendering ---
+        draw(options) {
+            const trackChar = drawable(options, "─", "-");
+            const markerChar = drawable(options, "●", "*");
+            const range = this.max - this.min;
+            const fraction = range === 0 ? 0 : (this.value - this.min) / range;
+            const markerIdx = Math.round(fraction * (this.width - 1));
+            const baseAttrs = { underline: this.focused };
+            const filledStyle = this.disabled
+                ? new Style({ color: "#666666", bgcolor: "#333333", dim: true, ...baseAttrs })
+                : new Style({ color: this.resolvePalette("primary"), ...baseAttrs });
+            const unfilledStyle = this.disabled
+                ? new Style({ color: "#666666", bgcolor: "#333333", dim: true, ...baseAttrs })
+                : new Style({ color: this.resolvePalette("surface"), ...baseAttrs });
+            const markerStyle = this.disabled
+                ? new Style({ color: "#666666", bgcolor: "#333333", dim: true, bold: true, ...baseAttrs })
+                : new Style({ color: this.resolvePalette("primary"), bold: true, ...baseAttrs });
+            const segments = [];
+            if (markerIdx > 0) {
+                segments.push(new Segment(trackChar.repeat(markerIdx), filledStyle));
+            }
+            segments.push(new Segment(markerChar, markerStyle));
+            const tail = this.width - markerIdx - 1;
+            if (tail > 0) {
+                segments.push(new Segment(trackChar.repeat(tail), unfilledStyle));
+            }
+            return segments;
+        }
+        measure(_options) {
+            return { minimum: this.width, maximum: this.width };
+        }
+        // --- Palette resolution ---
+        resolvePalette(key) {
+            const rgba = this._theme.palette.get(key);
+            // [LAW:no-defensive-null-guards] palette must contain all keys.
+            return ColorSpec.fromRgba(rgba);
+        }
+    };
+})();
+export { Slider };
+// [LAW:single-enforcer] Single function clamps a numeric value into the
+// [min, max] range and snaps to the nearest step boundary. All value
+// mutations route through this; min/max/step never produce out-of-bounds
+// observable state.
+function clampSnap(value, min, max, step) {
+    const clamped = Math.max(min, Math.min(max, value));
+    if (step <= 0)
+        return clamped;
+    const snapped = min + Math.round((clamped - min) / step) * step;
+    // Floating-point cleanup: re-clamp in case rounding nudged past max.
+    return Math.max(min, Math.min(max, snapped));
+}

package/dist/widgets/static-item.d.ts

@@ -0,0 +1,34 @@
+/**
+ * StaticItem — a renderable on the widget surface: it takes no focus and
+ * ignores keys, and it stamps its cells like any widget.
+ *
+ * [LAW:one-type-per-behavior] Display-only content is a `WidgetBase` with
+ * `focusable: false` and the no-op handlers the base already provides, not a
+ * second type.
+ *
+ * The wrapped renderable can be a function that re-evaluates each frame — it
+ * reads MobX observables, and the app repaints when they change — or a plain
+ * renderable.
+ */
+import { Segment } from "../core/segment.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import { WidgetBase } from "./widget-base.js";
+import type { KeyEvent } from "./types.js";
+export interface StaticItemOptions {
+    id: string;
+    render: Renderable | ((options: RenderOptions) => Iterable<Segment>);
+    measure?: Measurable["measure"];
+}
+export declare class StaticItem extends WidgetBase {
+    readonly id: string;
+    readonly focusable = false;
+    private readonly renderFn;
+    private readonly measureFn;
+    constructor(options: StaticItemOptions);
+    handleKey(_event: KeyEvent): void;
+    protected draw(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/widgets/static-item.js

@@ -0,0 +1,54 @@
+/**
+ * StaticItem — a renderable on the widget surface: it takes no focus and
+ * ignores keys, and it stamps its cells like any widget.
+ *
+ * [LAW:one-type-per-behavior] Display-only content is a `WidgetBase` with
+ * `focusable: false` and the no-op handlers the base already provides, not a
+ * second type.
+ *
+ * The wrapped renderable can be a function that re-evaluates each frame — it
+ * reads MobX observables, and the app repaints when they change — or a plain
+ * renderable.
+ */
+import { Segment } from "../core/segment.js";
+import { WidgetBase } from "./widget-base.js";
+export class StaticItem extends WidgetBase {
+    id;
+    focusable = false;
+    renderFn;
+    measureFn;
+    constructor(options) {
+        super();
+        this.id = options.id;
+        const r = options.render;
+        this.renderFn =
+            typeof r === "function"
+                ? (opts) => r(opts)
+                : (opts) => r.render(opts);
+        this.measureFn = options.measure;
+    }
+    // Static items don't respond to keys. WidgetBase.handleMouse / handleFocus
+    // are already no-ops, so we only need to satisfy the abstract handleKey.
+    handleKey(_event) { }
+    draw(options) {
+        return this.renderFn(options);
+    }
+    measure(options) {
+        if (this.measureFn)
+            return this.measureFn(options);
+        // [LAW:one-source-of-truth] Segment.splitLines is the line-break
+        // authority — it handles newlines embedded inside longer segment.text
+        // values too, not just the "\n" sentinel segment. Walking segments and
+        // testing `seg.text === "\n"` miscounts widths for any renderable
+        // that emits "a\nb" as a single segment.
+        const segments = Array.from(this.renderFn(options));
+        const lines = Segment.splitLines(segments);
+        let max = 0;
+        for (const line of lines) {
+            const w = Segment.getLineLength(line);
+            if (w > max)
+                max = w;
+        }
+        return { minimum: max, maximum: max };
+    }
+}

package/dist/widgets/text-input.d.ts

@@ -0,0 +1,274 @@
+/**
+ * TextInput widget — editable text field with cursor.
+ *
+ * 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.
+ */
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import { type CellCol, type CodePoint } from "../core/cells.js";
+import { type RenderOptions } from "../core/protocol.js";
+import type { TerminalTheme } from "../core/color.js";
+import { WidgetBase } from "./widget-base.js";
+import type { KeyEvent, WidgetMouseEvent } from "./types.js";
+/**
+ * A soft-wrap strategy. Given one logical line of text and cell-width budgets,
+ * return the visual sub-rows that line wraps into. The first sub-row uses
+ * `firstWidth` as its capacity; every subsequent (continuation) sub-row uses
+ * `continuationWidth` (typically `firstWidth - cellLen(continuationMarker)`).
+ *
+ * Each returned row carries:
+ *   - `content` — the displayed text for that visual row (the widget prepends
+ *     the continuation marker itself; the strategy never includes it).
+ *   - `start`   — code-unit offset into the *logical line* where `content`
+ *     begins, so the widget can map visual positions back to absolute `value`
+ *     offsets for cursor projection.
+ *
+ * [LAW:types-are-the-program] Budget params are `CellCol`; `start` is
+ * `CodePoint` (a `CodeUnit` on a code-point boundary) — the type system
+ * prevents mixing these integer spaces inside a custom strategy.
+ *
+ * Built-in: `charGreedyWrap` (break at any character at the width limit).
+ * Custom: any function matching this signature. Template-aware wrapping
+ * (break at `{{ }}` atoms, e.g.) is provided by consumers that know the
+ * value's domain syntax — the widget stays domain-neutral.
+ */
+export type WrapStrategy = (logicalLine: string, budget: {
+    firstWidth: CellCol;
+    continuationWidth: CellCol;
+}) => readonly WrapRow[];
+export interface WrapRow {
+    readonly content: string;
+    /** Code-point offset into the logical line where `content` begins. */
+    readonly start: CodePoint;
+}
+/**
+ * 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, and one too
+ * wide for the whole budget is force-taken — see `cellStepFrom`.
+ */
+export declare const charGreedyWrap: WrapStrategy;
+export interface TextInputOptions {
+    value?: string;
+    placeholder?: string;
+    id?: string;
+    disabled?: boolean;
+    theme?: TerminalTheme;
+    maxLength?: number;
+    password?: boolean;
+    /**
+     * When true, Enter inserts a `\n` into `value` instead of emitting submit,
+     * and Up/Down arrows + Ctrl+P/N navigate between visual rows.
+     * Single-line mode (the default) leaves Enter as submit and Up/Down as
+     * no-ops, which matches the conventional one-line-input widget shape.
+     */
+    multiline?: boolean;
+    /**
+     * Soft-wrap strategy. When set (multiline mode only), each logical line
+     * is wrapped to fit available width using this strategy; the widget
+     * renders one visual row per wrap row and Up/Down move across *visual*
+     * rows, not logical ones. When unset, multiline rendering emits each
+     * logical line as one (potentially overflowing) visual row.
+     *
+     * Pass `charGreedyWrap` for the conventional textarea wrap, or supply
+     * a custom strategy that understands the value's domain syntax (e.g. a
+     * tokenizer that breaks at expression boundaries instead of mid-token).
+     */
+    wrap?: WrapStrategy;
+    /**
+     * Continuation marker rendered at the start of each non-first visual row
+     * when a logical line wraps. Defaults to `"↳ "` (2 cells wide). The
+     * widget subtracts this marker's display width from the strategy's
+     * `continuationWidth` budget so wrapped content fits the available area.
+     */
+    continuationMarker?: string;
+    /**
+     * Maximum visible visual rows. When set and the wrapped value exceeds
+     * this many rows, the widget scrolls the visible window to keep the
+     * cursor row in view. Unset → render every row (let the host bound the
+     * pane).
+     */
+    maxRows?: number;
+    /**
+     * Minimum visible visual rows. When set and the wrapped value has fewer
+     * rows than this, the widget pads with empty rows so the rendered area
+     * occupies at least `minRows` lines (useful for stable layouts).
+     */
+    minRows?: number;
+    /**
+     * Scroll-state indicator style.
+     *
+     *   - `"arrows"` (default): the widget renders ▲/▼ inside its own content
+     *     area on the first/last visible row when scroll is possible in that
+     *     direction. Fully self-contained — host needs no wiring.
+     *   - `"indices"`: the widget suppresses in-content arrows and instead
+     *     publishes `scrollIndicatorText` (e.g. `"[14/102]"`) for the host
+     *     (typically a `Panel`'s `bottomRightAccessory`) to display in the
+     *     border. Useful when the surrounding chrome should carry the
+     *     indicator so widget content area stays untouched.
+     *   - `"none"`: no indicator at all.
+     */
+    scrollIndicator?: "arrows" | "indices" | "none";
+    /**
+     * Style override for the in-content scroll arrows (▲/▼). Defaults to the
+     * widget's `primary` palette color. Has no effect outside `"arrows"` mode.
+     */
+    indicatorStyle?: Style;
+    /**
+     * Style override for the cursor cell. Defaults to
+     * `bgcolor: primary, color: on-primary` (the WCAG-correct combination
+     * derived from the active theme).
+     */
+    cursorStyle?: Style;
+    /**
+     * Style override for the rendered content text. Defaults to the
+     * theme's `foreground` palette color.
+     */
+    contentStyle?: Style;
+}
+export declare class TextInput extends WidgetBase {
+    readonly id: string;
+    readonly focusable = true;
+    accessor value: string;
+    accessor cursorPosition: CodePoint;
+    accessor placeholder: string;
+    private _theme;
+    private readonly _maxLength;
+    private readonly _password;
+    private readonly _multiline;
+    private readonly _wrap;
+    private readonly _continuationMarker;
+    private readonly _markerWidth;
+    private readonly _maxRows;
+    private readonly _minRows;
+    private readonly _scrollIndicator;
+    accessor indicatorStyleOverride: Style | undefined;
+    accessor cursorStyleOverride: Style | undefined;
+    accessor contentStyleOverride: Style | undefined;
+    /**
+     * 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.
+     */
+    private _visualRows;
+    private _preferredColumn;
+    private _killBuffer;
+    private _scrollStart;
+    private _singleLineViewportStart;
+    readonly multiline: boolean;
+    constructor(options?: TextInputOptions);
+    setTheme(theme: TerminalTheme): void;
+    handleKey(event: KeyEvent): void;
+    handleMouse(event: WidgetMouseEvent): void;
+    setHovered(value: boolean): void;
+    moveCharLeft(): void;
+    moveCharRight(): void;
+    moveLineUp(): void;
+    moveLineDown(): void;
+    private _clampColForRow;
+    private _cursorVisualRow;
+    private _cursorVisualCol;
+    moveLineStart(): void;
+    moveLineEnd(): void;
+    moveDocStart(): void;
+    moveDocEnd(): void;
+    moveWordLeft(): void;
+    moveWordRight(): void;
+    deleteCharBack(): void;
+    deleteCharForward(): void;
+    deleteWordBack(): void;
+    deleteWordForward(): void;
+    killLineBack(): void;
+    killLineForward(): void;
+    yank(): void;
+    transposeChars(): void;
+    private _lineStart;
+    private _lineEnd;
+    private _insertText;
+    protected draw(options: RenderOptions): Iterable<Segment>;
+    private _renderSingleLine;
+    private _renderMultiline;
+    private _emitRowContent;
+    private _computeVisualRows;
+    measure(_options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    /**
+     * `[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(): string | undefined;
+    private resolvePalette;
+}