@linxiraos/pi-tui 1.1.4 → 1.1.5

package/CHANGELOG.md

@@ -2,11 +2,9 @@
 
 ## [Unreleased]
 
-## [1.1.4] - 2026-08-26
+## [1.1.5] - 2026-08-26
 
-### Changed
-
-- 同步 1.1.4 发布线（与 1.1.3 无功能差异）。
+- 同步上游 OMP v18.0.5 / v18.0.6：append-only transcript 声明与稳定行 API、markdown 渲染重构。
 
 ## [1.1.3] - 2026-08-25
 

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

@@ -14,7 +14,7 @@ export declare class Loader extends Text {
     private spinnerColorFn;
     private messageColorFn;
     private message;
-    constructor(ui: TUI, spinnerColorFn: ColorFn, messageColorFn: LoaderMessageColorFn, message?: string, spinnerFrames?: string[]);
+    constructor(ui: TUI, spinnerColorFn: ColorFn, messageColorFn: LoaderMessageColorFn, message?: string | (() => string), spinnerFrames?: string[]);
     render(width: number): readonly string[];
     start(): void;
     stop(): void;

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

@@ -6,6 +6,14 @@ export declare function mathStartIndex(src: string): number | undefined;
 export declare function autolinkSchemeScanIndex(src: string): number | undefined;
 /** @internal exported for tests — must never return false for a src the built-in url regex matches. */
 export declare function urlTokenPossible(src: string): boolean;
+/** @internal exported for tests — counts fast-tail splice frames. A future
+ *  regression that silently disarms the fast path (e.g. an over-broad gate)
+ *  leaves byte-identity intact but drops the counter to zero. */
+export declare let fastTailSplices: number;
+/** @internal exported for tests — resets the splice counter. */
+export declare function resetFastTailSplices(): void;
+/** @internal exported for tests — the grown-line-start block-kind gate. */
+export declare function fastLineStartHazard(grownLine: string): boolean;
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export declare function clearRenderCache(): void;
 /**
@@ -75,6 +83,12 @@ export declare class Markdown implements Component {
     constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
     setText(text: string): boolean;
     invalidate(): void;
+    /**
+     * Width-independent source prefix of the last render ending at a frozen
+     * Markdown block boundary. Only meaningful while streaming (transient
+     * render cache on); grows monotonically under append-only `setText`.
+     */
+    getLastRenderStableText(): string;
     get transientRenderCache(): boolean;
     set transientRenderCache(value: boolean);
     render(width: number): readonly string[];

package/dist/types/tui.d.ts

@@ -23,12 +23,19 @@ export interface ViewportSize {
     readonly columns: number;
     readonly rows: number;
 }
-/** Immutable finalized rows offered until the terminal accepts this identifier. */
+/** Immutable append or complete replay offered until the terminal accepts this identifier. */
 export interface HistoryBatch {
     readonly id: number;
     readonly rows: readonly string[];
+    /**
+     * `append` (the default) adds finalized or naturally emitted rows. `replay`
+     * is the complete logical ledger; the writer bottom-splits it against the
+     * leading blank viewport and serializes the remainder plus final viewport in
+     * one synchronous terminal write.
+     */
+    readonly kind?: "append" | "replay";
 }
-/** One history append and the complete mutable viewport for a terminal frame. */
+/** One history append or complete replay plus the mutable viewport for a terminal frame. */
 export interface TerminalFramePlan {
     readonly history?: HistoryBatch;
     readonly viewport: readonly string[];
@@ -40,7 +47,9 @@ export interface TerminalFrameProvider {
     /** Full semantic viewport used only on the transient resize buffer. */
     renderResizeFrame?(viewport: ViewportSize): readonly string[];
     /** Re-offer finalized history after a display reset or resize replay. */
-    resetHistory?(): void;
+    beginHistoryReplay?(): void;
+    /** Force every currently eligible finalized prefix to retire before stop. */
+    beginHistoryFlush?(): void;
 }
 export interface TUIStartOptions {
     /** Clear saved native scrollback before the first paint. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-tui",
-	"version": "1.1.4",
+	"version": "1.1.5",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Stencil Labs, Inc.",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.1.4",
-		"@linxiraos/pi-utils": "1.1.4"
+		"@linxiraos/pi-natives": "1.1.5",
+		"@linxiraos/pi-utils": "1.1.5"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/components/loader.ts

@@ -32,7 +32,7 @@ export class Loader extends Text {
 		ui: TUI,
 		private spinnerColorFn: ColorFn,
 		private messageColorFn: LoaderMessageColorFn,
-		private message: string = "Loading...",
+		private message: string | (() => string) = "Loading...",
 		spinnerFrames?: string[],
 	) {
 		super("", 1, 0);
@@ -149,11 +149,18 @@ export class Loader extends Text {
 		}, delayMs);
 		this.#intervalId = timer;
 	}
-	/** Re-wrap the underlying Text only when its message or frame width changes. */
+	#resolveMessage(): string {
+		return typeof this.message === "function" ? this.message() : this.message;
+	}
+
+	/** Re-wrap the underlying Text only when its message or frame width changes.
+	 * When {@link message} is a function it is re-evaluated on every spinner
+	 * tick, so a dynamic label (e.g. a live countdown) advances in sync with
+	 * the glyph instead of freezing on the initial value. */
 	#syncText(): boolean {
 		const layoutFrame = this.#layoutFrames[this.#currentFrame];
 		this.#layoutFrame = layoutFrame;
-		return this.setText(`${layoutFrame} ${this.message}`);
+		return this.setText(`${layoutFrame} ${this.#resolveMessage()}`);
 	}
 
 	#requestPaint() {

package/src/components/markdown.ts

@@ -953,12 +953,167 @@ function renderedLinesCacheSize(lines: readonly string[]): number {
 	return Math.max(1, size);
 }
 
+// ---------------------------------------------------------------------------
+// Fast-tail (B+) hazard gates
+// ---------------------------------------------------------------------------
+// Tier-1 eligibility: the appended delta is "markdown-inert" — it cannot open
+// or close an inline token, change block structure, or shift a swatch
+// boundary. A delta carrying a marker is re-lexed through the REAL inline
+// pipeline so self-contained marker pairs render styled — exactly what a full
+// re-lex of the grown row produces. `_` is included but narrowed: an
+// intraword `_` is literal per CommonMark flanking rules, so only FLANKED
+// underscores disarm (FAST_ROW_UNDERSCORE_RE on the row text, plus the
+// delta-edge trailingDelimiterSeamHazard check).
+const FAST_DELTA_RE = /[\n\r\\[`<!*_~$#&@\x1b]/;
+
+// Disarm when the captured row's RAW tail ends in trailing whitespace (wrap
+// trims it; appending a char moves the trim boundary), a trailing backslash
+// (it can become an escape once the delta supplies the next char — the `\\`
+// clause covers that escape-completion hazard), or a full/partial hex swatch
+// run (a `#` + 3-8 hex is a swatch glyph; the byte range may shift).
+const FAST_RUN_END_RE = /(?:[ \t\\]|#[0-9a-fA-F]{3,8}|#+)$/i;
+
+// A partial `#` + 1-2 hex digits can grow into a 3-8 digit swatch glyph
+// across the seam (delta hex digits are inert).
+const FAST_SWATCH_SEAM_RE = /#[0-9a-fA-F]{0,2}$/;
+
+// A partial HTML entity at the seam (`&am` + delta `p;`) OR a complete
+// numeric entity (`&#35;`, `&#x1f600;`) — which decodes to `#`, a swatch
+// lead — would normalize to different bytes than the plain concat.
+const FAST_ENTITY_SEAM_RE = /&(?:[A-Za-z0-9#]{0,31}|#[0-9]{1,7};|#[xX][0-9a-fA-F]{1,6};)$/;
+
+// A bare URL/email anywhere in the delta or across the seam (a URL the regex
+// cut at a trailing delimiter can re-link once the delta supplies more chars;
+// a protocol head ending at the seam completes in the delta) makes the full
+// re-lex autolink while the plain concat would not.
+const FAST_URL_ANYWHERE_RE = /(?:https?|ftp):\/\/|www\.[A-Za-z0-9]|[A-Za-z0-9._%+-]+@/i;
+
+// A bare-URL/email PREFIX may end at the seam and complete in the delta
+// (`ht` + `tps://x`, `foo@` + `bar.com`).
+const FAST_URL_PREFIX_SEAM_RE = /(?:https?|ftp):?\/{0,2}$|www\.$|[A-Za-z0-9._+-]+@[A-Za-z0-9._+-]*$/;
+
+// Inline-markup delimiters that survive into rendered output as LITERAL text
+// when unpaired. The fast path detects open constructs by walking the REAL
+// inline token stream (capture) and the delta's inline token stream (frame):
+// any top-level `text` token still carrying one of these bytes holds an open
+// delimiter, so a later delta could close it and a full re-lex would restyle
+// the seam. Closed pairs tokenize into styled tokens and never appear here.
+// `_` is excluded (intraword `_` is inert); a FLANKED underscore is caught
+// by FAST_ROW_UNDERSCORE_RE on the raw text (SGR bytes precede text, so word
+// boundaries are invisible after styling).
+const FAST_LITERAL_MARKER_RE = /[*~`[\]<>()$&#]/;
+
+// A flanking underscore (start-of-line or preceded by a non-word char) can
+// open an emphasis that a future delta closes. Only flanked `_` is a
+// delimiter; intraword `_` (a_b) is literal.
+const FAST_ROW_UNDERSCORE_RE = /(?:^|[^\w])_/;
+// Two distinct CommonMark word-char notions drive the seam re-flank checks.
+// For the `_`-underscore seam, "word char" = ASCII `\w` (which includes `_`)
+// plus Unicode letters/numbers — `[\w\p{L}\p{N}]`. `\w` alone missed a row
+// ending in a Unicode letter (`é`); CM's char class `[^\s\p{P}\p{S}]` would
+// wrongly treat `_` (\p{Pc}) as a word char and break the `_..._` intraword
+// gate. For `*`/`~` closing emphasis, marked's flanking test uses the full
+// class `[^\s\p{P}\p{S}]` (which covers format/combining marks like U+200C and
+// U+0301), so branch 2 must use that wider class.
+const FAST_UNDERSCORE_WORD_AT_END_RE = /[\w\p{L}\p{N}]$/u;
+const FAST_CMARK_WORD_AT_START_RE = /^[^\s\p{P}\p{S}]/u;
+// A GFM table delimiter row lets a preceding pipe-header line flip into a
+// table when a future inert delta completes it — even a marker-free delta
+// (`| col_a | col_b |\n| --` + `--- | -`). The cold render then re-wraps and
+// restyles the header, so the splice must disarm. The gate runs on the GROWN
+// last line (`recipe.rowRaw`'s last line + deltaTabs) in render().
+const FAST_TABLE_DELIM_ROW_RE = /^\s*(?:\|[\s:]*-+\s*(?:\|[\s:]*-+\s*)*|[\s:]*-+\s*(?:\|[\s:]*-+\s*)+)\|?\s*$/;
+
+// A paragraph's LAST line can complete into a different block kind under an
+// inert delta (ATX heading, blockquote, bullet marker, HR, ref-def) — disarm
+// when the grown line starts one (ref-def grammar: REF_DEF_LINE_RE).
+const FAST_LINE_START_HAZARD_RE =
+	// `-` is placed LAST so it is a literal, not a range bound. The other
+	// chars are in ASCENDING code-point order (no reversed ranges that
+	// rely on engine leniency): * + = – — ─ ━ ═ then the literal `-`.
+	/^ {0,3}(?:#{1,6}(?:[ \t]|$)|>|\d{1,9}[.)](?:[ \t]|$)|[*+=–—─━═-](?:[ \t]|$)|(?:[*+=–—─━═-][ \t]*){2,}[ \t]*$)/;
+/** @internal exported for tests — counts fast-tail splice frames. A future
+ *  regression that silently disarms the fast path (e.g. an over-broad gate)
+ *  leaves byte-identity intact but drops the counter to zero. */
+export let fastTailSplices = 0;
+/** @internal exported for tests — resets the splice counter. */
+export function resetFastTailSplices(): void {
+	fastTailSplices = 0;
+}
+
+/** @internal exported for tests — the grown-line-start block-kind gate. */
+export function fastLineStartHazard(grownLine: string): boolean {
+	return FAST_LINE_START_HAZARD_RE.test(grownLine) || REF_DEF_LINE_RE.test(grownLine);
+}
+
+/** Seam hazards between the captured raw row tail and the delta: the row must
+ *  not end in a wrap-trim, escape, swatch, entity, or URL/email prefix, and
+ *  must hold no unbalanced bracket an inert delta could close into a link. */
+function fastTailSeamSafe(raw: string): boolean {
+	if (FAST_RUN_END_RE.test(raw)) return false;
+	if (FAST_SWATCH_SEAM_RE.test(raw)) return false;
+	if (FAST_ENTITY_SEAM_RE.test(raw)) return false;
+	// Entities decode before swatch/whitespace detection (`&#35;ab` → `#ab`,
+	// `&nbsp;` → ` `): scan the DECODED tail so an entity-indirected swatch
+	// lead OR a decoded trailing space (wrap-trim boundary shifts) disarms.
+	// Autolinks are lex-time on RAW text, so URL prefix stays raw.
+	const rawTail = raw.length > 32 ? raw.slice(-32) : raw;
+	const decodedTail = normalizeHtmlEntitiesForTerminal(rawTail);
+	if (decodedTail !== rawTail && (FAST_RUN_END_RE.test(decodedTail) || FAST_SWATCH_SEAM_RE.test(decodedTail))) {
+		return false;
+	}
+	if (FAST_URL_PREFIX_SEAM_RE.test(raw)) return false;
+	if (raw.endsWith("]") || raw.lastIndexOf("[") > raw.lastIndexOf("]")) return false;
+	if (raw.lastIndexOf("(") > raw.lastIndexOf(")") || raw.lastIndexOf("<") > raw.lastIndexOf(">")) return false;
+	return true;
+}
+// Fast-tail (B+) recipe: captured frame state for the next inert-delta splice.
+interface FastTailRecipe {
+	readonly lines: readonly string[]; // frame rows at capture
+	readonly source: string; // raw #text at capture (append-only predicate)
+	readonly width: number; // contentWidth at capture
+	rowText: string; // RENDERED last wrap-output row (re-wrap input)
+	rowRaw: string; // RAW tail source backing that row (seam scan)
+	rowStart: number; // result[] index of the replaced row
+	rowEnd: number; // exclusive result[] index
+	readonly signature: RenderSignature; // full render signature at capture (bgColor etc.)
+}
+
+/** True when the inline token stream holds an OPEN construct: a `text` token
+ * that still carries a literal delimiter (an unpaired `*`/`` ` ``/`[`/… or a
+ * flanking `_`), or raw HTML. Closed constructs are styled tokens whose
+ * delimiters are absent from their text. An open means a FUTURE delta could
+ * close it — the fast path disarms so the splice always matches a full lex. */
+function inlineHasOpen(tokens: readonly Token[]): boolean {
+	for (const token of tokens) {
+		if (isMathToken(token)) continue;
+		if (token.type === "codespan") continue; // styled leaf; its content cannot re-pair
+		if (token.type === "html") return true; // raw HTML — conservative
+		if (token.type === "text") {
+			const text = "text" in token && typeof token.text === "string" ? token.text : "";
+			if (FAST_LITERAL_MARKER_RE.test(text) || FAST_ROW_UNDERSCORE_RE.test(text)) return true;
+		}
+		if ("tokens" in token && Array.isArray(token.tokens)) {
+			if (inlineHasOpen(token.tokens as Token[])) return true;
+		}
+	}
+	return false;
+}
+
+/** Isolated inline lex of a same-line delta. A single-line delta has no block
+ * structure, so the isolated inline pass equals the full lex's inline pass
+ * (marked's paragraph tokens run the same `inlineTokens` entry point). */
+function lexInlineTokens(text: string): Token[] {
+	return new Lexer(markdownParser.defaults).inlineTokens(text);
+}
+
 // A reference-link definition (`[label]: dest`) resolves across the whole
 // document, so a split lex cannot reproduce it — disable the streaming fast path
 // when one is present (rare in streamed output). The label may contain
 // backslash-escaped characters (`[a\]b]: x`), so escapes are matched explicitly;
 // over-matching is safe (it only costs the fast path), under-matching is not.
-const HAS_REF_DEF = /^ {0,3}\[(?:\\.|[^\]\\])+\]:/m;
+const REF_DEF_LINE_RE = /^ {0,3}\[(?:\\.|[^\]\\])+\]:/;
+const HAS_REF_DEF = new RegExp(REF_DEF_LINE_RE.source, "m");
 
 // marked's list tokenizer (Tokenizer.list, marked v18) continues a list across
 // blank lines only when the remaining source matches
@@ -1620,6 +1775,9 @@ export class Markdown implements Component {
 	#renderingStablePrefix = false;
 	#streamingHighlightCache?: StreamingHighlightCache;
 	#activeRenderSignature?: RenderSignature;
+	#fastTail?: FastTailRecipe; // undefined = disarmed
+	// B+ capture plumbing: #renderContentLines records the last rendered paragraph row.
+	#lastTailCapture?: { kind: "paragraph"; open: boolean; rowInput: string; rowRaw: string };
 	#ignoreTight = false;
 	setIgnoreTight(ignore: boolean): this {
 		this.#ignoreTight = ignore;
@@ -1694,6 +1852,9 @@ export class Markdown implements Component {
 			this.#streamPrefixTokens = undefined;
 			this.#streamPrefixLineCache = undefined;
 			this.#tailRowCache = undefined;
+			// B+: the captured fast-path rows index the replaced content — drop
+			// the recipe so a fresh stream cannot splice onto stale rows.
+			this.#fastTail = undefined;
 		}
 		this.invalidate();
 		return true;
@@ -1704,6 +1865,16 @@ export class Markdown implements Component {
 		this.#cachedWidth = undefined;
 		this.#cachedLines = undefined;
 	}
+
+	/**
+	 * Width-independent source prefix of the last render ending at a frozen
+	 * Markdown block boundary. Only meaningful while streaming (transient
+	 * render cache on); grows monotonically under append-only `setText`.
+	 */
+	getLastRenderStableText(): string {
+		return this.#transientRenderCache ? (this.#streamPrefixText ?? "") : "";
+	}
+
 	get transientRenderCache(): boolean {
 		return this.#transientRenderCache;
 	}
@@ -1717,6 +1888,11 @@ export class Markdown implements Component {
 		// so a memo computed on the other mode's buffer must not be reused —
 		// re-derive on the next frame instead.
 		this.#appendOnlySinceLastScan = false;
+		// B+ reset site: a transient flip (finalize, or a fresh stream on
+		// rewound text) means the next render re-lexes from the current
+		// source — drop the fast-path recipe so stale rows cannot be served
+		// across the transition.
+		this.#fastTail = undefined;
 		this.invalidate();
 	}
 
@@ -1863,6 +2039,132 @@ export class Markdown implements Component {
 			this.#lastScanValid = false;
 		}
 		const signature = this.#renderSignature(width, paddingX);
+		// B+ fast path: an append-only, same-line delta re-renders ONLY the
+		// last content row (the paragraph's trailing wrapped row) with the
+		// grown source, so the new text shows every frame while staying
+		// byte-identical to a cold full render (the full re-lex produces the
+		// same grown inline tokens and the same wrap). The previous frame's
+		// rows live in #fastTail.lines — the L1 #cachedLines was invalidated
+		// by setText, so the fast path cannot read it back. An inert delta
+		// has no "\n", so the frozen prefix cannot advance and the rows above
+		// the spliced span stay byte-identical.
+		if (
+			this.transientRenderCache &&
+			this.#fastTail !== undefined &&
+			contentWidth === this.#fastTail.width &&
+			this.#text.length > this.#fastTail.source.length &&
+			this.#text.startsWith(this.#fastTail.source)
+		) {
+			// Re-probe signature (pure) and require equality — a bgColor/theme
+			// change (width-constant) must not splice rows of the stale recipe.
+			const recipe = this.#fastTail;
+			if (!this.#signatureEquals(signature, recipe.signature)) {
+				this.#fastTail = undefined;
+			} else {
+				const delta = this.#text.slice(recipe.source.length);
+				const deltaTabs = replaceTabs(delta);
+				// Seam window contains the delta, so one URL/email scan catches both.
+				const seamSafe = fastTailSeamSafe(recipe.rowRaw);
+				const seamWindow =
+					recipe.rowRaw.slice(Math.max(recipe.rowRaw.lastIndexOf(" "), recipe.rowRaw.lastIndexOf("\t")) + 1) +
+					deltaTabs;
+				// A paragraph's last line can complete into a different block
+				// kind under an inert delta — disarm (single gate helper, kept
+				// in sync with the exported test surface).
+				const grownLine = recipe.rowRaw.slice(recipe.rowRaw.lastIndexOf("\n") + 1) + deltaTabs;
+				const lineStartHazard = fastLineStartHazard(grownLine);
+				// Only same-line deltas splice; marker deltas re-lex through the
+				// REAL inline pipeline so self-contained pairs render styled.
+				const hardDelta = /[\n\r\x1b]/.test(delta);
+				const markerDelta = FAST_DELTA_RE.test(delta);
+				// A delta starting/ending `_` after a word char pairs in isolation
+				// but stays intraword-literal in the full text. Symmetrically, a
+				// row ending with a closing delimiter (`_`, `*`, `~`) followed by
+				// a word-char delta makes the delimiter intraword / non-flanking in
+				// the joined text — the cold render drops the emphasis, but the
+				// splice keeps it. A row ending `$` (closed inline math) followed
+				// by a digit is invalidated by the anti-currency rule ($x$123 is
+				// literal, not math) — disarm.
+				const grownLastLine = recipe.rowRaw.slice(recipe.rowRaw.lastIndexOf("\n") + 1) + deltaTabs;
+				const trailingDelimiterSeamHazard =
+					(markerDelta &&
+						(deltaTabs.startsWith("_") || deltaTabs.endsWith("_")) &&
+						FAST_UNDERSCORE_WORD_AT_END_RE.test(recipe.rowRaw)) ||
+					(!markerDelta && /[*~_]$/.test(recipe.rowRaw) && FAST_CMARK_WORD_AT_START_RE.test(deltaTabs)) ||
+					(!markerDelta && recipe.rowRaw.endsWith("$") && /^[0-9]/.test(deltaTabs));
+				// A delta opening a pairing char when the captured row ENDS with the
+				// same char can re-pair across the seam: cold lex of the joined run
+				// makes ONE token (x *a**b* → em("a**b")), the splice keeps two.
+				// An image marker (`x!` + `[a](u)`) re-pairs the same way.
+				const pairSeamHazard =
+					markerDelta &&
+					((/^[*~`]/.test(deltaTabs) && /[*~`]$/.test(recipe.rowRaw)) ||
+						// "x!" + "[a](u)": cold lexes text("x") + image(alt); the splice would
+						// keep "x!" + a styled link byte-run.
+						(deltaTabs.startsWith("[") && recipe.rowRaw.endsWith("!")));
+				const deltaTokens = markerDelta && !hardDelta ? lexInlineTokens(deltaTabs) : null;
+				if (
+					seamSafe &&
+					!lineStartHazard &&
+					!hardDelta &&
+					!trailingDelimiterSeamHazard &&
+					// A grown GFM delimiter last line flips a preceding pipe-header
+					// into a table on a marker-free delta (`| --` + `--- | -`).
+					!FAST_TABLE_DELIM_ROW_RE.test(grownLastLine) &&
+					(!markerDelta || (!this.#lastTailCapture?.open && !pairSeamHazard && !inlineHasOpen(deltaTokens!))) &&
+					!FAST_URL_ANYWHERE_RE.test(seamWindow)
+				) {
+					// Same text paths a full re-lex applies: real pipeline for marker
+					// deltas, plain swatch/entity render for inert deltas.
+					const { applyText } = this.#getDefaultInlineStyleContext();
+					const grown =
+						recipe.rowText +
+						(markerDelta
+							? this.#renderInlineTokens(deltaTokens!)
+							: renderTextWithSwatches(
+									normalizeHtmlEntitiesForTerminal(deltaTabs),
+									applyText,
+									this.#theme.symbols.colorSwatch || DEFAULT_COLOR_SWATCH_GLYPH,
+								));
+					const wrapped = wrapTextWithAnsi(grown, contentWidth);
+					const fastPaddingX = this.#ignoreTight ? this.#paddingX : getPaddingX(this.#paddingX);
+					const leftMargin = padding(fastPaddingX);
+					const rightMargin = padding(fastPaddingX);
+					const bgFn = this.#defaultTextStyle?.bgColor;
+					const fastRows: string[] = [];
+					for (const row of wrapped) {
+						const withMargins = leftMargin + row + rightMargin;
+						fastRows.push(
+							bgFn
+								? applyBackgroundToLine(withMargins, width, bgFn)
+								: withMargins + padding(Math.max(0, width - visibleWidth(withMargins))),
+						);
+					}
+					// Splice onto the previous frame's rows (new array — parent may
+					// hold the old one).
+					const prev = recipe.lines;
+					const fastResult = [...prev.slice(0, recipe.rowStart), ...fastRows, ...prev.slice(recipe.rowEnd)];
+					this.#cachedText = this.#text;
+					this.#cachedWidth = width;
+					this.#cachedLines = fastResult;
+					this.#fastTail = {
+						lines: fastResult,
+						source: this.#text,
+						width: recipe.width,
+						rowText: wrapped[wrapped.length - 1] ?? "",
+						rowRaw: recipe.rowRaw + deltaTabs,
+						rowStart: recipe.rowStart + wrapped.length - 1,
+						rowEnd: recipe.rowStart + wrapped.length,
+						signature: recipe.signature,
+					};
+					fastTailSplices++;
+					return fastResult;
+				}
+			}
+			// Hazard → disarm until the next real render re-captures.
+			this.#fastTail = undefined;
+		}
+		// Replace tabs with 3 spaces for consistent rendering
 
 		// L2: module-level LRU — survives component disposal/recreation across
 		// session-tree navigations. Key encodes every dimension that affects the
@@ -1913,6 +2215,37 @@ export class Markdown implements Component {
 		this.#cachedWidth = width;
 		this.#cachedLines = result;
 
+		const fastEligible =
+			this.transientRenderCache &&
+			contentLines.length > 0 &&
+			// B+ invariant: only the FINAL #renderContentLines call captures;
+			// the all-cache-hit prefix path clears #lastTailCapture at its top.
+			this.#lastTailCapture !== undefined &&
+			this.#lastTailCapture.kind === "paragraph" &&
+			// Run-level default styling (color/bold/italic/strikethrough/
+			// underline) disarms: the splice yields two ANSI runs where a cold
+			// render yields one; bgColor is line-level and stays eligible.
+			!this.#defaultTextStyle?.color &&
+			!this.#defaultTextStyle?.bold &&
+			!this.#defaultTextStyle?.italic &&
+			!this.#defaultTextStyle?.strikethrough &&
+			!this.#defaultTextStyle?.underline;
+		if (fastEligible && this.#lastTailCapture !== undefined) {
+			const capture = this.#lastTailCapture;
+			this.#fastTail = {
+				lines: result,
+				source: this.#text,
+				width: contentWidth,
+				rowText: capture.rowInput,
+				rowRaw: capture.rowRaw,
+				rowStart: signature.paddingY + contentLines.length - 1,
+				rowEnd: signature.paddingY + contentLines.length,
+				signature,
+			};
+		} else {
+			this.#fastTail = undefined;
+		}
+
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.
 		if (cacheKey !== undefined) {
@@ -1938,6 +2271,10 @@ export class Markdown implements Component {
 			headingProbe,
 		};
 	}
+	// All-primitive signature — compare via the canonical render-cache encoding.
+	#signatureEquals(a: RenderSignature, b: RenderSignature): boolean {
+		return this.#renderCacheKey("", a) === this.#renderCacheKey("", b);
+	}
 
 	#renderCacheKey(normalizedText: string, signature: RenderSignature): string {
 		return `${normalizedText}\x00${signature.width}\x00${signature.paddingX}\x00${signature.paddingY}\x00${signature.codeBlockIndent}\x00${signature.themeId}\x00${signature.defaultTextStyleId}\x00${signature.imageProtocol}\x00${signature.hyperlinks ? 1 : 0}\x00${signature.textSizing ? 1 : 0}\x00${signature.bgColorProbe}\x00${signature.headingProbe}`;
@@ -2114,6 +2451,9 @@ export class Markdown implements Component {
 		signature: RenderSignature,
 		tailRecorder?: TailRenderRecorder,
 	): string[] {
+		// A non-capturing final call must not serve a stale recipe, so the
+		// B+ plumbing is cleared up front; the per-token capture re-fills it.
+		if (end === tokens.length) this.#lastTailCapture = undefined;
 		const wrappedLines: RenderedLine[] = [];
 		// Wrapped-row span per absolute token index. Call-local: stale values
 		// are never read across renders.
@@ -2141,6 +2481,36 @@ export class Markdown implements Component {
 				}
 			}
 			tokenWrappedRowCounts[i] = wrappedLines.length - tokenWrappedRowStart;
+			// B+ capture hook: the LAST token of the FINAL call is the frame's
+			// true trailing content row — record its rendered last row and raw
+			// tail so render() can build the fast-path recipe. The frozen
+			// prefix call (end < tokens.length) must never capture.
+			if (end === tokens.length && i === end - 1 && token.type === "paragraph") {
+				const raw = "raw" in token && typeof token.raw === "string" ? token.raw : "";
+				const lastLine = renderedTokenLines[renderedTokenLines.length - 1];
+				// Display math, a newline-terminated paragraph (a fresh line
+				// grows next frame — the captured row is not the mutable tail),
+				// or a tree-guide/OSC-8/OSC-66 trailing row are not
+				// self-contained.
+				if (
+					soleDisplayMath(token.tokens) ||
+					raw.endsWith("\n") ||
+					!lastLine ||
+					TREE_GUIDE_ANCHOR_RE.test(lastLine.text) ||
+					lastLine.text.includes("\x1b]") ||
+					TERMINAL.isImageLine(lastLine.text) ||
+					isOsc66Line(lastLine.text)
+				) {
+					continue;
+				}
+				const wrappedLast = wrappedLines[wrappedLines.length - 1];
+				this.#lastTailCapture = {
+					kind: "paragraph",
+					rowInput: wrappedLast?.text ?? lastLine.text,
+					rowRaw: raw.slice(raw.lastIndexOf("\n") + 1),
+					open: inlineHasOpen(token.tokens ?? []),
+				};
+			}
 		}
 
 		const leftMargin = padding(signature.paddingX);

package/src/tui.ts

@@ -2,8 +2,8 @@
  * Minimal TUI implementation with explicit history batches.
  *
  * Two output channels: a product-owned {@link TerminalFrameProvider} returns,
- * per frame, an optional immutable {@link HistoryBatch} (finalized transcript
- * rows appended to native history exactly once, gated by a monotonic id and
+ * per frame, an optional immutable {@link HistoryBatch} (finalized or naturally
+ * emitted stable rows, or one complete replay, gated by a monotonic id and
  * acknowledgement) plus the complete mutable viewport. The writer anchors the
  * viewport directly below whatever history remains visible, diffs
  * viewport-only frames, and never infers finality from a row's position.
@@ -109,13 +109,20 @@ export interface ViewportSize {
 	readonly rows: number;
 }
 
-/** Immutable finalized rows offered until the terminal accepts this identifier. */
+/** Immutable append or complete replay offered until the terminal accepts this identifier. */
 export interface HistoryBatch {
 	readonly id: number;
 	readonly rows: readonly string[];
+	/**
+	 * `append` (the default) adds finalized or naturally emitted rows. `replay`
+	 * is the complete logical ledger; the writer bottom-splits it against the
+	 * leading blank viewport and serializes the remainder plus final viewport in
+	 * one synchronous terminal write.
+	 */
+	readonly kind?: "append" | "replay";
 }
 
-/** One history append and the complete mutable viewport for a terminal frame. */
+/** One history append or complete replay plus the mutable viewport for a terminal frame. */
 export interface TerminalFramePlan {
 	readonly history?: HistoryBatch;
 	readonly viewport: readonly string[];
@@ -128,7 +135,9 @@ export interface TerminalFrameProvider {
 	/** Full semantic viewport used only on the transient resize buffer. */
 	renderResizeFrame?(viewport: ViewportSize): readonly string[];
 	/** Re-offer finalized history after a display reset or resize replay. */
-	resetHistory?(): void;
+	beginHistoryReplay?(): void;
+	/** Force every currently eligible finalized prefix to retire before stop. */
+	beginHistoryFlush?(): void;
 }
 
 export interface TUIStartOptions {
@@ -640,9 +649,50 @@ export class TUI extends Container {
 	#parkedViewportOffset = 0;
 	// In-flight post-resize anchor probe: the stale viewport snapshot and park
 	// offset captured when CSI 6n was written, plus the no-reply fallback timer.
-	#resizeProbe: { window: readonly string[]; offset: number; timer: RenderTimer } | undefined;
-	// Unanswered CSI 6n probes; CPR replies are consumed from input while > 0.
-	#pendingCprReplies = 0;
+	#resizeProbe:
+		| {
+				window: readonly string[];
+				offset: number;
+				timer: RenderTimer;
+				epoch: number;
+				retried: boolean;
+		  }
+		| undefined;
+	// Pre-erase viewport snapshot for the settled resize-anchor probe: the erase
+	// in #beginResizeAltPaint empties #providerWindow, so the probe must bound
+	// the anchor with the window that was actually on screen when the resize
+	// began (see #resolveResizeAnchor's `height - staleRows` clamp).
+	#resizeProbeWindow: readonly string[] = [];
+	#resizeProbeOffset = 0;
+	// Direction tracking for the current coalesced resize burst (reset when a
+	// plan frame commits, alongside #previousHeight). A burst containing any
+	// height grow invalidates the multiplexer clip model in
+	// #resolveResizeAnchor: the grow pulls scrollback into the pane and moves
+	// the parked logical row, so the net shrink no longer telescopes from
+	// pre-burst state.
+	#resizeBurstGrew = false;
+	#resizeBurstLastHeight: number | undefined;
+	// Sum of every grow step in the burst: bounds how much scrollback a
+	// multiplexer can have pulled down across the whole burst, including a
+	// shrink-then-regrow that never exceeds the pre-burst height (see the
+	// CPR-timeout fallback in #resolveResizeAnchor).
+	#resizeBurstPull = 0;
+	// Geometry epoch: bumped on every resize transaction entry, so each CSI 6n
+	// request records the geometry it was parked under.
+	#geometryEpoch = 0;
+	// CPR attribution: each request parks a distinct column (CHA) before its
+	// CSI 6n; the terminal processes requests serially, so every reply carries
+	// its own request's column. That makes attribution exact even when replies
+	// are dropped or arbitrarily delayed — anonymous FIFO counting cannot
+	// survive drops (forgetting retired requests eagerly misattributes late
+	// replies, remembering them forever poisons later probes with phantoms,
+	// and age expiry is unsound because replies carry no lifetime guarantee).
+	// A rewrap can only invalidate a reply's row via a width-change SIGWINCH,
+	// which bumps the geometry epoch and discards the reply anyway, so the
+	// scheme is sound on direct terminals too. Tags are never expired; a late
+	// reply to a dead tag is stripped and discarded by column.
+	#cprColumnTags = new Map<number, number>();
+	#cprProbeSeq = 0;
 	// Prepared rows painted by the previous provider frame, for row diffing.
 	#providerWindow: string[] = [];
 	#previousFrameLength = 0;
@@ -1004,7 +1054,7 @@ export class TUI extends Container {
 				if (this.#resizeProbe) {
 					// The anchor being probed is already stale; restart the transaction.
 					this.#cancelResizeProbe();
-					this.#beginResizeAltPaint();
+					this.#beginResizeAltPaint(true);
 					return;
 				}
 				if (this.#renderScheduler.now() < this.#suppressResizeUntil) {
@@ -1032,12 +1082,23 @@ export class TUI extends Container {
 		}
 		this.requestRender(true, { clearScrollback: options?.clearScrollback === true });
 	}
-	/** Borrow the alternate buffer for stable, history-free resize repainting. */
-	#beginResizeAltPaint(): void {
+	/**
+	 * Borrow the alternate buffer for stable, history-free resize repainting.
+	 * `restartingProbe` marks a transaction restarted by a SIGWINCH that
+	 * arrived while the settled anchor probe was in flight: the live window
+	 * was already stashed and emptied, so the snapshot below must be skipped
+	 * to keep the good stash.
+	 */
+	#beginResizeAltPaint(restartingProbe = false): void {
 		if (this.#altActive) {
 			this.requestRender(true);
 			return;
 		}
+		const burstLastHeight = this.#resizeBurstLastHeight ?? this.#previousHeight;
+		if (this.terminal.rows > burstLastHeight) this.#resizeBurstGrew = true;
+		this.#resizeBurstLastHeight = this.terminal.rows;
+		this.#resizeBurstPull += Math.max(0, this.terminal.rows - burstLastHeight);
+		this.#geometryEpoch++;
 		if (!this.#resizeAltActive) {
 			this.#resizeAltActive = true;
 			setAltScreenActive(true);
@@ -1056,10 +1117,19 @@ export class TUI extends Container {
 			// cursor-relative movement lands on the viewport's top row. On height
 			// shrink kitty clamps the cursor instead of moving it with pushed rows,
 			// so cursor-relative addressing would start rows late; fall back to the
-			// same bottom-preserving bound as resize-anchor recovery. The blank top
-			// row then anchors the settled CPR probe (empty window means staleRows 0).
+			// same bottom-preserving bound as resize-anchor recovery. The pre-erase
+			// window is stashed for the settled CPR probe: its reflowed row count
+			// bounds the anchor to `height - staleRows`, so a mis-parked cursor (a
+			// single-step tmux zoom re-lays the pane before SIGWINCH delivery,
+			// moving the park target under us) cannot anchor the settled repaint
+			// over pulled-back history rows or scroll-push the frame into
+			// scrollback again.
 			let erase = "";
-			if (this.#hasEverRendered && this.#providerWindow.length > 0) {
+			if (!restartingProbe) {
+				this.#resizeProbeWindow = this.#providerWindow;
+				this.#resizeProbeOffset = this.#parkedViewportOffset;
+			}
+			if (this.#hasEverRendered && this.#providerWindow.length > 0 && !isInsideTerminalMultiplexer()) {
 				if (this.terminal.rows < this.#previousHeight) {
 					const staleRows = this.#reflowedRowCount(
 						this.#providerWindow,
@@ -1078,6 +1148,22 @@ export class TUI extends Container {
 					);
 					erase = `\x1b[?25l${up > 0 ? `\x1b[${up}A` : ""}\r\x1b[J`;
 				}
+				// Both erase paths leave the cursor on the viewport's top row, so the
+				// parked offset no longer applies; carrying a stale nonzero offset
+				// into the probe would anchor the settled repaint above the real
+				// viewport top and overwrite visible committed rows.
+				this.#resizeProbeOffset = 0;
+				this.#providerWindow = [];
+				this.#parkedViewportOffset = 0;
+			}
+			if (this.#hasEverRendered && this.#providerWindow.length > 0 && isInsideTerminalMultiplexer()) {
+				// Multiplexers apply the pane re-layout on their own schedule relative
+				// to SIGWINCH delivery, so an immediate erase races it: with the pane
+				// already re-laid the stale coordinates blank pulled-back committed
+				// rows (destroying popped scrollback), and with the pane not yet
+				// re-laid the erase lands on rows about to move. Skip it — the
+				// settled repaint overwrites the live region at the clip-model anchor
+				// and erases below it, race-free after the quiet window.
 				this.#providerWindow = [];
 				this.#parkedViewportOffset = 0;
 			}
@@ -1103,14 +1189,60 @@ export class TUI extends Container {
 	 * trip against the parked cursor reports where the viewport's logical line
 	 * landed. The settled repaint waits for the reply (or a short timeout).
 	 */
-	#beginResizeAnchorProbe(): void {
+	#beginResizeAnchorProbe(retry = false): void {
 		this.#cancelResizeProbe();
 		const timer = this.#renderScheduler.scheduleRender(() => {
+			const probe = this.#resizeProbe;
+			if (probe !== undefined && !probe.retried && (isInsideTerminalMultiplexer() || this.#resizeBurstGrew)) {
+				// A CPR-less resolve is heuristic: a grow's pull span is unknown
+				// on any terminal, and SIGWINCH coalescing can hide intermediate
+				// grows entirely, so even an observed-monotonic multiplexer
+				// shrink cannot be modeled with certainty. A dropped DSR reply
+				// is a transient race — multiplexers in particular answer DSR
+				// themselves — so ask once more before falling back.
+				this.#beginResizeAnchorProbe(true);
+				return;
+			}
 			this.#resolveResizeAnchor(undefined);
 		}, TUI.#RESIZE_PROBE_TIMEOUT_MS);
-		this.#resizeProbe = { window: this.#providerWindow, offset: this.#parkedViewportOffset, timer };
-		this.#pendingCprReplies++;
-		this.terminal.write("\x1b[6n");
+		this.#resizeProbe = {
+			window: this.#resizeProbeWindow,
+			offset: this.#resizeProbeOffset,
+			timer,
+			epoch: this.#geometryEpoch,
+			retried: retry,
+		};
+		// Tags are never expired by age: a reply has no lifetime guarantee, and
+		// freeing a column while its reply may still arrive would let that
+		// reply match a newer tag on the reused column. Dead tags only
+		// accumulate from genuinely dropped replies; a terminal that drops
+		// enough of them to exhaust the span earns the timeout-only fallback.
+		// Park a distinct column for this request so its reply is
+		// self-identifying, then return the cursor to column 1 immediately:
+		// the reply snapshots the column when the terminal processes the CSI
+		// 6n, but a cursor RESTING on a nonzero column would reflow onto a
+		// later visual row if a direct terminal's width later shrank below it,
+		// corrupting the next probe's cursor-relative math. Columns 1-16 are
+		// never used as tags: column 1 cannot be told apart from a spurious or
+		// clamped reply, and modified F3 keys encode as CSI 1;<mod>R with
+		// modifier codes 2-16, which is byte-identical to a CPR for row 1 on
+		// those columns. A column may not be reused while its tag is live —
+		// the old request's delayed reply would be attributed to the new
+		// epoch — so scan for a free slot.
+		const span = Math.min(30, this.terminal.columns - 16);
+		if (span >= 4) {
+			for (let index = 0; index < span; index++) {
+				const candidate = 17 + ((this.#cprProbeSeq + index) % span);
+				if (this.#cprColumnTags.has(candidate)) continue;
+				this.#cprProbeSeq += index + 1;
+				this.#cprColumnTags.set(candidate, this.#geometryEpoch);
+				this.terminal.write(`\x1b[${candidate}G\x1b[6n\x1b[1G`);
+				return;
+			}
+		}
+		// Degenerate span or full occupancy: an untagged reply could never be
+		// attributed, so no DSR is sent at all; the timeout anchors
+		// conservatively on its own.
 	}
 
 	#cancelResizeProbe(): void {
@@ -1121,19 +1253,25 @@ export class TUI extends Container {
 
 	/**
 	 * Anchor the settled post-resize repaint. `reportedRow` is the 0-based CPR
-	 * row of the parked cursor (undefined = probe timed out). The viewport top
-	 * is `min(reported - parkOffset, height - staleRows)`: terminals track the
+	 * row of the parked cursor (undefined = probe timed out). Direct terminals
+	 * use `min(reported - parkOffset, height - staleRows)`: they track the
 	 * cursor exactly through width rewrap, and the second bound reconstructs
-	 * height-shrink scrollback pushes that leave the cursor behind (kitty clamps
-	 * the cursor instead of scrolling it) — bottom-preserving resize guarantees
-	 * the stale viewport ends on the last screen row whenever a push happened.
-	 * Validated against kitty's real core in resize-anchor-recovery.test.ts.
+	 * height-shrink scrollback pushes that leave the cursor behind (kitty
+	 * clamps the cursor instead of scrolling it) — bottom-preserving resize
+	 * guarantees the stale viewport ends on the last screen row whenever a
+	 * push happened; validated against kitty's real core in
+	 * resize-anchor-recovery.test.ts. Multiplexers clip on height changes
+	 * (though they reflow on width changes), so that bound never applies:
+	 * monotonic shrinks use the deterministic clip model below, everything
+	 * else trusts the CPR directly.
 	 */
 	#resolveResizeAnchor(reportedRow: number | undefined): void {
 		const probe = this.#resizeProbe;
 		if (!probe) return;
 		probe.timer.cancel();
 		this.#resizeProbe = undefined;
+		// Column tags stay live across resolves: their replies are
+		// self-identifying and discarded by tag whenever they arrive.
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
 		const staleRows = this.#reflowedRowCount(probe.window, 0, probe.window.length, width);
@@ -1141,7 +1279,58 @@ export class TUI extends Container {
 			reportedRow === undefined
 				? this.#providerViewportTop
 				: reportedRow - this.#reflowedRowCount(probe.window, 0, probe.offset, width);
-		const top = Math.max(0, Math.min(reportedTop, height - staleRows));
+		let top: number;
+		if (isInsideTerminalMultiplexer()) {
+			if (reportedRow !== undefined) {
+				// The parked cursor's reply is exact under multiplexer clipping:
+				// discards leave the cursor in place, pushes only occur after
+				// everything below it is discarded (the bottom row IS the
+				// attached position), and grow pull-down rides it down. It
+				// therefore also reflects intermediate geometries that SIGWINCH
+				// coalescing hid from the burst tracker, and always outranks the
+				// clip model. The `height - staleRows` bound must NOT apply here:
+				// it encodes bottom-preserving rewrap, but a multiplexer shrink
+				// may have discarded stale rows below the cursor instead of
+				// pushing the top ones. Frame-size clamping happens when the
+				// settled plan frame is emitted.
+				top = Math.max(0, reportedTop);
+			} else if (height < this.#previousHeight && !this.#resizeBurstGrew) {
+				// Last resort after the retry: model the clip deterministically
+				// from the saved parked cursor. Rows strictly below the cursor
+				// are discarded first (even non-blank ones — measured against
+				// real tmux), and only the remainder of the shrink pushes top
+				// rows into scrollback; across an observed burst the totals
+				// telescope from pre-burst state. SIGWINCH coalescing can hide a
+				// grow from this model, which is why a reply always wins above.
+				const parkedRow = this.#providerViewportTop + this.#reflowedRowCount(probe.window, 0, probe.offset, width);
+				const shrink = this.#previousHeight - height;
+				const discardedBelow = Math.min(shrink, Math.max(0, this.#previousHeight - 1 - parkedRow));
+				const pushed = Math.max(0, shrink - discardedBelow);
+				top = Math.max(0, this.#providerViewportTop - pushed);
+			} else {
+				// CPR-less grow or reversed burst: the pre-resize top is
+				// stale-low, every grow step already pulled scrollback down.
+				// Anchor at the conservative upper bound — pull never exceeds
+				// the burst's accumulated growth, and pushes/discards only lower
+				// the top. Exact when scrollback covers the pull; when it does
+				// not, the repaint lands below the real viewport and leaves
+				// stale rows above rather than overwriting committed ones.
+				top = Math.max(0, this.#providerViewportTop + this.#resizeBurstPull);
+			}
+		} else {
+			// Direct terminals rewrap bottom-preserving: with `staleRows` stale
+			// rows on screen the viewport top cannot exceed `height - staleRows`
+			// whenever a push happened, so the bound reconstructs height-shrink
+			// pushes that leave the cursor behind (kitty clamps the cursor
+			// instead of scrolling it). A CPR-less grow is stale-low like the
+			// multiplexer case — grow pull-down moved the real viewport — so it
+			// anchors at the accumulated pull bound, still under the clamp.
+			const fallbackTop =
+				reportedRow === undefined && this.#resizeBurstGrew
+					? this.#providerViewportTop + this.#resizeBurstPull
+					: reportedTop;
+			top = Math.max(0, Math.min(fallbackTop, height - staleRows));
+		}
 		if ($flag("PI_DEBUG_REDRAW")) {
 			const msg = `[${new Date().toISOString()}] resize anchor: size=${width}x${height} cpr=${reportedRow ?? "timeout"} park=${probe.offset} stale=${staleRows} old=${this.#providerViewportTop} top=${top}\n`;
 			fs.appendFileSync(getDebugLogPath(), msg);
@@ -1152,14 +1341,17 @@ export class TUI extends Container {
 	}
 
 	/**
-	 * Rows `[start, end)` of a previously painted window re-measured at `width`.
-	 * Direct terminals rewrap on resize (a row spans ceil(cells/width) rows);
-	 * multiplexers clip in place, so every row still spans exactly one row.
+	 * Rows `[start, end)` of a previously painted window re-measured at
+	 * `width`. Every terminal rewraps content on a width change — including
+	 * multiplexers: tmux clips in place on height changes only, and reflows
+	 * the pane (scrollback included) when the width moves, so a row painted
+	 * wider than the current width spans ceil(cells/width) physical rows
+	 * everywhere. For height-only resizes the painted rows already fit the
+	 * width and the count is unchanged.
 	 */
 	#reflowedRowCount(window: readonly string[], start: number, end: number, width: number): number {
 		const stop = Math.min(end, window.length);
 		const from = Math.max(0, start);
-		if (isInsideTerminalMultiplexer()) return Math.max(0, stop - from);
 		let rows = 0;
 		for (let index = from; index < stop; index++) {
 			rows += Math.max(1, Math.ceil(visibleWidth(window[index]!) / Math.max(1, width)));
@@ -1340,6 +1532,28 @@ export class TUI extends Container {
 		this.#paintEndSequence = enabled ? PAINT_END : PAINT_END_NO_SYNC;
 	}
 
+	#flushHistoryBeforeStop(): void {
+		const provider = this.#frameProvider;
+		if (provider?.beginHistoryFlush === undefined) return;
+		const width = this.terminal.columns;
+		const height = this.terminal.rows;
+		if (width <= 0 || height <= 0) return;
+		provider.beginHistoryFlush();
+		while (true) {
+			this.#imageBudget.beginPass();
+			const plan = provider.renderFrame({ columns: width, rows: height });
+			this.#imageBudget.endPass();
+			if (plan.history === undefined) return;
+			let viewport = Array.from(plan.viewport);
+			if (viewport.length > height) viewport = viewport.slice(0, height);
+			const acceptedBefore = this.#acceptedHistoryBatchId;
+			this.#emitPlanFrame(width, height, viewport, plan.history, provider);
+			if (plan.history.id > acceptedBefore && this.#acceptedHistoryBatchId === acceptedBefore) {
+				throw new Error("History flush did not accept the offered batch");
+			}
+		}
+	}
+
 	stop(): void {
 		this.#resizeSettleTimer?.cancel();
 		this.#resizeSettleTimer = undefined;
@@ -1359,6 +1573,12 @@ export class TUI extends Container {
 			this.#altPreviousLines = [];
 			this.#pendingAltExit = "";
 		}
+		// A latched destructive reset (settled rebuild-mode resize, /clear) pairs
+		// ED3 with a complete-ledger replay. Running that pair during stop would
+		// erase native history and re-stream the whole transcript at quit; drop
+		// the latch so the flush below writes only un-retired rows.
+		this.#clearScrollbackOnNextRender = false;
+		this.#flushHistoryBeforeStop();
 		// Deliberately leave transmitted images in the terminal's graphics store:
 		// placeholder cells committed to native scrollback render only while their
 		// image data lives, so a delete-by-id here blanks every transcript image
@@ -1492,7 +1712,7 @@ export class TUI extends Container {
 	}
 	#prepareForcedRender(clearScrollback: boolean): void {
 		if (clearScrollback && !this.#clearScrollbackOnNextRender) {
-			this.#frameProvider?.resetHistory?.();
+			this.#frameProvider?.beginHistoryReplay?.();
 			if (TERMINAL.imageProtocol === ImageProtocol.Kitty) this.#imageBudget.forgetTransmitted();
 		}
 		this.#clearScrollbackOnNextRender ||= clearScrollback;
@@ -1568,12 +1788,39 @@ export class TUI extends Container {
 		// Consume CPR replies (CSI row;col R) while an anchor probe is unanswered;
 		// they are terminal reports, never keystrokes, and must not reach the
 		// focused component.
-		while (this.#pendingCprReplies > 0) {
-			const match = data.match(/\x1b\[(\d+);(\d+)R/);
+		let searchFrom = 0;
+		while (this.#cprColumnTags.size > 0) {
+			const match = data.slice(searchFrom).match(/\x1b\[(\d+);(\d+)R/);
 			if (!match || match.index === undefined) break;
-			this.#pendingCprReplies--;
-			this.#resolveResizeAnchor(Number(match[1]) - 1);
-			data = data.slice(0, match.index) + data.slice(match.index + match[0].length);
+			const row = Number(match[1]);
+			const column = Number(match[2]);
+			if (!this.#cprColumnTags.has(column) && row === 1 && column >= 2) {
+				// CSI 1;<mod>R with no live tag is modified F3: the modifier
+				// parameter spans 2-256 once the lock-state bits (caps 64,
+				// num 128) and hyper/meta are included, so no practical tag
+				// range escapes it entirely. Anything row-1 we did not tag is
+				// treated as a keystroke and left for the focused component;
+				// a tagged column hit by a hyper/meta-modified F3 (params
+				// 17-64, practically unused) is still gated by the epoch check
+				// below.
+				searchFrom += match.index + match[0].length;
+				continue;
+			}
+			if (this.#cprColumnTags.has(column)) {
+				// Column-tagged reply: exact attribution. Resolve only when its
+				// request was parked under the active probe's geometry; a reply
+				// from an older epoch is stale and discarded.
+				const tagEpoch = this.#cprColumnTags.get(column);
+				this.#cprColumnTags.delete(column);
+				const probe = this.#resizeProbe;
+				if (probe !== undefined && tagEpoch === probe.epoch) {
+					this.#resolveResizeAnchor(Number(match[1]) - 1);
+				}
+			}
+			// Other unknown-column replies while expecting tagged ones are our
+			// requests answered with a clamped or mangled column: strip and
+			// discard; the probe timeout covers recovery.
+			data = data.slice(0, searchFrom + match.index) + data.slice(searchFrom + match.index + match[0].length);
 		}
 		if (data.length === 0) return;
 		// Ctrl+C/Esc use app-level double-press windows. Give those gestures one
@@ -1983,7 +2230,7 @@ export class TUI extends Container {
 			return;
 		}
 		const provider = this.#frameProvider;
-		if (!provider?.resetHistory) return;
+		if (!provider?.beginHistoryReplay) return;
 		this.#resizeReplaySize = size;
 		if (this.#clearScrollbackOnNextRender) {
 			this.#forceViewportRepaintOnNextRender = true;
@@ -1993,15 +2240,14 @@ export class TUI extends Container {
 			this.#prepareForcedRender(true);
 			return;
 		}
-		provider.resetHistory();
+		provider.beginHistoryReplay();
 		this.#forceViewportRepaintOnNextRender = true;
 	}
 
 	/**
-	 * Physical write transaction: append an unacknowledged history batch above
-	 * the anchored mutable viewport, repaint the viewport, and erase stale rows
-	 * below. Appending K rows scrolls at most K rows off the top — the oldest
-	 * visible history — and the viewport anchor follows the retained history.
+	 * Physical write transaction: append an ordinary batch, or bottom-split one
+	 * complete replay into a history remainder and final viewport, then serialize
+	 * the whole result in one terminal write before acknowledgement.
 	 */
 	#emitPlanFrame(
 		width: number,
@@ -2015,11 +2261,28 @@ export class TUI extends Container {
 			while (viewport.length < height) viewport.push("");
 			viewport = this.#compositeOverlaysIntoWindow(viewport, width, height);
 		}
-		const markers = this.#extractCursorMarkers(viewport);
-		const prepared = this.#prepareLinesArray(viewport, width);
 		const history = offered !== undefined && offered.id > this.#acceptedHistoryBatchId ? offered : undefined;
 		if (offered !== undefined && offered.id <= this.#acceptedHistoryBatchId) provider?.acknowledgeHistory(offered.id);
-		const historyRows = history?.rows ?? [];
+
+		let historyRows = history?.rows ?? [];
+		let replayViewportRows = 0;
+		if (history?.kind === "replay") {
+			// Providers may omit unused leading rows from a short viewport. Make
+			// that logical space explicit before the bottom-first replay split.
+			while (viewport.length < height) viewport.unshift("");
+			let leadingBlankRows = 0;
+			while (leadingBlankRows < viewport.length && !/\S/.test(viewport[leadingBlankRows]!)) {
+				leadingBlankRows++;
+			}
+			const moved = Math.min(historyRows.length, leadingBlankRows);
+			if (moved > 0) {
+				viewport = [...historyRows.slice(historyRows.length - moved), ...viewport.slice(moved)];
+				historyRows = historyRows.slice(0, historyRows.length - moved);
+				replayViewportRows = moved;
+			}
+		}
+		const markers = this.#extractCursorMarkers(viewport);
+		const prepared = this.#prepareLinesArray(viewport, width);
 		const preparedHistory = this.#prepareLinesArray(historyRows, width);
 		const rows = prepared.length;
 		// Destructive reset (session replace, /tree, explicit clear, or a settled
@@ -2051,7 +2314,14 @@ export class TUI extends Container {
 		} else {
 			this.#imageBudget.takePurgeIds();
 		}
-		if (destructiveReset) buffer += "\x1b[H\x1b[3J\x1b[2J";
+		// ED2 MUST precede ED3: tmux implements ED2 by scrolling the live screen
+		// into pane history (so cleared content stays reachable), so erasing
+		// history first would let ED2 refill it with a copy of the old screen —
+		// which the replay then repaints, duplicating one full frame per reset.
+		// ED2-then-ED3 clears the screen, then wipes history including that
+		// push. On xterm-family terminals the two erases are independent and
+		// the order is irrelevant.
+		if (destructiveReset) buffer += "\x1b[H\x1b[2J\x1b[3J";
 		const diffable =
 			geometryStable &&
 			historyRows.length === 0 &&
@@ -2112,6 +2382,8 @@ export class TUI extends Container {
 			}
 			if (newTop + rows < height) buffer += `\x1b[${newTop + rows + 1};1H\x1b[J`;
 		}
+		const mutableTop = newTop + replayViewportRows;
+		const mutablePrepared = replayViewportRows > 0 ? prepared.slice(replayViewportRows) : prepared;
 		const marker = markers[0];
 		const target =
 			marker !== undefined && rows > 0
@@ -2119,23 +2391,26 @@ export class TUI extends Container {
 				: null;
 		if (target) {
 			buffer += `\x1b[${target.row + 1};${target.col + 1}H${target.visible ? "\x1b[?25h" : "\x1b[?25l"}`;
-			this.#parkedViewportOffset = Math.max(0, target.row - newTop);
+			this.#parkedViewportOffset = Math.max(0, target.row - mutableTop);
 		} else {
 			// Park the hidden cursor on the viewport's top row: terminals keep the
 			// cursor attached to its logical line through resize reflow, so the
 			// post-resize anchor probe can recover where the viewport landed.
-			buffer += `\x1b[?25l\x1b[${newTop + 1};1H`;
+			buffer += `\x1b[?25l\x1b[${mutableTop + 1};1H`;
 			this.#parkedViewportOffset = 0;
 		}
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 		if (target) this.#recordHardwareCursorState(target);
 		else this.#recordHardwareCursorHidden();
-		this.#providerWindow = prepared;
-		this.#providerViewportTop = newTop;
+		this.#providerWindow = mutablePrepared;
+		this.#providerViewportTop = mutableTop;
 		this.#previousWidth = width;
 		this.#previousHeight = height;
-		this.#previousFrameLength = rows;
+		this.#resizeBurstGrew = false;
+		this.#resizeBurstLastHeight = undefined;
+		this.#resizeBurstPull = 0;
+		this.#previousFrameLength = mutablePrepared.length;
 		this.#clearScrollbackOnNextRender = false;
 		this.#forceViewportRepaintOnNextRender = false;
 		this.#hasEverRendered = true;
@@ -2143,10 +2418,9 @@ export class TUI extends Container {
 		if (history !== undefined) {
 			this.#acceptedHistoryBatchId = history.id;
 			provider?.acknowledgeHistory(history.id);
-			// Draining is one batch per frame; the provider may hold further
-			// finalized prefixes (large resumed transcripts). Pump the next frame
-			// instead of waiting for an unrelated render request.
-			this.requestRender();
+			// Normal retirement may hold another ordered batch. Replay is always
+			// complete, so pumping it would create a second visible redraw/write.
+			if (history.kind !== "replay") this.requestRender();
 		}
 	}