silvery 0.19.1 → 0.21.0

package/dist/{render-string-X-CxpTdZ.mjs → render-string-DkQacASz.mjs}

@@ -1,16 +1,18 @@
-import { c as signal, i as syncRectSignals, o as computed, t as rectEqual } from "./types-Bk2yw9Qj.mjs";
+import { i as __require } from "./chunk-BSw8zbkd.mjs";
+import { i as signal, n as computed } from "./src-DKp-_OFG.mjs";
 import { c as StdoutContext, l as TermContext, s as StderrContext } from "./context-BU5LkkIy.mjs";
-import { At as bufferToText, Dt as TerminalBuffer, Et as DEFAULT_BG, Ft as createTextFrame, H as ensureEmojiPresentation, I as canBreakAnywhere, It as init_buffer, K as graphemeWidth, Lt as isDefaultBg, Ot as ansi256ToRgb, Pt as createMutableCell, U as getActiveLineHeight, V as displayWidthAnsi, Z as isLikelyEmoji, _t as wrapText, a as hostConfig, at as parseAnsiText, b as createTerm, c as clearDirtyTracking, d as collectPlainText, et as isWordBoundary, f as advanceRenderEpoch, ft as splitGraphemes, g as isDirty, h as isCurrentEpoch, kt as bufferToStyledText, l as hasScrollDirty, lt as sliceByWidth, m as isAnyDirty, ot as runWithMeasurer, p as getRenderEpoch, pt as splitGraphemesAnsiAware, q as hasAnsi, r as getContainerRoot, t as createContainer, u as measureStats, ut as sliceByWidthFromEnd } from "./reconciler-Cwgm8hRR.mjs";
-import { A as backdropPlacementId, F as kittyUploadScrimImage, M as cupTo, N as kittyDeleteAllScrimPlacements, P as kittyPlaceAt, j as buildScrimPixels, k as resolveThemeColor, t as init_src, w as monoAttrsForColorString } from "./src-NCKb8kE5.mjs";
-import { i as isLayoutEngineInitialized, r as getLayoutEngine } from "./layout-engine-ClUgv6jB.mjs";
-import { x as ansi16DarkTheme } from "./src-B5GjfG7g.mjs";
+import { a as hasObservedLayoutSignal, c as syncDecorationRects, i as hasLayoutSignals, m as rectEqual, u as syncRectSignals } from "./layout-signals-Cnw6xk8Q.mjs";
+import { _ as isAnyDirty, b as clearDirtyTracking, g as getRenderEpoch, h as advanceRenderEpoch, l as measureStats, o as hostConfig, r as getContainerRoot, t as createContainer, u as collectPlainText, v as isCurrentEpoch, x as hasScrollDirty, y as isDirty } from "./reconciler-DldIJB93.mjs";
+import { _ as cupTo, b as kittyUploadScrimImage, d as monoAttrsForColorString, g as buildScrimPixels, h as backdropPlacementId, m as resolveThemeColor, t as init_src, v as kittyDeleteAllScrimPlacements, y as kittyPlaceAt } from "./src-BNTToU7l.mjs";
+import { t as ansi16DarkTheme } from "./schemes-JjNp4aSl.mjs";
+import { $ as splitGraphemesAnsiAware, A as getActiveLineHeight, Ct as init_buffer, H as isWordBoundary, J as runWithMeasurer, N as graphemeWidth, O as displayWidthAnsi, P as hasAnsi, Q as splitGraphemes, R as isLikelyEmoji, St as createTextFrame, X as sliceByWidthFromEnd, Y as sliceByWidth, _t as bufferToText, gt as bufferToStyledText, ht as ansi256ToRgb, k as ensureEmojiPresentation, mt as TerminalBuffer, n as createTerm, pt as DEFAULT_BG, q as parseAnsiText, rt as wrapText, w as canBreakAnywhere, wt as isDefaultBg, xt as createMutableCell, z as isSoftBreakPoint } from "./ansi-yC4RyBNY.mjs";
+import { t as init_src$1 } from "./src-5w9QR6_8.mjs";
+import { i as isLayoutEngineInitialized, r as getLayoutEngine } from "./layout-engine-C2px0RJE.mjs";
 import React, { act } from "react";
+import { hexToOklch, mixSrgb, oklchToHex, relativeLuminance } from "@silvery/color";
 import { createLogger } from "loggily";
-import * as Upstream from "@silvery/color";
-import { relativeLuminance } from "@silvery/color";
 import Reconciler from "react-reconciler";
 //#region packages/ag-term/src/pipeline/prepared-text.ts
-init_buffer();
 const MAX_FORMAT_ENTRIES = 4;
 /** Content-affecting flags that invalidate plain text. */
 const PLAIN_TEXT_DIRTY = 9;
@@ -217,6 +219,11 @@ function buildTextAnalysis(text, gWidthFn = graphemeWidth) {
 			breakIndices.push(i);
 			maxWordWidth = Math.max(maxWordWidth, currentWordWidth);
 			currentWordWidth = w;
+		} else if (isSoftBreakPoint(g) && i + 1 < len) {
+			currentWordWidth += w;
+			breakIndices.push(i + 1);
+			maxWordWidth = Math.max(maxWordWidth, currentWordWidth);
+			currentWordWidth = 0;
 		} else if (w > 0) currentWordWidth += w;
 	}
 	maxWordWidth = Math.max(maxWordWidth, currentWordWidth);
@@ -277,11 +284,23 @@ function shrinkwrapWidth(analysis, maxWidth) {
 * around forced breaks. Falls back to greedy wrapping for paragraphs
 * where the DP finds no feasible solution (overlong words).
 *
-* O(breakpoints²) per paragraph, typically much less with pruning.
+* `width` accepts either a constant number (uniform width — fast path)
+* or a `WidthFn(lineIndex)` for per-line widths. Per-line uses a
+* forward DP that tracks line index in state.
+*
+* Pass `opts.maxLines` to cap the wrap to ≤ N lines (a 2D DP over
+* candidates × lines-used). When infeasible the function returns `[]`
+* and the caller (`optimalWrap`) is responsible for the truncation
+* fallback.
+*
+* O(breakpoints²) for the constant-width unbounded case;
+* O(breakpoints² × maxLines) for per-line or when `maxLines` is set.
+* All variants are negligible for terminal-scale text.
 */
-function knuthPlassBreaks(analysis, width) {
-	if (width <= 0) return [];
-	if (analysis.totalWidth <= width && analysis.newlineIndices.length === 0) return [];
+function knuthPlassBreaks(analysis, width, opts) {
+	const w0 = typeof width === "function" ? width(0) : width;
+	if (w0 <= 0) return [];
+	if (analysis.totalWidth <= w0 && analysis.newlineIndices.length === 0) return [];
 	const { newlineIndices, graphemes } = analysis;
 	const allBreaks = [];
 	const paragraphStarts = [0];
@@ -290,14 +309,84 @@ function knuthPlassBreaks(analysis, width) {
 		const pStart = paragraphStarts[p];
 		const pEnd = p + 1 < paragraphStarts.length ? paragraphStarts[p + 1] - 1 : graphemes.length;
 		if (pStart >= pEnd) continue;
-		const breaks = knuthPlassForParagraph(analysis, pStart, pEnd, width);
+		const breaks = typeof width === "function" ? knuthPlassForParagraphPerLine(analysis, pStart, pEnd, width, opts) : knuthPlassForParagraph(analysis, pStart, pEnd, width, opts);
 		allBreaks.push(...breaks);
 		if (p < paragraphStarts.length - 1 && pEnd < graphemes.length) allBreaks.push(pEnd + 1);
 	}
 	return allBreaks;
 }
-/** DP for a single paragraph (no newlines). */
-function knuthPlassForParagraph(analysis, pStart, pEnd, width) {
+/**
+* Minimum visible-character count for a non-final line before the
+* orphan penalty kicks in. A "token" here is loosely "the visible width
+* of the line"; the penalty is tuned for terminal card widths (≈20-40
+* cols), where any line under 8 cols is visually a stranded fragment.
+*/
+const ORPHAN_MIN_WIDTH = 8;
+/** Penalty (added to leftover²) for a non-final line below ORPHAN_MIN_WIDTH. */
+const ORPHAN_PENALTY = 500;
+/**
+* Threshold for a hyphenated compound to count as "short" on either side.
+* Breaking inside `cmd-hover` (3-5 split) or `auto-` (4 chars left, 9
+* chars right of the hyphen) reads worse than letting the compound
+* stay intact. Penalty is gentler than the orphan penalty because
+* breaking after a hyphen IS sometimes the right call (long compounds,
+* narrow widths).
+*/
+const HYPHEN_COMPOUND_MIN_SIDE = 5;
+/** Penalty (added to leftover²) for a break inside a short hyphenated compound. */
+const HYPHEN_COMPOUND_PENALTY = 250;
+/**
+* Score the *quality* of a non-final wrapped line.
+*
+* Knuth-Plass's classic cost (leftover²) gives the line layout a global
+* raggedness optimum but doesn't know about typographical taboos —
+* single-word "hover" lines, breaks inside short hyphenated compounds
+* like `cmd-hover`, etc. The penalty is added to the squared-leftover
+* cost and tuned so it dominates *only* when the alternative is visually
+* better; if the alternative has worse raggedness, the leftover²
+* differential will still pick the better wrap.
+*
+* Parameters:
+* - `lineStart` — grapheme index where the line begins (a break candidate)
+* - `lineEnd`   — grapheme index where the next line begins (a break candidate)
+* - `trimEnd`   — `lineEnd` after trailing whitespace/ANSI trim (= visible end)
+*/
+function wrapQualityPenalty(analysis, lineStart, lineEnd, trimEnd) {
+	let penalty = 0;
+	const { cumWidths, graphemes } = analysis;
+	if (cumWidths[trimEnd] - cumWidths[lineStart] < ORPHAN_MIN_WIDTH) penalty += ORPHAN_PENALTY;
+	if (lineEnd > 0 && graphemes[lineEnd - 1] === "-") {
+		let leftLen = 0;
+		for (let k = lineEnd - 2; k >= 0; k--) {
+			const g = graphemes[k];
+			if (g === " " || g === "	" || g === "-" || g === "\n") break;
+			leftLen++;
+			if (leftLen >= HYPHEN_COMPOUND_MIN_SIDE) break;
+		}
+		let rightLen = 0;
+		for (let k = lineEnd; k < graphemes.length; k++) {
+			const g = graphemes[k];
+			if (g === " " || g === "	" || g === "-" || g === "\n") break;
+			rightLen++;
+			if (rightLen >= HYPHEN_COMPOUND_MIN_SIDE) break;
+		}
+		if (leftLen < HYPHEN_COMPOUND_MIN_SIDE || rightLen < HYPHEN_COMPOUND_MIN_SIDE) penalty += HYPHEN_COMPOUND_PENALTY;
+	}
+	return penalty;
+}
+/**
+* DP for a single paragraph (no newlines). Constant-width.
+*
+* Without `opts.maxLines`: backward 1D DP, `cost[i]` = min cost to reach
+* the end starting at candidate `i`. Final answer = `cost[0]`.
+*
+* With `opts.maxLines`: forward 2D DP, `f[i][k]` = min cost to reach
+* candidate `i` after consuming exactly `k` lines. See
+* `knuthPlassForParagraph2D` below — same shape as the per-line variant
+* but with a constant `width` for every line.
+*/
+function knuthPlassForParagraph(analysis, pStart, pEnd, width, opts) {
+	if (opts?.maxLines !== void 0) return knuthPlassForParagraph2D(analysis, pStart, pEnd, () => width, opts.maxLines);
 	const { cumWidths, breakIndices, widths, graphemes } = analysis;
 	const candidates = [pStart];
 	for (const bp of breakIndices) if (bp > pStart && bp <= pEnd) candidates.push(bp);
@@ -311,7 +400,8 @@ function knuthPlassForParagraph(analysis, pStart, pEnd, width) {
 		const lineStart = candidates[i];
 		const lineStartCum = cumWidths[lineStart];
 		for (let j = i + 1; j < n; j++) {
-			let trimEnd = candidates[j];
+			const lineEnd = candidates[j];
+			let trimEnd = lineEnd;
 			while (trimEnd > lineStart) {
 				const prevG = graphemes[trimEnd - 1];
 				if (widths[trimEnd - 1] === 0) {
@@ -327,7 +417,10 @@ function knuthPlassForParagraph(analysis, pStart, pEnd, width) {
 			const lineWidth = cumWidths[trimEnd] - lineStartCum;
 			if (lineWidth > width) break;
 			const leftover = width - lineWidth;
-			const totalCost = (j === n - 1 ? 0 : leftover * leftover) + cost[j];
+			const isLastLine = j === n - 1;
+			let lineCost = isLastLine ? 0 : leftover * leftover;
+			if (!isLastLine) lineCost += wrapQualityPenalty(analysis, lineStart, lineEnd, trimEnd);
+			const totalCost = lineCost + cost[j];
 			if (totalCost < cost[i]) {
 				cost[i] = totalCost;
 				next[i] = j;
@@ -344,23 +437,216 @@ function knuthPlassForParagraph(analysis, pStart, pEnd, width) {
 	return breaks;
 }
 /**
+* DP for a single paragraph (no newlines), per-line width.
+*
+* Forward DP — `f[i]` is the min cost to reach candidate i with `line[i]`
+* tracking the line index of position i in the optimal path. Each segment
+* (j → i) is on line `line[j]`, so its allowed width is `widthFn(line[j])`.
+*
+* O(n² × m) where m is max meaningful line index. For titles n is small
+* (~30 candidates, ~5 lines) so this is trivial. The constant-width path
+* above stays as the fast path for callers that don't need per-line.
+*
+* Dispatches to the 2D variant when `opts.maxLines` is set — needed because
+* the optimal path through candidate `i` for line-count `k` may differ from
+* the path for `k+1`, so the single-state `line[]` shortcut is unsafe under
+* a hard line cap.
+*/
+function knuthPlassForParagraphPerLine(analysis, pStart, pEnd, widthFn, opts) {
+	if (opts?.maxLines !== void 0) return knuthPlassForParagraph2D(analysis, pStart, pEnd, widthFn, opts.maxLines);
+	const { cumWidths, breakIndices, widths, graphemes } = analysis;
+	const candidates = [pStart];
+	for (const bp of breakIndices) if (bp > pStart && bp <= pEnd) candidates.push(bp);
+	candidates.push(pEnd);
+	const n = candidates.length;
+	if (n <= 2) return [];
+	const f = new Array(n).fill(Infinity);
+	const from = new Array(n).fill(-1);
+	const line = new Array(n).fill(0);
+	f[0] = 0;
+	for (let i = 1; i < n; i++) {
+		const lineEnd = candidates[i];
+		let trimEnd = lineEnd;
+		while (trimEnd > 0) {
+			const prevG = graphemes[trimEnd - 1];
+			if (widths[trimEnd - 1] === 0) {
+				trimEnd--;
+				continue;
+			}
+			if (prevG === " " || prevG === "	") {
+				trimEnd--;
+				continue;
+			}
+			break;
+		}
+		const trimEndCum = cumWidths[trimEnd];
+		for (let j = 0; j < i; j++) {
+			if (f[j] === Infinity) continue;
+			const lineStart = candidates[j];
+			const lineWidth = trimEndCum - cumWidths[lineStart];
+			const segLineIndex = line[j];
+			const allowedWidth = widthFn(segLineIndex);
+			if (lineWidth > allowedWidth) continue;
+			const leftover = allowedWidth - lineWidth;
+			const isLastLine = i === n - 1;
+			let lineCost = isLastLine ? 0 : leftover * leftover;
+			if (!isLastLine) lineCost += wrapQualityPenalty(analysis, lineStart, lineEnd, trimEnd);
+			const totalCost = f[j] + lineCost;
+			if (totalCost < f[i]) {
+				f[i] = totalCost;
+				from[i] = j;
+				line[i] = segLineIndex + 1;
+			}
+		}
+	}
+	if (f[n - 1] === Infinity) return [];
+	const breaks = [];
+	let idx = n - 1;
+	while (from[idx] > 0) {
+		idx = from[idx];
+		breaks.push(candidates[idx]);
+	}
+	breaks.reverse();
+	return breaks;
+}
+/**
+* DP for a single paragraph with a hard line-budget cap.
+*
+* Forward 2D DP — `f[i][k]` = min cost to reach candidate `i` using
+* exactly `k` lines. Transition:
+*
+*   f[i][k+1] = min over j<i of (f[j][k] + lineCost(j → i, line k))
+*
+* The line index `k` is consumed by the (j → i) segment, so its allowed
+* width is `widthFn(k)`. Final answer = `argmin_{k <= maxLines} f[n-1][k]`,
+* with `cost = 0` on the last line (no raggedness penalty on the final
+* line, matching the 1D contracts above).
+*
+* Returns `[]` when no path fits within `maxLines` lines (infeasibility
+* signal — `optimalWrap` falls back to truncation).
+*
+* Complexity: O(n² × maxLines). For terminal titles n ≈ 30 candidates and
+* maxLines ≈ 4-6, so ≤ 5400 ops per paragraph — negligible. Memory: one
+* 2D Float64Array sized `n × (maxLines + 1)`.
+*
+* Tracking: @km/silvery/15130-pretext-maxlines-aware.
+*/
+function knuthPlassForParagraph2D(analysis, pStart, pEnd, widthFn, maxLines) {
+	if (maxLines <= 0) return [];
+	const { cumWidths, breakIndices, widths, graphemes } = analysis;
+	const candidates = [pStart];
+	for (const bp of breakIndices) if (bp > pStart && bp <= pEnd) candidates.push(bp);
+	candidates.push(pEnd);
+	const n = candidates.length;
+	if (n <= 2) return [];
+	const K = maxLines + 1;
+	const f = new Float64Array(n * K).fill(Infinity);
+	const from = new Int32Array(n * K).fill(-1);
+	f[0] = 0;
+	const trimEnds = new Array(n);
+	for (let i = 0; i < n; i++) {
+		let trimEnd = candidates[i];
+		while (trimEnd > 0) {
+			const prevG = graphemes[trimEnd - 1];
+			if (widths[trimEnd - 1] === 0) {
+				trimEnd--;
+				continue;
+			}
+			if (prevG === " " || prevG === "	") {
+				trimEnd--;
+				continue;
+			}
+			break;
+		}
+		trimEnds[i] = trimEnd;
+	}
+	for (let j = 0; j < n - 1; j++) {
+		const lineStart = candidates[j];
+		const lineStartCum = cumWidths[lineStart];
+		for (let k = 0; k < maxLines; k++) {
+			const fjk = f[j * K + k];
+			if (fjk === Infinity) continue;
+			const allowedWidth = widthFn(k);
+			if (allowedWidth <= 0) continue;
+			for (let i = j + 1; i < n; i++) {
+				const lineEnd = candidates[i];
+				const trimEnd = trimEnds[i];
+				const lineWidth = cumWidths[trimEnd] - lineStartCum;
+				if (lineWidth > allowedWidth) continue;
+				const leftover = allowedWidth - lineWidth;
+				const isLastLine = i === n - 1;
+				let lineCost = isLastLine ? 0 : leftover * leftover;
+				if (!isLastLine) lineCost += wrapQualityPenalty(analysis, lineStart, lineEnd, trimEnd);
+				const total = fjk + lineCost;
+				const target = i * K + (k + 1);
+				if (total < f[target]) {
+					f[target] = total;
+					from[target] = j;
+				}
+			}
+		}
+	}
+	let bestK = -1;
+	let bestCost = Infinity;
+	for (let k = 1; k <= maxLines; k++) {
+		const c = f[(n - 1) * K + k];
+		if (c < bestCost) {
+			bestCost = c;
+			bestK = k;
+		}
+	}
+	if (bestK === -1 || bestCost === Infinity) return [];
+	const breaks = [];
+	let curI = n - 1;
+	let curK = bestK;
+	while (curK > 0) {
+		const prev = from[curI * K + curK];
+		if (prev < 0) break;
+		if (prev > 0) breaks.push(candidates[prev]);
+		curI = prev;
+		curK = curK - 1;
+	}
+	breaks.reverse();
+	return breaks;
+}
+/**
 * Wrap text using Knuth-Plass optimal breaks.
 * Returns line strings — drop-in replacement for greedy wrap.
 * Falls back to greedy wrapText when DP finds no feasible solution.
+*
+* `width` accepts a constant `number` (uniform width) OR a `WidthFn(lineIndex)`
+* for per-line widths (e.g. line 0 narrowed by a top-right pill, lines 1+
+* full width — CSS-float-equivalent layouts).
+*
+* `opts.maxLines` caps the wrap to ≤ N lines. When the DP can't fit the
+* text in that budget, falls back to a greedy wrap clipped to `maxLines`
+* with the final visible line truncated (head trimmed at a grapheme
+* boundary so `head + truncationSuffix` fits within the budget). Default
+* suffix is `"…"`.
+*
+* Tracking: @km/silvery/15130-pretext-maxlines-aware.
 */
-function optimalWrap(text, analysis, width) {
-	const breaks = knuthPlassBreaks(analysis, width);
+function optimalWrap(text, analysis, width, opts) {
+	const maxLines = opts?.maxLines;
+	const truncationSuffix = opts?.truncationSuffix ?? "…";
+	const breaks = knuthPlassBreaks(analysis, width, maxLines !== void 0 ? { maxLines } : void 0);
+	const fallbackWidth = typeof width === "function" ? width(0) : width;
 	if (breaks.length === 0) {
-		if (analysis.totalWidth <= width && analysis.newlineIndices.length === 0) return [text];
-		return wrapText(text, width, true, true);
+		if (analysis.totalWidth <= fallbackWidth && analysis.newlineIndices.length === 0) return [text];
+		const greedy = wrapText(text, fallbackWidth, true, true);
+		if (maxLines !== void 0 && greedy.length > maxLines) return clampToMaxLines(greedy, maxLines, fallbackWidth, truncationSuffix);
+		return greedy;
 	}
 	const { graphemes, widths } = analysis;
 	const lines = [];
 	let lineStart = 0;
+	let pendingAnsiPrefix = "";
 	for (const bp of breaks) {
 		let lineEnd = bp;
+		let trailingAnsi = "";
 		while (lineEnd > lineStart) {
 			if (widths[lineEnd - 1] === 0) {
+				trailingAnsi = graphemes[lineEnd - 1] + trailingAnsi;
 				lineEnd--;
 				continue;
 			}
@@ -371,20 +657,82 @@ function optimalWrap(text, analysis, width) {
 			}
 			break;
 		}
-		lines.push(graphemes.slice(lineStart, lineEnd).join(""));
+		lines.push(pendingAnsiPrefix + graphemes.slice(lineStart, lineEnd).join("") + trailingAnsi);
+		pendingAnsiPrefix = "";
 		lineStart = bp;
 		while (lineStart < graphemes.length) {
 			const g = graphemes[lineStart];
+			const w = widths[lineStart];
 			if (g === " " || g === "	") {
 				lineStart++;
 				continue;
 			}
+			if (w === 0) {
+				pendingAnsiPrefix += g;
+				lineStart++;
+				continue;
+			}
 			break;
 		}
 	}
-	if (lineStart < graphemes.length) lines.push(graphemes.slice(lineStart).join(""));
+	if (lineStart < graphemes.length) lines.push(pendingAnsiPrefix + graphemes.slice(lineStart).join(""));
+	else if (pendingAnsiPrefix !== "") {
+		if (lines.length > 0) lines[lines.length - 1] = lines[lines.length - 1] + pendingAnsiPrefix;
+	}
+	if (maxLines !== void 0 && lines.length > maxLines) return clampToMaxLines(lines, maxLines, fallbackWidth, truncationSuffix);
 	return lines;
 }
+/**
+* Clamp a wrapped output to `maxLines` rows. The final visible line is
+* truncated so that `head + suffix` fits within `width`; the head is cut
+* at a grapheme-aware boundary (using `splitGraphemesAnsiAware` to keep
+* ANSI tokens intact).
+*
+* Used by `optimalWrap` when the DP cannot satisfy `opts.maxLines` and
+* falls back to greedy + truncate, AND as a defensive net at the end of
+* `optimalWrap` (the DP already enforces the cap by construction).
+*
+* Tracking: @km/silvery/15130-pretext-maxlines-aware.
+*/
+function clampToMaxLines(lines, maxLines, width, suffix) {
+	if (lines.length <= maxLines) return lines;
+	if (maxLines <= 0) return [];
+	const kept = lines.slice(0, maxLines);
+	const lastIdx = maxLines - 1;
+	const last = kept[lastIdx];
+	kept[lastIdx] = appendTruncationSuffix(last, width, suffix);
+	return kept;
+}
+/**
+* Append `suffix` to `line`, trimming graphemes off the visible end if
+* needed so that `displayLength(line + suffix) <= width`. ANSI tokens
+* (zero-width) are preserved across the truncation boundary so styling
+* state isn't dropped.
+*
+* If `suffix` itself is wider than `width`, returns just the suffix
+* (truncated to width via the same grapheme walk). Callers using a
+* pathological width should size-check on their side.
+*/
+function appendTruncationSuffix(line, width, suffix) {
+	if (width <= 0) return "";
+	const suffixWidth = splitGraphemesAnsiAware(suffix).reduce((acc, g) => acc + graphemeWidth(g), 0);
+	const lineGraphemes = splitGraphemesAnsiAware(line);
+	if (lineGraphemes.reduce((acc, g) => acc + graphemeWidth(g), 0) + suffixWidth <= width) return line + suffix;
+	const budget = Math.max(0, width - suffixWidth);
+	let acc = 0;
+	let cutoff = 0;
+	for (let i = 0; i < lineGraphemes.length; i++) {
+		const g = lineGraphemes[i];
+		const w = graphemeWidth(g);
+		if (acc + w > budget) break;
+		acc += w;
+		cutoff = i + 1;
+	}
+	let tail = "";
+	for (let i = cutoff; i < lineGraphemes.length; i++) if (graphemeWidth(lineGraphemes[i]) === 0) tail += lineGraphemes[i];
+	else break;
+	return lineGraphemes.slice(0, cutoff).join("") + tail + suffix;
+}
 //#endregion
 //#region packages/ag-term/src/pipeline/helpers.ts
 /**
@@ -418,6 +766,363 @@ function getBorderSize(props) {
 	};
 }
 //#endregion
+//#region packages/ag-term/src/runtime/pass-cause.ts
+/**
+* pass-cause.ts — Renderer feedback-edge instrumentation, loggily-native.
+*
+* Captures the cause of each render/layout pass beyond pass 1. The convergence
+* loop in `renderer.ts` (singlePassLayout / classic) and `create-app.tsx`
+* (processEventBatch flush loop) iterate until `hadReactCommit` is false. Each
+* extra pass is a "feedback edge": some computation in pass N caused React
+* state to change, which forces pass N+1.
+*
+* This module attributes each extra pass to a category (PassCause) and an
+* originating identity (node id, signal name, etc.) so we can answer "what
+* keeps the loop alive?". The data feeds C3b (bounded-convergence) — once we
+* know which feedback edges dominate, we can replace MAX_SINGLE_PASS_ITERATIONS
+* with attributed bounds.
+*
+* ## Design (post dual-pro review, 2026-04-26)
+*
+* Pass-causes are CATEGORICAL events, not duration spans. Both GPT-5.4 Pro
+* and Kimi K2.6 converged on:
+*
+* - Use `log.debug?.("pass", { cause, edge, nodeId, producerPhase })` —
+*   not `log.span()`. Spans imply duration; a pass-cause is instantaneous
+*   and would log spurious 0ms entries that pollute traces.
+* - Aggregate via a custom pipeline `Stage` that captures `LogEvent.props`.
+*   The `Stage` type is part of loggily's public API (`loggily/index.ts`
+*   re-exports it from `./pipeline.js`) — it's the framework's intended
+*   extension point for non-duration aggregation.
+* - Do NOT use `loggily/metrics`. `MetricsCollector` is intentionally
+*   duration-only: `recordSpan(data)` only sees `{name, durationMs}`,
+*   props are dropped at the collector boundary, and `summary()` returns
+*   `"name: N spans, mean=Xms, p50=Yms"`. For pass-causes the durations
+*   would all be ~0ms, and we would lose the edge/node breakdown that
+*   C3b consumes.
+* - Emit on a parent + child sub-namespace (`silvery:passes` and
+*   `silvery:passes:<cause>`) so `DEBUG=silvery:passes:layout-invalidate`
+*   filters by cause without losing the canonical histogram (which reads
+*   from the parent-namespace stage).
+* - Default-off via the silvery-side `SILVERY_INSTRUMENT=1` constant-fold
+*   gate (zero overhead when unset). Setting it also sets the loggily
+*   `LOG_LEVEL=debug` for `silvery:passes` (see logger setup below).
+* - For tests: the aggregator stage is composable; tests can call
+*   `createPassCauseAggregator()` for a fresh aggregator and pass
+*   `.stage` into a test-local `createLogger("silvery:passes", ...)`.
+*
+* Tracking: km-silvery.renderer-feedback-trace, km-silvery.feedback-trace-loggily
+*/
+/**
+* Module-level instrumentation gate. Constant so JS engines can fold the
+* `if (INSTRUMENT) { ... }` blocks at every emit site out of the hot path.
+*
+* Mapping to loggily:
+* - SILVERY_INSTRUMENT=1 implies LOG_LEVEL=debug + DEBUG=silvery:passes
+*   for the silvery:passes namespace, so the loggily pipeline accepts
+*   debug-level events (default level is info, which would drop them).
+*
+* The two gates compose:
+* - INSTRUMENT controls the silvery side (emit-call evaluation, prop
+*   allocation).
+* - DEBUG/LOG_LEVEL controls the loggily side (which sinks/stages see
+*   the event).
+*/
+const INSTRUMENT = process.env.SILVERY_INSTRUMENT === "1";
+const instrumentEnabled = INSTRUMENT;
+function createPassCauseAggregator() {
+	let state = {
+		records: [],
+		perPass: []
+	};
+	let recordsAtPassStart = 0;
+	const stage = (event) => {
+		if (event.kind !== "log") return event;
+		if (event.namespace !== "silvery:passes" && !event.namespace.startsWith("silvery:passes:")) return event;
+		if (event.message !== "pass") return event;
+		const props = event.props;
+		if (!props?.cause) return event;
+		state.records.push({
+			cause: props.cause,
+			nodeId: props.nodeId,
+			edge: props.edge,
+			producerPhase: props.producerPhase,
+			detail: props.detail
+		});
+		return event;
+	};
+	function getHistogram() {
+		const byCauseMap = /* @__PURE__ */ new Map();
+		for (const r of state.records) {
+			let entry = byCauseMap.get(r.cause);
+			if (!entry) {
+				entry = {
+					count: 0,
+					edges: /* @__PURE__ */ new Map(),
+					nodes: /* @__PURE__ */ new Map()
+				};
+				byCauseMap.set(r.cause, entry);
+			}
+			entry.count += 1;
+			if (r.edge) entry.edges.set(r.edge, (entry.edges.get(r.edge) ?? 0) + 1);
+			if (r.nodeId !== void 0) entry.nodes.set(r.nodeId, (entry.nodes.get(r.nodeId) ?? 0) + 1);
+		}
+		const byCause = [];
+		for (const [cause, entry] of byCauseMap) {
+			const topEdges = [...entry.edges.entries()].map(([edge, count]) => ({
+				edge,
+				count
+			})).sort((a, b) => b.count - a.count).slice(0, 8);
+			const topNodes = [...entry.nodes.entries()].map(([nodeId, count]) => ({
+				nodeId,
+				count
+			})).sort((a, b) => b.count - a.count).slice(0, 8);
+			byCause.push({
+				cause,
+				count: entry.count,
+				topEdges,
+				topNodes
+			});
+		}
+		byCause.sort((a, b) => b.count - a.count);
+		return {
+			totalRecords: state.records.length,
+			perPass: state.perPass.slice(),
+			byCause
+		};
+	}
+	function formatSummary() {
+		const h = getHistogram();
+		if (h.totalRecords === 0) return "pass-cause histogram: no extra passes recorded";
+		const lines = [];
+		lines.push(`pass-cause histogram: ${h.totalRecords} extra-pass causes`);
+		if (h.perPass.length > 0) {
+			const perPassLine = h.perPass.map((c, i) => c > 0 ? `pass${i}=${c}` : null).filter((s) => s !== null).join(" ");
+			if (perPassLine) lines.push(`  per-pass commits: ${perPassLine}`);
+		}
+		for (const entry of h.byCause) {
+			const pct = (entry.count / h.totalRecords * 100).toFixed(1);
+			lines.push(`  ${entry.cause}: ${entry.count} (${pct}%)`);
+			if (entry.topEdges.length > 0) lines.push("    edges: " + entry.topEdges.map((e) => `${e.edge}×${e.count}`).join(", "));
+			if (entry.topNodes.length > 0) lines.push("    nodes: " + entry.topNodes.map((n) => `${n.nodeId}×${n.count}`).join(", "));
+		}
+		return lines.join("\n");
+	}
+	function reset() {
+		state = {
+			records: [],
+			perPass: []
+		};
+		recordsAtPassStart = 0;
+	}
+	function notePassCommit(passIndex) {
+		while (state.perPass.length <= passIndex) state.perPass.push(0);
+		state.perPass[passIndex] = (state.perPass[passIndex] ?? 0) + 1;
+		if (state.records.length === recordsAtPassStart) state.records.push({
+			cause: "unknown",
+			detail: `pass-${passIndex}-uncategorized-commit`
+		});
+	}
+	function beginPass(_passIndex) {
+		recordsAtPassStart = state.records.length;
+	}
+	function beginConvergenceLoop() {
+		recordsAtPassStart = state.records.length;
+	}
+	function appendJson(file) {
+		const h = getHistogram();
+		if (h.totalRecords === 0) return;
+		__require("node:fs").appendFileSync(file, JSON.stringify(h) + "\n");
+	}
+	return {
+		stage,
+		getHistogram,
+		formatSummary,
+		reset,
+		notePassCommit,
+		beginPass,
+		beginConvergenceLoop,
+		appendJson
+	};
+}
+const passAggregator = createPassCauseAggregator();
+/**
+* Pass-cause loggers. Parent namespace is `silvery:passes`. Each cause gets
+* a child namespace `silvery:passes:<cause>` so users can filter at any
+* granularity:
+*   DEBUG=silvery:passes                    → all causes
+*   DEBUG=silvery:passes:layout-invalidate  → only layout-invalidate
+*   DEBUG=silvery:passes:scrollto-settle    → only scrollto-settle
+*
+* Both the parent and every child share the same pipeline (level + the
+* aggregator stage). Children are cached on first use to avoid logger
+* construction in the hot path.
+*
+* The aggregator stage is always attached — it's a no-op when no events
+* arrive, and the INSTRUMENT gate at emit sites prevents events when the
+* env var is unset.
+*/
+const passLogConfig = [{ level: instrumentEnabled ? "debug" : "info" }, passAggregator.stage];
+createLogger("silvery:passes", [...passLogConfig]);
+const childLoggers = /* @__PURE__ */ new Map();
+function loggerForCause(cause) {
+	let child = childLoggers.get(cause);
+	if (!child) {
+		child = createLogger(`silvery:passes:${cause}`, [...passLogConfig]);
+		childLoggers.set(cause, child);
+	}
+	return child;
+}
+/**
+* Reset the per-loop pass-index tracker. Called at the top of each
+* convergence loop in renderer.ts / runtime/create-app.tsx.
+*/
+function beginConvergenceLoop() {
+	if (!instrumentEnabled) return;
+	passAggregator.beginConvergenceLoop();
+}
+/** Mark the start of pass N (0-based). */
+function beginPass(passIndex) {
+	if (!instrumentEnabled) return;
+	passAggregator.beginPass(passIndex);
+}
+/**
+* Record that a feedback edge fired during the current pass.
+*
+* Emits on the per-cause child namespace so that
+* `DEBUG=silvery:passes:<cause>` filters by cause; the aggregator stage
+* captures both parent and child events into the canonical histogram.
+*/
+function logPass(record) {
+	if (!instrumentEnabled) return;
+	loggerForCause(record.cause).debug?.("pass", record);
+}
+/**
+* Mark that pass N committed React work that will require pass N+1.
+* Bumps the per-pass-index counter and synthesizes an "unknown" record
+* if no specific cause was emitted during pass N.
+*/
+function notePassCommit(passIndex) {
+	if (!instrumentEnabled) return;
+	passAggregator.notePassCommit(passIndex);
+}
+/** Snapshot the current pass-cause histogram. */
+function getPassHistogram() {
+	if (!instrumentEnabled) return {
+		totalRecords: 0,
+		perPass: [],
+		byCause: []
+	};
+	return passAggregator.getHistogram();
+}
+/** Clear all captured records. */
+function resetPassHistogram() {
+	passAggregator.reset();
+}
+/**
+* Print histogram to stderr (test runner / app teardown). No-op if
+* instrumentation is disabled or no records exist.
+*
+* In test environments where stdout/stderr are intercepted, write to
+* SILVERY_INSTRUMENT_FILE instead.
+*/
+function printPassHistogram() {
+	if (!instrumentEnabled) return;
+	if (passAggregator.getHistogram().totalRecords === 0) return;
+	const formatted = passAggregator.formatSummary();
+	const file = process.env.SILVERY_INSTRUMENT_FILE;
+	if (file) {
+		__require("node:fs").appendFileSync(file, "\n" + formatted + "\n");
+		return;
+	}
+	process.stderr.write("\n" + formatted + "\n");
+}
+/** Append a JSON snapshot to a file (vitest exit hook). */
+function appendHistogramJson(file) {
+	if (!instrumentEnabled) return;
+	passAggregator.appendJson(file);
+}
+/**
+* Per-cause convergence bound: maximum extra passes (beyond the initial pass)
+* each PassCause category can structurally trigger before settling. Each
+* bound is an invariant of how the cause works in the pipeline — not a
+* histogram observation — and the math is documented in
+* `hub/silvery/design/convergence-bounds.md`.
+*
+* Empirical baseline (C3a v3 corpus, 105 termless app teardowns,
+* 11 538 records): no test reached pass 1+. The structural ceiling matches:
+* sum(PASS_CAUSE_BOUNDS) = 0, plus 1 initial pass + 1 settle pass = MAX=2.
+*
+* Why every cause's bound is 0:
+* - layout-invalidate: when a subscriber re-renders, the new layout produces
+*   the SAME rects (idempotent given same input) so the second
+*   notifyLayoutSubscribers reports no change. The settle pass drains the
+*   subscribers' commits; it doesn't seed new feedback.
+* - intrinsic-shrinkwrap: measurement is content-deterministic; same tree
+*   produces same shrunkWidth / fitContentHeight on the next pass.
+* - scrollto-settle: prevScrollTo === scrollTo guard prevents the same intent
+*   from re-firing; the recovery edge is a one-shot "target moved offscreen".
+* - sticky-resettle: stickyChildren is recomputed deterministically from
+*   layout positions — once layout is stable, sticky offsets are stable.
+* - viewport-resize: dim-change is a depth-0 root trigger, not a feedback
+*   edge. Once the new dims are observed, no further resize fires.
+* - unknown: any non-zero unknown count is a regression to surface, not
+*   budget to consume.
+*
+* The total convergence ceiling = 1 (initial) + 1 (settle) + sum of per-cause
+* bounds. Per the v3 corpus and the audit above, the per-cause bounds are
+* ALL 0 — each cause is satisfied within the single settle pass. Total = 2.
+*/
+const PASS_CAUSE_BOUNDS = {
+	"layout-invalidate": 0,
+	"intrinsic-shrinkwrap": 0,
+	"scrollto-settle": 0,
+	"sticky-resettle": 0,
+	"viewport-resize": 0,
+	unknown: 0
+};
+/**
+* Total subscriber-feedback bound: 1 (initial) + 1 (one settle pass) + sum
+* of PASS_CAUSE_BOUNDS = 2. This applies to loops where pipeline output and
+* React effects flush in **separate phases** — singlePassLayout (one
+* runPipeline + a separate effect-flush loop), the effect-flush loop
+* itself, and the production processEventBatch flush.
+*
+* The `classic` loop in renderer.ts is structurally different: it runs
+* runPipeline + flushSyncWork **interleaved** within the same loop, so a
+* single iteration may emit a rect-signal change AND drain a virtualizer
+* re-render that mounts new items, which then need ANOTHER iteration to
+* lay out. That's not subscriber feedback — it's layout-vs-React
+* stabilisation, and the historical empirical bound for it is 5. Tests
+* that exercise virtualizer + scroll convergence (e.g.
+* list-view-refinements with 100 items + indexed virtualization) actually
+* use 3-4 of those iterations to settle the rendered window.
+*
+* Both bounds replace the four prior magic constants
+* (MAX_SINGLE_PASS_ITERATIONS=15, MAX_LAYOUT_ITERATIONS=5,
+* MAX_EFFECT_FLUSHES=5, maxFlushes=5) — the 15-pass cap is gone, and the
+* 5 is now an explicit per-loop documented value, not a guess.
+*/
+const MAX_CONVERGENCE_PASSES = 2 + PASS_CAUSE_BOUNDS["layout-invalidate"] + PASS_CAUSE_BOUNDS["intrinsic-shrinkwrap"] + PASS_CAUSE_BOUNDS["scrollto-settle"] + PASS_CAUSE_BOUNDS["sticky-resettle"] + PASS_CAUSE_BOUNDS["viewport-resize"] + PASS_CAUSE_BOUNDS.unknown;
+/**
+* Assert the convergence loop did not exceed its cap. Called from the
+* renderer's loops + create-app's processEventBatch flush loop. No-op
+* outside SILVERY_STRICT — the loop bound itself is the production
+* safety net.
+*
+* STRICT=2: throws with a per-cause breakdown so a regression names the
+*   responsible edge instead of just "exhausted N iterations".
+* STRICT=1: emits a stderr warning with the same breakdown.
+*/
+function assertBoundedConvergence(passCount, loopName, cap) {
+	if (passCount <= cap) return;
+	const strict = process?.env?.SILVERY_STRICT;
+	if (!strict) return;
+	const msg = `convergence bound exceeded in ${loopName}: ${passCount} passes ran but cap=${cap} (default MAX_CONVERGENCE_PASSES=${MAX_CONVERGENCE_PASSES}). Per-cause breakdown: ${getPassHistogram().byCause.map((e) => `${e.cause}=${e.count}(bound=${PASS_CAUSE_BOUNDS[e.cause]})`).join(", ") || "(no records — INSTRUMENT off)"}. Either a feedback edge broke its per-cause invariant, or a new edge needs a PassCause category in pass-cause.ts.`;
+	if (strict === "2") throw new Error(msg);
+	process.stderr.write(`[silvery] ${msg}\n`);
+}
+//#endregion
 //#region packages/ag-term/src/pipeline/measure-phase.ts
 /**
 * Handle fit-content nodes by measuring their intrinsic content size.
@@ -446,11 +1151,25 @@ function measurePhase(root, ctx) {
 			}
 			if (isSnugContent) {
 				const shrunkWidth = computeSnugContentWidth(node, measureIntrinsicSize(node, ctx, availableWidth).width, ctx);
+				const prevWidth = node.boxRect?.width;
 				node.layoutNode.setMaxWidth(shrunkWidth);
+				if (INSTRUMENT && prevWidth !== void 0 && prevWidth !== shrunkWidth) logPass({
+					cause: "intrinsic-shrinkwrap",
+					edge: "snug-content:width",
+					producerPhase: "measure",
+					detail: `${prevWidth}→${shrunkWidth}`
+				});
 			}
 			if (isHeightFitContent) {
 				const intrinsicSize = measureIntrinsicSize(node, ctx, availableWidth);
+				const prevHeight = node.boxRect?.height;
 				node.layoutNode.setHeight(intrinsicSize.height);
+				if (INSTRUMENT && prevHeight !== void 0 && prevHeight !== intrinsicSize.height) logPass({
+					cause: "intrinsic-shrinkwrap",
+					edge: "fit-content:height",
+					producerPhase: "measure",
+					detail: `${prevHeight}→${intrinsicSize.height}`
+				});
 			}
 		}
 	});
@@ -482,8 +1201,10 @@ function measureIntrinsicSize(node, ctx, availableWidth) {
 		}
 		const transform = textProps.internal_transform;
 		let lines;
-		if (availableWidth !== void 0 && availableWidth > 0 && isWrapEnabled(textProps.wrap)) lines = ctx ? ctx.measurer.wrapText(text, availableWidth, true, true) : wrapText(text, availableWidth, true, true);
-		else lines = text.split("\n");
+		if (availableWidth !== void 0 && availableWidth > 0 && isWrapEnabled(textProps.wrap)) {
+			const truncateAtomic = textProps.wrap === "wrap-truncate";
+			lines = ctx ? ctx.measurer.wrapText(text, availableWidth, true, true, truncateAtomic) : wrapText(text, availableWidth, true, true, truncateAtomic);
+		} else lines = text.split("\n");
 		if (transform) lines = lines.map((line, index) => transform(line, index));
 		return {
 			width: Math.max(...lines.map((line) => getTextWidth$1(line, ctx))),
@@ -528,7 +1249,7 @@ function measureIntrinsicSize(node, ctx, availableWidth) {
 * Check if text wrapping is enabled for a text node.
 */
 function isWrapEnabled(wrap) {
-	return wrap === "wrap" || wrap === "hard" || wrap === "even" || wrap === true || wrap === void 0;
+	return wrap === "wrap" || wrap === "wrap-truncate" || wrap === "hard" || wrap === "even" || wrap === true || wrap === void 0;
 }
 /**
 * Compute snug-content width for a node.
@@ -612,6 +1333,49 @@ function getTextWidth$1(text, ctx) {
 */
 const log$2 = createLogger("silvery:layout");
 /**
+* Stable-ish identity string for an AgNode used by pass-cause records.
+* Prefers explicit identity props (testid / id / name / nodeId) and falls
+* back to type. Keeps the histogram readable without paying a Map lookup
+* per node when SILVERY_INSTRUMENT is unset (call site is gated by the
+* inert no-op in `logPass`).
+*/
+function nodeIdent(node) {
+	const props = node.props;
+	const ident = props?.["testid"] ?? props?.["id"] ?? props?.["name"] ?? props?.["nodeId"];
+	return ident ? `${node.type}#${ident}` : node.type;
+}
+function nodePath(node) {
+	const path = [];
+	let current = node;
+	while (current) {
+		path.push(nodeIdent(current));
+		current = current.parent;
+	}
+	return path.reverse().join(" > ");
+}
+function layoutPropsForLog(node) {
+	const props = node.props ?? {};
+	return {
+		width: props.width,
+		maxWidth: props.maxWidth,
+		minWidth: props.minWidth,
+		flexGrow: props.flexGrow,
+		flexShrink: props.flexShrink,
+		flexBasis: props.flexBasis,
+		alignSelf: props.alignSelf,
+		position: props.position,
+		overflow: props.overflow,
+		borderStyle: props.borderStyle,
+		padding: props.padding,
+		paddingLeft: props.paddingLeft,
+		paddingRight: props.paddingRight
+	};
+}
+function normalizeScrollOffset(offset) {
+	if (!Number.isFinite(offset)) return 0;
+	return Math.round(offset);
+}
+/**
 * Run Yoga layout calculation and propagate dimensions to all nodes.
 *
 * @param root The root SilveryNode
@@ -765,8 +1529,72 @@ function _hasChildPositionChanged(node) {
 	return false;
 }
 /**
-* Check if any descendant was overflowing THIS node's rect and had its layout change.
-* Recursive: follows subtreeDirty paths for efficiency.
+* Lightweight `getEffectiveBg` for the layout phase. Mirrors the
+* production helper in `render-box.ts` (Sterling-aware: `bg-surface-default`
+* → legacy `bg`). Inlined here to avoid a layout→render-box import cycle.
+*
+* The render phase still uses its own `getEffectiveBg` for the cascade
+* formulas; this duplicate exists ONLY so the layout phase can flag
+* "bg-bearing descendant moved/shrank" without dragging render-box into
+* the layout module graph.
+*/
+function _layoutGetEffectiveBg(props) {
+	if (props.backgroundColor) return props.backgroundColor;
+	const theme = props.theme;
+	if (theme) {
+		const sterlingBg = theme["bg-surface-default"];
+		if (typeof sterlingBg === "string") return sterlingBg;
+		const legacyBg = theme["bg"];
+		if (typeof legacyBg === "string") return legacyBg;
+	}
+}
+/**
+* True iff `prev` has any cells NOT covered by `cur` (shrink, move, or any
+* combination thereof). This is the "bg residue" predicate: cells the
+* painter occupied before but doesn't occupy now. Equivalent to
+* `prev \ cur ≠ ∅`.
+*/
+function _prevHasResidueOutside(prev, cur) {
+	return prev.x < cur.x || prev.y < cur.y || prev.x + prev.width > cur.x + cur.width || prev.y + prev.height > cur.y + cur.height;
+}
+/**
+* Check if any descendant was overflowing THIS node's rect and had its layout
+* change OR if any bg-bearing descendant shrank/moved within this node's rect
+* (leaving stale bg residue inside).
+*
+* Two related cases:
+*
+*   1. **Outside-overflow** (original): descendant's prev rect extended
+*      BEYOND `node`'s current rect. The descendant either grew past
+*      `node`'s edge before and shrank back inside, or moved out and back —
+*      either way `node`'s border/padding cells outside the descendant's
+*      new rect carry stale pixels.
+*
+*   2. **Inside-bg-residue** (added 2026-05-07, bead
+*      @km/silvery/incremental-bg-residue-shrink-move): descendant has
+*      `effectiveBg` AND its prev rect has cells NOT covered by its
+*      current rect (any shrink/move). The painter's prev paint covered
+*      those cells with its bg; on this frame nothing in the painter's
+*      subtree paints them. If those cells are within `node`'s rect,
+*      `node` must clear them via its own `clearNodeRegion` (when
+*      transparent) or `renderBox` fill (when bg-bearing). Without this
+*      flag, `node`'s contentAreaAffected may be FALSE — the painter's
+*      `clearExcessArea` SKIPS due to the position-change guard, and
+*      `node`'s fast-path-with-subtreeDirty doesn't trigger any cleanup.
+*      The cell carries forward bg from the prev frame indefinitely.
+*
+*      Why on `node` and not just the immediate parent: the residue
+*      cells must be covered by SOME ancestor that clears or fills.
+*      The closest transparent ancestor that contains the residue cells
+*      must clear them; if every ancestor up to a bg-bearing one is
+*      transparent, that bg-bearing ancestor's renderBox fill suffices.
+*      Setting the flag at every ancestor whose rect contains residue
+*      cells guarantees coverage regardless of where the bg-break is.
+*
+* Recursive: follows subtreeDirty paths for efficiency. Returns early on
+* first match. Performance: only runs when subtreeDirty (matches the
+* `_hasAbsoluteChildMutated` guard); for typical UI updates the search
+* touches < 10 nodes before terminating.
 */
 function _hasDescendantOverflowChanged(node, rect) {
 	return _checkDescendantOverflow(node.children, rect.x, rect.y, rect.x + rect.width, rect.y + rect.height);
@@ -776,6 +1604,16 @@ function _checkDescendantOverflow(children, nodeLeft, nodeTop, nodeRight, nodeBo
 		if (child.prevLayout && isCurrentEpoch(child.layoutChangedThisFrame)) {
 			const prev = child.prevLayout;
 			if (prev.x + prev.width > nodeRight || prev.y + prev.height > nodeBottom || prev.x < nodeLeft || prev.y < nodeTop) return true;
+			if (child.boxRect) {
+				const props = child.props;
+				if (_layoutGetEffectiveBg(props) !== void 0 && _prevHasResidueOutside(prev, child.boxRect)) {
+					const ix1 = Math.max(prev.x, nodeLeft);
+					const iy1 = Math.max(prev.y, nodeTop);
+					const ix2 = Math.min(prev.x + prev.width, nodeRight);
+					const iy2 = Math.min(prev.y + prev.height, nodeBottom);
+					if (ix2 > ix1 && iy2 > iy1) return true;
+				}
+			}
 		}
 		if (isDirty(child.dirtyBits, child.dirtyEpoch, 16) && child.children !== void 0) {
 			if (_checkDescendantOverflow(child.children, nodeLeft, nodeTop, nodeRight, nodeBottom)) return true;
@@ -796,11 +1634,44 @@ function _checkDescendantOverflow(children, nodeLeft, nodeTop, nodeRight, nodeBo
 * offset changes even when scrollRect stays the same.
 */
 function notifyLayoutSubscribers(node) {
-	rectEqual(node.prevLayout, node.boxRect);
-	rectEqual(node.prevScrollRect, node.scrollRect);
-	rectEqual(node.prevScreenRect, node.screenRect);
+	const contentChanged = !rectEqual(node.prevLayout, node.boxRect);
+	const sizeChanged = (node.prevLayout?.width ?? 0) !== (node.boxRect?.width ?? 0) || (node.prevLayout?.height ?? 0) !== (node.boxRect?.height ?? 0);
+	const screenChanged = !rectEqual(node.prevScrollRect, node.scrollRect);
+	const renderChanged = !rectEqual(node.prevScreenRect, node.screenRect);
+	if (INSTRUMENT) {
+		if (contentChanged || screenChanged || renderChanged) {
+			if (hasLayoutSignals(node)) {
+				const ident = nodeIdent(node);
+				if (contentChanged && hasObservedLayoutSignal(node, "boxRect")) logPass({
+					cause: "layout-invalidate",
+					edge: "boxRect",
+					nodeId: ident,
+					producerPhase: "layout"
+				});
+				if (sizeChanged && hasObservedLayoutSignal(node, "boxSize")) logPass({
+					cause: "layout-invalidate",
+					edge: "boxSize",
+					nodeId: ident,
+					producerPhase: "layout"
+				});
+				if (screenChanged && hasObservedLayoutSignal(node, "scrollRect")) logPass({
+					cause: "layout-invalidate",
+					edge: "scrollRect",
+					nodeId: ident,
+					producerPhase: "layout"
+				});
+				if (renderChanged && hasObservedLayoutSignal(node, "screenRect")) logPass({
+					cause: "layout-invalidate",
+					edge: "screenRect",
+					nodeId: ident,
+					producerPhase: "layout"
+				});
+			}
+		}
+	}
 	syncRectSignals(node);
 	for (const child of node.children) notifyLayoutSubscribers(child);
+	if (node.parent === null) syncDecorationRects(node);
 }
 /**
 * Verify that no child's boxRect.width exceeds its parent's inner content width.
@@ -843,9 +1714,24 @@ function strictLayoutOverflowCheck(root) {
 				if (child.boxRect.width > parentInnerWidth) {
 					const childId = childProps.id ?? child.type;
 					const parentId = parentProps.id ?? node.type;
-					const msg = `[SILVERY_STRICT] Layout overflow: child "${childId}" width ${child.boxRect.width} exceeds parent "${parentId}" inner width ${parentInnerWidth} (parent box: ${node.boxRect.width}, border: ${border.left}+${border.right}, padding: ${padding.left}+${padding.right})`;
+					const detail = {
+						child: nodeIdent(child),
+						parent: nodeIdent(node),
+						childPath: nodePath(child),
+						childBox: child.boxRect,
+						parentBox: node.boxRect,
+						parentInnerWidth,
+						border,
+						padding,
+						childProps: layoutPropsForLog(child),
+						parentProps: layoutPropsForLog(node)
+					};
+					const msg = `[SILVERY_STRICT] Layout overflow: child "${childId}" width ${child.boxRect.width} exceeds parent "${parentId}" inner width ${parentInnerWidth} (parent box: ${node.boxRect.width}, border: ${border.left}+${border.right}, padding: ${padding.left}+${padding.right}, path: ${detail.childPath})`;
 					if (shouldThrow) throw new Error(msg);
-					else console.warn(msg);
+					else {
+						log$2.debug?.("layout overflow", detail);
+						console.warn(msg);
+					}
 				}
 			}
 			walk(child);
@@ -941,18 +1827,38 @@ function calculateScrollState(node, props, skipStateUpdates) {
 	const viewportHeight = rawViewportHeight;
 	const indicatorReserve = props.overflowIndicator === true && !props.borderStyle && contentHeight > rawViewportHeight ? 1 : 0;
 	const prevOffset = node.scrollState?.offset;
+	const prevScrollTo = node.scrollState?.prevScrollTo;
 	let scrollOffset = props.scrollOffset ?? prevOffset ?? 0;
 	const scrollTo = props.scrollTo;
-	if (scrollTo !== void 0 && scrollTo >= 0 && scrollTo < childPositions.length) {
+	const scrollToChanged = prevScrollTo !== scrollTo;
+	let targetCompletelyOffscreen = false;
+	if (!scrollToChanged && scrollTo !== void 0 && scrollTo >= 0 && scrollTo < childPositions.length) {
+		const target = childPositions.find((c) => c.index === scrollTo);
+		if (target && target.top !== target.bottom) {
+			const visTop = scrollOffset;
+			const visBottom = scrollOffset + viewportHeight;
+			if (!(target.bottom > visTop && target.top < visBottom)) targetCompletelyOffscreen = true;
+		}
+	}
+	if (scrollTo !== void 0 && scrollTo >= 0 && scrollTo < childPositions.length && (scrollToChanged || targetCompletelyOffscreen)) {
 		const target = childPositions.find((c) => c.index === scrollTo);
 		if (target) {
+			if (INSTRUMENT) logPass({
+				cause: "scrollto-settle",
+				edge: targetCompletelyOffscreen ? "scrollTo:recovery" : "scrollTo:newIntent",
+				nodeId: nodeIdent(node),
+				producerPhase: "scroll",
+				detail: `target=${scrollTo}`
+			});
 			const effectiveHeight = viewportHeight - indicatorReserve;
 			const visibleTop = scrollOffset;
 			const visibleBottom = scrollOffset + effectiveHeight;
-			if (target.top < visibleTop) scrollOffset = target.top > 0 ? target.top - 1 : 0;
+			if (target.bottom - target.top > effectiveHeight) scrollOffset = target.top > 0 ? target.top - 1 : 0;
+			else if (target.top < visibleTop) scrollOffset = target.top > 0 ? target.top - 1 : 0;
 			else if (target.bottom > visibleBottom) scrollOffset = snapOffsetToChildTop(target.bottom - effectiveHeight, childPositions, target);
 		}
 	}
+	scrollOffset = normalizeScrollOffset(scrollOffset);
 	scrollOffset = Math.max(0, scrollOffset);
 	scrollOffset = Math.min(scrollOffset, Math.max(0, contentHeight - viewportHeight));
 	const visibleTop = scrollOffset;
@@ -961,6 +1867,10 @@ function calculateScrollState(node, props, skipStateUpdates) {
 	let lastVisible = -1;
 	let hiddenAbove = 0;
 	let hiddenBelow = 0;
+	const logicalCount = (cp) => {
+		const r = cp.child.props.representsItems;
+		return r !== void 0 && r >= 0 ? r : 1;
+	};
 	for (const cp of childPositions) {
 		if (cp.isSticky) {
 			if (firstVisible === -1) firstVisible = cp.index;
@@ -968,15 +1878,20 @@ function calculateScrollState(node, props, skipStateUpdates) {
 			continue;
 		}
 		if (cp.top === cp.bottom) continue;
-		if (cp.bottom <= visibleTop) hiddenAbove++;
-		else if (cp.top >= visibleBottom) hiddenBelow++;
+		if (cp.bottom <= visibleTop) hiddenAbove += logicalCount(cp);
+		else if (cp.top >= visibleBottom) hiddenBelow += logicalCount(cp);
 		else if (cp.top < visibleTop) {
 			if (firstVisible === -1) firstVisible = cp.index;
 			lastVisible = Math.max(lastVisible, cp.index);
 		} else if (cp.bottom > visibleBottom) {
 			if (firstVisible === -1) firstVisible = cp.index;
 			lastVisible = cp.index;
-			if (indicatorReserve > 0) hiddenBelow++;
+			const isLastChild = cp.index === childPositions[childPositions.length - 1]?.index;
+			const rawViewportBottom = scrollOffset + viewportHeight;
+			const childHeight = cp.bottom - cp.top;
+			const isPhantomReserveCut = isLastChild && cp.bottom <= rawViewportBottom;
+			const isOversizedLastAtEnd = isLastChild && childHeight > viewportHeight && scrollTo === cp.index;
+			if (indicatorReserve > 0 && !isPhantomReserveCut && !isOversizedLastAtEnd) hiddenBelow += logicalCount(cp);
 		} else {
 			if (firstVisible === -1) firstVisible = cp.index;
 			lastVisible = cp.index;
@@ -1006,6 +1921,7 @@ function calculateScrollState(node, props, skipStateUpdates) {
 			height: childHeight
 		});
 	}
+	strictScrollInvariants(node, props, scrollOffset, contentHeight, viewportHeight, indicatorReserve, childPositions, firstVisible, lastVisible, stickyChildren);
 	if (skipStateUpdates) return;
 	const prevFirstVisible = node.scrollState?.firstVisibleChild ?? firstVisible;
 	const prevLastVisible = node.scrollState?.lastVisibleChild ?? lastVisible;
@@ -1019,6 +1935,7 @@ function calculateScrollState(node, props, skipStateUpdates) {
 	node.scrollState = {
 		offset: scrollOffset,
 		prevOffset: prevOffset ?? scrollOffset,
+		prevScrollTo: scrollTo,
 		contentHeight,
 		viewportHeight,
 		firstVisibleChild: firstVisible,
@@ -1031,6 +1948,69 @@ function calculateScrollState(node, props, skipStateUpdates) {
 	};
 }
 /**
+* Runtime invariants for scroll state. Gated on SILVERY_STRICT.
+*
+* Invariant set (all violations use `[SILVERY_STRICT]` prefix, L1 warn / L2 throw):
+*   1. scrollOffset is clamped: 0 ≤ scrollOffset ≤ max(0, contentHeight - viewportHeight).
+*   2. If scrollTo is a valid index, the target child intersects the effective
+*      viewport (viewport minus indicatorReserve) after the offset calc.
+*   3. firstVisibleChild / lastVisibleChild correspond to children that actually
+*      intersect the effective viewport (not spacer indices outside).
+*   4. Sticky child renderOffset stays within legal viewport bounds — specifically
+*      `renderOffset + height > 0 && renderOffset < viewportHeight` (sticky row
+*      not clipped entirely out, which `calculateScrollState` already filters,
+*      but we also verify the sticky row's bottom doesn't sit ABOVE 0 for
+*      isSticking=true entries since clamping should have prevented that).
+*
+* These are GENERIC scroll invariants — no virtualizer knowledge. Any divergence
+* points to a bug in the scroll/sticky math itself.
+*/
+function strictScrollInvariants(node, props, scrollOffset, contentHeight, viewportHeight, indicatorReserve, childPositions, firstVisible, lastVisible, stickyChildren) {
+	const strict = process?.env?.SILVERY_STRICT;
+	if (!strict) return;
+	const shouldThrow = strict === "2";
+	const nodeId = props.id ?? node.type;
+	const report = (msg) => {
+		const full = `[SILVERY_STRICT] ${msg} (node: ${nodeId})`;
+		if (shouldThrow) throw new Error(full);
+		else console.warn(full);
+	};
+	const maxOffset = Math.max(0, contentHeight - viewportHeight);
+	if (scrollOffset < 0) report(`scrollOffset ${scrollOffset} < 0`);
+	else if (scrollOffset > maxOffset) report(`scrollOffset ${scrollOffset} exceeds max ${maxOffset} (contentHeight=${contentHeight}, viewportHeight=${viewportHeight})`);
+	const scrollTo = props.scrollTo;
+	if (scrollTo !== void 0 && scrollTo >= 0 && scrollTo < childPositions.length) {
+		const target = childPositions.find((c) => c.index === scrollTo);
+		if (target && target.top !== target.bottom) {
+			const visibleTop = scrollOffset;
+			const visibleBottom = scrollOffset + viewportHeight;
+			if (!(target.bottom > visibleTop && target.top < visibleBottom)) report(`scrollTo target index=${scrollTo} does not intersect viewport (target [${target.top},${target.bottom}), visible [${visibleTop},${visibleBottom}), indicatorReserve=${indicatorReserve})`);
+		}
+	}
+	const visibleTop = scrollOffset;
+	const visibleBottom = scrollOffset + viewportHeight - indicatorReserve;
+	const checkVisible = (label, idx) => {
+		if (idx < 0) return;
+		const cp = childPositions.find((c) => c.index === idx);
+		if (!cp) {
+			report(`${label}=${idx} but no child at that index`);
+			return;
+		}
+		if (cp.isSticky) return;
+		if (cp.top === cp.bottom) {
+			report(`${label}=${idx} references zero-height child`);
+			return;
+		}
+		if (!(cp.bottom > visibleTop && cp.top < visibleBottom)) report(`${label}=${idx} does not intersect effective viewport (child [${cp.top},${cp.bottom}), visible [${visibleTop},${visibleBottom}))`);
+	};
+	checkVisible("firstVisibleChild", firstVisible);
+	checkVisible("lastVisibleChild", lastVisible);
+	for (const sc of stickyChildren) {
+		const topRow = sc.renderOffset;
+		if (sc.renderOffset + sc.height <= 0 || topRow >= viewportHeight) report(`sticky child index=${sc.index} renderOffset=${topRow} height=${sc.height} outside viewport [0,${viewportHeight})`);
+	}
+}
+/**
 * Compute sticky offsets for non-scroll containers that have sticky children.
 *
 * Scroll containers handle their own sticky logic in calculateScrollState().
@@ -1102,6 +2082,13 @@ function stickyPhase(root) {
 				node.dirtyBits = 16;
 				node.dirtyEpoch = epoch;
 			} else node.dirtyBits |= 16;
+			if (INSTRUMENT) logPass({
+				cause: "sticky-resettle",
+				edge: "stickyChildren",
+				nodeId: nodeIdent(node),
+				producerPhase: "sticky",
+				detail: `${prev?.length ?? 0}→${next?.length ?? 0}`
+			});
 		}
 	});
 }
@@ -1265,6 +2252,7 @@ function detectPipelineFeatures(root) {
 }
 //#endregion
 //#region packages/ag-term/src/pipeline/state.ts
+init_src$1();
 /**
 * Safe fallback theme. Never mutated — the theme flows via the AgNode tree
 * (Box theme= prop + pushContextTheme/popContextTheme in render-phase.ts).
@@ -1312,18 +2300,7 @@ function popContextTheme() {
 }
 //#endregion
 //#region packages/ag-term/src/pipeline/render-helpers.ts
-/**
-* Render Helpers - Pure utility functions for content rendering.
-*
-* Contains:
-* - Color parsing (parseColor)
-* - Border character definitions (getBorderChars)
-* - Style extraction (getTextStyle)
-* - Text width utilities (getTextWidth)
-*
-* Re-exports layout helpers from helpers.ts:
-* - getPadding, getBorderSize
-*/
+init_buffer();
 init_src();
 const namedColors = {
 	black: 0,
@@ -1388,7 +2365,7 @@ function parseColor(color) {
 		}
 	}
 	if (color.startsWith("$")) {
-		if (getActiveColorLevel() === "none") return null;
+		if (getActiveColorLevel() === "mono") return null;
 		const resolved = resolveThemeColor(color, getActiveTheme());
 		if (resolved && resolved !== color) return parseColor(resolved);
 		return null;
@@ -1523,14 +2500,16 @@ function collectMonoAttrs(color, into) {
 function getTextStyle(props) {
 	let underlineStyle;
 	if (props.underlineStyle !== void 0) underlineStyle = props.underlineStyle;
-	else if (props.underline) underlineStyle = "single";
+	else if (typeof props.underline === "string") underlineStyle = props.underline;
+	else if (props.underline === true) underlineStyle = "single";
 	let bold = props.bold;
-	let dim = props.dim || props.dimColor;
+	let dim;
 	let italic = props.italic;
-	let underline = props.underline || !!underlineStyle;
+	let underline = !!props.underline || !!underlineStyle;
 	let strikethrough = props.strikethrough;
 	let inverse = props.inverse;
-	if (getActiveColorLevel() === "none") {
+	const overline = !!props.overline;
+	if (getActiveColorLevel() === "mono") {
 		const monoAttrs = /* @__PURE__ */ new Set();
 		collectMonoAttrs(props.color, monoAttrs);
 		collectMonoAttrs(props.backgroundColor, monoAttrs);
@@ -1554,6 +2533,7 @@ function getTextStyle(props) {
 			italic,
 			underline,
 			underlineStyle,
+			overline,
 			strikethrough,
 			inverse
 		}
@@ -1572,6 +2552,580 @@ function getTextWidth(text, ctx) {
 	return displayWidthAnsi(text);
 }
 //#endregion
+//#region packages/ag-term/src/strict-mode.ts
+let cachedRaw = void 0;
+let cachedParsed = null;
+function parseStrict(raw) {
+	if (!raw || raw === "0") return {
+		enabledTiers: /* @__PURE__ */ new Set(),
+		enabledSlugs: /* @__PURE__ */ new Set(),
+		disabledSlugs: /* @__PURE__ */ new Set(),
+		raw
+	};
+	const tiers = /* @__PURE__ */ new Set();
+	const slugs = /* @__PURE__ */ new Set();
+	const disabled = /* @__PURE__ */ new Set();
+	for (const part of raw.split(",")) {
+		const trimmed = part.trim();
+		if (!trimmed) continue;
+		if (trimmed.startsWith("!")) {
+			disabled.add(trimmed.slice(1));
+			continue;
+		}
+		const n = Number(trimmed);
+		if (Number.isFinite(n) && n >= 1) {
+			tiers.add(n);
+			continue;
+		}
+		slugs.add(trimmed);
+	}
+	return {
+		enabledTiers: tiers,
+		enabledSlugs: slugs,
+		disabledSlugs: disabled,
+		raw
+	};
+}
+function getParsed() {
+	const raw = process.env.SILVERY_STRICT;
+	if (raw !== cachedRaw || cachedParsed === null) {
+		cachedRaw = raw;
+		cachedParsed = parseStrict(raw);
+	}
+	return cachedParsed;
+}
+/**
+* Returns true if `slug` should fire under the current `SILVERY_STRICT`.
+*
+* - `!slug` always wins (per-check skip)
+* - explicit slug match wins
+* - any tier >= minTier (default 1) implies the check
+*/
+function isStrictEnabled(slug, minTier = 1) {
+	const p = getParsed();
+	if (p.disabledSlugs.has(slug)) return false;
+	if (p.enabledSlugs.has(slug)) return true;
+	for (const tier of p.enabledTiers) if (tier >= minTier) return true;
+	return false;
+}
+//#endregion
+//#region packages/ag-term/src/strict-bordered-rect.ts
+/** SILVERY_STRICT slug for the bordered-rect clip check. Tier 2 by design. */
+const BORDERED_RECT_CLIP_SLUG = "bordered-rect-clip";
+/** Returns true when the bordered-rect clip check should fire. */
+function isBorderedRectClipEnabled() {
+	return isStrictEnabled(BORDERED_RECT_CLIP_SLUG, 2);
+}
+/**
+* Error thrown when a cell is painted outside the nearest bordered
+* ancestor's inner content rect under SILVERY_STRICT=bordered-rect-clip.
+*
+* Like `IncrementalRenderMismatchError`, this should NOT be caught by
+* general error handlers — it indicates a real layout/clip bug that
+* needs a structural fix (`overflow="hidden"` on the bordered Box, or
+* `wrap="truncate"` on the inner Text).
+*/
+var BorderedRectClipError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BorderedRectClipError";
+	}
+};
+const renderingStack = [];
+/** Push the node currently being painted onto the rendering stack. */
+function pushRenderingNode(node) {
+	renderingStack.push(node);
+}
+/** Pop the most recently pushed rendering node. */
+function popRenderingNode() {
+	renderingStack.pop();
+}
+/** Peek the topmost rendering node, or null if the stack is empty. */
+function peekRenderingNode() {
+	return renderingStack.length === 0 ? null : renderingStack[renderingStack.length - 1] ?? null;
+}
+/**
+* Walk `node.parent` until we find a node with `borderStyle != null`.
+* Returns null when no ancestor is bordered (the outer canvas itself
+* has no border to honor).
+*
+* Excludes the starting node — a bordered Box's own border cells sit on
+* its perimeter (outside its OWN inner rect). The relevant constraint is
+* "stay inside the parent that borders me", not "stay inside myself".
+*/
+function findBorderedAncestor(node) {
+	let current = node.parent;
+	while (current) {
+		const props = current.props;
+		if (props && props.borderStyle != null) return current;
+		current = current.parent;
+	}
+	return null;
+}
+/**
+* Bordered-ancestor lookup result, cached against the topmost rendering
+* node identity. The renderer dispatches one `renderText` / `renderBox`
+* call per AgNode, and inside that call every emitSetCell shares the
+* same currently-rendering node. So a single-slot cache amortizes the
+* O(depth) walk to once per dispatch, not per cell.
+*
+* `cachedFor === null` means "no entry"; `cachedAncestor === null`
+* means "no bordered ancestor exists" (legitimate — outer-canvas paint).
+*/
+let cachedFor = null;
+let cachedAncestor = null;
+let cachedSkip = false;
+function getBorderedAncestorCached(node) {
+	if (cachedFor === node) return {
+		ancestor: cachedAncestor,
+		skip: cachedSkip
+	};
+	cachedFor = node;
+	cachedAncestor = findBorderedAncestor(node);
+	cachedSkip = cachedAncestor != null && hasOverflowHidden(cachedAncestor);
+	return {
+		ancestor: cachedAncestor,
+		skip: cachedSkip
+	};
+}
+function hasOverflowHidden(node) {
+	const p = node.props;
+	if (!p) return false;
+	if (p.overflow === "hidden") return true;
+	if (p.overflowX === "hidden" && p.overflowY === "hidden") return true;
+	return false;
+}
+/** Reset the per-render cache. Called at the boundary of each rendering
+*  push/pop so a stale identity from a previous frame never leaks. */
+function resetBorderedRectClipCache() {
+	cachedFor = null;
+	cachedAncestor = null;
+	cachedSkip = false;
+}
+function computeInnerRect(box, props) {
+	const top = props.borderTop !== false ? 1 : 0;
+	const bottom = props.borderBottom !== false ? 1 : 0;
+	const left = props.borderLeft !== false ? 1 : 0;
+	const right = props.borderRight !== false ? 1 : 0;
+	return {
+		left: box.x + left,
+		top: box.y + top,
+		right: box.x + box.width - right,
+		bottom: box.y + box.height - bottom
+	};
+}
+/**
+* Assert that cell (x, y) lies inside the nearest bordered ancestor's
+* inner content rect. No-op when:
+*   - the strict slug is not enabled
+*   - no rendering node is on the stack (paint outside a renderer
+*     dispatch — e.g. early init clear)
+*   - no bordered ancestor exists
+*   - the bordered ancestor has overflow="hidden" (clip enforced
+*     elsewhere by computeChildClipBounds)
+*
+* Throws `BorderedRectClipError` on violation.
+*/
+function assertCellInsideBorderedRect(x, y, opts = {}) {
+	if (!isBorderedRectClipEnabled()) return;
+	const node = peekRenderingNode();
+	if (!node) return;
+	const { ancestor, skip } = getBorderedAncestorCached(node);
+	if (!ancestor || skip) return;
+	const box = ancestor.screenRect ?? ancestor.scrollRect ?? ancestor.boxRect;
+	if (!box) return;
+	const props = ancestor.props;
+	const inner = computeInnerRect(box, props);
+	if (x >= inner.left && x < inner.right && y >= inner.top && y < inner.bottom) return;
+	const ancestorId = describeNode(ancestor);
+	const nodeId = describeNode(node);
+	const path = describeDepthPath(node);
+	throw new BorderedRectClipError(`STRICT bordered-rect-clip: cell painted outside ancestor's bordered rect\n  cell:        (x=${x}, y=${y}) char=${opts.char ? `'${opts.char}'` : "(unknown)"} bg=${formatColor(opts.bg)} fg=${formatColor(opts.fg)}\n  parent box:  id='${ancestorId}' rect=(${box.x},${box.y},${box.width},${box.height}) borderStyle='${props.borderStyle}'\n  inner rect:  (left=${inner.left}, top=${inner.top}, right=${inner.right}, bottom=${inner.bottom}) [exclusive]\n  painter:     '${nodeId}'\n  depth path:  ${path}\n\n  Suggested fix: set \`overflow="hidden"\` on the bordered Box,\n                 or use \`wrap="wrap"\` / \`wrap="truncate"\` on the inner Text.\n\n  Slug: SILVERY_STRICT=${BORDERED_RECT_CLIP_SLUG} (tier 2+).\n  Per-test opt-out: SILVERY_STRICT=2,!${BORDERED_RECT_CLIP_SLUG}.`);
+}
+function describeNode(node) {
+	const key = node.props?.key;
+	if (key !== void 0) return `${node.type}[key=${String(key)}]`;
+	if (node.type === "silvery-text" && typeof node.textContent === "string") {
+		const t = node.textContent.length > 20 ? `${node.textContent.slice(0, 20)}…` : node.textContent;
+		return `${node.type}[${JSON.stringify(t)}]`;
+	}
+	return `${node.type}`;
+}
+function describeDepthPath(node) {
+	const parts = [];
+	let cur = node;
+	let depth = 0;
+	while (cur && depth < 8) {
+		const props = cur.props;
+		let label = cur.type;
+		if (props?.borderStyle) label += `[border=${props.borderStyle}]`;
+		parts.unshift(label);
+		cur = cur.parent;
+		depth++;
+	}
+	if (cur) parts.unshift("…");
+	return parts.join(" > ");
+}
+function formatColor(c) {
+	if (c === null || c === void 0) return "default";
+	if (typeof c === "number") return `${c}`;
+	if (typeof c === "object") {
+		const o = c;
+		if (typeof o.r === "number") return `#${(o.r << 16 | o.g << 8 | o.b).toString(16).padStart(6, "0")}`;
+	}
+	return String(c);
+}
+//#endregion
+//#region packages/ag-term/src/pipeline/render-sink.ts
+function cloneCellPatch(cell) {
+	const out = { ...cell };
+	if (cell.attrs) out.attrs = { ...cell.attrs };
+	return out;
+}
+function cloneCell(cell) {
+	return {
+		...cell,
+		attrs: { ...cell.attrs }
+	};
+}
+function cloneStyle(style) {
+	return {
+		...style,
+		attrs: { ...style.attrs }
+	};
+}
+/**
+* `RenderSink` implementation that mutates a `TerminalBuffer` directly.
+* Behavior-equivalent to the legacy direct-mutation path. Used during
+* the Phase 2 transition: renderers route through the sink, but with
+* `BufferSink` the actual buffer mutation is unchanged.
+*
+* Once every renderer call site routes through a sink, swapping
+* `BufferSink` for `PlanSink` at one entry point flips the renderer
+* onto the plan/commit substrate.
+*/
+var BufferSink = class {
+	constructor(buffer) {
+		this.buffer = buffer;
+	}
+	selectableCell(cell, selectable) {
+		return selectable === void 0 ? cell : {
+			...cell,
+			selectable
+		};
+	}
+	get width() {
+		return this.buffer.width;
+	}
+	get height() {
+		return this.buffer.height;
+	}
+	emitScrollRegion(x, y, width, height, delta, clearCell = {}, selectable) {
+		this.buffer.scrollRegion(x, y, width, height, delta, this.selectableCell(clearCell, selectable));
+	}
+	emitClearRect(x, y, width, height, bg, selectable) {
+		this.buffer.fill(x, y, width, height, {
+			char: " ",
+			bg,
+			selectable
+		});
+	}
+	emitClearCells(x, y, width, height, cell, selectable) {
+		this.buffer.fill(x, y, width, height, this.selectableCell(cell, selectable));
+	}
+	emitSetCell(x, y, cell, selectable) {
+		assertCellInsideBorderedRect(x, y, {
+			char: cell.char,
+			fg: cell.fg,
+			bg: cell.bg
+		});
+		this.buffer.setCell(x, y, this.selectableCell(cell, selectable));
+	}
+	emitPaintFill(x, y, width, height, cell, selectable) {
+		this.buffer.fill(x, y, width, height, this.selectableCell(cell, selectable));
+	}
+	emitFillBg(x, y, width, height, bg) {
+		this.buffer.fillBg(x, y, width, height, bg);
+	}
+	emitRestyleRegion(x, y, width, height, style) {
+		this.buffer.restyleRegion(x, y, width, height, style);
+	}
+	emitMergeAttrs(x, y, width, height, attrs, underlineColor) {
+		this.buffer.mergeAttrsInRect(x, y, width, height, attrs, underlineColor);
+	}
+	setRowMeta(row, meta) {
+		this.buffer.setRowMeta(row, meta);
+	}
+	setOutlineSnapshots(_snapshots) {}
+};
+/**
+* `RenderSink` that fans every emission out to a PRIMARY sink and a
+* SECONDARY sink. Used by the SILVERY_RENDER_PLAN production wiring:
+*
+*   - primary = `BufferSink(buffer)`: keeps direct buffer mutation so
+*     intra-frame buffer reads (`getCellBg`, dirty rows, snapshot reads)
+*     return correct values during the render walk. Read-elimination is
+*     the Phase 2 Step 6 follow-up.
+*   - secondary = `PlanSink`: captures the same emissions into a
+*     `SectionedRenderPlan` for parity verification or for committing
+*     onto a fresh clone in plan-mode.
+*
+* The Tee fans every method to both sinks unconditionally. Since both
+* are in lock-step, the plan captures exactly the ops that were applied
+* to the buffer.
+*/
+var TeeSink = class {
+	constructor(primary, secondary) {
+		this.primary = primary;
+		this.secondary = secondary;
+	}
+	get width() {
+		return this.primary.width;
+	}
+	get height() {
+		return this.primary.height;
+	}
+	emitScrollRegion(x, y, width, height, delta, clearCell, selectable) {
+		this.primary.emitScrollRegion(x, y, width, height, delta, clearCell, selectable);
+		this.secondary.emitScrollRegion(x, y, width, height, delta, clearCell, selectable);
+	}
+	emitClearRect(x, y, width, height, bg, selectable) {
+		this.primary.emitClearRect(x, y, width, height, bg, selectable);
+		this.secondary.emitClearRect(x, y, width, height, bg, selectable);
+	}
+	emitClearCells(x, y, width, height, cell, selectable) {
+		this.primary.emitClearCells(x, y, width, height, cell, selectable);
+		this.secondary.emitClearCells(x, y, width, height, cell, selectable);
+	}
+	emitSetCell(x, y, cell, selectable) {
+		this.primary.emitSetCell(x, y, cell, selectable);
+		this.secondary.emitSetCell(x, y, cell, selectable);
+	}
+	emitPaintFill(x, y, width, height, cell, selectable) {
+		this.primary.emitPaintFill(x, y, width, height, cell, selectable);
+		this.secondary.emitPaintFill(x, y, width, height, cell, selectable);
+	}
+	emitFillBg(x, y, width, height, bg) {
+		this.primary.emitFillBg(x, y, width, height, bg);
+		this.secondary.emitFillBg(x, y, width, height, bg);
+	}
+	emitRestyleRegion(x, y, width, height, style) {
+		this.primary.emitRestyleRegion(x, y, width, height, style);
+		this.secondary.emitRestyleRegion(x, y, width, height, style);
+	}
+	emitMergeAttrs(x, y, width, height, attrs, underlineColor) {
+		this.primary.emitMergeAttrs(x, y, width, height, attrs, underlineColor);
+		this.secondary.emitMergeAttrs(x, y, width, height, attrs, underlineColor);
+	}
+	setRowMeta(row, meta) {
+		this.primary.setRowMeta(row, meta);
+		this.secondary.setRowMeta(row, meta);
+	}
+	setOutlineSnapshots(snapshots) {
+		this.primary.setOutlineSnapshots(snapshots);
+		this.secondary.setOutlineSnapshots(snapshots);
+	}
+};
+/**
+* The PlanSink that the current frame's BufferSink instances should also
+* record to (when SILVERY_RENDER_PLAN is enabled). Set by `withPlanCapture`
+* around a render-phase call; null at all other times.
+*
+* Module-level state because every renderer in render-phase / render-box /
+* render-text / decoration-phase constructs its own local sink. The
+* factory below reads this so all of them emit to the same plan.
+*/
+let _frameCapturePlanSink = null;
+/**
+* Run `fn` with frame-level plan capture enabled. Returns the plan
+* captured during `fn` along with whatever `fn` returned.
+*
+* Production wire path for SILVERY_RENDER_PLAN: ag.ts wraps the
+* `renderPhase()` call in `withPlanCapture(...)` and gets back both the
+* rendered buffer (already mutated by BufferSink-on-real-buffer) and the
+* matching `SectionedRenderPlan`. The plan can then be replayed onto a
+* fresh clone for parity verification, or used directly when buffer-read
+* elimination (Step 6) lets PlanSink stand alone.
+*/
+function withPlanCapture(width, height, fn) {
+	const captured = new PlanSink(width, height);
+	const prev = _frameCapturePlanSink;
+	_frameCapturePlanSink = captured;
+	try {
+		return {
+			result: fn(),
+			plan: captured.toPlan()
+		};
+	} finally {
+		_frameCapturePlanSink = prev;
+	}
+}
+/**
+* Construct the right sink for a renderer call site. By default
+* (`SILVERY_RENDER_PLAN` not set), returns a plain `BufferSink(buffer)`.
+*
+* When inside a `withPlanCapture` scope, returns a `TeeSink` that fans
+* every emission to BOTH the BufferSink AND the frame-shared PlanSink.
+* This is how every local sink construction in render-phase /
+* render-box / render-text / decoration-phase contributes to a single
+* SectionedRenderPlan for the frame.
+*/
+function createFrameSink(buffer) {
+	const direct = new BufferSink(buffer);
+	if (_frameCapturePlanSink === null) return direct;
+	return new TeeSink(direct, _frameCapturePlanSink);
+}
+/**
+* `RenderSink` implementation that builds a `SectionedRenderPlan` directly
+* — no heuristics, no backing buffer for reads (yet — see file header
+* REMAINING). Each emit method routes the op into the corresponding
+* section.
+*
+* This is the L4 substrate: ops land in their section by API call, not
+* by classification of post-hoc mutations. Wrong-order paint becomes
+* unrepresentable because a clear API call cannot land in `paintOps` —
+* it goes through `emitClearRect` which writes to `cleanupOps`.
+*
+* Limitation: the sink has no buffer to back reads. Renderers that
+* currently read from the buffer mid-frame (`getCellBg`, dirty row
+* checks, outline snapshot reads) will not work with `PlanSink`
+* directly. Phase 2 Step 4 audits and eliminates those reads. Until
+* then, `PlanSink` is for synthetic plans + tests; production routing
+* waits on Step 4.
+*/
+var PlanSink = class {
+	transferOps = [];
+	cleanupOps = [];
+	paintOps = [];
+	overlayOps = [];
+	postStateOps = [];
+	constructor(width, height) {
+		this.width = width;
+		this.height = height;
+	}
+	emitScrollRegion(x, y, width, height, delta, clearCell, selectable) {
+		this.transferOps.push({
+			kind: "scrollRegion",
+			x,
+			y,
+			width,
+			height,
+			delta,
+			clearCell: clearCell ? this.selectableCell(clearCell, selectable) : void 0,
+			selectable
+		});
+	}
+	emitClearRect(x, y, width, height, bg, selectable) {
+		this.cleanupOps.push({
+			kind: "clearRect",
+			x,
+			y,
+			width,
+			height,
+			bg,
+			selectable
+		});
+	}
+	emitClearCells(x, y, width, height, cell, selectable) {
+		this.cleanupOps.push({
+			kind: "clearCells",
+			x,
+			y,
+			width,
+			height,
+			cell: this.selectableCell(cell, selectable)
+		});
+	}
+	emitSetCell(x, y, cell, selectable) {
+		this.paintOps.push({
+			kind: "setCell",
+			x,
+			y,
+			cell: this.selectableCell(cell, selectable)
+		});
+	}
+	emitPaintFill(x, y, width, height, cell, selectable) {
+		this.paintOps.push({
+			kind: "paintFill",
+			x,
+			y,
+			width,
+			height,
+			cell: this.selectableCell(cell, selectable)
+		});
+	}
+	emitFillBg(x, y, width, height, bg) {
+		this.paintOps.push({
+			kind: "fillBg",
+			x,
+			y,
+			width,
+			height,
+			bg
+		});
+	}
+	emitRestyleRegion(x, y, width, height, style) {
+		this.paintOps.push({
+			kind: "restyleRegion",
+			x,
+			y,
+			width,
+			height,
+			style: cloneStyle(style)
+		});
+	}
+	emitMergeAttrs(x, y, width, height, attrs, underlineColor) {
+		this.overlayOps.push({
+			kind: "mergeAttrsInRect",
+			x,
+			y,
+			width,
+			height,
+			attrs: { ...attrs },
+			underlineColor
+		});
+	}
+	setRowMeta(row, meta) {
+		this.postStateOps.push({
+			kind: "setRowMeta",
+			row,
+			...meta
+		});
+	}
+	setOutlineSnapshots(snapshots) {
+		this.postStateOps.push({
+			kind: "setOutlineSnapshots",
+			snapshots: snapshots.map((snapshot) => ({
+				...snapshot,
+				cell: cloneCell(snapshot.cell)
+			}))
+		});
+	}
+	selectableCell(cell, selectable) {
+		const cloned = cloneCellPatch(cell);
+		return selectable === void 0 ? cloned : {
+			...cloned,
+			selectable
+		};
+	}
+	/**
+	* Snapshot the accumulated emissions as an immutable
+	* `SectionedRenderPlan`. After calling this, further emissions on the
+	* sink do not affect the returned plan.
+	*/
+	toPlan() {
+		return {
+			width: this.width,
+			height: this.height,
+			transferOps: this.transferOps.slice(),
+			cleanupOps: this.cleanupOps.slice(),
+			paintOps: this.paintOps.slice(),
+			overlayOps: this.overlayOps.slice(),
+			postStateOps: this.postStateOps.slice()
+		};
+	}
+};
+//#endregion
 //#region packages/ag-term/src/pipeline/render-text.ts
 init_buffer();
 const log$1 = createLogger("silvery:content");
@@ -1663,6 +3217,7 @@ function styleToAnsi(style) {
 	}
 	if (style.inverse) parts.push("7");
 	if (style.strikethrough) parts.push("9");
+	if (style.overline) parts.push("53");
 	if (parts.length === 0) return "";
 	return `\x1b[${parts.join(";")}m`;
 }
@@ -1671,15 +3226,31 @@ function styleToAnsi(style) {
 * Child values override parent values when specified.
 */
 function mergeStyleContext(parent, childProps) {
+	const effectiveChildColor = childProps.color === "inherit" || childProps.color === "currentColor" ? parent.color : childProps.color;
+	const childUl = childProps.underline;
+	const childUlStyle = childProps.underlineStyle;
+	let childUnderline;
+	let childUnderlineStyle;
+	if (childUlStyle !== void 0) {
+		childUnderline = childUlStyle === false ? false : true;
+		childUnderlineStyle = childUlStyle;
+	} else if (typeof childUl === "string") {
+		childUnderline = true;
+		childUnderlineStyle = childUl;
+	} else if (childUl !== void 0) {
+		childUnderline = childUl;
+		childUnderlineStyle = void 0;
+	}
 	return {
-		color: (childProps.color === "inherit" || childProps.color === "currentColor" ? parent.color : childProps.color) ?? parent.color,
+		color: effectiveChildColor ?? parent.color,
 		backgroundColor: childProps.backgroundColor ?? parent.backgroundColor,
 		bold: childProps.bold ?? parent.bold,
-		dim: childProps.dim ?? childProps.dimColor ?? parent.dim,
+		dim: parent.dim,
 		italic: childProps.italic ?? parent.italic,
-		underline: childProps.underline ?? childProps.underlineStyle ? true : parent.underline,
-		underlineStyle: childProps.underlineStyle ?? parent.underlineStyle,
+		underline: childUnderline ?? parent.underline,
+		underlineStyle: childUnderlineStyle ?? parent.underlineStyle,
 		underlineColor: childProps.underlineColor ?? parent.underlineColor,
+		overline: childProps.overline ?? parent.overline,
 		inverse: childProps.inverse ?? parent.inverse,
 		strikethrough: childProps.strikethrough ?? parent.strikethrough
 	};
@@ -1800,9 +3371,12 @@ function collectTextWithBg(node, parentContext = {}, offset = 0, maxDisplayWidth
 * @param lineCharEnd - Character offset in original text where this line ends
 * @param bgSegments - Background color segments to apply
 */
-function applyBgSegmentsToLine(buffer, x, y, lineText, lineCharStart, lineCharEnd, bgSegments, ctx) {
+function applyBgSegmentsToLine(buffer, x, y, lineText, lineCharStart, lineCharEnd, bgSegments, ctx, maxCol, minCol, selectable = false) {
 	if (bgSegments.length === 0) return;
-	if (y < 0 || y >= buffer.height) return;
+	const sink = createFrameSink(buffer);
+	if (y < 0 || y >= sink.height) return;
+	const rightClip = maxCol !== void 0 ? Math.min(maxCol, sink.width) : sink.width;
+	const leftClip = minCol !== void 0 ? Math.max(minCol, 0) : 0;
 	const bgCell = createMutableCell();
 	const gWidthFn = ctx ? ctx.measurer.graphemeWidth : graphemeWidth;
 	for (const seg of bgSegments) {
@@ -1818,17 +3392,20 @@ function applyBgSegmentsToLine(buffer, x, y, lineText, lineCharStart, lineCharEn
 			if (gWidth === 0) continue;
 			const displayOffset = col - x;
 			if (displayOffset >= relStart && displayOffset < relEnd) {
-				buffer.readCellInto(col, y, bgCell);
-				bgCell.bg = seg.bg;
-				buffer.setCell(col, y, bgCell);
-				if (gWidth === 2 && col + 1 < buffer.width) {
-					buffer.readCellInto(col + 1, y, bgCell);
+				if (col < rightClip && col >= leftClip) {
+					buffer.readCellInto(col, y, bgCell);
 					bgCell.bg = seg.bg;
-					buffer.setCell(col + 1, y, bgCell);
+					sink.emitSetCell(col, y, bgCell, selectable);
+					if (gWidth === 2 && col + 1 < sink.width && col + 1 < rightClip) {
+						buffer.readCellInto(col + 1, y, bgCell);
+						bgCell.bg = seg.bg;
+						sink.emitSetCell(col + 1, y, bgCell, selectable);
+					}
 				}
 			}
 			col += gWidth;
 			if (col - x >= relEnd) break;
+			if (col >= rightClip) break;
 		}
 	}
 }
@@ -1949,6 +3526,10 @@ function formatTextLines(text, width, wrap, ctx, trim = true) {
 	if (wrap === "truncate-start") return lines.map((line) => truncateText(line, width, "start", ctx));
 	if (wrap === "truncate-middle") return lines.map((line) => truncateText(line, width, "middle", ctx));
 	if (wrap === "even") return optimalWrap(normalizedText, buildTextAnalysis(normalizedText, ctx?.measurer?.graphemeWidth?.bind(ctx.measurer) ?? graphemeWidth), width);
+	if (wrap === "wrap-truncate") {
+		if (ctx) return ctx.measurer.wrapText(normalizedText, width, true, false, true);
+		return wrapText(normalizedText, width, true, true, true);
+	}
 	if (ctx) return ctx.measurer.wrapText(normalizedText, width, true, trim);
 	return wrapText(normalizedText, width, true, trim);
 }
@@ -1979,20 +3560,20 @@ function truncateText(text, width, mode, ctx) {
 *   become stale during incremental rendering (the owning container's dirty
 *   tracking doesn't cover cells outside its layout bounds).
 */
-function renderTextLine(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx) {
+function renderTextLine(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, selectable = false) {
 	if (hasAnsi(text)) {
-		renderAnsiTextLine(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx);
+		renderAnsiTextLine(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, selectable);
 		return;
 	}
-	renderGraphemes(buffer, splitGraphemes(text), x, y, baseStyle, maxCol, inheritedBg, ctx);
+	renderGraphemes(buffer, splitGraphemes(text), x, y, baseStyle, maxCol, inheritedBg, ctx, void 0, selectable);
 }
 /**
 * Like renderTextLine but returns the column position after the last rendered character.
 * Used by renderText to know where to clear remaining cells.
 */
-function renderTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, minCol) {
-	if (hasAnsi(text)) return renderAnsiTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, minCol);
-	return renderGraphemes(buffer, splitGraphemes(text), x, y, baseStyle, maxCol, inheritedBg, ctx, minCol);
+function renderTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, minCol, selectable = false, bgConflictOverride) {
+	if (hasAnsi(text)) return renderAnsiTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, minCol, selectable, bgConflictOverride);
+	return renderGraphemes(buffer, splitGraphemes(text), x, y, baseStyle, maxCol, inheritedBg, ctx, minCol, selectable);
 }
 /**
 * Render graphemes to buffer cells with proper Unicode handling.
@@ -2011,9 +3592,10 @@ function renderTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inheritedBg
 *
 * Returns the column position after the last rendered grapheme.
 */
-function renderGraphemes(buffer, graphemes, startCol, y, style, maxCol, inheritedBg, ctx, minCol) {
+function renderGraphemes(buffer, graphemes, startCol, y, style, maxCol, inheritedBg, ctx, minCol, selectable = false) {
+	const sink = createFrameSink(buffer);
 	let col = startCol;
-	const rightEdge = maxCol !== void 0 ? Math.min(maxCol, buffer.width) : buffer.width;
+	const rightEdge = maxCol !== void 0 ? Math.min(maxCol, sink.width) : sink.width;
 	const leftEdge = minCol !== void 0 ? Math.max(minCol, 0) : 0;
 	const gWidthFn = ctx ? ctx.measurer.graphemeWidth : graphemeWidth;
 	for (const grapheme of graphemes) {
@@ -2028,9 +3610,9 @@ function renderGraphemes(buffer, graphemes, startCol, y, style, maxCol, inherite
 			col = leftEdge;
 			continue;
 		}
-		const existingBg = style.bg !== null ? style.bg : inheritedBg !== void 0 ? inheritedBg : buffer.getCellBg(col, y);
+		const existingBg = style.bg !== null ? style.bg : inheritedBg !== void 0 ? inheritedBg : null;
 		if (width === 2 && col + 1 >= rightEdge) {
-			buffer.setCell(col, y, {
+			sink.emitSetCell(col, y, {
 				char: " ",
 				fg: style.fg,
 				bg: existingBg,
@@ -2039,12 +3621,12 @@ function renderGraphemes(buffer, graphemes, startCol, y, style, maxCol, inherite
 				wide: false,
 				continuation: false,
 				hyperlink: style.hyperlink
-			});
+			}, false);
 			col += 1;
 			continue;
 		}
 		const outputChar = width === 2 ? ensureEmojiPresentation(grapheme) : grapheme;
-		buffer.setCell(col, y, {
+		sink.emitSetCell(col, y, {
 			char: outputChar,
 			fg: style.fg,
 			bg: existingBg,
@@ -2053,10 +3635,10 @@ function renderGraphemes(buffer, graphemes, startCol, y, style, maxCol, inherite
 			wide: width === 2,
 			continuation: false,
 			hyperlink: style.hyperlink
-		});
-		if (width === 2 && col + 1 < buffer.width) {
-			const existingBg2 = style.bg !== null ? style.bg : inheritedBg !== void 0 ? inheritedBg : buffer.getCellBg(col + 1, y);
-			buffer.setCell(col + 1, y, {
+		}, selectable);
+		if (width === 2 && col + 1 < sink.width) {
+			const existingBg2 = style.bg !== null ? style.bg : inheritedBg !== void 0 ? inheritedBg : null;
+			sink.emitSetCell(col + 1, y, {
 				char: "",
 				fg: style.fg,
 				bg: existingBg2,
@@ -2065,7 +3647,7 @@ function renderGraphemes(buffer, graphemes, startCol, y, style, maxCol, inherite
 				wide: false,
 				continuation: true,
 				hyperlink: style.hyperlink
-			});
+			}, selectable);
 			col += 2;
 		} else col += width;
 	}
@@ -2075,20 +3657,21 @@ function renderGraphemes(buffer, graphemes, startCol, y, style, maxCol, inherite
 * Render text line with ANSI escape sequences.
 * Parses ANSI codes and applies styles to individual segments.
 */
-function renderAnsiTextLine(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx) {
-	renderAnsiTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx);
+function renderAnsiTextLine(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, selectable = false) {
+	renderAnsiTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, void 0, selectable);
 }
 /**
 * Like renderAnsiTextLine but returns the column position after the last rendered character.
 */
-function renderAnsiTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, minCol) {
+function renderAnsiTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inheritedBg, ctx, minCol, selectable = false, bgConflictOverride) {
+	createFrameSink(buffer);
 	const segments = parseAnsiText(text);
 	let col = x;
 	for (const segment of segments) {
 		const style = mergeAnsiStyle(baseStyle, segment);
-		const effectiveBgConflictMode = ctx?.bgConflictMode ?? getBgConflictMode();
+		const effectiveBgConflictMode = bgConflictOverride ?? ctx?.bgConflictMode ?? getBgConflictMode();
 		if (effectiveBgConflictMode !== "ignore" && !segment.bgOverride && segment.bg !== void 0 && segment.bg !== null) {
-			const existingBufBg = col < buffer.width ? buffer.getCellBg(col, y) : null;
+			const existingBufBg = inheritedBg !== void 0 ? inheritedBg : null;
 			if (baseStyle.bg !== null || existingBufBg !== null) {
 				const preview = segment.text.slice(0, 30);
 				const chalkBg = formatBgConflictColor(segment.bg);
@@ -2104,7 +3687,7 @@ function renderAnsiTextLineReturn(buffer, x, y, text, baseStyle, maxCol, inherit
 				}
 			}
 		}
-		col = renderGraphemes(buffer, splitGraphemes(segment.text), col, y, style, maxCol, inheritedBg, ctx, minCol);
+		col = renderGraphemes(buffer, splitGraphemes(segment.text), col, y, style, maxCol, inheritedBg, ctx, minCol, selectable);
 	}
 	return col;
 }
@@ -2135,10 +3718,12 @@ function mergeStyles(base, overlay, options = {}) {
 			attrs.underlineStyle = overlayAttrs.underlineStyle ?? baseAttrs.underlineStyle ?? "single";
 		}
 		attrs.strikethrough = overlayAttrs.strikethrough || baseAttrs.strikethrough;
+		attrs.overline = overlayAttrs.overline || baseAttrs.overline;
 	} else {
 		attrs.underline = overlayAttrs.underline ?? baseAttrs.underline;
 		attrs.underlineStyle = overlayAttrs.underlineStyle ?? baseAttrs.underlineStyle;
 		attrs.strikethrough = overlayAttrs.strikethrough ?? baseAttrs.strikethrough;
+		attrs.overline = overlayAttrs.overline ?? baseAttrs.overline;
 	}
 	if (preserveEmphasis) {
 		attrs.bold = overlayAttrs.bold || baseAttrs.bold;
@@ -2178,6 +3763,8 @@ function mergeAnsiStyle(base, segment, options = {}) {
 	if (segment.underline !== void 0) overlayAttrs.underline = segment.underline;
 	if (segment.underlineStyle !== void 0) overlayAttrs.underlineStyle = segment.underlineStyle;
 	if (segment.inverse !== void 0) overlayAttrs.inverse = segment.inverse;
+	if (segment.strikethrough !== void 0) overlayAttrs.strikethrough = segment.strikethrough;
+	if (segment.overline !== void 0) overlayAttrs.overline = segment.overline;
 	const merged = mergeStyles(base, {
 		fg,
 		bg,
@@ -2215,6 +3802,7 @@ function ansiColorToColor(code) {
 * See km-silvery.bg-bleed for details.
 */
 function renderText(node, buffer, layout, props, nodeState, inheritedBg, inheritedFg, ctx) {
+	const sink = createFrameSink(buffer);
 	const { scrollOffset, clipBounds } = nodeState;
 	const { x, width, height } = layout;
 	let { y } = layout;
@@ -2236,20 +3824,29 @@ function renderText(node, buffer, layout, props, nodeState, inheritedBg, inherit
 			lineCount = (plainText.match(/\n/g)?.length ?? 0) + 1;
 			setCachedPlainText(node, plainText, lineCount);
 		}
-		maxDisplayWidth = (width + 1) * lineCount;
+		maxDisplayWidth = (width + 2) * lineCount;
 	}
 	let text;
 	let bgSegments;
 	let childSpans;
+	let rootUnderline;
+	let rootUnderlineStyle;
+	if (props.underlineStyle !== void 0) {
+		rootUnderline = props.underlineStyle !== false;
+		rootUnderlineStyle = props.underlineStyle;
+	} else if (typeof props.underline === "string") {
+		rootUnderline = true;
+		rootUnderlineStyle = props.underline;
+	} else if (props.underline !== void 0) rootUnderline = props.underline;
 	const rootContext = {
 		color: props.color,
 		backgroundColor: props.backgroundColor,
 		bold: props.bold,
-		dim: props.dim || props.dimColor,
 		italic: props.italic,
-		underline: !!(props.underline || props.underlineStyle),
-		underlineStyle: props.underlineStyle,
+		underline: rootUnderline,
+		underlineStyle: rootUnderlineStyle,
 		underlineColor: props.underlineColor,
+		overline: props.overline,
 		inverse: props.inverse,
 		strikethrough: props.strikethrough
 	};
@@ -2288,14 +3885,16 @@ function renderText(node, buffer, layout, props, nodeState, inheritedBg, inherit
 		const lineY = y + lineIdx;
 		if (clipBounds && (lineY < clipBounds.top || lineY >= clipBounds.bottom)) continue;
 		const line = lines[lineIdx];
-		const layoutRight = internalTransform ? buffer.width : x + width;
+		const layoutRight = internalTransform ? sink.width : x + width;
 		const maxCol = clipBounds && "right" in clipBounds && clipBounds.right !== void 0 ? Math.min(layoutRight, clipBounds.right) : layoutRight;
 		const minCol = clipBounds && "left" in clipBounds && clipBounds.left !== void 0 ? clipBounds.left : void 0;
-		const endCol = renderTextLineReturn(buffer, x, lineY, line, style, maxCol, inheritedBg, ctx, minCol);
+		const lineTextForSelection = hasAnsi(line) ? stripAnsiForBg(line) : line;
+		const lineSelectable = nodeState.selectableMode && /\S/.test(lineTextForSelection);
+		const endCol = renderTextLineReturn(buffer, x, lineY, line, style, maxCol, inheritedBg, ctx, minCol, lineSelectable, props.bgConflict);
 		const clearStart = minCol !== void 0 ? Math.max(endCol, minCol) : endCol;
 		if (clearStart < maxCol) {
 			const clearBg = inheritedBg ?? null;
-			for (let cx = clearStart; cx < maxCol && cx < buffer.width; cx++) buffer.setCell(cx, lineY, {
+			const clearCell = {
 				char: " ",
 				fg: style.fg,
 				bg: clearBg,
@@ -2305,6 +3904,7 @@ function renderText(node, buffer, layout, props, nodeState, inheritedBg, inherit
 					dim: false,
 					italic: false,
 					underline: false,
+					overline: false,
 					inverse: false,
 					strikethrough: false,
 					blink: false,
@@ -2312,11 +3912,12 @@ function renderText(node, buffer, layout, props, nodeState, inheritedBg, inherit
 				},
 				wide: false,
 				continuation: false
-			});
+			};
+			for (let cx = clearStart; cx < maxCol && cx < sink.width; cx++) sink.emitClearCells(cx, lineY, 1, 1, clearCell);
 		}
 		if (bgSegments.length > 0 && lineIdx < lineOffsets.length) {
 			const { start, end } = lineOffsets[lineIdx];
-			applyBgSegmentsToLine(buffer, x, lineY, line, start, end, bgSegments, ctx);
+			applyBgSegmentsToLine(buffer, x, lineY, line, start, end, bgSegments, ctx, maxCol, minCol, lineSelectable);
 		}
 	}
 	if (childSpans.length > 0 && lineOffsets.length > 0) computeInlineRects(childSpans, lineOffsets, x, y, lines.length, height);
@@ -2378,6 +3979,7 @@ function getEffectiveBg(props) {
 * Render a Box node.
 */
 function renderBox(_node, buffer, layout, props, nodeState, skipBgFill = false, inheritedBg, bgOnlyChange = false, inheritedFg) {
+	const sink = createFrameSink(buffer);
 	const { scrollOffset, clipBounds } = nodeState;
 	const { x, width, height } = layout;
 	const y = layout.y - scrollOffset;
@@ -2399,17 +4001,17 @@ function renderBox(_node, buffer, layout, props, nodeState, skipBgFill = false,
 				clippedX = Math.max(x, clipBounds.left);
 				clippedWidth = Math.min(x + width, clipBounds.right) - clippedX;
 			}
-			if (clippedHeight > 0 && clippedWidth > 0) if (bgOnlyChange) buffer.fillBg(clippedX, clippedY, clippedWidth, clippedHeight, bg);
-			else buffer.fill(clippedX, clippedY, clippedWidth, clippedHeight, { bg });
-		} else if (bgOnlyChange) buffer.fillBg(x, y, width, height, bg);
-		else buffer.fill(x, y, width, height, { bg });
+			if (clippedHeight > 0 && clippedWidth > 0) if (bgOnlyChange) sink.emitFillBg(clippedX, clippedY, clippedWidth, clippedHeight, bg);
+			else sink.emitPaintFill(clippedX, clippedY, clippedWidth, clippedHeight, { bg });
+		} else if (bgOnlyChange) sink.emitFillBg(x, y, width, height, bg);
+		else sink.emitPaintFill(x, y, width, height, { bg });
 	}
-	if (props.borderStyle) renderBorder(buffer, x, y, width, height, props, clipBounds, inheritedBg, inheritedFg);
+	if (props.borderStyle) renderBorder(buffer, sink, x, y, width, height, props, clipBounds, inheritedBg, inheritedFg);
 }
 /**
 * Render a border around a box.
 */
-function renderBorder(buffer, x, y, width, height, props, clipBounds, inheritedBg, inheritedFg) {
+function renderBorder(buffer, sink, x, y, width, height, props, clipBounds, inheritedBg, inheritedFg) {
 	const chars = getBorderChars(props.borderStyle ?? "single");
 	let color;
 	if (props.borderColor === "currentColor" || props.borderColor === "inherit") color = props.color ? parseColor(props.color) : inheritedFg ?? null;
@@ -2430,27 +4032,27 @@ function renderBorder(buffer, x, y, width, height, props, clipBounds, inheritedB
 	const showLeft = props.borderLeft !== false;
 	const showRight = props.borderRight !== false;
 	const isRowVisible = (row) => {
-		if (!clipBounds) return row >= 0 && row < buffer.height;
-		return row >= clipBounds.top && row < clipBounds.bottom && row < buffer.height;
+		if (!clipBounds) return row >= 0 && row < sink.height;
+		return row >= clipBounds.top && row < clipBounds.bottom && row < sink.height;
 	};
 	const isColVisible = (col) => {
-		if (clipBounds?.left === void 0 || clipBounds.right === void 0) return col >= 0 && col < buffer.width;
-		return col >= clipBounds.left && col < clipBounds.right && col < buffer.width;
+		if (clipBounds?.left === void 0 || clipBounds.right === void 0) return col >= 0 && col < sink.width;
+		return col >= clipBounds.left && col < clipBounds.right && col < sink.width;
 	};
 	if (showTop && isRowVisible(y)) {
-		if (showLeft && isColVisible(x)) buffer.setCell(x, y, {
+		if (showLeft && isColVisible(x)) sink.emitSetCell(x, y, {
 			char: chars.topLeft,
 			fg: color,
 			bg: topBg
 		});
 		const hStart = showLeft ? x + 1 : x;
 		const hEnd = showRight ? x + width - 1 : x + width;
-		for (let col = hStart; col < hEnd && col < buffer.width; col++) if (isColVisible(col)) buffer.setCell(col, y, {
+		for (let col = hStart; col < hEnd && col < sink.width; col++) if (isColVisible(col)) sink.emitSetCell(col, y, {
 			char: chars.horizontal,
 			fg: color,
 			bg: topBg
 		});
-		if (showRight && x + width - 1 < buffer.width && isColVisible(x + width - 1)) buffer.setCell(x + width - 1, y, {
+		if (showRight && x + width - 1 < sink.width && isColVisible(x + width - 1)) sink.emitSetCell(x + width - 1, y, {
 			char: chars.topRight,
 			fg: color,
 			bg: topBg
@@ -2461,12 +4063,12 @@ function renderBorder(buffer, x, y, width, height, props, clipBounds, inheritedB
 	const sideEnd = showBottom ? y + height - 1 : y + height;
 	for (let row = sideStart; row < sideEnd; row++) {
 		if (!isRowVisible(row)) continue;
-		if (showLeft && isColVisible(x)) buffer.setCell(x, row, {
+		if (showLeft && isColVisible(x)) sink.emitSetCell(x, row, {
 			char: chars.vertical,
 			fg: color,
 			bg: leftBg
 		});
-		if (showRight && x + width - 1 < buffer.width && isColVisible(x + width - 1)) buffer.setCell(x + width - 1, row, {
+		if (showRight && x + width - 1 < sink.width && isColVisible(x + width - 1)) sink.emitSetCell(x + width - 1, row, {
 			char: rightVertical,
 			fg: color,
 			bg: rightBg
@@ -2475,19 +4077,19 @@ function renderBorder(buffer, x, y, width, height, props, clipBounds, inheritedB
 	const bottomHorizontal = chars.bottomHorizontal ?? chars.horizontal;
 	const bottomY = y + height - 1;
 	if (showBottom && isRowVisible(bottomY)) {
-		if (showLeft && isColVisible(x)) buffer.setCell(x, bottomY, {
+		if (showLeft && isColVisible(x)) sink.emitSetCell(x, bottomY, {
 			char: chars.bottomLeft,
 			fg: color,
 			bg: bottomBg
 		});
 		const bStart = showLeft ? x + 1 : x;
 		const bEnd = showRight ? x + width - 1 : x + width;
-		for (let col = bStart; col < bEnd && col < buffer.width; col++) if (isColVisible(col)) buffer.setCell(col, bottomY, {
+		for (let col = bStart; col < bEnd && col < sink.width; col++) if (isColVisible(col)) sink.emitSetCell(col, bottomY, {
 			char: bottomHorizontal,
 			fg: color,
 			bg: bottomBg
 		});
-		if (showRight && x + width - 1 < buffer.width && isColVisible(x + width - 1)) buffer.setCell(x + width - 1, bottomY, {
+		if (showRight && x + width - 1 < sink.width && isColVisible(x + width - 1)) sink.emitSetCell(x + width - 1, bottomY, {
 			char: chars.bottomRight,
 			fg: color,
 			bg: bottomBg
@@ -2504,7 +4106,7 @@ function renderBorder(buffer, x, y, width, height, props, clipBounds, inheritedB
 * The outline occupies cells at (x-1, y-1) through (x+width, y+height) —
 * entirely outside the box's own rect. Content is never overlapped.
 */
-function renderOutline(buffer, x, y, width, height, props, clipBounds, inheritedBg) {
+function renderOutline(buffer, sink, x, y, width, height, props, clipBounds, inheritedBg) {
 	const chars = getBorderChars(props.outlineStyle ?? "single");
 	const color = props.outlineColor ? parseColor(props.outlineColor) : null;
 	const bg = props.backgroundColor ? parseColor(props.backgroundColor) : inheritedBg ?? null;
@@ -2514,31 +4116,31 @@ function renderOutline(buffer, x, y, width, height, props, clipBounds, inherited
 	const ow = width + 2;
 	const oh = height + 2;
 	const isRowVisible = (row) => {
-		if (!clipBounds) return row >= 0 && row < buffer.height;
-		return row >= clipBounds.top && row < clipBounds.bottom && row < buffer.height;
+		if (!clipBounds) return row >= 0 && row < sink.height;
+		return row >= clipBounds.top && row < clipBounds.bottom && row < sink.height;
 	};
 	const isColVisible = (col) => {
-		if (clipBounds?.left === void 0 || clipBounds.right === void 0) return col >= 0 && col < buffer.width;
-		return col >= clipBounds.left && col < clipBounds.right && col < buffer.width;
+		if (clipBounds?.left === void 0 || clipBounds.right === void 0) return col >= 0 && col < sink.width;
+		return col >= clipBounds.left && col < clipBounds.right && col < sink.width;
 	};
 	const showTop = props.outlineTop !== false;
 	const showBottom = props.outlineBottom !== false;
 	const showLeft = props.outlineLeft !== false;
 	const showRight = props.outlineRight !== false;
 	if (showTop && isRowVisible(oy)) {
-		if (showLeft && isColVisible(ox)) buffer.setCell(ox, oy, {
+		if (showLeft && isColVisible(ox)) sink.emitSetCell(ox, oy, {
 			char: chars.topLeft,
 			fg: color,
 			bg,
 			attrs
 		});
-		for (let col = ox + 1; col < ox + ow - 1 && col < buffer.width; col++) if (isColVisible(col)) buffer.setCell(col, oy, {
+		for (let col = ox + 1; col < ox + ow - 1 && col < sink.width; col++) if (isColVisible(col)) sink.emitSetCell(col, oy, {
 			char: chars.horizontal,
 			fg: color,
 			bg,
 			attrs
 		});
-		if (showRight && ox + ow - 1 < buffer.width && isColVisible(ox + ow - 1)) buffer.setCell(ox + ow - 1, oy, {
+		if (showRight && ox + ow - 1 < sink.width && isColVisible(ox + ow - 1)) sink.emitSetCell(ox + ow - 1, oy, {
 			char: chars.topRight,
 			fg: color,
 			bg,
@@ -2550,13 +4152,13 @@ function renderOutline(buffer, x, y, width, height, props, clipBounds, inherited
 	const sideEnd = showBottom ? oy + oh - 1 : oy + oh;
 	for (let row = sideStart; row < sideEnd; row++) {
 		if (!isRowVisible(row)) continue;
-		if (showLeft && isColVisible(ox)) buffer.setCell(ox, row, {
+		if (showLeft && isColVisible(ox)) sink.emitSetCell(ox, row, {
 			char: chars.vertical,
 			fg: color,
 			bg,
 			attrs
 		});
-		if (showRight && ox + ow - 1 < buffer.width && isColVisible(ox + ow - 1)) buffer.setCell(ox + ow - 1, row, {
+		if (showRight && ox + ow - 1 < sink.width && isColVisible(ox + ow - 1)) sink.emitSetCell(ox + ow - 1, row, {
 			char: outlineRightVertical,
 			fg: color,
 			bg,
@@ -2566,19 +4168,19 @@ function renderOutline(buffer, x, y, width, height, props, clipBounds, inherited
 	const outlineBottomHorizontal = chars.bottomHorizontal ?? chars.horizontal;
 	const bottomY = oy + oh - 1;
 	if (showBottom && isRowVisible(bottomY)) {
-		if (showLeft && isColVisible(ox)) buffer.setCell(ox, bottomY, {
+		if (showLeft && isColVisible(ox)) sink.emitSetCell(ox, bottomY, {
 			char: chars.bottomLeft,
 			fg: color,
 			bg,
 			attrs
 		});
-		for (let col = ox + 1; col < ox + ow - 1 && col < buffer.width; col++) if (isColVisible(col)) buffer.setCell(col, bottomY, {
+		for (let col = ox + 1; col < ox + ow - 1 && col < sink.width; col++) if (isColVisible(col)) sink.emitSetCell(col, bottomY, {
 			char: outlineBottomHorizontal,
 			fg: color,
 			bg,
 			attrs
 		});
-		if (showRight && ox + ow - 1 < buffer.width && isColVisible(ox + ow - 1)) buffer.setCell(ox + ow - 1, bottomY, {
+		if (showRight && ox + ow - 1 < sink.width && isColVisible(ox + ow - 1)) sink.emitSetCell(ox + ow - 1, bottomY, {
 			char: chars.bottomRight,
 			fg: color,
 			bg,
@@ -2613,43 +4215,277 @@ function renderScrollIndicators(_node, buffer, layout, props, ss, ctx) {
 		const indicator = `\u25b2${ss.hiddenAbove}`;
 		if (border.top > 0) {
 			const contentWidth = layout.width - border.left - border.right;
-			const bar = padCenter(indicator, contentWidth);
 			const x = layout.x + border.left;
 			const y = layout.y;
-			renderTextLine(buffer, x, y, bar, indicatorStyle, x + contentWidth, void 0, ctx);
+			renderCenteredIndicator(buffer, x, y, indicator, indicatorStyle, contentWidth, x + contentWidth, ctx);
 		} else if (showBorderless) {
 			const padding = getPadding(props);
 			const contentWidth = layout.width - padding.left - padding.right;
-			const bar = padCenter(indicator, contentWidth);
 			const x = layout.x + padding.left;
-			renderTextLine(buffer, x, layout.y + padding.top, bar, indicatorStyle, x + contentWidth, void 0, ctx);
+			renderCenteredIndicator(buffer, x, layout.y + padding.top, indicator, indicatorStyle, contentWidth, x + contentWidth, ctx);
 		}
 	}
 	if (ss.hiddenBelow > 0) {
 		const indicator = `\u25bc${ss.hiddenBelow}`;
 		if (border.bottom > 0) {
 			const contentWidth = layout.width - border.left - border.right;
-			const bar = padCenter(indicator, contentWidth);
 			const x = layout.x + border.left;
-			renderTextLine(buffer, x, layout.y + layout.height - 1, bar, indicatorStyle, x + contentWidth, void 0, ctx);
+			renderCenteredIndicator(buffer, x, layout.y + layout.height - 1, indicator, indicatorStyle, contentWidth, x + contentWidth, ctx);
 		} else if (showBorderless) {
 			const padding = getPadding(props);
 			const contentWidth = layout.width - padding.left - padding.right;
-			const bar = padCenter(indicator, contentWidth);
 			const x = layout.x + padding.left;
-			renderTextLine(buffer, x, layout.y + layout.height - padding.bottom - 1, bar, indicatorStyle, x + contentWidth, void 0, ctx);
+			renderCenteredIndicator(buffer, x, layout.y + layout.height - padding.bottom - 1, indicator, indicatorStyle, contentWidth, x + contentWidth, ctx);
 		}
 	}
 }
-/** Center text within a fixed width, padding with spaces on both sides.
-*  Truncates from the right if text exceeds available width. */
-function padCenter(text, width) {
-	if (width <= 0) return "";
-	if (text.length > width) return text.slice(0, width);
-	if (text.length === width) return text;
-	const leftPad = Math.floor((width - text.length) / 2);
-	const rightPad = width - text.length - leftPad;
-	return " ".repeat(leftPad) + text + " ".repeat(rightPad);
+function renderCenteredIndicator(buffer, x, y, indicator, style, width, maxCol, ctx) {
+	if (width <= 0) return;
+	const text = indicator.length > width ? indicator.slice(0, width) : indicator;
+	const indicatorX = x + Math.max(0, Math.floor((width - text.length) / 2));
+	renderTextLine(buffer, x, y, " ".repeat(width), {
+		fg: null,
+		bg: null,
+		attrs: {}
+	}, maxCol, void 0, ctx);
+	renderTextLine(buffer, indicatorX, y, text, style, Math.min(maxCol, indicatorX + text.length), void 0, ctx);
+}
+//#endregion
+//#region packages/ag-term/src/strict-island.ts
+/**
+* Runtime checks for `<Island>` strict slugs.
+*
+* The Island contract lives in `@silvery/ag`, but SILVERY_STRICT is a
+* terminal-target runtime gate. Keep the instrumentation here so core remains
+* target-agnostic while the terminal renderer can still enforce the contract.
+*/
+/** Tier-2 paint budget: one 256x256 island frame. */
+const ISLAND_PAINT_BUDGET_CELLS = 65536;
+const instrumentedHandles = /* @__PURE__ */ new WeakSet();
+/**
+* Attach strict wrappers to a live island handle once.
+*
+* This is called from the render phase when the terminal target first sees a
+* handle. Wrapping at the target avoids pulling SILVERY_STRICT into `@silvery/ag`.
+*/
+function ensureIslandStrictInstrumentation(node) {
+	if (!needsIslandStrictInstrumentation()) return;
+	const state = node.islandState;
+	const handle = state?.handle;
+	if (!state || !handle || instrumentedHandles.has(handle)) return;
+	instrumentedHandles.add(handle);
+	wrapWriteCells(handle);
+	wrapSubscription(handle.output, state, "output");
+	wrapSubscription(handle.size, state, "size");
+	if (handle.modes) wrapSubscription(handle.modes, state, "modes");
+	if (handle.input) wrapMouseInput(handle.input, handle);
+}
+function needsIslandStrictInstrumentation() {
+	return isStrictEnabled("island-paint-oob", 2) || isStrictEnabled("island-dispose-leak", 2) || isStrictEnabled("island-boundary-limits", 2);
+}
+/** Render-phase checks that do not depend on guest mutation APIs. */
+function assertIslandRenderInvariants(node, layout) {
+	const state = node.islandState;
+	const handle = state?.handle;
+	if (!state || !handle) return;
+	const source = handle.output.buffer;
+	assertResizeRace(handle, source);
+	assertPaintBudget(source, layout);
+	assertGraphemeWidth(source);
+	assertCursorBoundary(handle);
+	assertNoDisposedRender(state);
+}
+function wrapWriteCells(handle) {
+	const original = handle.output.writeCells.bind(handle.output);
+	handle.output.writeCells = (dirtyRects, source) => {
+		assertDirtyRectsInsideIsland(handle, dirtyRects, source);
+		return original(dirtyRects, source);
+	};
+}
+function wrapSubscription(owner, state, label) {
+	const original = owner.subscribe.bind(owner);
+	owner.subscribe = ((listener) => {
+		return original((...args) => {
+			assertNoPostDisposeCallback(state, label);
+			listener(...args);
+		});
+	});
+}
+function wrapMouseInput(input, handle) {
+	if (!input.onMouse) return;
+	const original = input.onMouse.bind(input);
+	input.onMouse = (handler) => {
+		return original((event) => {
+			assertMouseInsideIsland(handle, event);
+			handler(event);
+		});
+	};
+}
+function assertDirtyRectsInsideIsland(handle, dirtyRects, source) {
+	if (!isStrictEnabled("island-paint-oob", 2)) return;
+	const cols = Math.min(handle.size.cols, source.cols);
+	const rows = Math.min(handle.size.rows, source.rows);
+	for (const rect of dirtyRects) {
+		const c1 = rect.col + rect.width;
+		const r1 = rect.row + rect.height;
+		if (!Number.isInteger(rect.col) || !Number.isInteger(rect.row) || !Number.isInteger(rect.width) || !Number.isInteger(rect.height) || rect.col < 0 || rect.row < 0 || rect.width < 0 || rect.height < 0 || c1 > cols || r1 > rows) throw new Error(`[SILVERY_STRICT=island-paint-oob] guest dirty rect ${formatRect(rect)} escapes island ${cols}x${rows}`);
+	}
+}
+function assertResizeRace(handle, source) {
+	if (!isStrictEnabled("island-resize-race", 2)) return;
+	if (source.cols <= handle.size.cols && source.rows <= handle.size.rows) return;
+	throw new Error(`[SILVERY_STRICT=island-resize-race] guest output ${source.cols}x${source.rows} exceeds size-owner acknowledgement ${handle.size.cols}x${handle.size.rows}`);
+}
+function assertPaintBudget(source, layout) {
+	if (!isStrictEnabled("island-paint-budget", 2)) return;
+	const cells = Math.max(0, Math.min(layout.width, source.cols)) * Math.max(0, Math.min(layout.height, source.rows));
+	if (cells <= 65536) return;
+	throw new Error(`[SILVERY_STRICT=island-paint-budget] island paints ${cells} cells in one frame (budget ${ISLAND_PAINT_BUDGET_CELLS})`);
+}
+function assertGraphemeWidth(source) {
+	if (!isStrictEnabled("island-grapheme-width", 2)) return;
+	for (let row = 0; row < source.rows; row++) for (let col = 0; col < source.cols; col++) {
+		const cell = source.getCell(col, row);
+		if (cell.continuation) {
+			if (col === 0 || !source.getCell(col - 1, row).wide) throw new Error(`[SILVERY_STRICT=island-grapheme-width] continuation cell at ${col},${row} has no leading wide cell`);
+			continue;
+		}
+		const width = graphemeWidth(cell.char);
+		if (width === 2) {
+			const next = col + 1 < source.cols ? source.getCell(col + 1, row) : null;
+			if (!cell.wide || !next?.continuation) throw new Error(`[SILVERY_STRICT=island-grapheme-width] wide grapheme ${JSON.stringify(cell.char)} at ${col},${row} is missing wide+continuation metadata`);
+			continue;
+		}
+		if (cell.wide || width > 2) throw new Error(`[SILVERY_STRICT=island-grapheme-width] cell ${JSON.stringify(cell.char)} at ${col},${row} declares wide=${String(cell.wide)} but measures width ${width}`);
+	}
+}
+function assertCursorBoundary(handle) {
+	if (!isStrictEnabled("island-boundary-limits", 2)) return;
+	const cursor = handle.output.cursor;
+	if (!handle.output.cursorVisible || !cursor) return;
+	if (cursor.row >= 0 && cursor.row < handle.size.rows && cursor.col >= 0 && cursor.col < handle.size.cols) return;
+	throw new Error(`[SILVERY_STRICT=island-boundary-limits] guest cursor ${cursor.col},${cursor.row} escapes island ${handle.size.cols}x${handle.size.rows}`);
+}
+function assertMouseInsideIsland(handle, event) {
+	if (!isStrictEnabled("island-boundary-limits", 2)) return;
+	if (event.row >= 0 && event.row < handle.size.rows && event.col >= 0 && event.col < handle.size.cols) return;
+	throw new Error(`[SILVERY_STRICT=island-boundary-limits] mouse event ${event.col},${event.row} escapes island ${handle.size.cols}x${handle.size.rows}`);
+}
+function assertNoPostDisposeCallback(state, label) {
+	if (!isStrictEnabled("island-dispose-leak", 2)) return;
+	if (state.lifecycle !== "disposed" && !state.abortController.signal.aborted) return;
+	throw new Error(`[SILVERY_STRICT=island-dispose-leak] ${label} callback fired after island dispose`);
+}
+function assertNoDisposedRender(state) {
+	if (!isStrictEnabled("island-dispose-leak", 2)) return;
+	if (state.lifecycle !== "disposed") return;
+	throw new Error("[SILVERY_STRICT=island-dispose-leak] disposed island reached render phase");
+}
+function formatRect(rect) {
+	return `{col:${rect.col},row:${rect.row},width:${rect.width},height:${rect.height}}`;
+}
+//#endregion
+//#region packages/ag-term/src/pipeline/render-viewport.ts
+/**
+* Blit the foreign cell buffer at `node.viewportState.buffer` into `buffer`
+* (via `sink.emitSetCell`) at `layout` (the viewport's content rect in
+* absolute parent-buffer coordinates). Cells outside `buffer`'s bounds are
+* silently clipped — the Viewport rect's right/bottom may extend off-screen
+* and that's fine.
+*/
+function renderViewport(node, buffer, sink, layout, scrollOffset) {
+	const state = node.viewportState;
+	if (!state) return;
+	const src = state.buffer;
+	const baseX = layout.x;
+	const baseY = layout.y - scrollOffset;
+	const drawW = Math.min(layout.width, src.cols);
+	const drawH = Math.min(layout.height, src.rows);
+	for (let r = 0; r < drawH; r++) {
+		const dstY = baseY + r;
+		if (dstY < 0 || dstY >= buffer.height) continue;
+		for (let c = 0; c < drawW; c++) {
+			const dstX = baseX + c;
+			if (dstX < 0 || dstX >= buffer.width) continue;
+			const cell = src.getCell(c, r);
+			sink.emitSetCell(dstX, dstY, viewportCellToPatch(cell));
+		}
+	}
+}
+/**
+* Convert a viewport {@link Cell} (string-colored, framework-agnostic shape
+* from `@silvery/ag/types`) to a {@link CellPatch} the parent
+* {@link TerminalBuffer} accepts (Color = `number | RGB | null`). String
+* colors are parsed once per cell — the upcoming xterm adapter writes
+* pre-resolved RGB strings, so parseColor's fast path runs.
+*
+* Reused by {@link renderIsland} — both viewport and island share the same
+* Cell shape from `@silvery/ag/types`. Islands pass an inherited background
+* so snapshot guests can leave cell.bg null and still sit on host chrome.
+*/
+function viewportCellToPatch(cell, inheritedBg = null) {
+	return {
+		char: cell.char,
+		fg: cell.fg === null ? null : parseColor(cell.fg),
+		bg: cell.bg === null ? inheritedBg : parseColor(cell.bg),
+		attrs: cell.attrs,
+		wide: cell.wide,
+		continuation: cell.continuation
+	};
+}
+/**
+* Blit a `silvery-island` node's guest cell buffer into the parent buffer.
+*
+* Sibling of {@link renderViewport}: reads from
+* `node.islandState.handle.output.buffer` (the guest's read-only output
+* surface from {@link IslandOutputOwner}) instead of
+* `node.viewportState.buffer`. Same routing — through {@link RenderSink}'s
+* `emitSetCell`, not direct buffer writes — so the cells survive
+* `commitSectionedPlan` under `SILVERY_RENDER_PLAN`.
+*
+* Bails when the host node has no `islandState` (factory still mounting) or
+* the guest's `init()` hasn't resolved yet (`handle === null`, lifecycle
+* `"pending"` / `"errored"` / `"disposed"`). In that case the parent's
+* `clearNodeRegion` (or inherited bg fill) has already painted blanks at
+* the island's rect, so we paint nothing and the host chrome shows through.
+*
+* Cursor handling: `IslandOutputOwner.cursor` is the guest's internal
+* cursor descriptor. v1 (Phase 1) does NOT render the guest cursor into the
+* host frame — the host cursor sits OUTSIDE the island, and the
+* `IslandModesOwner` contract un-applies the host cursor on focus blur to
+* the island. Phase 3 of `@km/silvery/15646-islands` wires the guest cursor
+* into the host's cursor signal (separate epic unit); until then, the
+* cursor field is read by the focus aggregator, not the blit.
+*
+* Clipping: same as viewport — out-of-bounds cells are silently dropped.
+* Both axes (right + bottom) clip; an island whose `cols×rows` overshoots
+* the parent buffer paints only its in-bounds intersection.
+*
+* See {@link island-types.ts} in `@silvery/ag` and bead
+* `@km/silvery/15646-islands`.
+*/
+function renderIsland(node, buffer, sink, layout, scrollOffset, inheritedBg = null) {
+	const state = node.islandState;
+	if (!state) return;
+	const handle = state.handle;
+	if (!handle) return;
+	ensureIslandStrictInstrumentation(node);
+	assertIslandRenderInvariants(node, layout);
+	const src = handle.output.buffer;
+	const baseX = layout.x;
+	const baseY = layout.y - scrollOffset;
+	const drawW = Math.min(layout.width, src.cols);
+	const drawH = Math.min(layout.height, src.rows);
+	for (let r = 0; r < drawH; r++) {
+		const dstY = baseY + r;
+		if (dstY < 0 || dstY >= buffer.height) continue;
+		for (let c = 0; c < drawW; c++) {
+			const dstX = baseX + c;
+			if (dstX < 0 || dstX >= buffer.width) continue;
+			const cell = src.getCell(c, r);
+			sink.emitSetCell(dstX, dstY, viewportCellToPatch(cell, inheritedBg));
+		}
+	}
 }
 //#endregion
 //#region packages/ag-term/src/pipeline/decoration-phase.ts
@@ -2658,12 +4494,20 @@ function padCenter(text, width) {
 * state. Called at the start of each incremental render, before the content
 * phase, on the cloned buffer. No-op when there are no previous snapshots
 * (fresh render or no outlines last frame).
+*
+* Phase 2 Step 5 (paint-clear-invariant L5): snapshots are read from the
+* `RenderPostState` carrier owned by `createAg`, NOT from the buffer. The
+* sink still receives a `setOutlineSnapshots([])` op so the plan-shape
+* captures the cleanup intent for parity tests; the authoritative state
+* lives in `postState.outlineSnapshots`.
 */
-function clearPreviousOutlines(buffer) {
-	const snapshots = buffer.outlineSnapshots;
-	if (!snapshots || snapshots.length === 0) return;
-	for (const snap of snapshots) buffer.setCell(snap.x, snap.y, snap.cell);
-	buffer.outlineSnapshots = [];
+function clearPreviousOutlines(buffer, postState) {
+	const snapshots = postState.outlineSnapshots;
+	if (snapshots.length === 0) return;
+	const sink = createFrameSink(buffer);
+	for (const snap of snapshots) sink.emitSetCell(snap.x, snap.y, snap.cell);
+	postState.outlineSnapshots = [];
+	sink.setOutlineSnapshots([]);
 }
 /**
 * Walk the node tree, drawing outlines for every node with `outlineStyle`.
@@ -2673,18 +4517,25 @@ function clearPreviousOutlines(buffer) {
 * incremental). Mirrors `renderNodeToBuffer`'s state threading for scroll
 * offsets, clip bounds, and inherited background — but does nothing except
 * visit the tree and draw outlines.
+*
+* Phase 2 Step 5 (paint-clear-invariant L5): snapshots are written to the
+* `RenderPostState` carrier; the sink op is recorded in the plan for parity
+* tests only. After this call, `postState.outlineSnapshots` holds exactly
+* the cells that need restoring on the next frame.
 */
-function renderDecorationPass(buffer, root) {
+function renderDecorationPass(buffer, root, postState) {
 	const snapshots = [];
-	walk(root, buffer, 0, void 0, { color: null }, snapshots);
-	buffer.outlineSnapshots = snapshots;
+	const sink = createFrameSink(buffer);
+	walk(root, buffer, sink, 0, void 0, { color: null }, snapshots);
+	postState.outlineSnapshots = snapshots;
+	sink.setOutlineSnapshots(snapshots);
 }
 /**
 * Recursive tree walk. Each invocation corresponds to the state at a single
 * node — scroll offset, clip bounds, inherited background — matching what
 * `renderNodeToBuffer` would have threaded through its `NodeRenderState`.
 */
-function walk(node, buffer, scrollOffset, clipBounds, inheritedBg, snapshots) {
+function walk(node, buffer, sink, scrollOffset, clipBounds, inheritedBg, snapshots) {
 	if (!node.layoutNode) return;
 	const layout = node.boxRect;
 	if (!layout) return;
@@ -2692,20 +4543,23 @@ function walk(node, buffer, scrollOffset, clipBounds, inheritedBg, snapshots) {
 	const props = node.props;
 	if (props.display === "none") return;
 	const y = layout.y - scrollOffset;
-	if (y >= buffer.height || y + layout.height <= 0) return;
+	if (y >= sink.height || y + layout.height <= 0) return;
 	const effectiveBg = getEffectiveBg(props);
 	const theme = props.theme;
 	const themeBg = theme && typeof theme["bg-surface-default"] === "string" ? theme["bg-surface-default"] : theme && typeof theme["bg"] === "string" ? theme["bg"] : void 0;
 	const childInheritedBg = effectiveBg ? { color: parseColor(effectiveBg) } : themeBg !== void 0 ? { color: parseColor(themeBg) } : inheritedBg;
 	if (node.type === "silvery-box" && props.outlineStyle) {
 		const boxInheritedBg = effectiveBg ? void 0 : inheritedBg.color;
-		const positions = collectOutlineCells(layout.x, y, layout.width, layout.height, props, clipBounds, buffer);
+		const positions = collectOutlineCells(layout.x, y, layout.width, layout.height, props, clipBounds, sink.width, sink.height);
 		for (const pos of positions) snapshots.push({
 			x: pos.x,
 			y: pos.y,
-			cell: buffer.getCell(pos.x, pos.y)
+			cell: {
+				...buffer.getCell(pos.x, pos.y),
+				selectable: buffer.isCellSelectable(pos.x, pos.y)
+			}
 		});
-		renderOutline(buffer, layout.x, y, layout.width, layout.height, props, clipBounds, boxInheritedBg);
+		renderOutline(buffer, sink, layout.x, y, layout.width, layout.height, props, clipBounds, boxInheritedBg);
 	}
 	if (node.children.length === 0) return;
 	const isScrollContainer = props.overflow === "scroll" && node.scrollState;
@@ -2719,16 +4573,16 @@ function walk(node, buffer, scrollOffset, clipBounds, inheritedBg, snapshots) {
 			if (!child) continue;
 			if (child.props.position === "sticky") continue;
 			if (i < ss.firstVisibleChild || i > ss.lastVisibleChild) continue;
-			walk(child, buffer, ss.offset, childClip, childInheritedBg, snapshots);
+			walk(child, buffer, sink, ss.offset, childClip, childInheritedBg, snapshots);
 		}
 		if (ss.stickyChildren) for (const sticky of ss.stickyChildren) {
 			const child = node.children[sticky.index];
 			if (!child) continue;
-			walk(child, buffer, sticky.naturalTop - sticky.renderOffset, childClip, childInheritedBg, snapshots);
+			walk(child, buffer, sink, sticky.naturalTop - sticky.renderOffset, childClip, childInheritedBg, snapshots);
 		}
 	} else {
 		const childClip = clipX || clipY ? computeChildClip(layout, props, clipBounds, scrollOffset, clipX, clipY) : clipBounds;
-		for (const child of node.children) walk(child, buffer, scrollOffset, childClip, childInheritedBg, snapshots);
+		for (const child of node.children) walk(child, buffer, sink, scrollOffset, childClip, childInheritedBg, snapshots);
 	}
 }
 /**
@@ -2741,19 +4595,19 @@ function walk(node, buffer, scrollOffset, clipBounds, inheritedBg, snapshots) {
 * Uses the SAME visibility checks as `renderOutline` so the snapshot set is
 * an exact match for the cell set the renderer will overwrite.
 */
-function collectOutlineCells(x, y, width, height, props, clipBounds, buffer) {
+function collectOutlineCells(x, y, width, height, props, clipBounds, bufferWidth, bufferHeight) {
 	const out = [];
 	const ox = x - 1;
 	const oy = y - 1;
 	const ow = width + 2;
 	const oh = height + 2;
 	const isRowVisible = (row) => {
-		if (!clipBounds) return row >= 0 && row < buffer.height;
-		return row >= clipBounds.top && row < clipBounds.bottom && row < buffer.height;
+		if (!clipBounds) return row >= 0 && row < bufferHeight;
+		return row >= clipBounds.top && row < clipBounds.bottom && row < bufferHeight;
 	};
 	const isColVisible = (col) => {
-		if (clipBounds?.left === void 0 || clipBounds.right === void 0) return col >= 0 && col < buffer.width;
-		return col >= clipBounds.left && col < clipBounds.right && col < buffer.width;
+		if (clipBounds?.left === void 0 || clipBounds.right === void 0) return col >= 0 && col < bufferWidth;
+		return col >= clipBounds.left && col < clipBounds.right && col < bufferWidth;
 	};
 	const showTop = props.outlineTop !== false;
 	const showBottom = props.outlineBottom !== false;
@@ -2764,11 +4618,11 @@ function collectOutlineCells(x, y, width, height, props, clipBounds, buffer) {
 			x: ox,
 			y: oy
 		});
-		for (let col = ox + 1; col < ox + ow - 1 && col < buffer.width; col++) if (isColVisible(col)) out.push({
+		for (let col = ox + 1; col < ox + ow - 1 && col < bufferWidth; col++) if (isColVisible(col)) out.push({
 			x: col,
 			y: oy
 		});
-		if (showRight && ox + ow - 1 < buffer.width && isColVisible(ox + ow - 1)) out.push({
+		if (showRight && ox + ow - 1 < bufferWidth && isColVisible(ox + ow - 1)) out.push({
 			x: ox + ow - 1,
 			y: oy
 		});
@@ -2781,7 +4635,7 @@ function collectOutlineCells(x, y, width, height, props, clipBounds, buffer) {
 			x: ox,
 			y: row
 		});
-		if (showRight && ox + ow - 1 < buffer.width && isColVisible(ox + ow - 1)) out.push({
+		if (showRight && ox + ow - 1 < bufferWidth && isColVisible(ox + ow - 1)) out.push({
 			x: ox + ow - 1,
 			y: row
 		});
@@ -2792,11 +4646,11 @@ function collectOutlineCells(x, y, width, height, props, clipBounds, buffer) {
 			x: ox,
 			y: bottomY
 		});
-		for (let col = ox + 1; col < ox + ow - 1 && col < buffer.width; col++) if (isColVisible(col)) out.push({
+		for (let col = ox + 1; col < ox + ow - 1 && col < bufferWidth; col++) if (isColVisible(col)) out.push({
 			x: col,
 			y: bottomY
 		});
-		if (showRight && ox + ow - 1 < buffer.width && isColVisible(ox + ow - 1)) out.push({
+		if (showRight && ox + ow - 1 < bufferWidth && isColVisible(ox + ow - 1)) out.push({
 			x: ox + ow - 1,
 			y: bottomY
 		});
@@ -2843,6 +4697,15 @@ function computeChildClip(layout, props, parentClip, scrollOffset, horizontal, v
 	return result;
 }
 //#endregion
+//#region packages/ag-term/src/pipeline/render-post-state.ts
+/**
+* Construct an empty `RenderPostState`. Called once per `createAg` lifetime
+* (and on `resetBuffer` to mirror prevBuffer reset semantics).
+*/
+function createRenderPostState() {
+	return { outlineSnapshots: [] };
+}
+//#endregion
 //#region packages/ag-term/src/pipeline/cascade-predicates.ts
 /**
 * Compute all cascade predicate values from boolean inputs.
@@ -3049,9 +4912,17 @@ const cellLog = createLogger("silvery:content:cell");
 *
 * @param root The root SilveryNode
 * @param prevBuffer Previous buffer for incremental rendering (optional)
+* @param ctx Pipeline context (instrumentation, measurer)
+* @param postState Cross-frame post-state carrier (outline snapshots, etc.).
+*   Owned by `createAg`; passed in here rather than read from the buffer so
+*   the decoration phase can run against either a BufferSink-mutated buffer
+*   or a PlanSink-committed buffer (Phase 2 Step 5 of paint-clear-invariant L5).
+*   When omitted (legacy callers), a fresh empty post-state is used per call —
+*   correct for fresh renders, but means outline cleanup is lost across frames
+*   if the caller doesn't hold the post-state externally.
 * @returns A TerminalBuffer with the rendered content
 */
-function renderPhase(root, prevBuffer, ctx) {
+function renderPhase(root, prevBuffer, ctx, postState = createRenderPostState()) {
 	const layout = root.boxRect;
 	if (!layout) throw new Error("renderPhase called before layout phase");
 	const instr = resolveInstrumentation(ctx);
@@ -3073,10 +4944,10 @@ function renderPhase(root, prevBuffer, ctx) {
 	const t0 = instr.enabled ? performance.now() : 0;
 	const buffer = hasPrevBuffer ? prevBuffer.clone() : new TerminalBuffer(layout.width, layout.height);
 	const tClone = instr.enabled ? performance.now() - t0 : 0;
-	buffer.setSelectableMode(true);
-	clearPreviousOutlines(buffer);
+	const frameSink = createFrameSink(buffer);
+	clearPreviousOutlines(buffer, postState);
 	const t1 = instr.enabled ? performance.now() : 0;
-	renderNodeToBuffer(root, buffer, {
+	renderNodeToBuffer(root, buffer, frameSink, {
 		scrollOffset: 0,
 		clipBounds: void 0,
 		hasPrevBuffer: !!hasPrevBuffer,
@@ -3087,10 +4958,11 @@ function renderPhase(root, prevBuffer, ctx) {
 			color: null,
 			ancestorRect: null
 		},
-		inheritedFg: null
+		inheritedFg: null,
+		selectableMode: true
 	}, ctx);
 	const tRender = instr.enabled ? performance.now() - t1 : 0;
-	renderDecorationPass(buffer, root);
+	renderDecorationPass(buffer, root, postState);
 	if (instr.enabled) emitRenderPhaseStats(instr.stats, instr.nodeTrace, instr.nodeTraceEnabled, tClone, tRender);
 	syncPrevLayout(root, isCurrentEpoch(root.layoutChangedThisFrame) || isDirty(root.dirtyBits, root.dirtyEpoch, 16) || !hasPrevBuffer);
 	advanceRenderEpoch();
@@ -3156,6 +5028,7 @@ const _renderPhaseStats = {
 	scrollClearReason: "",
 	normalChildrenRepaint: 0,
 	normalRepaintReason: "",
+	siblingOverlapForced: 0,
 	cascadeMinDepth: 999,
 	cascadeNodes: "",
 	_noopSkip: 0,
@@ -3234,8 +5107,14 @@ function emitRenderPhaseStats(stats, nodeTrace, nodeTraceEnabled, tClone, tRende
 }
 /**
 * Render a single node to the buffer.
+*
+* `sink` is the frame-shared RenderSink threaded from `renderPhase`. All
+* post-state writes (selectableMode), cleanup ops (executeRegionClearing),
+* paint ops (renderOwnContent inner sinks), and overlay ops
+* (applyBoxAttrOverlay) route through this single sink. See Smell #2 from
+* the 2026-04-27 dual-pro review for the rationale.
 */
-function renderNodeToBuffer(node, buffer, nodeState, ctx) {
+function renderNodeToBuffer(node, buffer, sink, nodeState, ctx) {
 	const { scrollOffset, clipBounds, hasPrevBuffer, ancestorCleared, bufferIsCloned, ancestorLayoutChanged = false } = nodeState;
 	const instr = resolveInstrumentation(ctx);
 	if (instr.enabled) instr.stats.nodesVisited++;
@@ -3250,20 +5129,12 @@ function renderNodeToBuffer(node, buffer, nodeState, ctx) {
 		return;
 	}
 	const props = node.props;
-	const prevSelectableMode = buffer.getSelectableMode();
-	const userSelect = props.userSelect;
-	if (userSelect === "none") buffer.setSelectableMode(false);
-	else if (userSelect === "text" || userSelect === "contain") buffer.setSelectableMode(true);
 	if (props.display === "none") {
 		clearDirtyFlags(node);
-		buffer.setSelectableMode(prevSelectableMode);
 		return;
 	}
 	const screenY = layout.y - scrollOffset;
-	if (screenY >= buffer.height || screenY + layout.height <= 0) {
-		buffer.setSelectableMode(prevSelectableMode);
-		return;
-	}
+	if (screenY >= buffer.height || screenY + layout.height <= 0) return;
 	const layoutChanged = isCurrentEpoch(node.layoutChangedThisFrame);
 	const childPositionChanged = !!(hasPrevBuffer && !layoutChanged && hasChildPositionChanged(node));
 	const scrollOffsetChanged = !!(node.scrollState && node.scrollState.offset !== node.scrollState.prevOffset);
@@ -3298,7 +5169,6 @@ function renderNodeToBuffer(node, buffer, nodeState, ctx) {
 			});
 		}
 		clearDirtyFlags(node);
-		buffer.setSelectableMode(prevSelectableMode);
 		return;
 	}
 	if (instr.enabled) {
@@ -3312,6 +5182,15 @@ function renderNodeToBuffer(node, buffer, nodeState, ctx) {
 		if (childPositionChanged) instr.stats.flagChildPositionChanged++;
 		if (ancestorLayoutChanged) instr.stats.flagAncestorLayoutChanged++;
 	}
+	const prevSelectableMode = nodeState.selectableMode;
+	const userSelect = props.userSelect;
+	let currentSelectableMode = prevSelectableMode;
+	if (userSelect === "none") currentSelectableMode = false;
+	else if (userSelect === "text" || userSelect === "contain") currentSelectableMode = true;
+	const currentNodeState = currentSelectableMode === prevSelectableMode ? nodeState : {
+		...nodeState,
+		selectableMode: currentSelectableMode
+	};
 	const nodeTheme = props.theme;
 	if (nodeTheme) pushContextTheme(nodeTheme);
 	try {
@@ -3357,13 +5236,31 @@ function renderNodeToBuffer(node, buffer, nodeState, ctx) {
 				childrenNeedFreshRender
 			};
 		}
+		if (node.type === "silvery-box" && isDirty(node.dirtyBits, node.dirtyEpoch, 2) && (mayHaveBoxAttrOverlay(props) || node.hadBoxAttrOverlay)) {
+			const contentRegionCleared = (hasPrevBuffer || ancestorCleared) && !getEffectiveBg(props);
+			const childrenNeedFreshRender = hasPrevBuffer || ancestorCleared;
+			cascade = {
+				...cascade,
+				contentAreaAffected: true,
+				bgOnlyChange: false,
+				contentRegionCleared,
+				childrenNeedFreshRender
+			};
+		}
 		const { contentRegionCleared, skipBgFill, childrenNeedFreshRender } = cascade;
 		if (instr.enabled || _cellDbg && (_coversCellNow || _coversCellPrev)) traceRenderDecision(node, props, layout, screenY, scrollOffset, hasPrevBuffer, ancestorCleared, layoutChanged, childPositionChanged, cascade, _nodeId, _traceThis, _cellDbg, _coversCellNow, _coversCellPrev, instr.enabled, instr.stats, instr.nodeTrace);
 		const useTextStyleFastPath = false;
-		executeRegionClearing(node, buffer, layout, scrollOffset, clipBounds, bufferIsCloned, layoutChanged, contentRegionCleared, descendantOverflowChanged, instr.enabled, instr.stats, nodeState.inheritedBg);
-		const needsOwnRepaint = !hasPrevBuffer || ancestorCleared || ancestorLayoutChanged || cascade.contentAreaAffected || isDirty(node.dirtyBits, node.dirtyEpoch, 2) || cascade.bgRefillNeeded;
-		node.type === "silvery-box" && !getEffectiveBg(props) && nodeState.inheritedBg.color;
-		if (needsOwnRepaint) renderOwnContent(node, buffer, layout, props, nodeState, skipBgFill, instr.enabled, instr.stats, ctx, cascade.bgOnlyChange, useTextStyleFastPath);
+		executeRegionClearing(node, buffer, sink, layout, scrollOffset, clipBounds, bufferIsCloned, layoutChanged, contentRegionCleared, descendantOverflowChanged, instr.enabled, instr.stats, nodeState.inheritedBg, hasPrevBuffer);
+		if (!hasPrevBuffer || ancestorCleared || ancestorLayoutChanged || cascade.contentAreaAffected || isDirty(node.dirtyBits, node.dirtyEpoch, 2) || cascade.bgRefillNeeded) {
+			pushRenderingNode(node);
+			resetBorderedRectClipCache();
+			try {
+				renderOwnContent(node, buffer, sink, layout, props, currentNodeState, skipBgFill, instr.enabled, instr.stats, ctx, cascade.bgOnlyChange, useTextStyleFastPath);
+			} finally {
+				popRenderingNode();
+				resetBorderedRectClipCache();
+			}
+		}
 		const effectiveBg = getEffectiveBg(props);
 		const childInheritedBg = effectiveBg ? {
 			color: parseColor(effectiveBg),
@@ -3374,18 +5271,19 @@ function renderNodeToBuffer(node, buffer, nodeState, ctx) {
 		} : nodeState.inheritedBg;
 		const childInheritedFg = props.color === "inherit" || props.color === "currentColor" ? nodeState.inheritedFg : props.color ? parseColor(props.color) : nodeTheme ? parseColor(nodeTheme.fg) : nodeState.inheritedFg;
 		const childState = {
-			...nodeState,
+			...currentNodeState,
 			inheritedBg: childInheritedBg,
-			inheritedFg: childInheritedFg
+			inheritedFg: childInheritedFg,
+			selectableMode: currentSelectableMode
 		};
 		if (isScrollContainer) {
-			renderScrollContainerChildren(node, buffer, props, childState, contentRegionCleared, childrenNeedFreshRender, ctx);
+			renderScrollContainerChildren(node, buffer, sink, props, childState, contentRegionCleared, childrenNeedFreshRender, ctx);
 			renderScrollIndicators(node, buffer, layout, props, node.scrollState, ctx);
-		} else renderNormalChildren(node, buffer, props, childState, childPositionChanged, contentRegionCleared, childrenNeedFreshRender, ctx);
+		} else renderNormalChildren(node, buffer, sink, props, childState, childPositionChanged, contentRegionCleared, childrenNeedFreshRender, ctx);
+		if (node.type === "silvery-box") node.hadBoxAttrOverlay = applyBoxAttrOverlay(buffer, sink, layout, props, scrollOffset, clipBounds);
 		clearNodeDirtyFlags(node);
 	} finally {
 		if (nodeTheme) popContextTheme();
-		buffer.setSelectableMode(prevSelectableMode);
 	}
 }
 /**
@@ -3486,12 +5384,14 @@ function traceRenderDecision(node, props, layout, screenY, scrollOffset, hasPrev
 *
 * All clearing runs BEFORE renderBox/renderText so borders drawn later are not overwritten.
 */
-function executeRegionClearing(node, buffer, layout, scrollOffset, clipBounds, bufferIsCloned, layoutChanged, contentRegionCleared, descendantOverflowChanged, instrumentEnabled, stats, threadedInheritedBg) {
+function executeRegionClearing(node, buffer, sink, layout, scrollOffset, clipBounds, bufferIsCloned, layoutChanged, contentRegionCleared, descendantOverflowChanged, instrumentEnabled, stats, threadedInheritedBg, hasPrevBuffer) {
 	if (contentRegionCleared) {
 		if (instrumentEnabled) stats.clearOps++;
-		clearNodeRegion(node, buffer, layout, scrollOffset, clipBounds, layoutChanged, threadedInheritedBg);
-	} else if (bufferIsCloned && layoutChanged && node.prevLayout) clearExcessArea(node, buffer, layout, scrollOffset, clipBounds, layoutChanged, threadedInheritedBg);
-	if (descendantOverflowChanged) clearDescendantOverflowRegions(node, buffer, layout, scrollOffset, clipBounds, threadedInheritedBg);
+		clearNodeRegion(node, sink, layout, scrollOffset, clipBounds, threadedInheritedBg);
+	}
+	const excessGate = requireExcessClearGate(bufferIsCloned, layoutChanged, node.prevLayout, hasPrevBuffer);
+	if (excessGate) clearExcessArea(excessGate, node, buffer, sink, layout, scrollOffset, clipBounds, threadedInheritedBg);
+	if (descendantOverflowChanged) clearDescendantOverflowRegions(node, buffer, sink, layout, scrollOffset, clipBounds, threadedInheritedBg);
 }
 /**
 * Render this node's own content (box background/border or text).
@@ -3501,12 +5401,14 @@ function executeRegionClearing(node, buffer, layout, scrollOffset, clipBounds, b
 *
 * @returns The boxInheritedBg color (needed by outline rendering after children).
 */
-function renderOwnContent(node, buffer, layout, props, nodeState, skipBgFill, instrumentEnabled, stats, ctx, bgOnlyChange = false, useTextStyleFastPath = false) {
+function renderOwnContent(node, buffer, sink, layout, props, nodeState, skipBgFill, instrumentEnabled, stats, ctx, bgOnlyChange = false, useTextStyleFastPath = false) {
 	const boxInheritedBg = node.type === "silvery-box" && !getEffectiveBg(props) ? nodeState.inheritedBg.color : void 0;
 	if (node.type === "silvery-box") {
 		if (instrumentEnabled) stats.boxNodes++;
 		renderBox(node, buffer, layout, props, nodeState, skipBgFill, boxInheritedBg, bgOnlyChange, nodeState.inheritedFg);
-	} else if (node.type === "silvery-text") {
+	} else if (node.type === "silvery-viewport") renderViewport(node, buffer, sink, layout, nodeState.scrollOffset);
+	else if (node.type === "silvery-island") renderIsland(node, buffer, sink, layout, nodeState.scrollOffset, nodeState.inheritedBg.color);
+	else if (node.type === "silvery-text") {
 		if (instrumentEnabled) stats.textNodes++;
 		const textInheritedBg = nodeState.inheritedBg.color;
 		const textInheritedFg = nodeState.inheritedFg;
@@ -3516,7 +5418,7 @@ function renderOwnContent(node, buffer, layout, props, nodeState, skipBgFill, in
 			const effectiveBg = style.bg !== null ? style.bg : textInheritedBg ?? null;
 			const { x, width, height } = layout;
 			const y = layout.y - nodeState.scrollOffset;
-			buffer.restyleRegion(x, y, width, height, {
+			sink.emitRestyleRegion(x, y, width, height, {
 				fg: style.fg,
 				bg: effectiveBg,
 				underlineColor: style.underlineColor ?? null,
@@ -3527,6 +5429,125 @@ function renderOwnContent(node, buffer, layout, props, nodeState, skipBgFill, in
 	return boxInheritedBg;
 }
 /**
+* Cheap check: is ANY attr-overlay prop present on this Box right now?
+*
+* Used by the cascade to decide whether `stylePropsDirty` on a silvery-box
+* should escalate to `contentAreaAffected`. We can't reliably inspect the
+* PREVIOUS frame's props from here, so we conservatively escalate whenever
+* EITHER the current frame OR a neighbor frame might have had overlay.
+* The single-call common case (Box with no attr overlay ever) stays on the
+* fast path because this returns false both frames and the stylePropsDirty
+* gate doesn't fire (stylePropsDirty requires a prop-change reconciler event,
+* which won't happen for a Box that never had these props).
+*/
+function mayHaveBoxAttrOverlay(props) {
+	return !!(props.underline || props.underlineStyle || props.underlineColor || props.overline || props.bold || props.italic || props.inverse || props.strikethrough);
+}
+/**
+* Detect which attr props are active on a Box. Only returns the overlay
+* subset — attrs that benefit from merge-over-children semantics.
+*
+* bold / dim / italic / inverse / strikethrough / underline / underlineColor
+* all qualify. Text color, bg color, and border-related props are handled
+* elsewhere and are NOT attr-overlay props.
+*
+* Returns null when no overlay attrs are present (fast path — most Boxes).
+*/
+function computeBoxAttrOverlay(props) {
+	let underlineStyle;
+	if (props.underlineStyle !== void 0 && props.underlineStyle !== false) underlineStyle = props.underlineStyle;
+	else if (typeof props.underline === "string") underlineStyle = props.underline;
+	else if (props.underline === true) underlineStyle = "single";
+	const hasUnderline = !!underlineStyle;
+	const bold = !!props.bold;
+	const italic = !!props.italic;
+	const inverse = !!props.inverse;
+	const strikethrough = !!props.strikethrough;
+	const overline = !!props.overline;
+	if (!hasUnderline && !bold && !italic && !inverse && !strikethrough && !overline) return null;
+	return {
+		attrs: {
+			bold: bold || void 0,
+			italic: italic || void 0,
+			inverse: inverse || void 0,
+			strikethrough: strikethrough || void 0,
+			overline: overline || void 0,
+			underline: hasUnderline || void 0,
+			underlineStyle: hasUnderline ? underlineStyle : void 0
+		},
+		underlineColor: (props.underlineColor ? parseColor(props.underlineColor) : void 0) ?? void 0
+	};
+}
+/**
+* Apply a Box's attr overlay to its rect, respecting scroll offset and clip
+* bounds. Runs AFTER children render so attrs layer on top of content without
+* overwriting glyphs/fg/bg.
+*
+* @returns true when an overlay was actually applied — used by the caller to
+* set `node.hadBoxAttrOverlay`, which next frame's cascade reads to detect
+* overlay removal.
+*/
+function applyBoxAttrOverlay(buffer, sink, layout, props, scrollOffset, clipBounds) {
+	const overlay = computeBoxAttrOverlay(props);
+	if (!overlay) return false;
+	const x = layout.x;
+	const y = layout.y - scrollOffset;
+	let rx = x;
+	let rw = layout.width;
+	let ry = y;
+	let rh = layout.height;
+	if (clipBounds) {
+		const topClipped = Math.max(ry, clipBounds.top);
+		const bottomClipped = Math.min(ry + rh, clipBounds.bottom);
+		if (topClipped >= bottomClipped) return false;
+		ry = topClipped;
+		rh = bottomClipped - topClipped;
+		if (clipBounds.left !== void 0 && clipBounds.right !== void 0) {
+			const leftClipped = Math.max(rx, clipBounds.left);
+			const rightClipped = Math.min(rx + rw, clipBounds.right);
+			if (leftClipped >= rightClipped) return false;
+			rx = leftClipped;
+			rw = rightClipped - leftClipped;
+		}
+	}
+	sink.emitMergeAttrs(rx, ry, rw, rh, overlay.attrs, overlay.underlineColor);
+	return true;
+}
+/**
+* Check whether any transparent sibling of this scroll container is an
+* absolute-positioned Box whose rect overlaps with the scroll container's rect.
+*
+* This matters for Tier 1 (buffer shift) safety: when a transparent sibling
+* absolute child paints into our rect (e.g., an overlay glyph at col=width-1),
+* the shift would smear those pixels along with the content. Opaque absolute
+* siblings are safe because the normal third pass always re-renders absolute
+* children after the scroll container and repaints their whole rect.
+*
+* O(siblings) — typically 1-3 siblings under common parents (ListView outer
+* Box has scroll container + scrollbar + edge-bump indicator). Returns false
+* for the common case (no parent or no absolute siblings).
+*/
+function checkOverlappingAbsoluteSibling(node, scrollRect) {
+	const parent = node.parent;
+	if (!parent) return false;
+	const siblings = parent.children;
+	if (!siblings) return false;
+	const sLeft = scrollRect.x;
+	const sTop = scrollRect.y;
+	const sRight = scrollRect.x + scrollRect.width;
+	const sBottom = scrollRect.y + scrollRect.height;
+	for (const sib of siblings) {
+		if (sib === node) continue;
+		const sp = sib.props;
+		if (sp?.position !== "absolute") continue;
+		if (getEffectiveBg(sp)) continue;
+		const r = sib.boxRect;
+		if (!r) continue;
+		if (r.x < sRight && r.x + r.width > sLeft && r.y < sBottom && r.y + r.height > sTop) return true;
+	}
+	return false;
+}
+/**
 * Determine the scroll tier strategy for this frame.
 *
 * Pure function -- no side effects, no node access beyond the inputs.
@@ -3534,15 +5555,15 @@ function renderOwnContent(node, buffer, layout, props, nodeState, skipBgFill, in
 * Three-tier strategy:
 * 1. **shift**: Only scroll offset changed, no sticky children. Buffer contents
 *    shifted by scroll delta; only newly visible edges re-render.
-* 2. **clear**: Children restructured, visible range changed with scroll, or
-*    parent region changed. Entire viewport cleared and all children re-render.
+* 2. **clear**: Children restructured, sticky/overlaid scroll, or parent region
+*    changed. Entire viewport cleared and all children re-render.
 * 3. **subtree-only**: Only some descendants changed. Children use hasPrevBuffer=true
 *    and skip via fast-path if clean. With sticky children, forces all first-pass
 *    items to re-render (stickyForceRefresh).
 */
 function planScrollRender(inputs) {
-	const { scrollOffsetChanged, visibleRangeChanged, hasStickyChildren, childrenNeedFreshRender, childrenDirty, hasPrevBuffer, ancestorCleared, contentRegionCleared, scrollBg } = inputs;
-	const scrollOnly = hasPrevBuffer && scrollOffsetChanged && !childrenDirty && !childrenNeedFreshRender && !hasStickyChildren && !visibleRangeChanged;
+	const { scrollOffsetChanged, visibleRangeChanged, hasStickyChildren, childrenNeedFreshRender, childrenDirty, hasPrevBuffer, ancestorCleared, contentRegionCleared, scrollBg, hasOverlappingAbsoluteSibling = false } = inputs;
+	const scrollOnly = hasPrevBuffer && scrollOffsetChanged && !childrenDirty && !childrenNeedFreshRender && !hasStickyChildren && !hasOverlappingAbsoluteSibling;
 	const needsViewportClear = hasPrevBuffer && !scrollOnly && (scrollOffsetChanged || childrenDirty || childrenNeedFreshRender || visibleRangeChanged);
 	const stickyForceRefresh = hasStickyChildren && hasPrevBuffer && !needsViewportClear;
 	const reasons = [];
@@ -3552,6 +5573,7 @@ function planScrollRender(inputs) {
 		if (childrenDirty) reasons.push("childrenDirty");
 		if (childrenNeedFreshRender) reasons.push("childrenNeedFreshRender");
 		if (visibleRangeChanged) reasons.push("visibleRangeChanged");
+		if (hasOverlappingAbsoluteSibling) reasons.push("overlappingAbsoluteSibling");
 	}
 	if (stickyForceRefresh) reasons.push("stickyForceRefresh");
 	return {
@@ -3566,8 +5588,8 @@ function planScrollRender(inputs) {
 /**
 * Render children of a scroll container with proper clipping and offset.
 */
-function renderScrollContainerChildren(node, buffer, props, nodeState, contentRegionCleared = false, childrenNeedFreshRender = false, ctx) {
-	const { clipBounds, hasPrevBuffer, ancestorCleared, bufferIsCloned, ancestorLayoutChanged, inheritedBg, inheritedFg } = nodeState;
+function renderScrollContainerChildren(node, buffer, sink, props, nodeState, contentRegionCleared = false, childrenNeedFreshRender = false, ctx) {
+	const { clipBounds, hasPrevBuffer, ancestorCleared, bufferIsCloned, ancestorLayoutChanged, inheritedBg, inheritedFg, selectableMode } = nodeState;
 	const instr = resolveInstrumentation(ctx);
 	const layout = node.boxRect;
 	const ss = node.scrollState;
@@ -3593,6 +5615,7 @@ function renderScrollContainerChildren(node, buffer, props, nodeState, contentRe
 	const contentX = layout.x + border.left + padding.left;
 	const contentWidth = layout.width - border.left - border.right - padding.left - padding.right;
 	const scrollBg = scrollOffsetChanged || isDirty(node.dirtyBits, node.dirtyEpoch, 8) || childrenNeedFreshRender || visibleRangeChanged ? getEffectiveBg(props) ? parseColor(getEffectiveBg(props)) : inheritedBg.color : null;
+	const hasOverlappingAbsoluteSibling = checkOverlappingAbsoluteSibling(node, layout);
 	const plan = planScrollRender({
 		scrollOffsetChanged,
 		visibleRangeChanged,
@@ -3602,7 +5625,8 @@ function renderScrollContainerChildren(node, buffer, props, nodeState, contentRe
 		hasPrevBuffer,
 		ancestorCleared,
 		contentRegionCleared,
-		scrollBg
+		scrollBg,
+		hasOverlappingAbsoluteSibling
 	});
 	const { tier, stickyForceRefresh } = plan;
 	const defaultChildHasPrev = plan.childHasPrev;
@@ -3623,28 +5647,16 @@ function renderScrollContainerChildren(node, buffer, props, nodeState, contentRe
 		if (props.overflowIndicator === true && !border.top && !border.bottom) {
 			const topIndicatorY = clearY;
 			const bottomIndicatorY = clearY + clearHeight - 1;
-			if (ss.prevOffset != null && ss.prevOffset > 0) buffer.fill(contentX, topIndicatorY, contentWidth, 1, {
-				char: " ",
-				bg: plan.clearBg
-			});
-			buffer.fill(contentX, bottomIndicatorY, contentWidth, 1, {
-				char: " ",
-				bg: plan.clearBg
-			});
+			if (ss.prevOffset != null && ss.prevOffset > 0) sink.emitClearRect(contentX, topIndicatorY, contentWidth, 1, plan.clearBg);
+			sink.emitClearRect(contentX, bottomIndicatorY, contentWidth, 1, plan.clearBg);
 		}
-		buffer.scrollRegion(contentX, clearY, contentWidth, clearHeight, scrollDelta, {
+		sink.emitScrollRegion(contentX, clearY, contentWidth, clearHeight, scrollDelta, {
 			char: " ",
 			bg: plan.clearBg
 		});
 	}
-	if (tier === "clear" && clearHeight > 0) buffer.fill(contentX, clearY, contentWidth, clearHeight, {
-		char: " ",
-		bg: plan.clearBg
-	});
-	if (stickyForceRefresh && clearHeight > 0) buffer.fill(contentX, clearY, contentWidth, clearHeight, {
-		char: " ",
-		bg: null
-	});
+	if (tier === "clear" && clearHeight > 0) sink.emitClearRect(contentX, clearY, contentWidth, clearHeight, plan.clearBg);
+	if (stickyForceRefresh && clearHeight > 0) sink.emitClearRect(contentX, clearY, contentWidth, clearHeight, null);
 	const childAncestorLayoutChanged = isCurrentEpoch(node.layoutChangedThisFrame) || !!ancestorLayoutChanged;
 	const prevVisTop = ss.prevOffset ?? ss.offset;
 	const prevVisBottom = prevVisTop + ss.viewportHeight;
@@ -3663,6 +5675,7 @@ function renderScrollContainerChildren(node, buffer, props, nodeState, contentRe
 				const wasFullyVisible = childTop >= prevVisTop && childBottom <= prevVisBottom;
 				thisChildHasPrev = wasFullyVisible;
 				thisChildAncestorCleared = wasFullyVisible ? ancestorCleared || contentRegionCleared : true;
+				if (!wasFullyVisible) clearShiftedNewChildRegion(childRect, ss.offset, childClipBounds, sink, plan.clearBg);
 			}
 		}
 		if (stickyForceRefresh && thisChildHasPrev) {
@@ -3670,7 +5683,7 @@ function renderScrollContainerChildren(node, buffer, props, nodeState, contentRe
 			thisChildAncestorCleared = false;
 		}
 		if (canSkipChildSubtree(child, thisChildHasPrev, childAncestorLayoutChanged)) continue;
-		renderNodeToBuffer(child, buffer, {
+		renderNodeToBuffer(child, buffer, sink, {
 			scrollOffset: ss.offset,
 			clipBounds: childClipBounds,
 			hasPrevBuffer: thisChildHasPrev,
@@ -3678,13 +5691,14 @@ function renderScrollContainerChildren(node, buffer, props, nodeState, contentRe
 			bufferIsCloned,
 			ancestorLayoutChanged: childAncestorLayoutChanged,
 			inheritedBg,
-			inheritedFg
+			inheritedFg,
+			selectableMode
 		}, ctx);
 	}
 	if (ss.stickyChildren) for (const sticky of ss.stickyChildren) {
 		const child = node.children[sticky.index];
 		if (!child?.boxRect) continue;
-		renderNodeToBuffer(child, buffer, {
+		renderNodeToBuffer(child, buffer, sink, {
 			scrollOffset: sticky.naturalTop - sticky.renderOffset,
 			clipBounds: childClipBounds,
 			hasPrevBuffer: false,
@@ -3692,15 +5706,42 @@ function renderScrollContainerChildren(node, buffer, props, nodeState, contentRe
 			bufferIsCloned,
 			ancestorLayoutChanged: childAncestorLayoutChanged,
 			inheritedBg,
-			inheritedFg
+			inheritedFg,
+			selectableMode
 		}, ctx);
 	}
 }
 /**
+* Tier-1 scroll shifting reuses previous-frame pixels. A child that was not fully
+* visible in the previous viewport is rendered like a fresh subtree, but the
+* shifted buffer under its transparent cells may still contain unrelated pixels
+* from a previous row. Clear the child's currently visible rectangle first so
+* transparent boxes/text render onto the same blank base as a fresh render.
+*/
+function clearShiftedNewChildRegion(childRect, scrollOffset, clipBounds, sink, bg) {
+	let x = childRect.x;
+	let y = childRect.y - scrollOffset;
+	let width = childRect.width;
+	let height = childRect.height;
+	if (clipBounds) {
+		if (clipBounds.left !== void 0 && x < clipBounds.left) {
+			width -= clipBounds.left - x;
+			x = clipBounds.left;
+		}
+		if (clipBounds.right !== void 0 && x + width > clipBounds.right) width = clipBounds.right - x;
+		if (y < clipBounds.top) {
+			height -= clipBounds.top - y;
+			y = clipBounds.top;
+		}
+		if (y + height > clipBounds.bottom) height = clipBounds.bottom - y;
+	}
+	if (width > 0 && height > 0) sink.emitClearRect(x, y, width, height, bg);
+}
+/**
 * Render children of a normal (non-scroll) container.
 */
-function renderNormalChildren(node, buffer, props, nodeState, childPositionChanged = false, contentRegionCleared = false, childrenNeedFreshRender = false, ctx) {
-	const { scrollOffset, clipBounds, hasPrevBuffer, ancestorCleared, bufferIsCloned, ancestorLayoutChanged, inheritedBg, inheritedFg } = nodeState;
+function renderNormalChildren(node, buffer, sink, props, nodeState, childPositionChanged = false, contentRegionCleared = false, childrenNeedFreshRender = false, ctx) {
+	const { scrollOffset, clipBounds, hasPrevBuffer, ancestorCleared, bufferIsCloned, ancestorLayoutChanged, inheritedBg, inheritedFg, selectableMode } = nodeState;
 	const instr = resolveInstrumentation(ctx);
 	const layout = node.boxRect;
 	if (!layout) return;
@@ -3735,10 +5776,7 @@ function renderNormalChildren(node, buffer, props, nodeState, childPositionChang
 			}
 			if (clipBounds.right !== void 0 && clearX + clearW > clipBounds.right) clearW = clipBounds.right - clearX;
 		}
-		if (clearW > 0 && clearH > 0) buffer.fill(clearX, clearY, clearW, clearH, {
-			char: " ",
-			bg: null
-		});
+		if (clearW > 0 && clearH > 0) sink.emitClearRect(clearX, clearY, clearW, clearH, null);
 	}
 	const childrenNeedRepaint = isDirty(node.dirtyBits, node.dirtyEpoch, 8) || childPositionChanged || childrenNeedFreshRender;
 	if (instr.enabled && childrenNeedRepaint && hasPrevBuffer) {
@@ -3757,6 +5795,7 @@ function renderNormalChildren(node, buffer, props, nodeState, childPositionChang
 		childAncestorCleared = false;
 	}
 	let hasAbsoluteChildren = false;
+	const firstPassChildren = [];
 	for (const child of node.children) {
 		const childProps = child.props;
 		if (childProps.position === "absolute") {
@@ -3764,22 +5803,46 @@ function renderNormalChildren(node, buffer, props, nodeState, childPositionChang
 			continue;
 		}
 		if (hasStickyChildren && childProps.position === "sticky") continue;
-		if (canSkipChildSubtree(child, childHasPrev, childAncestorLayoutChanged)) continue;
-		renderNodeToBuffer(child, buffer, {
+		firstPassChildren.push(child);
+	}
+	const willRender = firstPassChildren.map((child) => !canSkipChildSubtree(child, childHasPrev, childAncestorLayoutChanged));
+	if (childHasPrev) for (let i = 0; i < firstPassChildren.length; i++) {
+		if (!willRender[i]) continue;
+		const childI = firstPassChildren[i];
+		const ei = computeSubtreePaintExtent(childI);
+		if (!ei || ei.width <= 0 || ei.height <= 0) continue;
+		for (let j = i + 1; j < firstPassChildren.length; j++) {
+			if (willRender[j]) continue;
+			const rj = firstPassChildren[j].boxRect;
+			if (!rj || rj.width <= 0 || rj.height <= 0) continue;
+			const overlapX = ei.x < rj.x + rj.width && rj.x < ei.x + ei.width;
+			const overlapY = ei.y < rj.y + rj.height && rj.y < ei.y + ei.height;
+			if (overlapX && overlapY) {
+				willRender[j] = true;
+				if (instr.enabled) instr.stats.siblingOverlapForced++;
+			}
+		}
+	}
+	for (let i = 0; i < firstPassChildren.length; i++) {
+		if (!willRender[i]) continue;
+		const child = firstPassChildren[i];
+		const overlapForced = !!canSkipChildSubtree(child, childHasPrev, childAncestorLayoutChanged);
+		renderNodeToBuffer(child, buffer, sink, {
 			scrollOffset,
 			clipBounds: effectiveClipBounds,
-			hasPrevBuffer: childHasPrev,
-			ancestorCleared: childAncestorCleared,
+			hasPrevBuffer: overlapForced ? false : childHasPrev,
+			ancestorCleared: overlapForced ? false : childAncestorCleared,
 			bufferIsCloned,
 			ancestorLayoutChanged: childAncestorLayoutChanged,
 			inheritedBg,
-			inheritedFg
+			inheritedFg,
+			selectableMode
 		}, ctx);
 	}
 	if (node.stickyChildren) for (const sticky of node.stickyChildren) {
 		const child = node.children[sticky.index];
 		if (!child?.boxRect) continue;
-		renderNodeToBuffer(child, buffer, {
+		renderNodeToBuffer(child, buffer, sink, {
 			scrollOffset: sticky.naturalTop - sticky.renderOffset,
 			clipBounds: effectiveClipBounds,
 			hasPrevBuffer: false,
@@ -3787,12 +5850,13 @@ function renderNormalChildren(node, buffer, props, nodeState, childPositionChang
 			bufferIsCloned,
 			ancestorLayoutChanged: childAncestorLayoutChanged,
 			inheritedBg,
-			inheritedFg
+			inheritedFg,
+			selectableMode
 		}, ctx);
 	}
 	if (hasAbsoluteChildren) for (const child of node.children) {
 		if (child.props.position !== "absolute") continue;
-		renderNodeToBuffer(child, buffer, {
+		renderNodeToBuffer(child, buffer, sink, {
 			scrollOffset,
 			clipBounds: effectiveClipBounds,
 			hasPrevBuffer: false,
@@ -3800,11 +5864,51 @@ function renderNormalChildren(node, buffer, props, nodeState, childPositionChang
 			bufferIsCloned,
 			ancestorLayoutChanged: childAncestorLayoutChanged,
 			inheritedBg,
-			inheritedFg
+			inheritedFg,
+			selectableMode
 		}, ctx);
 	}
 }
 /**
+* Compute the screen-space rectangle that bounds every paint within this
+* subtree. Used by sibling-overlap detection in renderNormalChildren so
+* that a descendant overflowing its ancestor still triggers force-repaint
+* of any later sibling at the painted row.
+*
+* Returns the union of `node.boxRect` with the recursive paint extent of
+* each child whose `boxRect` is set. Returns null if `node.boxRect` is
+* unset (e.g. abandoned subtree). Skipping descendants without a boxRect
+* is safe because they never paint.
+*
+* Cost: O(N) per call where N is the subtree's node count. Only called
+* for first-pass children that will render AND only when their parent has
+* a prev buffer (i.e. real incremental render frames). Skipped children
+* never trigger the walk.
+*/
+function computeSubtreePaintExtent(node) {
+	const own = node.boxRect;
+	if (!own) return null;
+	let minX = own.x;
+	let minY = own.y;
+	let maxX = own.x + own.width;
+	let maxY = own.y + own.height;
+	const children = node.children;
+	if (children) for (const child of children) {
+		const sub = computeSubtreePaintExtent(child);
+		if (!sub) continue;
+		if (sub.x < minX) minX = sub.x;
+		if (sub.y < minY) minY = sub.y;
+		if (sub.x + sub.width > maxX) maxX = sub.x + sub.width;
+		if (sub.y + sub.height > maxY) maxY = sub.y + sub.height;
+	}
+	return {
+		x: minX,
+		y: minY,
+		width: maxX - minX,
+		height: maxY - minY
+	};
+}
+/**
 * O(1) pre-check: can we skip calling renderNodeToBuffer() on this child entirely?
 *
 * This is the Phase 4 "dirty set rendering" optimization. Instead of calling
@@ -3950,15 +6054,15 @@ function computeChildClipBounds(layout, props, parentClip, scrollOffset = 0, hor
 * Only clears OUTSIDE the node's rect — interior clearing is handled by clearNodeRegion
 * and renderBox. Recursive: follows subtreeDirty paths to find all overflowing descendants.
 */
-function clearDescendantOverflowRegions(node, buffer, layout, scrollOffset, clipBounds, threadedInheritedBg) {
+function clearDescendantOverflowRegions(node, buffer, sink, layout, scrollOffset, clipBounds, threadedInheritedBg) {
 	const clearBg = threadedInheritedBg.color;
 	const nodeRight = layout.x + layout.width;
 	const nodeBottom = layout.y - scrollOffset + layout.height;
 	const nodeLeft = layout.x;
 	const nodeTop = layout.y - scrollOffset;
-	_clearDescendantOverflow(node.children, buffer, nodeLeft, nodeTop, nodeRight, nodeBottom, scrollOffset, clipBounds, clearBg);
+	_clearDescendantOverflow(node.children, buffer, sink, nodeLeft, nodeTop, nodeRight, nodeBottom, scrollOffset, clipBounds, clearBg);
 }
-function _clearDescendantOverflow(children, buffer, nodeLeft, nodeTop, nodeRight, nodeBottom, scrollOffset, clipBounds, clearBg) {
+function _clearDescendantOverflow(children, buffer, sink, nodeLeft, nodeTop, nodeRight, nodeBottom, scrollOffset, clipBounds, clearBg) {
 	for (const child of children) {
 		if (child.prevLayout && isCurrentEpoch(child.layoutChangedThisFrame)) {
 			const prev = child.prevLayout;
@@ -3970,53 +6074,51 @@ function _clearDescendantOverflow(children, buffer, nodeLeft, nodeTop, nodeRight
 				const overflowWidth = Math.min(prevRight, buffer.width) - overflowX;
 				const overflowTop = Math.max(prevTop, clipBounds?.top ?? 0);
 				const overflowBottom = Math.min(prevBottom, clipBounds?.bottom ?? buffer.height);
-				if (overflowWidth > 0 && overflowBottom > overflowTop) buffer.fill(overflowX, overflowTop, overflowWidth, overflowBottom - overflowTop, {
-					char: " ",
-					bg: clearBg
-				});
+				if (overflowWidth > 0 && overflowBottom > overflowTop) sink.emitClearRect(overflowX, overflowTop, overflowWidth, overflowBottom - overflowTop, clearBg);
 			}
 			if (prevBottom > nodeBottom) {
 				const overflowTop = Math.max(nodeBottom, clipBounds?.top ?? 0);
 				const overflowBottom = Math.min(prevBottom, clipBounds?.bottom ?? buffer.height);
 				const overflowX = Math.max(prev.x, clipBounds?.left ?? 0);
 				const overflowWidth = Math.min(prevRight, clipBounds?.right ?? buffer.width) - overflowX;
-				if (overflowWidth > 0 && overflowBottom > overflowTop) buffer.fill(overflowX, overflowTop, overflowWidth, overflowBottom - overflowTop, {
-					char: " ",
-					bg: clearBg
-				});
+				if (overflowWidth > 0 && overflowBottom > overflowTop) sink.emitClearRect(overflowX, overflowTop, overflowWidth, overflowBottom - overflowTop, clearBg);
 			}
 			if (prev.x < nodeLeft) {
 				const overflowX = Math.max(prev.x, 0);
 				const overflowWidth = Math.min(nodeLeft, buffer.width) - overflowX;
 				const overflowTop = Math.max(prevTop, clipBounds?.top ?? 0);
 				const overflowBottom = Math.min(prevBottom, clipBounds?.bottom ?? buffer.height);
-				if (overflowWidth > 0 && overflowBottom > overflowTop) buffer.fill(overflowX, overflowTop, overflowWidth, overflowBottom - overflowTop, {
-					char: " ",
-					bg: clearBg
-				});
+				if (overflowWidth > 0 && overflowBottom > overflowTop) sink.emitClearRect(overflowX, overflowTop, overflowWidth, overflowBottom - overflowTop, clearBg);
 			}
 			if (prevTop < nodeTop) {
 				const overflowTop = Math.max(prevTop, clipBounds?.top ?? 0);
 				const overflowBottom = Math.min(nodeTop, clipBounds?.bottom ?? buffer.height);
 				const overflowX = Math.max(prev.x, clipBounds?.left ?? 0);
 				const overflowWidth = Math.min(prevRight, clipBounds?.right ?? buffer.width) - overflowX;
-				if (overflowWidth > 0 && overflowBottom > overflowTop) buffer.fill(overflowX, overflowTop, overflowWidth, overflowBottom - overflowTop, {
-					char: " ",
-					bg: clearBg
-				});
+				if (overflowWidth > 0 && overflowBottom > overflowTop) sink.emitClearRect(overflowX, overflowTop, overflowWidth, overflowBottom - overflowTop, clearBg);
 			}
 		}
-		if (isDirty(child.dirtyBits, child.dirtyEpoch, 16) && child.children !== void 0) _clearDescendantOverflow(child.children, buffer, nodeLeft, nodeTop, nodeRight, nodeBottom, scrollOffset, clipBounds, clearBg);
+		if (isDirty(child.dirtyBits, child.dirtyEpoch, 16) && child.children !== void 0) _clearDescendantOverflow(child.children, buffer, sink, nodeLeft, nodeTop, nodeRight, nodeBottom, scrollOffset, clipBounds, clearBg);
 	}
 }
 /**
-* Clear a node's region with inherited bg when it has no backgroundColor.
-* Also clears excess area when the node shrank (previous layout was larger).
+* Clear a node's CURRENT region with inherited bg when it has no backgroundColor.
+*
+* Single responsibility: fill the node's `layout` rect with `clearBg`,
+* clipped to the parent's bounds and to the colored ancestor's bounds.
+*
+* Smell #3 (paint-clear-step2-followups) — pre-decouple, this function
+* tail-called `clearExcessArea` unconditionally. That meant excess
+* clearing could fire on a fresh buffer when contentRegionCleared=true
+* but bufferIsCloned/hasPrevBuffer were false. Post-decouple,
+* `executeRegionClearing` is the SOLE coordinator: it calls
+* `clearNodeRegion` AND `clearExcessArea` independently when their
+* respective gates are true.
 *
 * Clipping: clips to parent's boxRect (prevents overflow) and to the
 * colored ancestor's bounds (prevents bg color bleeding into siblings).
 */
-function clearNodeRegion(node, buffer, layout, scrollOffset, clipBounds, layoutChanged, threadedInheritedBg) {
+function clearNodeRegion(node, sink, layout, scrollOffset, clipBounds, threadedInheritedBg) {
 	const inherited = threadedInheritedBg;
 	const clearBg = inherited.color;
 	const screenY = layout.y - scrollOffset;
@@ -4051,33 +6153,51 @@ function clearNodeRegion(node, buffer, layout, scrollOffset, clipBounds, layoutC
 			_cellDbg2.log.push(msg);
 			cellLog.debug?.(msg);
 		}
-		buffer.fill(clearX, clearY, clearWidth, clearHeight, {
-			char: " ",
-			bg: clearBg
-		});
+		sink.emitClearRect(clearX, clearY, clearWidth, clearHeight, clearBg);
 	}
-	clearExcessArea(node, buffer, layout, scrollOffset, clipBounds, layoutChanged, inherited);
+}
+/**
+* Construct an `ExcessClearGate` if and only if all four preconditions hold.
+* Returns null otherwise. This is the SOLE constructor for the brand.
+*
+* Preconditions (each enforces one structural invariant):
+*   - bufferIsCloned: there are stale pixels to clear (false for fresh buffers).
+*   - layoutChanged: the node's rect changed this frame (no shrink → no excess).
+*   - prevLayout != null: we have an old rect to compute the excess from.
+*   - hasPrevBuffer: the buffer at this node's position contains the *previous
+*     frame's* pixels (not first-pass-painted current-frame siblings — the
+*     latter is what second-pass absolute/sticky/overlap-forced dispatch sites
+*     pass with hasPrevBuffer=false). Excess-clearing on top of fresh sibling
+*     paint corrupts the in-progress frame; see km-silvery.ai-chat-incremental-mismatch.
+*/
+function requireExcessClearGate(bufferIsCloned, layoutChanged, prevLayout, hasPrevBuffer) {
+	if (!bufferIsCloned) return null;
+	if (!layoutChanged) return null;
+	if (prevLayout == null) return null;
+	if (!hasPrevBuffer) return null;
+	return { prevLayout };
 }
 /**
 * Clear the excess area when a node shrinks (old bounds were larger than new).
 *
-* This is separated from clearNodeRegion because excess area clearing must happen
-* even when contentRegionCleared is false. Key scenario: absolute-positioned overlays
-* (e.g., search dialog) that shrink while normal-flow siblings are dirty. The
-* forceRepaint path sets hasPrevBuffer=false + ancestorCleared=false, making
-* contentRegionCleared=false — but the cloned buffer still has stale pixels from
-* the old larger layout that must be cleared.
+* Requires an `ExcessClearGate` as the first parameter — only obtainable via
+* `requireExcessClearGate`, which checks the four preconditions. This makes
+* the wrong-order second-pass call site (the bug that motivated silvery
+* 168b4989) structurally unrepresentable: a caller cannot write
+* `clearExcessArea(...)` without first flowing through the factory, which
+* returns null when hasPrevBuffer=false (the second-pass case).
 *
-* Clips to the COLORED ANCESTOR's content area (not immediate parent's full rect)
-* to prevent inherited color from bleeding into sibling areas with different bg.
+* Clips to the COLORED ANCESTOR's content area (not immediate parent's full
+* rect) to prevent inherited color from bleeding into sibling areas with
+* different bg.
 *
 * IMPORTANT: Uses content area (inside border/padding), not full boxRect.
 * Without this, excess clearing of a child that previously filled the parent's
-* content area will extend into the parent's border row, overwriting border chars.
+* content area will extend into the parent's border row, overwriting border
+* chars.
 */
-function clearExcessArea(node, buffer, layout, scrollOffset, clipBounds, layoutChanged, inherited) {
-	if (!layoutChanged || !node.prevLayout) return;
-	const prev = node.prevLayout;
+function clearExcessArea(gate, node, buffer, sink, layout, scrollOffset, clipBounds, inherited) {
+	const prev = gate.prevLayout;
 	const _cellDbg3 = getCellDebug();
 	const _prevCoversCell3 = _cellDbg3 && cellCoversPoint(_cellDbg3, prev.x, prev.y - scrollOffset, prev.width, prev.height);
 	if (prev.width <= layout.width && prev.height <= layout.height) {
@@ -4117,16 +6237,16 @@ function clearExcessArea(node, buffer, layout, scrollOffset, clipBounds, layoutC
 		const excessX = layout.x + layout.width;
 		let excessWidth = prev.width - layout.width;
 		if (excessX + excessWidth > clipRectRight) excessWidth = Math.max(0, clipRectRight - excessX);
-		if (excessWidth > 0) clippedFill(buffer, excessX, excessWidth, prevScreenY, prevScreenY + prev.height, clipBounds, clipRectBottom, clearBg);
+		if (excessWidth > 0) clippedFill(sink, excessX, excessWidth, prevScreenY, prevScreenY + prev.height, clipBounds, clipRectBottom, clearBg);
 	}
 	if (prev.height > layout.height) {
 		let bottomWidth = prev.width;
 		if (layout.x + bottomWidth > clipRectRight) bottomWidth = Math.max(0, clipRectRight - layout.x);
-		clippedFill(buffer, layout.x, bottomWidth, screenY + layout.height, prevScreenY + prev.height, clipBounds, clipRectBottom, clearBg);
+		clippedFill(sink, layout.x, bottomWidth, screenY + layout.height, prevScreenY + prev.height, clipBounds, clipRectBottom, clearBg);
 	}
 }
 /** Fill a rectangular region, clipping to clipBounds and an outer bottom limit. */
-function clippedFill(buffer, x, width, top, bottom, clipBounds, outerBottom, bg) {
+function clippedFill(sink, x, width, top, bottom, clipBounds, outerBottom, bg) {
 	const clippedTop = clipBounds ? Math.max(top, clipBounds.top) : top;
 	const clippedBottom = Math.min(clipBounds ? Math.min(bottom, clipBounds.bottom) : bottom, outerBottom);
 	let clippedX = x;
@@ -4139,10 +6259,98 @@ function clippedFill(buffer, x, width, top, bottom, clipBounds, outerBottom, bg)
 		if (clippedX + clippedWidth > clipBounds.right) clippedWidth = Math.max(0, clipBounds.right - clippedX);
 	}
 	const height = clippedBottom - clippedTop;
-	if (height > 0 && clippedWidth > 0) buffer.fill(clippedX, clippedTop, clippedWidth, height, {
+	if (height > 0 && clippedWidth > 0) sink.emitClearRect(clippedX, clippedTop, clippedWidth, height, bg);
+}
+//#endregion
+//#region packages/ag-term/src/pipeline/render-plan.ts
+init_buffer();
+/**
+* Read the SILVERY_RENDER_PLAN env var. Returns true (default) UNLESS
+* the user explicitly opts out with `SILVERY_RENDER_PLAN=0` /
+* `SILVERY_RENDER_PLAN=false`.
+*
+* Phase 1: opt-in only (default off).
+* Phase 2: opt-in via flag for testing.
+* Phase 3 (current): default ON, opt-out for one release. The plan
+* capture + sectioned commit is now load-bearing — it runs every
+* frame, the captured plan is committed onto a fresh clone for parity
+* (verified by tests/features/render-plan-fuzz.test.tsx +
+* tests/features/render-plan-production.test.tsx). The opt-out exists
+* solely to roll back if a regression slips through; the next release
+* removes the env var entirely.
+*/
+function isRenderPlanEnabled() {
+	const v = (typeof process !== "undefined" ? process.env : void 0)?.SILVERY_RENDER_PLAN;
+	if (v === void 0) return true;
+	const lower = v.toLowerCase();
+	return lower !== "0" && lower !== "false" && lower !== "" && lower !== "off" && lower !== "no";
+}
+/**
+* Apply a sectioned plan to a target buffer in structural order:
+* transfer → cleanup → paint → overlay → postState. Within each section,
+* ops apply in plan-emission order (which preserves CSS paint order for
+* paintOps: later sibling bg can legitimately cover earlier sibling
+* overflow text).
+*
+* This is the L4 commit path: wrong-order sibling-stomp is unrepresentable
+* by construction because a `ClearOp` cannot end up in `paintOps` — the
+* type system rejects it.
+*/
+function commitSectionedPlan(target, plan) {
+	if (target.width !== plan.width || target.height !== plan.height) throw new Error(`commitSectionedPlan: buffer dimensions ${target.width}x${target.height} do not match plan ${plan.width}x${plan.height}`);
+	for (const op of plan.transferOps) applyTransfer(target, op);
+	for (const op of plan.cleanupOps) applyClear(target, op);
+	for (const op of plan.paintOps) applyPaint(target, op);
+	for (const op of plan.overlayOps) applyOverlay(target, op);
+	for (const op of plan.postStateOps) applyPostState(target, op);
+}
+function applyTransfer(buffer, op) {
+	buffer.scrollRegion(op.x, op.y, op.width, op.height, op.delta, selectablePatch(op.clearCell ?? {}, op.selectable));
+}
+function applyClear(buffer, op) {
+	if (op.kind === "clearRect") buffer.fill(op.x, op.y, op.width, op.height, {
 		char: " ",
-		bg
+		bg: op.bg,
+		selectable: op.selectable
 	});
+	else buffer.fill(op.x, op.y, op.width, op.height, op.cell);
+}
+function applyPaint(buffer, op) {
+	switch (op.kind) {
+		case "setCell":
+			buffer.setCell(op.x, op.y, op.cell);
+			return;
+		case "fillBg":
+			buffer.fillBg(op.x, op.y, op.width, op.height, op.bg);
+			return;
+		case "paintFill":
+			buffer.fill(op.x, op.y, op.width, op.height, op.cell);
+			return;
+		case "restyleRegion":
+			buffer.restyleRegion(op.x, op.y, op.width, op.height, op.style);
+			return;
+	}
+}
+function applyOverlay(buffer, op) {
+	buffer.mergeAttrsInRect(op.x, op.y, op.width, op.height, op.attrs, op.underlineColor);
+}
+function applyPostState(buffer, op) {
+	switch (op.kind) {
+		case "setRowMeta": {
+			const meta = {};
+			if (op.softWrapped !== void 0) meta.softWrapped = op.softWrapped;
+			if (op.lastContentCol !== void 0) meta.lastContentCol = op.lastContentCol;
+			buffer.setRowMeta(op.row, meta);
+			return;
+		}
+		case "setOutlineSnapshots": return;
+	}
+}
+function selectablePatch(cell, selectable) {
+	return selectable === void 0 ? cell : {
+		...cell,
+		selectable
+	};
 }
 //#endregion
 //#region packages/ag-term/src/pipeline/backdrop/color.ts
@@ -4207,12 +6415,15 @@ function normalizeHex(hex) {
 /**
 * Backdrop fade — stage 1: build the immutable `Plan`.
 *
-* `buildPlan(root, options)` is a PURE, capability-independent pass that
-* walks the tree, collects `data-backdrop-fade` / `data-backdrop-fade-excluded`
-* markers, enforces the single-amount invariant, and resolves the scrim +
-* default colors. The realizers (`./realize-buffer.ts`, `./realize-kitty.ts`)
-* trust the plan: they do NOT re-walk the tree, re-resolve the scrim, or
-* re-validate amounts. This module is the single source of truth.
+* `buildPlan(root, options)` is a PURE pass that walks the tree, collects
+* `data-backdrop-fade` / `data-backdrop-fade-excluded` markers, enforces
+* the single-amount invariant, and resolves the scrim + default colors.
+* It returns a `TerminalPlan` (`CorePlan` + `kittyEnabled`); call
+* `buildCorePlan` for a framework-agnostic plan that strips terminal
+* capability flags. The realizers (`./realize-buffer.ts`,
+* `./realize-kitty.ts`) trust the plan: they do NOT re-walk the tree,
+* re-resolve the scrim, or re-validate amounts. This module is the
+* single source of truth.
 *
 * ## The model: per-channel alpha scrim with perceptually-aware fg
 *
@@ -4232,7 +6443,7 @@ function normalizeHex(hex) {
 * Fg uses OKLCH deemphasize with explicit polarity so colored text
 * deemphasizes toward the correct theme neutral — toward black on dark
 * themes (same formula we've always used), toward white on light themes
-* (new — see `./color-compat.ts` for the math). The quadratic chroma
+* (new — see `./color-shim.ts` for the math). The quadratic chroma
 * falloff compensates for the human-vision nonlinearity that reads chroma
 * relative to luminance. Bg uses sRGB source-over because the Kitty
 * graphics scrim overlay composites in sRGB at alpha at the hardware
@@ -4303,10 +6514,15 @@ const INACTIVE_PLAN = Object.freeze({
 	kittyEnabled: false
 });
 /**
-* Quick check: does the tree contain any backdrop markers? Used as a gate so
-* we don't clone the buffer every frame when no fade is active. Walks the
-* full tree once (O(N)) — the alternative (tracking dirty markers in the
-* reconciler) is more complex and the walk is cheap compared to the pass.
+* Syntactic check: does the tree contain any `data-backdrop-fade*`
+* attribute? Returns true even when the marker amounts are 0 (which
+* yields an inactive plan). For "is the plan active this frame?" use
+* `buildPlan(...).active`.
+*
+* Used as a gate so we don't clone the buffer every frame when no
+* backdrop markers are mounted. Walks the full tree once (O(N)) — the
+* alternative (tracking dirty markers in the reconciler) is more complex
+* and the walk is cheap compared to the pass.
 */
 function hasBackdropMarkers(root) {
 	const props = root.props;
@@ -4314,20 +6530,28 @@ function hasBackdropMarkers(root) {
 	for (const child of root.children) if (hasBackdropMarkers(child)) return true;
 	return false;
 }
+Object.freeze({
+	active: false,
+	amount: 0,
+	scrim: null,
+	defaultBg: null,
+	defaultFg: null,
+	includes: Object.freeze([]),
+	excludes: Object.freeze([]),
+	mixedAmounts: false,
+	scrimTowardLight: false
+});
 /**
-* Stage 1 — build the immutable `Plan`.
-*
-* Pure function of `(tree markers, options)`. No buffer access, no Kitty
-* capability knowledge, no console I/O. The realizers read from the plan
-* exclusively; the orchestrator (`./index.ts`) handles dev-mode diagnostics
-* derived from `plan.mixedAmounts`.
+* Stage 1 (terminal) — build the immutable `TerminalPlan`.
 *
-* Returns `INACTIVE_PLAN` when:
-* - `colorLevel === "none"` (monochrome terminal — pass is a no-op).
-* - The tree has no backdrop markers, OR all markers have `amount <= 0`.
+* Same as `buildCorePlan` plus the derived `kittyEnabled` capability flag.
+* `kittyEnabled = options.kittyGraphics === true && scrim !== null` — the
+* overlay needs a resolvable tint to composite, so a null-scrim plan
+* cannot use the Kitty path even when the caller has the capability
+* enabled.
 */
 function buildPlan(root, options) {
-	if ((options?.colorLevel ?? "truecolor") === "none") return INACTIVE_PLAN;
+	if ((options?.colorLevel ?? "truecolor") === "mono") return INACTIVE_PLAN;
 	const includes = [];
 	const excludes = [];
 	const includeAmounts = [];
@@ -4340,7 +6564,10 @@ function buildPlan(root, options) {
 	const scrimTowardLight = isLightScrim(scrim);
 	const defaultFg = normalizeHex(options?.defaultFg) ?? (scrim === null ? null : scrimTowardLight ? "#000000" : "#ffffff");
 	const { amount, hasMixedAmounts } = assertSingleAmount(includeAmounts, excludeAmounts);
-	return {
+	const kittyEnabled = options?.kittyGraphics === true && scrim !== null;
+	Object.freeze(includes);
+	Object.freeze(excludes);
+	return Object.freeze({
 		active: true,
 		amount,
 		scrim,
@@ -4350,8 +6577,8 @@ function buildPlan(root, options) {
 		excludes,
 		mixedAmounts: hasMixedAmounts,
 		scrimTowardLight,
-		kittyEnabled: options?.kittyGraphics === true && scrim !== null
-	};
+		kittyEnabled
+	});
 }
 /**
 * Detect the single-amount invariant across all markers. Returns the
@@ -4411,16 +6638,22 @@ function collectBackdropMarkers(node, includes, excludes, includeAmounts, exclud
 	const includeRaw = props[BACKDROP_FADE_ATTR];
 	const excludeRaw = props[BACKDROP_FADE_EXCLUDE_ATTR];
 	if (includeRaw !== void 0 || excludeRaw !== void 0) {
-		const rect = node.screenRect ?? node.scrollRect ?? node.boxRect;
-		if (rect && rect.width > 0 && rect.height > 0) {
+		const sourceRect = node.screenRect ?? node.scrollRect ?? node.boxRect;
+		if (sourceRect && sourceRect.width > 0 && sourceRect.height > 0) {
+			const rect = Object.freeze({
+				x: sourceRect.x,
+				y: sourceRect.y,
+				width: sourceRect.width,
+				height: sourceRect.height
+			});
 			const inc = parseFade(includeRaw);
 			if (inc !== null) {
-				includes.push({ rect });
+				includes.push(Object.freeze({ rect }));
 				includeAmounts.push(inc);
 			}
 			const exc = parseFade(excludeRaw);
 			if (exc !== null) {
-				excludes.push({ rect });
+				excludes.push(Object.freeze({ rect }));
 				excludeAmounts.push(exc);
 			}
 		}
@@ -4459,48 +6692,23 @@ function parseFade(raw) {
 	return n > 1 ? 1 : n;
 }
 //#endregion
-//#region packages/ag-term/src/pipeline/backdrop/color-compat.ts
+//#region packages/ag-term/src/pipeline/backdrop/color-shim.ts
 /**
-* Backdrop fade — `@silvery/color` compatibility shim.
+* Backdrop fade — `@silvery/color` polarity-aware deemphasize shim.
 *
-* Temporary shim while `@silvery/color` lags behind on publish cycles.
-* `@silvery/color` does export `mixSrgb` and `deemphasize` from source; this
-* module prefers the upstream versions at runtime and falls back to a
-* local implementation when an upstream export is missing — e.g., when a
-* new helper is introduced in the same release cycle as the silvery
-* package that imports it (the published `@silvery/color` dist doesn't
-* ship the new name until its next publish, breaking CI verify).
+* `@silvery/color` exports `deemphasize` (dark-only, drifts L toward 0) and
+* `mixSrgb` directly. Use those whenever possible. The light-theme-aware
+* variant `deemphasizeOklchToward` (drifts L toward 0 OR 1 by polarity) is
+* NOT yet upstream — this file ships it locally.
 *
-* The fallback implementations are byte-identical to the upstream ones.
-* Once all downstream consumers of silvery are on a published version of
-* `@silvery/color` that exports every name we reference, delete the
-* `local*` fallbacks and collapse each export to a direct re-export.
-*
-* Light-theme-aware deemphasize (`deemphasizeOklchToward`) is NOT in
-* upstream yet — it's only shipped by this module. When it lands in
-* `@silvery/color`, replace the local implementation with an upstream
-* re-export behind the same shim.
+* **Deletion condition**: when `@silvery/color` exports
+* `deemphasizeOklchToward`, delete this file entirely and update
+* `./realize-buffer.ts` to import directly from `@silvery/color`. Audit
+* with `rg "from .*color-shim"` — should drop to zero.
 *
 * @see ./color.ts for hex↔rgb adapter helpers and `HexColor` type.
 */
 /**
-* sRGB source-over alpha mix. `out = a * (1 - t) + b * t`.
-*
-* Prefers `@silvery/color`'s published export; falls back to the local copy
-* when upstream doesn't ship the name yet. The local implementation matches
-* `@silvery/color/src/color.ts` byte-for-byte and is safe to use while the
-* publish train catches up.
-*/
-function localMixSrgb(a, b, t) {
-	const ra = hexToRgb$1(a);
-	const rb = hexToRgb$1(b);
-	if (!ra || !rb) return a;
-	const u = Math.max(0, Math.min(1, t));
-	return rgbToHex(ra.r * (1 - u) + rb.r * u, ra.g * (1 - u) + rb.g * u, ra.b * (1 - u) + rb.b * u);
-}
-/** sRGB source-over mix. Prefers upstream `@silvery/color`; falls back to the local copy. */
-const mixSrgb = Upstream.mixSrgb ?? localMixSrgb;
-/**
 * OKLCH-native deemphasize that drifts toward EITHER black (dark themes)
 * OR white (light themes). `towardLight` controls the lightness target;
 * the chroma falloff is identical in both directions.
@@ -4517,16 +6725,7 @@ const mixSrgb = Upstream.mixSrgb ?? localMixSrgb;
 * the human visual system reads chroma RELATIVE to luminance, so a modest
 * OKLCH C at extreme L *appears* distinctly more chromatic than the same C
 * near mid-L. Proportional L+C scaling (`C *= 1-α`, preserving C/L) feels
-* "more saturated when darkened" to viewers — the exact complaint that
-* prompted the quadratic version.
-*
-* Using `(1-α)²` for chroma reduces saturation faster than lightness on
-* both polarities:
-*
-*   α=0.25 → C *= 0.563  (C/L drops to 75% of original)
-*   α=0.40 → C *= 0.360  (C/L drops to 60%)
-*   α=0.50 → C *= 0.250  (C/L drops to 50%)
-*   α=1.00 → C *= 0      (fully faded to the target luminance).
+* "more saturated when darkened" to viewers.
 *
 * Light-theme case (towardLight=true): a bright colored text on a light
 * backdrop is made paler by raising L toward 1 and dropping C — the
@@ -4535,21 +6734,18 @@ const mixSrgb = Upstream.mixSrgb ?? localMixSrgb;
 * would darken colored text on a light bg, which reads as "text popping"
 * against the faded scrim rather than receding.
 */
-function localDeemphasizeOklchToward(hex, amount, towardLight) {
-	const o = upstreamHexToOklch(hex);
+function deemphasizeOklchToward(hex, amount, towardLight) {
+	const o = hexToOklch(hex);
 	if (!o) return hex;
 	const a = Math.max(0, Math.min(1, amount));
 	const chromaFactor = (1 - a) * (1 - a);
 	const L = towardLight ? o.L + (1 - o.L) * a : o.L * (1 - a);
-	return upstreamOklchToHex({
+	return oklchToHex({
 		L: Math.max(0, Math.min(1, L)),
 		C: Math.max(0, o.C * chromaFactor),
 		H: o.H
 	});
 }
-const upstreamHexToOklch = Upstream.hexToOklch;
-const upstreamOklchToHex = Upstream.oklchToHex;
-const deemphasizeOklchToward = Upstream.deemphasizeOklchToward ?? localDeemphasizeOklchToward;
 //#endregion
 //#region packages/ag-term/src/pipeline/backdrop/region.ts
 /**
@@ -4568,7 +6764,7 @@ const deemphasizeOklchToward = Upstream.deemphasizeOklchToward ?? localDeemphasi
 * Returns the count of unique cells visited. Useful for short-circuiting
 * the "was any cell modified?" signal in realizers.
 */
-function forEachFadeRegionCell(bufferWidth, bufferHeight, includes, excludes, visit) {
+function forEachBackdropCell(bufferWidth, bufferHeight, includes, excludes, visit) {
 	if (bufferWidth <= 0 || bufferHeight <= 0) return 0;
 	if (includes.length === 0 && excludes.length === 0) return 0;
 	const seen = new Uint8Array(bufferWidth * bufferHeight);
@@ -4617,9 +6813,47 @@ function forEachFadeRegionCell(bufferWidth, bufferHeight, includes, excludes, vi
 //#endregion
 //#region packages/ag-term/src/pipeline/backdrop/realize-buffer.ts
 /**
+* Backdrop fade — stage 2a: apply the plan's cell-level transform to the
+* terminal buffer.
+*
+* Uses the shared `forEachBackdropCell` walker (`./region.ts`) to visit
+* every cell covered by the plan's include + exclude rects exactly once.
+* Trusts the plan: no marker re-collection, no scrim/default resolution,
+* no amount validation, no capability re-derivation (`plan.kittyEnabled`
+* is the sole source of truth for the emoji branch).
+*
+* Wide ≠ emoji. CJK / Hangul / Japanese fullwidth text occupies two columns
+* but responds to `fg` color normally — it goes through the standard mix
+* path. Only EMOJI (bitmap glyphs that ignore `fg`) need special handling,
+* detected via `isLikelyEmoji(cell.char)`.
+*
+* For emoji cells, two paths, mutually exclusive:
+*
+* 1. **Kitty graphics available** (`plan.kittyEnabled === true`): emoji cells
+*    are SKIPPED entirely here. `./realize-kitty.ts` emits a translucent
+*    scrim image at alpha=amount above each emoji cell, and the terminal
+*    composites the overlay on top of the unmixed cell, landing at
+*    `cell_bg * (1 - amount) + scrim * amount` — the same luminance as
+*    surrounding text cells. This avoids the double-fade that would make
+*    emoji bg visibly blacker.
+*
+* 2. **Kitty graphics unavailable** (`plan.kittyEnabled === false`): the
+*    per-cell mix runs on emoji cells too and stamps `attrs.dim` (SGR 2)
+*    on lead + continuation. Terminals honoring SGR 2 on emoji fade the
+*    glyph; others see the glyph at full brightness but the cell bg
+*    matches surroundings.
+*
+* @see ./plan.ts for the color model and scrim derivation.
+* @see ./color.ts for the hex↔rgb adapter helpers.
+* @see @silvery/color for `mixSrgb`.
+* @see ./color-shim.ts for `deemphasizeOklchToward` (polarity-aware,
+*   not yet upstream).
+* @see ./region.ts for the shared include/exclude region walker.
+*/
+/**
 * Stage 2a — apply the plan's cell-level transform to the buffer.
 *
-* Walks every include + exclude cell once via `forEachFadeRegionCell` and
+* Walks every include + exclude cell once via `forEachBackdropCell` and
 * applies `fadeCell` with the plan's single `amount`. The buffer is mutated
 * in place.
 *
@@ -4635,7 +6869,7 @@ function realizeToBuffer(plan, buffer) {
 	if (!plan.active) return false;
 	if (plan.amount <= 0) return false;
 	let modified = false;
-	forEachFadeRegionCell(buffer.width, buffer.height, plan.includes, plan.excludes, (x, y) => {
+	forEachBackdropCell(buffer.width, buffer.height, plan.includes, plan.excludes, (x, y) => {
 		if (fadeCell(buffer, x, y, plan)) modified = true;
 	});
 	return modified;
@@ -4751,6 +6985,19 @@ function fadeCell(buffer, x, y, plan) {
 	if (fgHex && bgHex) {
 		const mixedRgb = hexToRgb$1(mixSrgb(fgHex, bgHex, amount));
 		if (!mixedRgb) return false;
+		if (isEmojiGlyph) {
+			const newAttrs = cell.attrs.dim ? cell.attrs : {
+				...cell.attrs,
+				dim: true
+			};
+			buffer.setCell(x, y, {
+				...cell,
+				fg: mixedRgb,
+				attrs: newAttrs
+			});
+			propagateToContinuation(buffer, cell, x, y, { dim: true });
+			return true;
+		}
 		buffer.setCell(x, y, {
 			...cell,
 			fg: mixedRgb
@@ -4818,17 +7065,19 @@ init_src();
 * Stage 2b — emit the Kitty graphics overlay for the plan.
 *
 * The output always begins with `CURSOR_SAVE + kittyDeleteAllScrimPlacements()
-* + CURSOR_RESTORE` when `plan.active` is true — even when zero emoji cells
+* + CURSOR_RESTORE` when the plan is realized — even when zero emoji cells
 * fall inside the faded region this frame. The unconditional clear is what
 * erases stale placements from a previous frame.
 *
-* Returns `""` when `plan.active` is false. Callers that also need to
-* suppress the overlay because Kitty graphics are not available should NOT
-* call this function at all — the orchestrator (`./index.ts`) guards the
-* call site with `plan.kittyEnabled`.
+* Returns `""` when the plan can't be realized as a Kitty overlay. Public
+* API safety — callers (tests, future consumers) should be able to invoke
+* this directly without re-deriving the `kittyEnabled` / `scrim` /
+* `amount > 0` gate. The orchestrator (`./index.ts`) also gates with
+* `plan.kittyEnabled` for clarity, but the early-out below is the
+* authoritative contract.
 */
 function realizeToKitty(plan, buffer) {
-	if (!plan.active) return "";
+	if (!plan.active || !plan.kittyEnabled || plan.amount <= 0 || plan.scrim === null) return "";
 	const cells = collectEmojiCellsInFadeRegion(buffer, plan);
 	const tint = hexToRgb$1(plan.scrim ?? plan.defaultBg ?? "#000000") ?? {
 		r: 0,
@@ -4866,13 +7115,13 @@ function realizeToKitty(plan, buffer) {
 * overlay because their rendering ignores the fg color.
 *
 * The iteration order is deterministic (delegated to
-* `forEachFadeRegionCell`), matching the buffer realizer's order. STRICT
+* `forEachBackdropCell`), matching the buffer realizer's order. STRICT
 * mode compares the overlay string across fresh and incremental paths —
 * any drift in this order would fail the comparison.
 */
 function collectEmojiCellsInFadeRegion(buffer, plan) {
 	const out = [];
-	forEachFadeRegionCell(buffer.width, buffer.height, plan.includes, plan.excludes, (x, y) => {
+	forEachBackdropCell(buffer.width, buffer.height, plan.includes, plan.excludes, (x, y) => {
 		if (x + 1 >= buffer.width) return;
 		if (!buffer.isCellWide(x, y)) return;
 		if (buffer.isCellContinuation(x, y)) return;
@@ -4917,7 +7166,7 @@ const EMPTY_RESULT = Object.freeze({
 */
 function applyBackdrop(root, buffer, options) {
 	const plan = buildPlan(root, options);
-	if (plan.mixedAmounts && process.env.NODE_ENV !== "production") console.warn(`[silvery:backdrop] multiple fade amounts in one frame (using ${plan.amount}); Kitty overlay will use the first observed amount. See plan.ts / assertSingleAmount.`);
+	if (plan.mixedAmounts && process.env.NODE_ENV !== "production") console.warn(`[silvery:backdrop] multiple fade amounts in one frame; plan.amount collapsed to the first observed (${plan.amount}). Visuals may differ from intent. See plan.ts / assertSingleAmount.`);
 	if (!plan.active) return EMPTY_RESULT;
 	return {
 		modified: realizeToBuffer(plan, buffer),
@@ -4925,62 +7174,6 @@ function applyBackdrop(root, buffer, options) {
 	};
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.126.0/helpers/usingCtx.js
-function _usingCtx() {
-	var r = "function" == typeof SuppressedError ? SuppressedError : function(r, e) {
-		var n = Error();
-		return n.name = "SuppressedError", n.error = r, n.suppressed = e, n;
-	}, e = {}, n = [];
-	function using(r, e) {
-		if (null != e) {
-			if (Object(e) !== e) throw new TypeError("using declarations can only be used with objects, functions, null, or undefined.");
-			if (r) var o = e[Symbol.asyncDispose || Symbol["for"]("Symbol.asyncDispose")];
-			if (void 0 === o && (o = e[Symbol.dispose || Symbol["for"]("Symbol.dispose")], r)) var t = o;
-			if ("function" != typeof o) throw new TypeError("Object is not disposable.");
-			t && (o = function o() {
-				try {
-					t.call(e);
-				} catch (r) {
-					return Promise.reject(r);
-				}
-			}), n.push({
-				v: e,
-				d: o,
-				a: r
-			});
-		} else r && n.push({
-			d: e,
-			a: r
-		});
-		return e;
-	}
-	return {
-		e,
-		u: using.bind(null, !1),
-		a: using.bind(null, !0),
-		d: function d() {
-			var o, t = this.e, s = 0;
-			function next() {
-				for (; o = n.pop();) try {
-					if (!o.a && 1 === s) return s = 0, n.push(o), Promise.resolve().then(next);
-					if (o.d) {
-						var r = o.d.call(o.v);
-						if (o.a) return s |= 2, Promise.resolve(r).then(next, err);
-					} else s |= 1;
-				} catch (r) {
-					return err(r);
-				}
-				if (1 === s) return t !== e ? Promise.reject(t) : Promise.resolve();
-				if (t !== e) throw t;
-			}
-			function err(n) {
-				return t = t !== e ? new r(n, t) : n, next();
-			}
-			return next();
-		}
-	};
-}
-//#endregion
 //#region packages/ag-term/src/ag.ts
 /**
 * Ag — tree + layout engine + renderer.
@@ -5071,129 +7264,106 @@ function createAg(root, options) {
 	const kittyGraphics = options?.kittyGraphics !== void 0 ? options.kittyGraphics : isKittyGraphicsEnabledFromEnv();
 	const ctx = measurer ? { measurer } : void 0;
 	let _prevBuffer = null;
+	let _postState = createRenderPostState();
 	let _kittyActive = false;
 	let hasScroll = false;
 	let hasSticky = false;
 	function doLayout(cols, rows, opts) {
-		try {
-			var _usingCtx$1 = _usingCtx();
-			const prevRootLayout = root.boxRect;
-			if (!(prevRootLayout && (prevRootLayout.width !== cols || prevRootLayout.height !== rows)) && !root.layoutNode?.isDirty() && !hasScrollDirty()) {
-				log.debug?.("layout: skipped (Flexily clean, no scrollDirty, dimensions unchanged)");
-				layoutPhase(root, cols, rows);
-				return {
-					tMeasure: 0,
-					tLayout: 0,
-					tScroll: 0,
-					tScrollRect: 0,
-					tNotify: 0
-				};
-			}
-			const render = _usingCtx$1.u(baseLog.span("pipeline", {
-				width: cols,
-				height: rows
-			}));
-			let tMeasure;
-			try {
-				var _usingCtx3 = _usingCtx();
-				_usingCtx3.u(render.span("measure"));
-				const t = performance.now();
-				measurePhase(root, ctx);
-				tMeasure = performance.now() - t;
-				log.debug?.(`measure: ${tMeasure.toFixed(2)}ms`);
-			} catch (_) {
-				_usingCtx3.e = _;
-			} finally {
-				_usingCtx3.d();
-			}
-			let tLayout;
-			try {
-				var _usingCtx4 = _usingCtx();
-				_usingCtx4.u(render.span("layout"));
-				const t = performance.now();
-				layoutPhase(root, cols, rows);
-				tLayout = performance.now() - t;
-				log.debug?.(`layout: ${tLayout.toFixed(2)}ms`);
-			} catch (_) {
-				_usingCtx4.e = _;
-			} finally {
-				_usingCtx4.d();
-			}
-			strictLayoutOverflowCheck(root);
-			if (!hasScroll || !hasSticky) {
-				const features = detectPipelineFeatures(root);
-				if (features.hasScroll) hasScroll = true;
-				if (features.hasSticky) hasSticky = true;
-			}
-			let tScroll;
-			if (hasScroll) try {
-				var _usingCtx5 = _usingCtx();
-				_usingCtx5.u(render.span("scroll"));
-				const t = performance.now();
-				scrollPhase(root, { skipStateUpdates: opts?.skipScrollStateUpdates });
-				tScroll = performance.now() - t;
-			} catch (_) {
-				_usingCtx5.e = _;
-			} finally {
-				_usingCtx5.d();
-			}
-			else tScroll = 0;
-			if (hasSticky) stickyPhase(root);
-			let tScrollRect;
-			try {
-				var _usingCtx6 = _usingCtx();
-				_usingCtx6.u(render.span("scrollRect"));
-				const t = performance.now();
-				if (hasScroll || hasSticky) scrollrectPhase(root);
-				else scrollrectPhaseSimple(root);
-				tScrollRect = performance.now() - t;
-			} catch (_) {
-				_usingCtx6.e = _;
-			} finally {
-				_usingCtx6.d();
-			}
-			let tNotify = 0;
-			if (!opts?.skipLayoutNotifications) try {
-				var _usingCtx7 = _usingCtx();
-				_usingCtx7.u(render.span("notify"));
-				const t = performance.now();
-				notifyLayoutSubscribers(root);
-				tNotify = performance.now() - t;
-			} catch (_) {
-				_usingCtx7.e = _;
-			} finally {
-				_usingCtx7.d();
-			}
-			const acc = globalThis.__silvery_bench_phases;
-			if (acc) {
-				acc.measure += tMeasure;
-				acc.layout += tLayout;
-				acc.scroll += tScroll;
-				acc.scrollRect += tScrollRect;
-				acc.notify += tNotify;
-				acc.layoutTotal += tMeasure + tLayout + tScroll + tScrollRect + tNotify;
-			}
+		const prevRootLayout = root.boxRect;
+		if (!(prevRootLayout && (prevRootLayout.width !== cols || prevRootLayout.height !== rows)) && !root.layoutNode?.isDirty() && !hasScrollDirty()) {
+			log.debug?.("layout: skipped (Flexily clean, no scrollDirty, dimensions unchanged)");
+			layoutPhase(root, cols, rows);
 			return {
-				tMeasure,
-				tLayout,
-				tScroll,
-				tScrollRect,
-				tNotify
+				tMeasure: 0,
+				tLayout: 0,
+				tScroll: 0,
+				tScrollRect: 0,
+				tNotify: 0
 			};
-		} catch (_) {
-			_usingCtx$1.e = _;
-		} finally {
-			_usingCtx$1.d();
 		}
+		using render = baseLog.span?.("pipeline", {
+			width: cols,
+			height: rows
+		});
+		let tMeasure;
+		{
+			using _m = render?.span("measure");
+			const t = performance.now();
+			measurePhase(root, ctx);
+			tMeasure = performance.now() - t;
+			log.debug?.(`measure: ${tMeasure.toFixed(2)}ms`);
+		}
+		let tLayout;
+		{
+			using _l = render?.span("layout");
+			const t = performance.now();
+			layoutPhase(root, cols, rows);
+			tLayout = performance.now() - t;
+			log.debug?.(`layout: ${tLayout.toFixed(2)}ms`);
+		}
+		strictLayoutOverflowCheck(root);
+		if (!hasScroll || !hasSticky) {
+			const features = detectPipelineFeatures(root);
+			if (features.hasScroll) hasScroll = true;
+			if (features.hasSticky) hasSticky = true;
+		}
+		let tScroll;
+		if (hasScroll) {
+			using _s = render?.span("scroll");
+			const t = performance.now();
+			scrollPhase(root, { skipStateUpdates: opts?.skipScrollStateUpdates });
+			tScroll = performance.now() - t;
+		} else tScroll = 0;
+		if (hasSticky) stickyPhase(root);
+		let tScrollRect;
+		{
+			using _r = render?.span("scrollRect");
+			const t = performance.now();
+			if (hasScroll || hasSticky) scrollrectPhase(root);
+			else scrollrectPhaseSimple(root);
+			tScrollRect = performance.now() - t;
+		}
+		let tNotify = 0;
+		if (!opts?.skipLayoutNotifications) {
+			using _n = render?.span("notify");
+			const t = performance.now();
+			notifyLayoutSubscribers(root);
+			tNotify = performance.now() - t;
+		}
+		const acc = globalThis.__silvery_bench_phases;
+		if (acc) {
+			acc.measure += tMeasure;
+			acc.layout += tLayout;
+			acc.scroll += tScroll;
+			acc.scrollRect += tScrollRect;
+			acc.notify += tNotify;
+			acc.layoutTotal += tMeasure + tLayout + tScroll + tScrollRect + tNotify;
+		}
+		return {
+			tMeasure,
+			tLayout,
+			tScroll,
+			tScrollRect,
+			tNotify
+		};
 	}
 	function doRender(opts) {
 		clearBgConflictWarnings();
 		const prevBuffer = opts?.fresh ? null : opts?.prevBuffer !== void 0 ? opts.prevBuffer : _prevBuffer;
+		const postState = opts?.fresh ? createRenderPostState() : opts?.postState ?? _postState;
 		let tContent;
 		let buffer;
 		{
 			const t = performance.now();
-			buffer = renderPhase(root, prevBuffer, ctx);
+			if (isRenderPlanEnabled()) {
+				const layout = root.boxRect;
+				if (!layout) throw new Error("doRender: SILVERY_RENDER_PLAN enabled but root has no boxRect");
+				const captured = withPlanCapture(layout.width, layout.height, () => renderPhase(root, prevBuffer, ctx, postState));
+				captured.result;
+				const replay = prevBuffer && prevBuffer.width === layout.width && prevBuffer.height === layout.height ? prevBuffer.clone() : new TerminalBuffer(layout.width, layout.height);
+				commitSectionedPlan(replay, captured.plan);
+				buffer = replay;
+			} else buffer = renderPhase(root, prevBuffer, ctx, postState);
 			tContent = performance.now() - t;
 			log.debug?.(`content: ${tContent.toFixed(2)}ms`);
 		}
@@ -5228,7 +7398,8 @@ function createAg(root, options) {
 			carryForwardBuffer,
 			prevBuffer,
 			tContent,
-			overlay
+			overlay,
+			postState
 		};
 	}
 	function agCreateNode(type, props) {
@@ -5281,11 +7452,13 @@ function createAg(root, options) {
 				buffer: result.buffer,
 				carryForwardBuffer: result.carryForwardBuffer,
 				prevBuffer: result.prevBuffer,
-				overlay: result.overlay
+				overlay: result.overlay,
+				postState: result.postState
 			};
 		},
 		resetBuffer() {
 			_prevBuffer = null;
+			_postState = createRenderPostState();
 		},
 		createNode: agCreateNode,
 		insertChild: agInsertChild,
@@ -5362,7 +7535,7 @@ init_buffer();
 let engineInitialized = false;
 async function ensureLayoutEngine() {
 	if (engineInitialized || isLayoutEngineInitialized()) return;
-	const { ensureDefaultLayoutEngine } = await import("./layout-engine-B6Cdz1yZ.mjs");
+	const { ensureDefaultLayoutEngine } = await import("./layout-engine-C07LEXWT.mjs");
 	await ensureDefaultLayoutEngine();
 	engineInitialized = true;
 }
@@ -5426,7 +7599,7 @@ function renderStringSync(element, options = {}) {
 		removeListener: () => mockStdout,
 		addListener: () => mockStdout
 	};
-	const mockTerm = createTerm({ color: plain ? null : "truecolor" });
+	const mockTerm = createTerm({ colorLevel: plain ? null : "truecolor" });
 	const wrapped = React.createElement(TermContext.Provider, { value: mockTerm }, React.createElement(StdoutContext.Provider, { value: {
 		stdout: mockStdout,
 		write: () => {}
@@ -5509,6 +7682,6 @@ function withActEnvironment(fn) {
 	}
 }
 //#endregion
-export { setActiveColorLevel as a, _usingCtx as i, renderStringSync as n, createAg as r, renderString as t };
+export { printPassHistogram as _, createRenderPostState as a, setActiveColorLevel as c, appendHistogramJson as d, assertBoundedConvergence as f, notePassCommit as g, logPass as h, hexToRgb$1 as i, INSTRUMENT as l, beginPass as m, renderStringSync as n, isStrictEnabled as o, beginConvergenceLoop as p, createAg as r, parseColor as s, renderString as t, MAX_CONVERGENCE_PASSES as u, resetPassHistogram as v };
 
-//# sourceMappingURL=render-string-X-CxpTdZ.mjs.map
+//# sourceMappingURL=render-string-DkQacASz.mjs.map