@oh-my-pi/pi-tui 15.10.9 → 15.10.11

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## [Unreleased]
 
+## [15.10.11] - 2026-06-10
+
+### Added
+
+- `SettingsList` now supports type-to-search filtering with Escape clearing an active query before canceling.
+
+### Changed
+
+- Preserved list selection by item ID when replacing settings so focus stays on the same setting
+- Displayed a no matching settings message and search-editing hint when filtering returns no matches
+- Expanded settings search matching to include IDs, current values, descriptions, and option values as well as labels
+- Raised the stdin split-escape flush window from 10ms to 50ms: over laggy links (ssh, slow multiplexers) a CSI sequence split across reads was flushed as literal data, leaking `[` + `A` style fragments into the editor as typed text
+- Lengthened the OSC 11 appearance poll on terminals without Mode 2031 from 2s to 30s — each poll's query write cleared the user's active text selection, breaking copy every two seconds on Alacritty/Warp/older WezTerm
+- Rewrote `StdinBuffer.extractCompleteSequences` to index-based scanning: the previous per-iteration `slice` + `Array.from(remaining)[0]` made plain-text bursts O(n²), turning a 100KB non-bracketed paste into a multi-second freeze
+- Capped the editor undo stack at 100 entries with word-level coalescing of consecutive single-character inserts (matching `Input`), capped the kill ring at 60 entries, cached word-wrap layout per (line, width) so each render and key handler shares one wrap pass, and batched ≤1000-char single-line pastes into one insert + one trigger-detection pass instead of per-character replay
+- Virtualized the frame pipeline around a stable-prefix contract — the renderer no longer does O(total transcript) work per frame. `Component.render` now returns `readonly string[]`: results are component-owned, callers must not mutate them, and an unchanged component returns the same array reference (reference equality proves byte-identical rows). `Container.render` memoizes its concatenation on child references (children are still rendered every frame for their side effects); `Box` replaced its content-hashing cache with the same child-reference memo (no more per-frame `leftPad + line` rebuilds and full-content hashing); `Markdown`, `Spacer`, and `TruncatedText` return their cached arrays by reference instead of defensive copies. The TUI composes a persistent frame from per-child segments and an opt-in `RenderStablePrefix` report (consumable floor semantics for in-place mutators like the transcript), so marker extraction, line preparation (persistent prepared-frame replacing the per-frame rebuilt cache arrays), and the committed-prefix audit now run only over rows at/after the first changed row instead of every line of the transcript every frame
+- Rewrote the render core around an append-only native-scrollback contract. Committed rows are immutable: rows enter terminal history exactly once, in order, when the component-reported commit boundary (`NativeScrollbackLiveRegion`) marks them final, and the visible window repaints in place with relative moves. The engine no longer probes the terminal's scroll position or guesses whether a destructive rebuild is safe — the entire ED3-risk/defer/checkpoint machinery (viewport probes, eager streaming mode, dirty-scrollback reconciliation, deferred shrink/mutation intents, streaming high-water rebuilds, ConPTY-specific defer paths) is deleted. ED3 (`CSI 3 J`) now fires only on explicit user gestures: session replace, resize outside multiplexers, and `resetDisplay()`. This structurally removes the yank / flash / duplicated-rows / invisible-until-resize failure families tracked across #1610, #1635, #1651, #1682, #1719, #1746, #1799, #1823, #1962, #1974, #2000, #2011, #2154.
+- A frame that shrinks into its committed prefix re-anchors the visible window at the new tail and restarts commit bookkeeping; previously committed rows stay in history (history is never rewritten without a gesture).
+- Overlays now composite into the visible window slice only and freeze commits while visible, so overlay pixels can never enter native scrollback and closing an overlay no longer triggers a destructive history rebuild.
+- Inline-image budget demotion now deletes the demoted image's graphics by id and lets the window diff repaint the text fallback — no more mid-session destructive full replay when the image cap is exceeded.
+- The render-stress harness now validates the contract with a shadow commit ledger (an independent reimplementation of the ledger math fed only by observed frames and bytes), asserting scrollback equals the committed prefix row-for-row and that tape growth matches physical scroll exactly, across randomized op sequences, resizes, overlays, and multiplexer scenarios. The ghostty-web virtual terminal additionally survives libghostty-vt 0.4's WASM allocator traps via an event-log replay/compaction recovery, and strips non-spacing combining marks on input (a margin-aligned combining cluster deterministically corrupts that engine; mark placement through it was already unverifiable).
+
+### Fixed
+
+- Fixed Windows rendering degrading into CP437 mojibake (`Γöé`/`ΓöÇ` instead of box-drawing borders and Nerd Font glyphs) after a console-sharing child process changed the console codepage (e.g. PHP CLI's implicit `chcp`, php.net request #73716): the breakage stayed latent until the next full repaint such as ctrl+o expand. The terminal now re-asserts the UTF-8 codepage (output and input) before each stdout write
+- Fixed crash recovery leaving the shell unusable: `emergencyTerminalRestore` (and `terminal.stop()`) never left the alt screen nor disabled mouse tracking, so a crash during a fullscreen overlay stranded the user on the alternate buffer with any-motion mouse reporting spewing escape garbage until a manual `reset`
+- Fixed bracketed paste with a lost `ESC[201~` end marker (ssh/tmux truncation) silently eating all subsequent input forever while growing memory unboundedly — paste mode now has an inactivity watchdog (1s) and a byte cap (64 MiB) that exit paste mode and deliver the accumulated bytes through the paste event
+- Fixed vertical cursor movement using UTF-16 code units as visual columns: Up/Down over emoji/CJK lines could land the cursor mid-surrogate-pair, rendering a lone surrogate and permanently corrupting the buffer on the next insert; movement now walks graphemes and snaps the target offset to a cluster boundary, also fixing column drift across wide glyphs
+- Fixed cursor positions inside whitespace trimmed at a word-wrap boundary mapping to no layout line — the cursor vanished and the viewport jumped to the buffer's last line; the preceding chunk now owns the skipped whitespace run
+- Fixed word-delete and kill-to-line operations (Ctrl+W/Alt+D/Ctrl+U/Ctrl+K) cutting through atomic paste markers, leaving `[Paste #1, +30` junk that no longer expanded to the pasted content on submit — delete ranges now extend over any atomic token they intersect
+- Fixed the kitty CSI-u printable dedup swallowing a real keystroke arbitrarily long after the duplicated event; the pending codepoint now expires after 25ms
+- Fixed `resetDisplay()` being a no-op on the alt screen: the redraw gesture could not repair a corrupted fullscreen modal because `#emitAltFrame` skipped identical-string repaints without consulting the force-repaint flag
+- Fixed the ghostty initial-image paint deferral consuming resize/cursor state before abandoning the frame, which could misclassify the deferred render's reflow and corrupt the paint — the deferral check now runs before any frame state is touched
+- Fixed the terminal-cursor inline-hint branch adding the full hint width to the line accounting even though the rendered hint was truncated, misaligning right padding whenever the hint overflowed
+- Fixed nested markdown list detection sniffing for hardcoded `\x1b[36m` (chalk cyan): every shipped theme emits truecolor/256-color SGR for bullets, so nested items doubled their indentation per level on all real themes; nesting is now tagged structurally by the list renderer. Ordered-list continuation lines also hang by the actual bullet width, so wrapped text under `10.`+ items aligns
+- Fixed committed transcript rows silently vanishing when a component re-laid-out content the engine had already scrolled into native history — a TTSR stream rewind truncating a streamed block, or the image budget demoting a committed inline image to its one-line fallback, shifted every row below by the height delta and the engine kept committing from the stale index, skipping that many rows of everything after (missing interruption banners, half-cut images in scrollback). The engine now audits its committed prefix every ordinary frame: an in-place edit or restyle keeps its alignment (stale styling in history remains the accepted artifact), while any shift re-anchors the commit index at the first moved row and recommits from there — history keeps the stale copy and gains a fresh one. Duplication, never loss. The detector (`findCommittedPrefixResync`, exported for the stress harness's shadow ledger) samples the prefix tail SGR-stripped so theme restyles and single-row edits never trigger spurious recommits.
+- Fixed budget-demoted inline images shrinking their transcript block: the text fallback is now height-preserving once a graphic has rendered (reserved rows plus the fallback line), so demotion never shifts content below a committed image.
+- Fixed stale trailing cells bleeding into committed history on combining-heavy rows: the native width model can over-count Arabic/combining clusters, classifying a short-rendering row as full-width and skipping the trailing erase — the previous occupant's cells then scrolled into scrollback baked into the committed row. Non-ASCII row rewrites now erase the line before writing.
+
+### Removed
+
+- Removed the probe/defer API surface: `TUI.setEagerNativeScrollbackRebuild()`, `TUI.refreshNativeScrollbackIfDirty()`, `TUI.setClearOnShrink()`/`getClearOnShrink()`, `RenderRequestOptions.allowUnknownViewportMutation`, `NativeScrollbackRefreshOptions`, `Terminal.isNativeViewportAtBottom()`, `Terminal.hasEagerEraseScrollbackRisk()`, and the `eagerEraseScrollbackRisk`/`submitPinsViewportToTail` capability fields with their detectors.
+- Removed the `PI_TUI_ED3_SAFE`, `PI_CLEAR_ON_SHRINK`, and `PI_TUI_DEBUG` environment variables (the levers they tuned no longer exist; `PI_DEBUG_REDRAW` now logs the commit-ledger state per frame).
+
 ## [15.10.9] - 2026-06-09
 
 ### Added
@@ -23,6 +67,7 @@
 ### Added
 
 - Added `TUI.getFocused()` accessor and `Input.pasteText(text)` method so callers consuming non-bracketed paste transports (e.g. kitty's OSC 5522 enhanced clipboard) can route a paste payload to the currently focused modal Input rather than always to the primary editor. Mirrors the existing `Editor.pasteText` semantics: newlines stripped, tabs normalized, NFC normalization applied. ([#2127](https://github.com/can1357/oh-my-pi/issues/2127))
+
 ### Fixed
 
 - Fixed tmux/screen/zellij rewind/branch (`requestRender(true, { clearScrollback: true })`) permanently anchoring the input box to the pane top and overlaying scrollback after a streamed reply had grown past the viewport. `#emitFullPaint` only reset `#scrollbackHighWater` inside the `clearScrollback` branch and otherwise raised it monotonically, so inside multiplexers (where `\x1b[3J` is a no-op and `clearScrollback` is forced off) the streaming peak survived the rewind; on the next frame `#planLiveRegionPinnedRender` saw the stale high-water and anchored `renderViewportTop` past the actual content, repainting every visible row blank and parking the cursor at screen row 0 for the rest of the session. A full repaint with `clearViewport: true` re-emits the entire transcript from row 0, so `#scrollbackHighWater` is now assigned (not max-clamped) to the natural push count regardless of whether ED 3 was issued ([#2130](https://github.com/can1357/oh-my-pi/issues/2130)).

package/README.md

@@ -62,7 +62,7 @@ All components implement:
 
 ```typescript
 interface Component {
-	render(width: number): string[];
+	render(width: number): readonly string[];
 	handleInput?(data: string): void;
 	invalidate?(): void;
 }
@@ -70,7 +70,7 @@ interface Component {
 
 | Method               | Description                                                                                                                                                        |
 | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `render(width)`      | Returns an array of strings, one per line. Each line **must not exceed `width`** or the TUI will error. Use `truncateToWidth()` or manual wrapping to ensure this. |
+| `render(width)`      | Returns an array of strings, one per line. Each line **must not exceed `width`** or the TUI will error. Use `truncateToWidth()` or manual wrapping to ensure this. The result is component-owned and immutable to callers; return the same array reference when unchanged (enables renderer memoization) and a new array when content changed. |
 | `handleInput?(data)` | Called when the component has focus and receives keyboard input. The `data` string contains raw terminal input (may include ANSI escape sequences).                |
 | `invalidate?()`      | Called to clear any cached render state. Components should re-render from scratch on the next `render()` call.                                                     |
 
@@ -590,7 +590,7 @@ class MyInteractiveComponent implements Component {
 		}
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		return this.items.map((item, i) => {
 			const prefix = i === this.selectedIndex ? "> " : "  ";
 			return truncateToWidth(prefix + item, width);
@@ -614,7 +614,7 @@ class MyComponent implements Component {
 		this.text = text;
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		// Option 1: Truncate long lines
 		return [truncateToWidth(this.text, width)];
 
@@ -656,7 +656,7 @@ class CachedComponent implements Component {
 	private cachedWidth?: number;
 	private cachedLines?: string[];
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		if (this.cachedLines && this.cachedWidth === width) {
 			return this.cachedLines;
 		}

package/dist/types/components/box.d.ts

@@ -13,5 +13,5 @@ export declare class Box implements Component {
     setPaddingY(paddingY: number): void;
     setBgFn(bgFn?: (text: string) => string): void;
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
 }

package/dist/types/components/editor.d.ts

@@ -81,7 +81,7 @@ export declare class Editor implements Component, Focusable {
      */
     addToHistory(text: string): void;
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
     handleInput(data: string): void;
     getText(): string;
     /**

package/dist/types/components/image.d.ts

@@ -82,5 +82,5 @@ export declare class Image implements Component {
     #private;
     constructor(base64Data: string, mimeType: string, theme: ImageTheme, options?: ImageOptions, dimensions?: ImageDimensions);
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
 }

package/dist/types/components/input.d.ts

@@ -17,5 +17,5 @@ export declare class Input implements Component, Focusable {
      *  (e.g. kitty's OSC 5522 enhanced clipboard read). Mirrors `Editor.pasteText`. */
     pasteText(text: string): void;
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
 }

package/dist/types/components/loader.d.ts

@@ -10,7 +10,7 @@ export declare class Loader extends Text {
     private messageColorFn;
     private message;
     constructor(ui: TUI, spinnerColorFn: ColorFn, messageColorFn: LoaderMessageColorFn, message?: string, spinnerFrames?: string[]);
-    render(width: number): string[];
+    render(width: number): readonly string[];
     start(): void;
     stop(): void;
     /** Lifecycle teardown: stop the animation timer. Idempotent. */

package/dist/types/components/markdown.d.ts

@@ -49,10 +49,14 @@ export interface MarkdownTheme {
 }
 export declare class Markdown implements Component {
     #private;
+    /** When true, skip the module-level LRU (lookup and insert) for this instance's
+     *  renders. Set for in-flight streaming partials whose text changes every frame —
+     *  caching those churns the LRU with near-duplicate full-message snapshots. */
+    transientRenderCache: boolean;
     constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
     setText(text: string): void;
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
 }
 /**
  * Render inline markdown (bold, italic, code, links, strikethrough) to a styled string.

package/dist/types/components/scroll-view.d.ts

@@ -57,6 +57,6 @@ export declare class ScrollView implements Component {
      */
     handleScrollKey(data: string): boolean;
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
 }
 export {};

package/dist/types/components/select-list.d.ts

@@ -50,7 +50,7 @@ export declare class SelectList implements Component {
     setFilter(filter: string): void;
     setSelectedIndex(index: number): void;
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
     handleInput(keyData: string): void;
     getSelectedItem(): SelectItem | null;
 }

package/dist/types/components/settings-list.d.ts

@@ -25,17 +25,20 @@ export interface SettingsListTheme {
 export declare class SettingsList implements Component {
     #private;
     constructor(items: SettingItem[], maxVisible: number, theme: SettingsListTheme, onChange: (id: string, newValue: string) => void, onCancel: () => void);
+    getSearchQuery(): string;
+    hasSearchQuery(): boolean;
+    clearSearch(): void;
     /** Update an item's currentValue */
     updateValue(id: string, newValue: string): void;
     /**
-     * Replace the entire items array. Selection is preserved when the prior
-     * index is still valid, otherwise clamped to the last item (or 0 if the
-     * list is now empty). An open submenu is left untouched — its lifetime
-     * is bounded by its own done callback, and `#closeSubmenu` re-clamps the
-     * restored index against the new list on the way out.
+     * Replace the entire items array. Selection is preserved by item id when
+     * the previous selection still survives the active filter, otherwise
+     * clamped to the last filtered item (or 0 if there are no matches).
+     * An open submenu is left untouched — its lifetime is bounded by its own
+     * done callback, and `#closeSubmenu` re-clamps the restored index on exit.
      */
     setItems(items: SettingItem[]): void;
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
     handleInput(data: string): void;
 }

package/dist/types/components/spacer.d.ts

@@ -7,5 +7,5 @@ export declare class Spacer implements Component {
     constructor(lines?: number);
     setLines(lines: number): void;
     invalidate(): void;
-    render(_width: number): string[];
+    render(_width: number): readonly string[];
 }

package/dist/types/components/tab-bar.d.ts

@@ -52,5 +52,5 @@ export declare class TabBar implements Component {
      */
     handleInput(data: string): boolean;
     /** Render the tab bar, wrapping to multiple lines if needed */
-    render(width: number): string[];
+    render(width: number): readonly string[];
 }

package/dist/types/components/text.d.ts

@@ -9,5 +9,5 @@ export declare class Text implements Component {
     setText(text: string): boolean;
     setCustomBgFn(customBgFn?: (text: string) => string): void;
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
 }

package/dist/types/components/truncated-text.d.ts

@@ -6,5 +6,5 @@ export declare class TruncatedText implements Component {
     #private;
     constructor(text: string, paddingX?: number, paddingY?: number);
     invalidate(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
 }

package/dist/types/kill-ring.d.ts

@@ -1,10 +1,3 @@
-/**
- * Ring buffer for Emacs-style kill/yank operations.
- *
- * Tracks killed (deleted) text entries. Consecutive kills can accumulate
- * into a single entry. Supports yank (paste most recent) and yank-pop
- * (cycle through older entries).
- */
 export declare class KillRing {
     #private;
     /**

package/dist/types/stdin-buffer.d.ts

@@ -23,6 +23,17 @@ export type StdinBufferOptions = {
      * After this time, a genuinely incomplete escape is flushed.
      */
     timeout?: number;
+    /**
+     * Paste-mode inactivity watchdog (default: 1000ms). If no input arrives for
+     * this long while waiting for the bracketed-paste end marker, the paste is
+     * assumed truncated: accumulated bytes are delivered and input recovers.
+     */
+    pasteTimeout?: number;
+    /**
+     * Paste-mode byte cap (default: 64 MiB). Exceeding it aborts paste mode the
+     * same way, bounding memory when the end marker never arrives.
+     */
+    pasteByteLimit?: number;
 };
 export type StdinBufferEventMap = {
     data: [string];

package/dist/types/terminal-capabilities.d.ts

@@ -16,22 +16,13 @@ export declare class TerminalInfo {
     readonly trueColor: boolean;
     readonly hyperlinks: boolean;
     readonly notifyProtocol: NotifyProtocol;
-    readonly eagerEraseScrollbackRisk: boolean;
     readonly deccara: boolean;
     readonly supportsScreenToScrollback: boolean;
     /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
     readonly textSizing: boolean;
-    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, eagerEraseScrollbackRisk?: boolean, deccara?: boolean, supportsScreenToScrollback?: boolean, 
+    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, deccara?: boolean, supportsScreenToScrollback?: boolean, 
     /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
     textSizing?: boolean);
-    /**
-     * Whether a prompt-submit keystroke scrolls this host to its tail, so the
-     * native-scrollback reconciliation checkpoint may ED3-rebuild even when the
-     * viewport position is unprobeable. Assigned by the TERMINAL builder from
-     * {@link detectSubmitPinsViewportToTail}; readonly but tests opt in via the
-     * {@link setTerminalSubmitPinsViewportToTail} mutable-cast setter.
-     */
-    readonly submitPinsViewportToTail: boolean;
     /**
      * Mutable clone for the {@link TERMINAL} singleton: copies every field and
      * keeps the prototype methods, so the builder and runtime setters flip
@@ -50,36 +41,6 @@ export declare function isNotificationSuppressed(): boolean;
  * Windows Terminal introduced SIXEL support in preview 1.22.
  */
 export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
-/**
- * Whether live-frame native scrollback rebuilds are unsafe when the terminal
- * viewport position is unobservable.
- *
- * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). Many
- * terminals either clamp a scrolled reader back to the active tail or erase host
- * scrollback when ED3 lands. The important property is not the brand name — it
- * is that an unknown viewport position cannot be proven safe. Environment
- * markers are therefore only used to prove *risk* or a strongly-known profile;
- * unknown POSIX/remote/multiplexer shapes default to risky for passive renders.
- *
- * Native win32 is excluded here because the renderer has dedicated ConPTY
- * deferral paths; a `WT_SESSION` sighting on POSIX means Windows Terminal is the
- * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
- */
-export declare function detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
-/**
- * Whether a prompt-submit keystroke scrolls this terminal to its tail, making the
- * native-scrollback reconciliation checkpoint (`refreshNativeScrollbackIfDirty`)
- * safe to ED3-rebuild even when the viewport position cannot be probed.
- *
- * True only for recognized genuine *local* terminals where typing into the prompt
- * brings the host viewport to the bottom. False — the checkpoint keeps deferring
- * until a positive at-tail probe — for hosts whose scrollback a keystroke does not
- * move: Windows consoles/ConPTY, Windows Terminal (incl. WSL), SSH, multiplexers,
- * and unrecognized profiles. This is the per-terminal counterpart to the blanket
- * block from #1610/#1682/#1746: those hosts genuinely cannot treat a submit as
- * proof of at-tail, but genuine local terminals can.
- */
-export declare function detectSubmitPinsViewportToTail(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
  * Resolve an explicit user override for DEC 2026 synchronized output. Returns
  * `false` for an opt-out, `true` for a force-on, or `null` when the user has
@@ -134,11 +95,9 @@ export declare const TERMINAL_ID: TerminalId;
 export interface RuntimeTerminal extends TerminalInfo {
     imageProtocol: ImageProtocol | null;
     hyperlinks: boolean;
-    eagerEraseScrollbackRisk: boolean;
     deccara: boolean;
     supportsScreenToScrollback: boolean;
     textSizing: boolean;
-    submitPinsViewportToTail: boolean;
 }
 export declare const TERMINAL: RuntimeTerminal;
 /**
@@ -153,8 +112,6 @@ export declare function setTerminalImageProtocol(imageProtocol: ImageProtocol |
 export declare function setTerminalDeccara(enabled: boolean): void;
 /** Override screen-to-scrollback clear support for targeted renderer tests. */
 export declare function setTerminalScreenToScrollback(enabled: boolean): void;
-/** Override submit-pins-viewport-to-tail for checkpoint reconciliation tests. */
-export declare function setTerminalSubmitPinsViewportToTail(enabled: boolean): void;
 /**
  * Enable/disable OSC 66 text-sizing at runtime. The coding-agent calls this from
  * the `tui.textSizing` setting (gated on the terminal's static `textSizing`

package/dist/types/terminal.d.ts

@@ -48,42 +48,6 @@ export interface Terminal {
     clearScreen(): void;
     setTitle(title: string): void;
     setProgress(active: boolean): void;
-    /**
-     * Returns whether the native terminal viewport is at the scrollback tail when
-     * the host exposes that state. `undefined` means the terminal cannot report it.
-     *
-     * `ProcessTerminal` deliberately does not implement this — no real terminal
-     * can answer it truthfully:
-     *
-     * - POSIX terminals expose no scrollback-position API at all.
-     * - Every modern Windows terminal host (Windows Terminal, VS Code, Tabby,
-     *   Hyper, Alacritty, WezTerm, JetBrains, …) fronts console apps through
-     *   ConPTY, where kernel32's `GetConsoleScreenBufferInfo` describes the
-     *   pseudo-console buffer. That buffer is pinned to the visible grid —
-     *   scrollback lives in the host UI, invisible to console APIs
-     *   (microsoft/terminal#10191) — so a probe reads "at bottom" no matter
-     *   where the user scrolled. Trusting it let streaming-time rebuilds emit
-     *   `\x1b[3J` and yank scrolled readers: #1635 (Windows Terminal), #1746
-     *   (Tabby and other ConPTY hosts). No env var distinguishes these hosts
-     *   (Tabby sets none), so trust cannot be conditional on the environment.
-     * - Legacy conhost (the only non-ConPTY host) keeps a real scrollback
-     *   buffer, but its window follows the output cursor: a probe comparing
-     *   `srWindow.Bottom` against `dwSize.Y - 1` reads "scrolled up" for a user
-     *   following live output until all ~9001 buffer rows fill, permanently
-     *   blocking checkpoint scrollback reconciliation.
-     *
-     * The renderer treats a missing implementation / `undefined` as "unknown":
-     * live mutations defer destructive rebuilds and reconcile native scrollback
-     * at explicit checkpoints (prompt submit), where the user's keystroke has
-     * already pinned the host viewport to the bottom. Only test terminals
-     * (xterm.js-backed) implement this with a real answer.
-     */
-    isNativeViewportAtBottom?(): boolean | undefined;
-    /**
-     * Override the global terminal-profile ED3 risk decision for custom/test
-     * terminals. `undefined` falls back to the resolved `TERMINAL` profile.
-     */
-    hasEagerEraseScrollbackRisk?(): boolean | undefined;
     /**
      * Register a callback for terminal appearance (dark/light) changes.
      * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.

package/dist/types/tui.d.ts

@@ -24,14 +24,26 @@ export interface TUIStartOptions {
 }
 /**
  * Component interface - all components must implement this
+ *
+ * Render contract: the returned array (and its rows) belongs to the component.
+ * Callers MUST NOT mutate it — components are allowed to return a cached array
+ * and will return the exact same reference for as long as their rendered
+ * content is unchanged. Conversely, a component MUST return a fresh array
+ * reference whenever its content changed; reference equality across two
+ * render() calls is the engine's proof that the rows are byte-identical
+ * (containers memoize their concatenation on it, and the TUI derives the
+ * frame's stable prefix from it). A component that mutates a previously
+ * returned array in place must implement {@link RenderStablePrefix} to declare
+ * which leading rows survived.
  */
 export interface Component {
     /**
-     * Render the component to lines for the given viewport width
-     * @param width - Current viewport width
-     * @returns Array of strings, each representing a line
+     * Render the component to an array of physical rows at the given width.
+     * The result is component-owned and `readonly` to the caller; an unchanged
+     * component may (and should) return the same array reference it returned
+     * last time.
      */
-    render(width: number): string[];
+    render(width: number): readonly string[];
     /**
      * Optional handler for keyboard input when component has focus
      */
@@ -55,27 +67,50 @@ export interface Component {
     dispose?(): void;
 }
 /**
- * Optional component seam for native-scrollback pinning. A component that
- * renders a stable prefix followed by a live/transient suffix reports the local
- * line index where that suffix begins after each render. TUI treats that suffix
- * — and every root child rendered below it — as not yet safe to commit to native
- * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ * Component seam for append-only native-scrollback commits. A component that
+ * renders a finalized prefix followed by a live/mutating suffix reports the
+ * local line index where that suffix begins after each render. The engine
+ * commits rows to native scrollback only up to that boundary; everything
+ * below repaints in place inside the visible window and never enters history
+ * until it finalizes.
  *
  * `getNativeScrollbackCommitSafeEnd` optionally reports a *deeper* boundary
- * inside that live suffix: the line index up to which the live region is
- * append-only (its earlier rows never re-layout, only new rows append at the
- * bottom — a streaming assistant message). Rows in `[liveRegionStart,
- * commitSafeEnd)` that scroll above the viewport are safe to commit to native
- * scrollback even though they are technically live, because they will never
- * change. Without this, a single live block that alone overflows the viewport
- * loses its scrolled-off head (committed nowhere, repainted nowhere). Volatile
- * live blocks (tool previews that collapse) omit it, so their mutable rows stay
- * deferred. Defaults to `liveRegionStart` when absent.
+ * inside the live suffix: the line index up to which the live region is
+ * append-only (earlier rows never re-layout — a streaming assistant message).
+ * Rows in `[liveRegionStart, commitSafeEnd)` may commit even though they are
+ * technically live, because they will never change. Without it, a single live
+ * block that alone overflows the window would hold its scrolled-off head out
+ * of history until it finalizes. Volatile live blocks (tool previews that
+ * collapse) omit it. Defaults to `liveRegionStart` when absent; a root that
+ * reports no seam at all commits everything that scrolls (shell semantics).
  */
 export interface NativeScrollbackLiveRegion {
     getNativeScrollbackLiveRegionStart(): number | undefined;
     getNativeScrollbackCommitSafeEnd?(): number | undefined;
 }
+/**
+ * Opt-in stability report for components that mutate their returned render
+ * array in place across frames (instead of returning a fresh array per
+ * change). The engine reads it right after the component's `render()` returns:
+ * the report counts the leading rows of the just-returned array that are
+ * byte-identical to the array state the reader last observed. The engine uses
+ * it to reuse the composed frame's prefix — skipping marker extraction, line
+ * preparation, and the committed-prefix audit for those rows.
+ *
+ * Contract:
+ * - Reading CONSUMES the report: it re-bases the baseline to the current
+ *   array state. The accumulated count therefore covers every render since
+ *   the previous read, so out-of-band `render()` calls between engine frames
+ *   (an exporter walking the tree) can only lower the report, never inflate
+ *   it past what the engine actually has.
+ * - An implementer that cannot prove stability for a frame must lower the
+ *   accumulated count to 0 for that render.
+ * - Rows at or beyond the report may have been mutated in place; rows before
+ *   it must be the identical string values at the identical indices.
+ */
+export interface RenderStablePrefix {
+    getRenderStablePrefixRows(): number;
+}
 /**
  * Interface for components that can receive focus and display a cursor.
  * When focused, the component should emit CURSOR_MARKER at the cursor position
@@ -97,21 +132,6 @@ export interface Focusable {
 export interface RenderRequestOptions {
     /** Clear terminal scrollback for intentional transcript replacement. */
     clearScrollback?: boolean;
-    /**
-     * Allow a transient live-viewport repaint when the terminal cannot report
-     * whether its native viewport is at the tail.
-     *
-     * This is **not** a settled transcript commit and must not be used for tool
-     * completion, session replay, or other background/offscreen rewrites. On
-     * ED3-risk terminals it may deliberately choose a viewport repaint/deferred
-     * shrink without clearing native scrollback so autocomplete, IME, and focused
-     * editor chrome stay responsive without yanking a scrolled reader.
-     */
-    allowUnknownViewportMutation?: boolean;
-}
-/** Options for deferred native scrollback rebuild checkpoints. Reserved for API stability. */
-export interface NativeScrollbackRefreshOptions {
-    allowUnknownViewport?: boolean;
 }
 /** Type guard to check if a component implements Focusable */
 export declare function isFocusable(component: Component | null): component is Component & Focusable;
@@ -192,6 +212,7 @@ export interface OverlayHandle {
  * Container - a component that contains other components
  */
 export declare class Container implements Component {
+    #private;
     children: Component[];
     addChild(component: Component): void;
     removeChild(component: Component): void;
@@ -203,8 +224,28 @@ export declare class Container implements Component {
      * {@link clear} for that). Idempotent per child via each child's own dispose.
      */
     dispose(): void;
-    render(width: number): string[];
+    render(width: number): readonly string[];
 }
+/**
+ * Decide whether `frame` still aligns with the committed prefix, and where to
+ * re-anchor the commit index when it does not. Returns the resync row index,
+ * or -1 when no resync is needed.
+ *
+ * The detector exploits the asymmetry between the two mutation classes: an
+ * in-place edit or restyle of committed rows disturbs only the touched rows
+ * (alignment below them is intact — the stale copy in history is the
+ * long-accepted artifact), while any insertion or deletion shifts EVERY row
+ * below it, including the rows just above the commit boundary. So the prefix
+ * *tail* is sampled (up to 8 non-blank rows within the last 24, compared
+ * SGR-stripped so theme changes stay quiet, tolerating one mismatch for a
+ * legitimate single-row edit): aligned ⇒ no resync; misaligned ⇒ resync at
+ * the first non-equivalent row, recommitting from there — duplication, never
+ * loss. Highly repetitive tails (identical filler rows) can mask a shift, in
+ * which case the skipped rows are content-identical to the committed ones —
+ * observationally harmless. Exported for the render-stress harness, whose
+ * shadow commit ledger must mirror the engine's law exactly.
+ */
+export declare function findCommittedPrefixResync(frame: readonly string[], prefix: readonly string[]): number;
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -220,7 +261,7 @@ export declare class TUI extends Container {
         hidden: boolean;
     }[];
     constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: TUIOptions);
-    render(width: number): string[];
+    render(width: number): readonly string[];
     get fullRedraws(): number;
     /** Shared budget that caps how many inline images render as live graphics. */
     get imageBudget(): ImageBudget;
@@ -232,13 +273,6 @@ export declare class TUI extends Container {
     setMaxInlineImages(cap: number): void;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
-    getClearOnShrink(): boolean;
-    /**
-     * Set whether to trigger full re-render when content shrinks.
-     * When true (default), empty rows are cleared when content shrinks.
-     * When false, empty rows remain (reduces redraws on slower terminals).
-     */
-    setClearOnShrink(enabled: boolean): void;
     /**
      * Whether DEC 2026 synchronized-output wrappers are currently emitted around
      * paints. Starts from conservative terminal/env detection and is reconciled at
@@ -246,30 +280,6 @@ export declare class TUI extends Container {
      * positive report, disabled on a negative one.
      */
     get synchronizedOutput(): boolean;
-    /**
-     * When enabled, live render frames rebuild native scrollback on offscreen and
-     * structural changes even when the viewport position is unobservable (POSIX,
-     * where `isNativeViewportAtBottom()` is `undefined`), instead of deferring to a
-     * non-destructive repaint. This trades the anti-yank guarantee for a clean,
-     * duplicate-free history and is meant for windows where output above the fold
-     * is actively re-rendering — e.g. a tool whose result is still streaming and
-     * re-laying-out rows that have already scrolled into history. A terminal that
-     * reports a *known*-scrolled viewport still defers, as does native Windows
-     * (the viewport is never observable there and ConPTY hosts erase host
-     * scrollback on ED3 — #1635/#1746); only the unknown POSIX case is forced to
-     * rebuild. POSIX hosts known to disturb scrolled readers on xterm ED3
-     * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint
-     * rebuilds are unaffected.
-     *
-     * Disabling stays active through one already-requested frame: the event batch
-     * that ends a foreground stream both removes its UI rows (loader/status
-     * teardown — a shrink) and clears this flag before the throttled render timer
-     * fires. If the flag dropped immediately, that teardown frame would hit the
-     * ED3-risk idle deferral and freeze on screen (stale spinner) until the next
-     * keystroke. When no render is pending, disable immediately so a later
-     * unrelated content mutation does not inherit foreground-stream privileges.
-     */
-    setEagerNativeScrollbackRebuild(enabled: boolean): void;
     setFocus(component: Component | null): void;
     /** Component currently receiving keyboard input, if any. */
     getFocused(): Component | null;
@@ -288,12 +298,6 @@ export declare class TUI extends Container {
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
     stop(): void;
-    /**
-     * Rebuild native terminal scrollback if live rendering deferred a history rewrite.
-     * Callers should only invoke this at checkpoints where the user is expected to be
-     * at the terminal bottom, such as after submitting a new prompt.
-     */
-    refreshNativeScrollbackIfDirty(_options?: NativeScrollbackRefreshOptions): boolean;
     /**
      * Force an immediate full replay of the current frame, including native
      * scrollback. This is the keyboard-accessible equivalent of the resize reset: