@deepseek-harness-tui/dsh-tui 0.10.0 → 0.10.2

package/lib/types/ink/output.d.ts

@@ -93,6 +93,8 @@ type WriteOperation = {
     x: number;
     y: number;
     text: string;
+    /** Prepared physical lines, reused by unchanged Text nodes across scrolls. */
+    lines?: readonly string[];
     /**
      * Per-line soft-wrap flags, parallel to text.split('\n'). softWrap[i]=true
      * means line i is a continuation of line i-1 (the `\n` before it was
@@ -267,8 +269,11 @@ export default class Output {
      * @param y - the top row.
      * @param text - the text to write.
      * @param softWrap - per-line soft-wrap flags parallel to text.split('\n').
+     * @param lines - optional pre-split physical lines, exactly text.split('\n').
      */
-    write(x: number, y: number, text: string, softWrap?: boolean[]): void;
+    write(x: number, y: number, text: string, softWrap?: boolean[], lines?: readonly string[]): void;
+    /** Whether a rectangle can contribute cells under the current paint clip. */
+    isRectVisible(x: number, y: number, width: number, height: number): boolean;
     /**
      * Push a clip region; subsequent writes are restricted to it.
      * @param clip - the clip region to apply.

package/lib/types/ink/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../src/ink/output.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../src/ink/output.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,sBAAsB,CAAA;AAChE,OAAO,EAcL,KAAK,MAAM,EACX,KAAK,SAAS,EAIf,MAAM,aAAa,CAAA;AAGpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAA;AAG5B;;;;;;;;;GASG;AACH,KAAK,aAAa,GAAG;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;CAC9B,CAAA;AAsCD;;;;GAIG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,GAAG,CAAqC;IAChD,OAAO,CAAC,KAAK,CAAI;IAEjB;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,GAAG,SAAS;IAS9C;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,IAAI;IAuBpD,mEAAmE;IACnE,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,qCAAqC;IACrC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;GAIG;AACH,KAAK,OAAO,GAAG;IACb,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,SAAS,CAAA;IACpB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,sBAAsB,KAAK,OAAO,CAAA;IAC3D,4EAA4E;IAC5E,cAAc,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACnD,CAAA;AAED,6FAA6F;AAC7F,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,aAAa,GACb,eAAe,GACf,aAAa,GACb,cAAc,GACd,cAAc,GACd,iBAAiB,GACjB,cAAc,CAAA;AAElB;;;;;GAKG;AACH,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,SAAS,CAAA;CAClB,CAAA;AAED,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,OAAO,CAAA;IACb,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,IAAI,EAAE,MAAM,CAAA;IACZ,8EAA8E;IAC9E,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CACrB,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,IAAI,CAAA;CACX,CAAA;AAED,uEAAuE;AACvE,MAAM,MAAM,IAAI,GAAG;IACjB,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;IACtB,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;IACtB,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;IACtB,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;CACvB,CAAA;AA6CD,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,QAAQ,CAAA;CACf,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,OAAO,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,CAAC,EAAE,MAAM,CAAA;CACV,CAAA;AAED,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,SAAS,CAAA;IACjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAED,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,UAAU,CAAA;IAChB,MAAM,EAAE,SAAS,CAAA;CAClB,CAAA;AAkKD;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,MAAM,CAAQ;IACtB,qBAAqB,EAAE,OAAO,CAAA;IAC9B,OAAO,CAAC,UAAU,CAA8D;IAEhF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA+B;IAC/D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwB;IACnD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgC;IACjE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,cAAc,CAAmC;IAEzD,OAAO,CAAC,SAAS,CAAkB;IAEnC;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,WAAW,CAAI;IAEvB,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAK3B;IAED,2EAA2E;IAC3E,OAAO,CAAC,aAAa;IAmBrB;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAA2D;gBAEpE,OAAO,EAAE,OAAO;IAc5B;;;;;;;;;OASG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,cAAc,UAAQ,EACtB,cAAc,GAAE,SAAS,sBAAsB,EAAO,EACtD,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,sBAAsB,KAAK,OAAO,GAC1D,IAAI;IAmBP;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAI5E;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAInD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI;IAItD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAI9B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAIjC;;;;OAIG;IACH,KAAK,CACH,IAAI,EAAE,UAAU,EAChB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,mBAAmB,EAC3B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO;IAgEV;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAuBtC,0EAA0E;IAC1E,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAI3C,6DAA6D;IAC7D,wBAAwB,CACtB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO;IAcV,uEAAuE;IACvE,SAAS,IAAI,SAAS,sBAAsB,EAAE;IAoB9C,gFAAgF;IAChF,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IASpC;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAehG,6EAA6E;IAC7E,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAQ3E;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAQtB,uCAAuC;IACvC,MAAM,IAAI,IAAI;IAOd;;;OAGG;IACH,GAAG,IAAI,MAAM;CAoPd"}

package/lib/types/ink/output.js

@@ -6,6 +6,7 @@ import { reorderBidi } from './bidi.js';
 import { unionRect } from './layout/geometry.js';
 import { blitRegion, cellRunSpan, createCellRun, extractHyperlinkFromStyles, filterOutHyperlinkStyles, markNoSelectRegion, OSC8_PREFIX, shadeRegion, recordCellRunEntry, recordSpacerRunEntry, replayCellRun, resetScreen, setCellAt, shiftRows, } from './screen.js';
 import { stringWidth } from './stringWidth.js';
+import { expandTabs } from './tabstops.js';
 import { TERMINAL_IMAGE_MAX_CELLS, TERMINAL_IMAGE_MAX_FRAME_BYTES, TERMINAL_IMAGE_MAX_PLACEMENTS, } from './terminal-image.js';
 import { widestLine } from './widest-line.js';
 /**
@@ -540,7 +541,7 @@ export default class Output {
             const occluded = this.operations.slice(end).some(op => {
                 if (op.type === 'write')
                     return overlaps({ x: op.x, y: op.y,
-                        width: widestLine(op.text), height: op.text.split('\n').length });
+                        width: widestLine(op.text), height: op.lines?.length ?? op.text.split('\n').length });
                 if (op.type === 'blit')
                     return overlaps(op);
                 if (op.type === 'clear' || op.type === 'shade')
@@ -568,8 +569,9 @@ export default class Output {
      * @param y - the top row.
      * @param text - the text to write.
      * @param softWrap - per-line soft-wrap flags parallel to text.split('\n').
+     * @param lines - optional pre-split physical lines, exactly text.split('\n').
      */
-    write(x, y, text, softWrap) {
+    write(x, y, text, softWrap, lines) {
         if (!text) {
             return;
         }
@@ -579,8 +581,17 @@ export default class Output {
             y,
             text,
             softWrap,
+            lines,
         });
     }
+    /** Whether a rectangle can contribute cells under the current paint clip. */
+    isRectVisible(x, y, width, height) {
+        const clip = this.imageClips.at(-1);
+        return x < Math.min(this.width, clip?.x2 ?? this.width) &&
+            x + width > Math.max(0, clip?.x1 ?? 0) &&
+            y < Math.min(this.height, clip?.y2 ?? this.height) &&
+            y + height > Math.max(0, clip?.y1 ?? 0);
+    }
     /**
      * Push a clip region; subsequent writes are restricted to it.
      * @param clip - the clip region to apply.
@@ -724,72 +735,51 @@ export default class Output {
                 case 'write': {
                     const { text, softWrap } = operation;
                     let { x, y } = operation;
-                    let lines = text.split('\n');
-                    let swFrom = 0;
+                    let lines = operation.lines ?? text.split('\n');
                     let prevContentEnd = 0;
                     const clip = clips.at(-1);
-                    if (clip) {
-                        const clipHorizontally = typeof clip?.x1 === 'number' && typeof clip?.x2 === 'number';
-                        const clipVertically = typeof clip?.y1 === 'number' && typeof clip?.y2 === 'number';
-                        // If text is positioned outside of clipping area altogether,
-                        // skip to the next operation to avoid unnecessary calculations
-                        if (clipHorizontally) {
-                            const width = widestLine(text);
-                            if (x + width <= clip.x1 || x >= clip.x2) {
-                                continue;
-                            }
-                        }
-                        if (clipVertically) {
-                            const height = lines.length;
-                            if (y + height <= clip.y1 || y >= clip.y2) {
-                                continue;
-                            }
-                        }
-                        if (clipHorizontally) {
-                            lines = lines.map(line => {
-                                const from = x < clip.x1 ? clip.x1 - x : 0;
-                                const width = stringWidth(line);
-                                const to = x + width > clip.x2 ? clip.x2 - x : width;
-                                // Fast path: the line sits entirely inside the clip — no
-                                // slice needed. sliceAnsi re-tokenizes the line (the
-                                // dominant per-frame cost of long sessions otherwise:
-                                // every settled line, every frame).
-                                if (from === 0 && to === width)
-                                    return line;
-                                let sliced = sliceAnsi(line, from, to);
-                                // Wide chars (CJK, emoji) occupy 2 cells. When `to` lands
-                                // on the first cell of a wide char, sliceAnsi includes the
-                                // entire glyph and the result overflows clip.x2 by one cell,
-                                // writing a SpacerTail into the adjacent sibling. Re-slice
-                                // one cell earlier; wide chars are exactly 2 cells, so a
-                                // single retry always fits.
-                                if (stringWidth(sliced) > to - from) {
-                                    sliced = sliceAnsi(line, from, to - 1);
-                                }
-                                return sliced;
-                            });
-                            if (x < clip.x1) {
-                                x = clip.x1;
-                            }
-                        }
-                        if (clipVertically) {
-                            const from = y < clip.y1 ? clip.y1 - y : 0;
-                            const height = lines.length;
-                            const to = y + height > clip.y2 ? clip.y2 - y : height;
-                            // If the first visible line is a soft-wrap continuation, we
-                            // need the clipped previous line's content end so
-                            // screen.softWrap[lineY] correctly records the join point
-                            // even though that line's cells were never written.
-                            if (softWrap && from > 0 && softWrap[from] === true) {
-                                prevContentEnd = x + stringWidth(lines[from - 1]);
-                            }
-                            lines = lines.slice(from, to);
-                            swFrom = from;
-                            if (y < clip.y1) {
-                                y = clip.y1;
-                            }
-                        }
+                    // Clip vertically BEFORE measuring or slicing ANSI lines. A long
+                    // tool result/code block may intersect the viewport by one row;
+                    // horizontal work over its entire history is still O(transcript).
+                    // Screen bounds apply even without an explicit overflow clip.
+                    const from = Math.max(0, Math.max(0, clip?.y1 ?? 0) - y);
+                    const to = Math.min(lines.length, Math.min(screenHeight, clip?.y2 ?? screenHeight) - y);
+                    if (from >= to)
+                        continue;
+                    const swFrom = from;
+                    const clipHorizontally = typeof clip?.x1 === 'number' && typeof clip?.x2 === 'number';
+                    if (clipHorizontally && x >= clip.x2)
+                        continue;
+                    const clipLine = (line) => {
+                        // Width/slicing treat raw tabs as zero cells. Expand at the
+                        // ORIGINAL x before clipping, also for the soft-wrap predecessor.
+                        line = expandTabs(line, undefined, x);
+                        if (!clipHorizontally)
+                            return line;
+                        const start = Math.max(0, clip.x1 - x);
+                        const width = stringWidth(line);
+                        const end = Math.min(width, clip.x2 - x);
+                        if (start >= end)
+                            return '';
+                        if (start === 0 && end === width)
+                            return line;
+                        let sliced = sliceAnsi(line, start, end);
+                        // Do not leave a wide glyph's SpacerTail outside the clip.
+                        if (stringWidth(sliced) > end - start)
+                            sliced = sliceAnsi(line, start, end - 1);
+                        return sliced;
+                    };
+                    const writeX = clipHorizontally ? Math.max(x, clip.x1) : x;
+                    // Copy joins need only the preceding (horizontally clipped) line,
+                    // not every discarded line. Preserve its content-end coordinate.
+                    if (softWrap && from > 0 && softWrap[from] === true) {
+                        prevContentEnd = writeX + stringWidth(clipLine(lines[from - 1]));
                     }
+                    lines = lines.slice(from, to);
+                    if (clipHorizontally)
+                        lines = lines.map(clipLine);
+                    x = writeX;
+                    y += from;
                     const swBits = screen.softWrap;
                     let offsetY = 0;
                     for (const line of lines) {

package/lib/types/ink/render-node-to-output.d.ts

@@ -27,12 +27,20 @@ export type AbsoluteHitEntry = {
     node: DOMElement;
     rect: Rectangle;
 };
+export type OcclusionSurface = {
+    node: DOMElement;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    filled: boolean;
+};
 /**
  * The current frame's absolute-positioned nodes in paint order.
  * @returns read-only list; reverse-iterate for topmost-first hit-testing.
  */
 export declare function getAbsoluteHitList(): readonly AbsoluteHitEntry[];
-/** Reset the scroll hint for the next frame and rotate the absolute-rect buffers. */
+/** Reset the scroll hint for the next frame and rotate the per-frame buffers. */
 export declare function resetScrollHint(): void;
 /**
  * Frame-end check: did any PREVIOUS frame's absolute overlay vacate cells
@@ -58,6 +66,21 @@ export declare function resetScrollHint(): void;
  * a smaller image left the wider card's borders and title on screen).
  */
 export declare function hasOverlayVacatedCells(): boolean;
+/**
+ * Frame-end check: occlusion surfaces whose recorded cover decision no
+ * longer matches the frame's terminal-image placements.
+ *
+ * Two paths leave a surface stale: (1) it painted before a same-frame
+ * image that registers later in walk order — output.getImages() had not
+ * admitted the placement yet and the previous frame had none; (2) a
+ * clean-subtree blit skipped the surface entirely, restoring its old
+ * cells while an image behind it appeared, moved, or was removed. The
+ * caller re-walks each stale surface (markDirty) and schedules a frame
+ * so the cover follows image changes even with no pending React commit.
+ * @param output - the output whose previous/current placements re-decide.
+ * @returns surfaces (nodes) whose recorded decision mismatches; may be empty.
+ */
+export declare function getOcclusionMismatchNodes(output: Output): DOMElement[];
 /**
  * The scroll hint captured this frame, or null.
  * @returns the scroll hint, or null when none was captured.

package/lib/types/ink/render-node-to-output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-node-to-output.d.ts","sourceRoot":"","sources":["../../../src/ink/render-node-to-output.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render-node-to-output.d.ts","sourceRoot":"","sources":["../../../src/ink/render-node-to-output.ts"],"names":[],"mappings":"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"}

package/lib/types/ink/render-node-to-output.js

@@ -3,7 +3,7 @@ import { applyTextStyles } from './colorize.js';
 import { GEOMETRY_TRACE_ENABLED, noteScrollGeometry } from './geometry-trace.js';
 import getMaxWidth from './get-max-width.js';
 import { LayoutDisplay, LayoutEdge } from './layout/node.js';
-import { nodeCache, pendingClears } from './node-cache.js';
+import { nodeCache, pendingClears, textPaintCache } from './node-cache.js';
 import renderBorder from './render-border.js';
 import { squashTextNodesToSegments, } from './squash-text-nodes.js';
 import { isXtermJs } from './terminal.js';
@@ -44,6 +44,8 @@ let scrollHint = null;
 let absoluteRectsPrev = [];
 let absoluteRectsCur = [];
 let absoluteHitList = [];
+let occlusionSurfacesPrev = [];
+let occlusionSurfacesCur = [];
 /**
  * The current frame's absolute-positioned nodes in paint order.
  * @returns read-only list; reverse-iterate for topmost-first hit-testing.
@@ -51,21 +53,61 @@ let absoluteHitList = [];
 export function getAbsoluteHitList() {
     return absoluteHitList;
 }
-/** Reset the scroll hint for the next frame and rotate the absolute-rect buffers. */
+/** Reset the scroll hint for the next frame and rotate the per-frame buffers. */
 export function resetScrollHint() {
     scrollHint = null;
     absoluteRectsPrev = absoluteRectsCur;
     absoluteRectsCur = [];
     absoluteHitList = [];
+    occlusionSurfacesPrev = occlusionSurfacesCur;
+    occlusionSurfacesCur = [];
 }
 /** A node fills every cell of its rect when it has its own background or
  *  is declared `opaque`; anything else leaves gaps to the layer below. */
 function paintsOwnRect(node) {
     return node.style.opaque === true || node.style.backgroundColor !== undefined;
 }
+/** Whether a ready terminal-image placement overlaps the given screen rect
+ *  — the paint condition for `occlusionColor`. Consults the previous
+ *  frame's placements (the overlay may cover an image rendered in an
+ *  earlier tree position that has not painted yet this frame) and the
+ *  current frame's (an image may appear behind an already-open overlay);
+ *  same intersection and graphicsReady semantics as
+ *  Output.hasPreviousImageInRegion. */
+function terminalImageBehindRect(output, x, y, width, height) {
+    const left = Math.floor(x);
+    const top = Math.floor(y);
+    const occlusionWidth = Math.floor(width);
+    const occlusionHeight = Math.floor(height);
+    if (output.hasPreviousImageInRegion(left, top, occlusionWidth, occlusionHeight)) {
+        return true;
+    }
+    const right = left + occlusionWidth;
+    const bottom = top + occlusionHeight;
+    return output.getImages().some(placement => placement.graphicsReady !== false &&
+        placement.x < right &&
+        placement.x + placement.columns > left &&
+        placement.y < bottom &&
+        placement.y + placement.rows > top);
+}
 function sameRect(a, b) {
     return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
 }
+/** Whether a READY placement from the CURRENT frame's registrations overlaps
+ *  the rect — the frame-end truth for getOcclusionMismatchNodes. Unlike the
+ *  walk-time check it does not consult the previous frame: a cover that
+ *  outlived its image must be corrected, and reuseImages keeps every
+ *  still-valid placement in the current set even under clean-subtree blits.
+ *  Coordinates are pre-floored (OcclusionSurface records). */
+function currentImageBehindRect(images, x, y, width, height) {
+    const right = x + width;
+    const bottom = y + height;
+    return images.some(placement => placement.graphicsReady !== false &&
+        placement.x < right &&
+        placement.x + placement.columns > x &&
+        placement.y < bottom &&
+        placement.y + placement.rows > y);
+}
 /**
  * Frame-end check: did any PREVIOUS frame's absolute overlay vacate cells
  * that no CURRENT overlay rect covers (the overlay shrank or moved)?
@@ -114,6 +156,43 @@ export function hasOverlayVacatedCells() {
     }
     return false;
 }
+/**
+ * Frame-end check: occlusion surfaces whose recorded cover decision no
+ * longer matches the frame's terminal-image placements.
+ *
+ * Two paths leave a surface stale: (1) it painted before a same-frame
+ * image that registers later in walk order — output.getImages() had not
+ * admitted the placement yet and the previous frame had none; (2) a
+ * clean-subtree blit skipped the surface entirely, restoring its old
+ * cells while an image behind it appeared, moved, or was removed. The
+ * caller re-walks each stale surface (markDirty) and schedules a frame
+ * so the cover follows image changes even with no pending React commit.
+ * @param output - the output whose previous/current placements re-decide.
+ * @returns surfaces (nodes) whose recorded decision mismatches; may be empty.
+ */
+export function getOcclusionMismatchNodes(output) {
+    const stale = [];
+    const walked = new Set();
+    // One snapshot for every surface: getImages() rescans the operation
+    // stream per placement, so calling it per surface would be quadratic.
+    const images = output.getImages();
+    for (const surface of occlusionSurfacesCur) {
+        walked.add(surface.node);
+        if (currentImageBehindRect(images, surface.x, surface.y, surface.width, surface.height) !==
+            surface.filled) {
+            stale.push(surface.node);
+        }
+    }
+    for (const surface of occlusionSurfacesPrev) {
+        if (walked.has(surface.node))
+            continue;
+        if (currentImageBehindRect(images, surface.x, surface.y, surface.width, surface.height) !==
+            surface.filled) {
+            stale.push(surface.node);
+        }
+    }
+    return stale;
+}
 /**
  * The scroll hint captured this frame, or null.
  * @returns the scroll hint, or null when none was captured.
@@ -489,7 +568,27 @@ function renderNodeToOutput(node, output, options) {
         // diff finds nothing, and the highlight never clears). Compare against
         // the value recorded at the previous render and refuse the blit when it
         // moved.
-        const effectiveBg = node.style.backgroundColor ?? inheritedBackgroundColor;
+        // `occlusionColor` promotes to a real background only while a
+        // terminal image sits behind this node's rect (see the Styles doc):
+        // transparent overlay surfaces in the common frame, covered image
+        // placements otherwise.
+        const occlusionBackground = node.style.backgroundColor === undefined &&
+            node.style.occlusionColor !== undefined &&
+            terminalImageBehindRect(output, x, y, width, height)
+            ? node.style.occlusionColor
+            : undefined;
+        if (node.style.occlusionColor !== undefined &&
+            node.style.backgroundColor === undefined) {
+            occlusionSurfacesCur.push({
+                node,
+                x: Math.floor(x),
+                y: Math.floor(y),
+                width: Math.floor(width),
+                height: Math.floor(height),
+                filled: occlusionBackground !== undefined,
+            });
+        }
+        const effectiveBg = node.style.backgroundColor ?? occlusionBackground ?? inheritedBackgroundColor;
         const bgChanged = cached?.bg !== effectiveBg;
         const imageBackingChanged = node.nodeName === 'ink-image' &&
             output.terminalImagesEnabled &&
@@ -580,6 +679,13 @@ function renderNodeToOutput(node, output, options) {
             node.dirty = false;
             return;
         }
+        // Text is a paint leaf: unlike boxes, it cannot own an escaping overlay.
+        // Keep the old-position cleanup above, but cull before squash/wrap/style.
+        if (node.nodeName === 'ink-text' && width > 0 && height > 0 && !output.isRectVisible(x, y, width, height)) {
+            nodeCache.delete(node);
+            node.dirty = false;
+            return;
+        }
         if (node.nodeName === 'ink-raw-ansi') {
             // Pre-rendered ANSI content. The producer already wrapped to width and
             // emitted terminal-ready escape codes. Skip squash, measure, wrap, and
@@ -590,70 +696,87 @@ function renderNodeToOutput(node, output, options) {
             }
         }
         else if (node.nodeName === 'ink-text') {
-            const segments = squashTextNodesToSegments(node, inheritedBackgroundColor
-                ? { backgroundColor: inheritedBackgroundColor }
-                : undefined);
-            // First, get plain text to check if wrapping is needed
-            const plainText = segments.map(s => s.text).join('');
-            if (plainText.length > 0) {
-                // Upstream Ink uses getMaxWidth(yogaNode) unclamped here. That
-                // width comes from Yoga's AtMost pass and can exceed the actual
-                // screen space (see getMaxWidth docstring). Yoga's height for this
-                // node already reflects the constrained Exactly pass, so clamping
-                // the wrap width here keeps line count consistent with layout.
-                // Without this, characters past the screen edge are dropped by
-                // setCellAt's bounds check.
-                const maxWidth = Math.min(getMaxWidth(yogaNode), output.width - x);
-                const textWrap = node.style.textWrap ?? 'wrap';
-                // Check if wrapping is needed
-                const needsWrapping = widestLine(plainText) > maxWidth;
-                let text;
-                let softWrap;
-                if (needsWrapping && segments.length === 1) {
-                    // Single segment: wrap plain text first, then apply styles to each line
-                    const segment = segments[0];
-                    const w = wrapWithSoftWrap(plainText, maxWidth, textWrap);
-                    softWrap = w.softWrap;
-                    text = w.wrapped
-                        .split('\n')
-                        .map(line => {
-                        let styled = applyTextStyles(line, segment.styles);
-                        // Apply OSC 8 hyperlink per-line so each line is independently
-                        // clickable. output.ts splits on newlines and tokenizes each
-                        // line separately, so a single wrapper around the whole block
-                        // would only apply the hyperlink to the first line.
-                        if (segment.hyperlink) {
-                            styled = wrapWithOsc8Link(styled, segment.hyperlink);
-                        }
-                        return styled;
-                    })
-                        .join('\n');
-                }
-                else if (needsWrapping) {
-                    // Multiple segments with wrapping: wrap plain text first, then re-apply
-                    // each segment's styles based on character positions. This preserves
-                    // per-segment styles even when text wraps across lines.
-                    const w = wrapWithSoftWrap(plainText, maxWidth, textWrap);
-                    softWrap = w.softWrap;
-                    const charToSegment = buildCharToSegmentMap(segments);
-                    text = applyStylesToWrappedText(w.wrapped, segments, charToSegment, plainText, textWrap === 'wrap-trim');
-                    // Hyperlinks are handled per-run in applyStylesToWrappedText via
-                    // wrapWithOsc8Link, similar to how styles are applied per-run.
-                }
-                else {
-                    // No wrapping needed: apply styles directly
-                    text = segments
-                        .map(segment => {
-                        let styledText = applyTextStyles(segment.text, segment.styles);
-                        if (segment.hyperlink) {
-                            styledText = wrapWithOsc8Link(styledText, segment.hyperlink);
-                        }
-                        return styledText;
-                    })
-                        .join('');
+            // A partially visible long block moves on every scroll/stream frame.
+            // Node blits cannot reuse it at a new y, but its prepared lines can.
+            // Keep one current preparation, independent of the shared wrap LRU
+            // (a single large tool/code block can overflow that cache by itself).
+            const maxWidth = Math.min(getMaxWidth(yogaNode), output.width - x);
+            const paddingNode = node.childNodes[0]?.yogaNode;
+            const paddingLeft = paddingNode?.getComputedLeft() ?? 0;
+            const paddingTop = paddingNode?.getComputedTop() ?? 0;
+            const prepared = textPaintCache.get(node);
+            if (prepared !== undefined &&
+                prepared.maxWidth === maxWidth &&
+                prepared.background === inheritedBackgroundColor &&
+                prepared.paddingLeft === paddingLeft &&
+                prepared.paddingTop === paddingTop) {
+                output.write(x, y, prepared.text, prepared.softWrap, prepared.lines);
+            }
+            else {
+                const segments = squashTextNodesToSegments(node, inheritedBackgroundColor
+                    ? { backgroundColor: inheritedBackgroundColor }
+                    : undefined);
+                // First, get plain text to check if wrapping is needed
+                const plainText = segments.map(s => s.text).join('');
+                if (plainText.length > 0) {
+                    // Use the same content constraint as measurement, not the rounded
+                    // pixel-grid box. Offscreen overflow still clips at the terminal edge.
+                    const textWrap = node.style.textWrap ?? 'wrap';
+                    // Check if wrapping is needed
+                    const needsWrapping = widestLine(plainText) > maxWidth;
+                    let text;
+                    let softWrap;
+                    if (needsWrapping && segments.length === 1) {
+                        // Single segment: wrap plain text first, then apply styles to each line
+                        const segment = segments[0];
+                        const w = wrapWithSoftWrap(plainText, maxWidth, textWrap);
+                        softWrap = w.softWrap;
+                        text = w.wrapped
+                            .split('\n')
+                            .map(line => {
+                            let styled = applyTextStyles(line, segment.styles);
+                            // Apply OSC 8 hyperlink per-line so each line is independently
+                            // clickable. output.ts splits on newlines and tokenizes each
+                            // line separately, so a single wrapper around the whole block
+                            // would only apply the hyperlink to the first line.
+                            if (segment.hyperlink) {
+                                styled = wrapWithOsc8Link(styled, segment.hyperlink);
+                            }
+                            return styled;
+                        })
+                            .join('\n');
+                    }
+                    else if (needsWrapping) {
+                        // Multiple segments with wrapping: wrap plain text first, then re-apply
+                        // each segment's styles based on character positions. This preserves
+                        // per-segment styles even when text wraps across lines.
+                        const w = wrapWithSoftWrap(plainText, maxWidth, textWrap);
+                        softWrap = w.softWrap;
+                        const charToSegment = buildCharToSegmentMap(segments);
+                        text = applyStylesToWrappedText(w.wrapped, segments, charToSegment, plainText, textWrap === 'wrap-trim');
+                        // Hyperlinks are handled per-run in applyStylesToWrappedText via
+                        // wrapWithOsc8Link, similar to how styles are applied per-run.
+                    }
+                    else {
+                        // No wrapping needed: apply styles directly
+                        text = segments
+                            .map(segment => {
+                            let styledText = applyTextStyles(segment.text, segment.styles);
+                            if (segment.hyperlink) {
+                                styledText = wrapWithOsc8Link(styledText, segment.hyperlink);
+                            }
+                            return styledText;
+                        })
+                            .join('');
+                    }
+                    text = applyPaddingToText(node, text, softWrap);
+                    const lines = text.split('\n');
+                    textPaintCache.set(node, {
+                        maxWidth, background: inheritedBackgroundColor, paddingLeft, paddingTop,
+                        text, lines, softWrap,
+                    });
+                    output.write(x, y, text, softWrap, lines);
                 }
-                text = applyPaddingToText(node, text, softWrap);
-                output.write(x, y, text, softWrap);
             }
         }
         else if (node.nodeName === 'ink-image' &&
@@ -675,7 +798,7 @@ function renderNodeToOutput(node, output, options) {
             }
         }
         else if (node.nodeName === 'ink-box' || node.nodeName === 'ink-image') {
-            const boxBackgroundColor = node.style.backgroundColor ?? inheritedBackgroundColor;
+            const boxBackgroundColor = node.style.backgroundColor ?? occlusionBackground ?? inheritedBackgroundColor;
             // Mark this box's region as non-selectable (fullscreen text
             // selection). noSelect ops are applied AFTER blits/writes in
             // output.get(), so this wins regardless of what's rendered into
@@ -1216,11 +1339,12 @@ function renderNodeToOutput(node, output, options) {
                                 // blitted content — output.clear() only expands damage and
                                 // cannot zero cells that the blit already wrote.
                                 const screenBottom = Math.min(Math.floor(contentY + childBottom), Math.floor((y1 ?? y) + padTop + innerHeight));
-                                if (screenY < screenBottom) {
-                                    const fill = Array(screenBottom - screenY)
+                                const fillTop = Math.max(screenY, top);
+                                if (fillTop < screenBottom) {
+                                    const fill = Array(screenBottom - fillTop)
                                         .fill(spaces)
                                         .join('\n');
-                                    output.write(Math.floor(x), screenY, fill);
+                                    output.write(Math.floor(x), fillTop, fill);
                                     output.clip({
                                         x1: undefined,
                                         x2: undefined,
@@ -1322,7 +1446,7 @@ function renderNodeToOutput(node, output, options) {
                 if (node.style.backdrop !== undefined) {
                     output.shade({ x: Math.floor(x), y: Math.floor(y), width: Math.floor(width), height: Math.floor(height) });
                 }
-                const ownBackgroundColor = node.style.backgroundColor;
+                const ownBackgroundColor = node.style.backgroundColor ?? occlusionBackground;
                 if (ownBackgroundColor || node.style.opaque) {
                     const borderLeft = yogaNode.getComputedBorder(LayoutEdge.Left);
                     const borderRight = yogaNode.getComputedBorder(LayoutEdge.Right);