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

package/lib/types/ink/ink.js

@@ -38,7 +38,7 @@ import { applyPositionedHighlight, scanPositions } from './render-to-screen.js';
 import createRenderer from './renderer.js';
 import { CharPool, cellAt, createScreen, HyperlinkPool, isEmptyCellAt, migrateScreenPools, StylePool } from './screen.js';
 import { applySearchHighlight } from './transcript-highlight.js';
-import { applySelectionOverlay, captureScrolledRows, clearSelection, createSelectionState, extendSelection, findPlainTextUrlAt, getSelectedText, hasSelection, moveFocus, pickFollowForSelection, selectLineAt, selectWordAt, shiftSelection, shiftSelectionForFollow, shiftSelectionForViewportResize, shiftSelectionForViewportTranslation, startSelection, updateSelection } from './selection.js';
+import { applySelectionOverlay, captureScrolledRows, clearSelection, createSelectionState, extendSelection, findPlainTextUrlAt, getSelectedText, hasSelection, moveFocus, pickFollowForSelection, refreshSelectionFingerprint, selectLineAt, selectWordAt, shiftSelection, shiftSelectionForFollow, shiftSelectionForViewportResize, shiftSelectionForViewportTranslation, startSelection, updateSelection } from './selection.js';
 import { isDecstbmSafe, SYNC_OUTPUT_SUPPORTED, serializeDiff, supportsDecrqmProbe, supportsExtendedKeys, supportsWin32InputMode, writeDiffToTerminal } from './terminal.js';
 import { CURSOR_HOME, cursorMove, cursorPosition, DISABLE_KITTY_KEYBOARD, DISABLE_MODIFY_OTHER_KEYS, DISABLE_WIN32_INPUT_MODE, ENABLE_KITTY_KEYBOARD, ENABLE_MODIFY_OTHER_KEYS, ENABLE_WIN32_INPUT_MODE, ERASE_SCREEN, ERASE_SCROLLBACK, SGR_RESET } from './termio/csi.js';
 import { DBP, DFE, DISABLE_MOUSE_TRACKING, ENABLE_MOUSE_TRACKING, ENTER_ALT_SCREEN, EXIT_ALT_SCREEN, SHOW_CURSOR } from './termio/dec.js';
@@ -674,9 +674,20 @@ export default class Ink {
             altScreen: this.altScreenActive,
             terminalImages: this.altScreenActive && (this.kittyGraphicsSupported || this.sixelGraphicsSupported),
             imageReady: sixelActive ? this.sixelGraphicsManager.prepare : undefined,
+            // Sixel paints rasters over the cells: an image's own cells must then
+            // carry the surface background instead of terminal-default blanks.
+            opaqueImageBacking: sixelActive,
             prevFrameContaminated: this.prevFrameContaminated
         });
         const rendererMs = performance.now() - renderStart;
+        // Whether THIS frame ran a selection-coordinate translation (viewport
+        // resize/follow-shift). A covered-rows fingerprint change in such a
+        // frame is the coordinated kind — content moved WITH the highlight.
+        // An UNcoordinated change means the rows under a stationary highlight
+        // were replaced in place (streaming transcript overwrite), and the
+        // selection is marked stale so commit-time copy refuses (see
+        // refreshSelectionFingerprint below the overlay block).
+        let selectionCoordinated = false;
         this.maybeProbeKittyGraphics(frame.images ?? []);
         // Viewport-shrink translation (companion to the follow block below):
         // chrome mounting around a ScrollBox (the new-messages pill, the sticky
@@ -706,12 +717,14 @@ export default class Ink {
                 const hadSelection = hasSelection(this.selection);
                 if (resize.kind === 'translate') {
                     const cleared = shiftSelectionForViewportTranslation(this.selection, resize.rowDelta, resize.prevTop, resize.prevBottom, resize.top, resize.bottom);
+                    selectionCoordinated = true;
                     if (cleared)
                         for (const cb of this.selectionListeners)
                             cb();
                 }
                 else {
                     shiftSelectionForViewportResize(this.selection, this.frontFrame.screen, resize.prevTop, resize.prevBottom, resize.top, resize.bottom);
+                    selectionCoordinated = true;
                     // Both-ends-covered clear must notify React-land so useHasSelection
                     // re-renders and the footer copy/escape hint disappears — direct
                     // listener fire (notifySelectionChange would re-enter onRender).
@@ -775,6 +788,7 @@ export default class Ink {
                 // allowClear=false: both ends clamp to the edge; the ghost guard
                 // runs at release via dragBounds above.
                 shiftSelectionForFollow(this.selection, shift, viewportTop, viewportBottom, false);
+                selectionCoordinated = true;
             }
             else if (
             // Flag-3 guard: the anchor check above only proves ONE endpoint is
@@ -794,6 +808,7 @@ export default class Ink {
                     captureScrolledRows(this.selection, this.frontFrame.screen, firstRow, lastRow, side, follow.screenRowOffset);
                 }
                 const cleared = shiftSelectionForFollow(this.selection, shift, viewportTop, viewportBottom);
+                selectionCoordinated = true;
                 // Auto-clear (both ends overshot an edge — off the top via
                 // follow/wheel-down, off the bottom via wheel-up) must notify
                 // React-land so useHasSelection re-renders and the footer
@@ -832,6 +847,13 @@ export default class Ink {
             if (selActive) {
                 applySelectionOverlay(frame.screen, this.selection, this.stylePool);
             }
+            // Commit-consistency guard: hash the rows under the highlight on the
+            // frame the copy would actually read. An uncoordinated change since
+            // the previous frame latches selection.stale; copySelectionNoClear
+            // then refuses rather than shipping whatever text now occupies the
+            // highlight coordinates. Runs on frame.screen (post-render, pre-swap)
+            // with this frame's coordinated selection coordinates.
+            refreshSelectionFingerprint(this.selection, frame.screen, selectionCoordinated);
             // Scan-highlight: inverse on ALL visible matches (less/vim style).
             // Position-highlight (below) overlays CURRENT (yellow) on top.
             hlActive = applySearchHighlight(frame.screen, this.searchHighlightQuery, this.stylePool);
@@ -1910,6 +1932,19 @@ export default class Ink {
     copySelectionNoClear() {
         if (!hasSelection(this.selection))
             return '';
+        // Commit-consistency guard: the rows under the highlight changed
+        // without follow coordination during the selection's lifetime, so
+        // these coordinates now hold text the user never highlighted.
+        // Shipping it would copy visibly wrong content (the "mojibake-looking"
+        // paste of another line); refuse, clear the stale highlight, and let
+        // the caller surface it (React callers enter through copySelection /
+        // useCopyOnSelect's onRefused — the direct no-clear entry must not
+        // leave the misleading highlight up either).
+        if (this.selection.stale) {
+            clearSelection(this.selection);
+            this.notifySelectionChange();
+            return '';
+        }
         const text = getSelectedText(this.selection, this.frontFrame.screen);
         if (text) {
             // Raw OSC 52, or DCS-passthrough-wrapped OSC 52 inside tmux (tmux

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

@@ -73,6 +73,14 @@ type Options = {
     /** Paint image fallbacks as blank backing cells and collect placements. */
     terminalImages?: boolean;
     imageReady?: (placement: TerminalImagePlacement) => boolean;
+    /**
+     * True when the active protocol paints rasters OVER the cell grid (Sixel)
+     * instead of behind it (Kitty). Image-owned cells must then carry the
+     * surface background: the raster covers them anyway, and terminal-default
+     * blanks would show as black holes wherever a raster fails to cover a cell
+     * (aspect rounding, suppressed/occluded placements).
+     */
+    opaqueImageBacking?: boolean;
     /** Image requests from the diff baseline, reused by clean subtree blits. */
     previousImages?: readonly TerminalImagePlacement[];
 };
@@ -161,6 +169,7 @@ export default class Output {
     private readonly stylePool;
     private screen;
     terminalImagesEnabled: boolean;
+    opaqueImageBacking: boolean;
     private imageReady;
     private readonly operations;
     private readonly imagePlacements;
@@ -201,7 +210,7 @@ export default class Output {
      * @param height - the new screen height in rows.
      * @param screen - the screen buffer to render into.
      */
-    reset(width: number, height: number, screen: Screen, terminalImages?: boolean, previousImages?: readonly TerminalImagePlacement[], imageReady?: (placement: TerminalImagePlacement) => boolean): void;
+    reset(width: number, height: number, screen: Screen, terminalImages?: boolean, previousImages?: readonly TerminalImagePlacement[], imageReady?: (placement: TerminalImagePlacement) => boolean, opaqueImageBacking?: boolean): void;
     /**
      * Copy cells from a source screen region (blit = block image transfer).
      * @param src - the source screen.

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":"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"}

package/lib/types/ink/output.js

@@ -274,6 +274,81 @@ function buildClusteredChars(line, stylePool, slot) {
     updateStreamingSlot(slot, line, clustered, chars);
     return clustered;
 }
+/**
+ * The screen rect a paint operation covers, when it can occlude a raster
+ * painted earlier in the same frame. `clip`/`unclip`/`noSelect` paint nothing.
+ */
+function imageOcclusionRect(op, width) {
+    if (op.type === 'write') {
+        return { x: op.x, y: op.y, width: widestLine(op.text), height: op.lines?.length ?? op.text.split('\n').length };
+    }
+    if (op.type === 'blit')
+        return op;
+    if (op.type === 'clear' || op.type === 'shade')
+        return op.region;
+    if (op.type === 'shift')
+        return { x: 0, y: op.top, width, height: op.bottom - op.top + 1 };
+    return undefined;
+}
+/**
+ * The union of two rects, but only when that union covers no cell the pair did
+ * not already cover between them. Two rects qualify when one contains the
+ * other, or when they are bands sharing a full edge span (same x-span and
+ * abutting/overlapping rows, or the transpose) — exactly the pairs whose union
+ * is itself a rectangle. An L-shaped pair does not qualify: the bounding box of
+ * its two arms covers cells neither arm covers, and the caller would erase
+ * pixels that are still visible.
+ * @param a - the first rectangle.
+ * @param b - the second rectangle.
+ * @returns their union, or undefined when folding them would add cells.
+ */
+function exactUnion(a, b) {
+    const contains = (outer, inner) => outer.x <= inner.x && outer.y <= inner.y &&
+        outer.x + outer.width >= inner.x + inner.width &&
+        outer.y + outer.height >= inner.y + inner.height;
+    if (contains(a, b))
+        return a;
+    if (contains(b, a))
+        return b;
+    const sameColumns = a.x === b.x && a.width === b.width &&
+        a.y <= b.y + b.height && b.y <= a.y + a.height;
+    const sameRows = a.y === b.y && a.height === b.height &&
+        a.x <= b.x + b.width && b.x <= a.x + a.width;
+    return sameColumns || sameRows ? unionRect(a, b) : undefined;
+}
+/**
+ * Fold occluder rects that can be folded without covering anything new, so an
+ * image protocol that has to erase them (Sixel) does not repeat the same cells.
+ * One overlay usually contributes several rects for the same area (interior
+ * fill, border row, text row), and an overlay that covers several placements
+ * would otherwise erase the shared cells once per placement.
+ *
+ * Folding stops at exact unions on purpose. The erasure has to match the cells
+ * an overlay really covers: merging any two intersecting rects into their
+ * bounding box would take down the pixels beside an L-shaped cover, which are
+ * still on screen.
+ */
+function mergeOcclusionRects(rects) {
+    const merged = [];
+    for (const rect of rects) {
+        let current = rect;
+        let joined = true;
+        while (joined) {
+            joined = false;
+            for (let index = merged.length - 1; index >= 0; index--) {
+                const other = merged[index];
+                const union = exactUnion(current, other);
+                if (union === undefined)
+                    continue;
+                current = union;
+                merged.splice(index, 1);
+                joined = true;
+            }
+        }
+        merged.push(current);
+    }
+    return merged;
+}
 /**
  * Collects write/blit/clear/clip operations from the render tree, then
  * applies them to a Screen buffer in get(). The Screen is what gets
@@ -287,6 +362,7 @@ export default class Output {
     stylePool;
     screen;
     terminalImagesEnabled;
+    opaqueImageBacking;
     imageReady;
     operations = [];
     imagePlacements = [];
@@ -345,6 +421,7 @@ export default class Output {
         this.stylePool = stylePool;
         this.screen = screen;
         this.terminalImagesEnabled = options.terminalImages ?? false;
+        this.opaqueImageBacking = options.opaqueImageBacking ?? false;
         this.imageReady = options.imageReady;
         this.previousImages = options.previousImages ?? [];
         resetScreen(screen, width, height);
@@ -359,11 +436,12 @@ export default class Output {
      * @param height - the new screen height in rows.
      * @param screen - the screen buffer to render into.
      */
-    reset(width, height, screen, terminalImages = false, previousImages = [], imageReady) {
+    reset(width, height, screen, terminalImages = false, previousImages = [], imageReady, opaqueImageBacking = false) {
         this.width = width;
         this.height = height;
         this.screen = screen;
         this.terminalImagesEnabled = terminalImages;
+        this.opaqueImageBacking = opaqueImageBacking;
         this.imageReady = imageReady;
         this.previousImages = previousImages;
         this.operations.length = 0;
@@ -535,22 +613,36 @@ export default class Output {
             if (end === undefined)
                 return placement;
             const visible = placement.clip ?? placement;
-            const overlaps = (rect) => rect.x < visible.x + visible.columns &&
-                rect.x + rect.width > visible.x && rect.y < visible.y + visible.rows &&
-                rect.y + rect.height > visible.y;
-            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.lines?.length ?? op.text.split('\n').length });
-                if (op.type === 'blit')
-                    return overlaps(op);
-                if (op.type === 'clear' || op.type === 'shade')
-                    return overlaps(op.region);
-                if (op.type === 'shift')
-                    return overlaps({ x: 0, y: op.top, width: this.width, height: op.bottom - op.top + 1 });
-                return false;
-            });
-            return { ...placement, occluded };
+            const right = visible.x + visible.columns;
+            const bottom = visible.y + visible.rows;
+            const overlaps = (rect) => rect.x < right &&
+                rect.x + rect.width > visible.x && rect.y < bottom && rect.y + rect.height > visible.y;
+            // A later paint that covers the whole visible rect makes the raster
+            // unreachable and erasing is the only correct outcome (a blank `opaque`
+            // overlay would otherwise be pierced by the pixels beneath it). A paint
+            // that covers only part of it must not take the rest of the raster down
+            // with it — SixelGraphicsManager keeps those pixels instead.
+            const covers = (rect) => rect.x <= visible.x && rect.y <= visible.y &&
+                rect.x + rect.width >= right && rect.y + rect.height >= bottom;
+            let occluded = false;
+            let covered = false;
+            const occluders = [];
+            for (const op of this.operations.slice(end)) {
+                const rect = imageOcclusionRect(op, this.width);
+                if (rect === undefined || !overlaps(rect))
+                    continue;
+                occluded = true;
+                if (covers(rect)) {
+                    covered = true;
+                    break;
+                }
+                occluders.push(rect);
+            }
+            if (!occluded)
+                return placement;
+            if (covered)
+                return { ...placement, occluded, occludedFully: true };
+            return { ...placement, occluded, coveredRects: mergeOcclusionRects(occluders) };
         });
     }
     /** Pixel ownership is determined by paint order, not just final text values. */

package/lib/types/ink/render-border.d.ts

@@ -1,6 +1,7 @@
 import { type Boxes, type BoxStyle } from 'cli-boxes';
 import type { DOMNode } from './dom.js';
 import type Output from './output.js';
+import type { Color } from './styles.js';
 /** Options for embedding a text label into a border line. */
 export type BorderTextOptions = {
     content: string;
@@ -30,7 +31,11 @@ export type BorderStyle = keyof Boxes | keyof typeof CUSTOM_BORDER_STYLES | BoxS
  * @param y - the border's top row.
  * @param node - the node whose border style to render.
  * @param output - the output buffer receiving the border writes.
+ * @param background - the surface color the border's cells belong to, when the
+ *   node paints its own rect (own background, `opaque`, or an occlusion color
+ *   while a terminal image sits behind it). Transparent bordered overlays pass
+ *   undefined and keep terminal-transparent border cells.
  */
-declare const renderBorder: (x: number, y: number, node: DOMNode, output: Output) => void;
+declare const renderBorder: (x: number, y: number, node: DOMNode, output: Output, background?: Color) => void;
 export default renderBorder;
 //# sourceMappingURL=render-border.d.ts.map

package/lib/types/ink/render-border.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-border.d.ts","sourceRoot":"","sources":["../../../src/ink/render-border.ts"],"names":[],"mappings":"AACA,OAAiB,EAAE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAA;AAE/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAIrC,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,KAAK,GAAG,QAAQ,CAAA;IAC1B,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAA;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;CAYvB,CAAA;AAEV,qFAAqF;AACrF,MAAM,MAAM,WAAW,GACnB,MAAM,KAAK,GACX,MAAM,OAAO,oBAAoB,GACjC,QAAQ,CAAA;AAiDZ;;;;;;;GAOG;AACH,QAAA,MAAM,YAAY,GAChB,GAAG,MAAM,EACT,GAAG,MAAM,EACT,MAAM,OAAO,EACb,QAAQ,MAAM,KACb,IA8IF,CAAA;AAED,eAAe,YAAY,CAAA"}
+{"version":3,"file":"render-border.d.ts","sourceRoot":"","sources":["../../../src/ink/render-border.ts"],"names":[],"mappings":"AACA,OAAiB,EAAE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAA;AAE/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,KAAK,GAAG,QAAQ,CAAA;IAC1B,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAA;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;CAYvB,CAAA;AAEV,qFAAqF;AACrF,MAAM,MAAM,WAAW,GACnB,MAAM,KAAK,GACX,MAAM,OAAO,oBAAoB,GACjC,QAAQ,CAAA;AA0DZ;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,YAAY,GAChB,GAAG,MAAM,EACT,GAAG,MAAM,EACT,MAAM,OAAO,EACb,QAAQ,MAAM,EACd,aAAa,KAAK,KACjB,IAqJF,CAAA;AAED,eAAe,YAAY,CAAA"}

package/lib/types/ink/render-border.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import cliBoxes from 'cli-boxes';
-import { applyColor } from './colorize.js';
+import { applyColor, applyTextStyles } from './colorize.js';
 import { stringWidth } from './stringWidth.js';
 /** Built-in border styles beyond those provided by cli-boxes. */
 export const CUSTOM_BORDER_STYLES = {
@@ -40,11 +40,19 @@ function embedTextInBorder(borderLine, text, align, offset = 0, borderChar) {
         borderLine.substring(borderLength - 1);
     return [before, text, after];
 }
-function styleBorderLine(line, color, dim) {
+function styleBorderLine(line, color, dim, background) {
     let styled = applyColor(line, color);
     if (dim) {
         styled = chalk.dim(styled);
     }
+    // The cells a border occupies belong to the surface it frames. Without an
+    // explicit background they diff back to the terminal default, which reads
+    // as a black frame around any bordered surface sitting on a colored one (a
+    // tooltip over the preview card, that card over a tool card) and as a black
+    // hole wherever a Sixel raster is exposed by a border row or column.
+    if (background !== undefined) {
+        styled = applyTextStyles(styled, { backgroundColor: background });
+    }
     return styled;
 }
 /**
@@ -54,8 +62,12 @@ function styleBorderLine(line, color, dim) {
  * @param y - the border's top row.
  * @param node - the node whose border style to render.
  * @param output - the output buffer receiving the border writes.
+ * @param background - the surface color the border's cells belong to, when the
+ *   node paints its own rect (own background, `opaque`, or an occlusion color
+ *   while a terminal image sits behind it). Transparent bordered overlays pass
+ *   undefined and keep terminal-transparent border cells.
  */
-const renderBorder = (x, y, node, output) => {
+const renderBorder = (x, y, node, output, background) => {
     if (node.style.borderStyle) {
         const width = Math.floor(node.yogaNode.getComputedWidth());
         const height = Math.floor(node.yogaNode.getComputedHeight());
@@ -85,12 +97,12 @@ const renderBorder = (x, y, node, output) => {
         if (showTopBorder && node.style.borderText?.position === 'top') {
             const [before, text, after] = embedTextInBorder(topBorderLine, node.style.borderText.content, node.style.borderText.align, node.style.borderText.offset, box.top);
             topBorder =
-                styleBorderLine(before, topBorderColor, dimTopBorderColor) +
+                styleBorderLine(before, topBorderColor, dimTopBorderColor, background) +
                     text +
-                    styleBorderLine(after, topBorderColor, dimTopBorderColor);
+                    styleBorderLine(after, topBorderColor, dimTopBorderColor, background);
         }
         else if (showTopBorder) {
-            topBorder = styleBorderLine(topBorderLine, topBorderColor, dimTopBorderColor);
+            topBorder = styleBorderLine(topBorderLine, topBorderColor, dimTopBorderColor, background);
         }
         let verticalBorderHeight = height;
         if (showTopBorder) {
@@ -108,6 +120,10 @@ const renderBorder = (x, y, node, output) => {
         if (dimRightBorderColor) {
             rightBorder = chalk.dim(rightBorder);
         }
+        if (background !== undefined) {
+            leftBorder = applyTextStyles(leftBorder, { backgroundColor: background });
+            rightBorder = applyTextStyles(rightBorder, { backgroundColor: background });
+        }
         const bottomBorderLine = showBottomBorder
             ? (showLeftBorder ? box.bottomLeft : '') +
                 box.bottom.repeat(contentWidth) +
@@ -118,12 +134,12 @@ const renderBorder = (x, y, node, output) => {
         if (showBottomBorder && node.style.borderText?.position === 'bottom') {
             const [before, text, after] = embedTextInBorder(bottomBorderLine, node.style.borderText.content, node.style.borderText.align, node.style.borderText.offset, box.bottom);
             bottomBorder =
-                styleBorderLine(before, bottomBorderColor, dimBottomBorderColor) +
+                styleBorderLine(before, bottomBorderColor, dimBottomBorderColor, background) +
                     text +
-                    styleBorderLine(after, bottomBorderColor, dimBottomBorderColor);
+                    styleBorderLine(after, bottomBorderColor, dimBottomBorderColor, background);
         }
         else if (showBottomBorder) {
-            bottomBorder = styleBorderLine(bottomBorderLine, bottomBorderColor, dimBottomBorderColor);
+            bottomBorder = styleBorderLine(bottomBorderLine, bottomBorderColor, dimBottomBorderColor, background);
         }
         const offsetY = showTopBorder ? 1 : 0;
         if (topBorder) {

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

@@ -787,10 +787,23 @@ function renderNodeToOutput(node, output, options) {
             // rect, though, and those non-default-background cells would also hide
             // the image itself. Replace only the image-owned cells with default-
             // background spaces; layout and surrounding inherited color stay intact.
+            //
+            // Sixel paints the raster OVER the cells instead, so its backing may
+            // (and must) carry the surface background: the raster covers those
+            // cells anyway, and terminal-default blanks would show as black holes
+            // wherever the raster misses a cell — aspect rounding at the right
+            // edge, or a suppressed placement whose cells the frame no longer
+            // repaints.
             const imageWidth = Math.floor(width);
             const imageHeight = Math.floor(height);
+            const backingColor = output.opaqueImageBacking
+                ? node.style.backgroundColor ?? inheritedBackgroundColor
+                : undefined;
             const imageLine = ' '.repeat(imageWidth);
-            output.write(Math.floor(x), Math.floor(y), Array(imageHeight).fill(imageLine).join('\n'));
+            const fillLine = backingColor === undefined
+                ? imageLine
+                : applyTextStyles(imageLine, { backgroundColor: backingColor });
+            output.write(Math.floor(x), Math.floor(y), Array(imageHeight).fill(fillLine).join('\n'));
             output.imageBacking(node);
             for (const child of node.childNodes) {
                 if (child.nodeName !== '#text')
@@ -891,10 +904,25 @@ function renderNodeToOutput(node, output, options) {
                 // Capture previous scroll bounds BEFORE overwriting — the at-bottom
                 // follow check compares against last frame's max.
                 const prevScrollHeight = node.scrollHeight ?? scrollHeight;
-                const prevInnerHeight = node.scrollViewportHeight ?? innerHeight;
+                const prevViewportHeight = node.scrollViewportHeight;
+                const prevInnerHeight = prevViewportHeight ?? innerHeight;
                 const prevViewportTop = node.scrollViewportTop;
                 node.scrollHeight = scrollHeight;
                 node.scrollViewportHeight = innerHeight;
+                // Viewport-height change is the one geometry move no scroll notify
+                // covers: chrome above/below the box mounts or unmounts (pill,
+                // pinned header, recap row) or the terminal changes row count —
+                // the viewport resizes with no scroll delta and no sticky flip,
+                // while subscribers that paint from the handle's bounds still hold
+                // the previous pass's geometry. Fire only on a real transition
+                // between two passes: a first frame (`undefined`) observed no
+                // change, and scrollTop/scrollViewportTop motion is excluded on
+                // purpose (see DOMElement.onViewportHeightChange). Called in the
+                // render pass like onStickyRestore below.
+                if (prevViewportHeight !== undefined &&
+                    prevViewportHeight !== innerHeight) {
+                    node.onViewportHeightChange?.();
+                }
                 // Absolute screen-buffer row where the scrollable area (inside
                 // padding) begins. Exposed via ScrollBoxHandle.getViewportTop() so
                 // drag-to-scroll can detect when the drag leaves the scroll viewport.
@@ -1447,7 +1475,17 @@ function renderNodeToOutput(node, output, options) {
                     output.shade({ x: Math.floor(x), y: Math.floor(y), width: Math.floor(width), height: Math.floor(height) });
                 }
                 const ownBackgroundColor = node.style.backgroundColor ?? occlusionBackground;
-                if (ownBackgroundColor || node.style.opaque) {
+                // A Sixel image node owns cells the raster normally paints over. When
+                // no placement is admitted — the modal suppressed graphics, the decode
+                // is still pending, or it failed — those cells must still read as the
+                // enclosing surface: the admitted branch above painted them with the
+                // same inherited color, so leaving them unwritten would diff them back
+                // to terminal-default blanks and punch black holes in the card.
+                const imageSurfaceColor = output.opaqueImageBacking && node.nodeName === 'ink-image'
+                    ? ownBackgroundColor ?? inheritedBackgroundColor
+                    : undefined;
+                const fillColor = ownBackgroundColor ?? imageSurfaceColor;
+                if (fillColor || node.style.opaque) {
                     const borderLeft = yogaNode.getComputedBorder(LayoutEdge.Left);
                     const borderRight = yogaNode.getComputedBorder(LayoutEdge.Right);
                     const borderTop = yogaNode.getComputedBorder(LayoutEdge.Top);
@@ -1456,8 +1494,8 @@ function renderNodeToOutput(node, output, options) {
                     const innerHeight = Math.floor(height) - borderTop - borderBottom;
                     if (innerWidth > 0 && innerHeight > 0) {
                         const spaces = ' '.repeat(innerWidth);
-                        const fillLine = ownBackgroundColor
-                            ? applyTextStyles(spaces, { backgroundColor: ownBackgroundColor })
+                        const fillLine = fillColor
+                            ? applyTextStyles(spaces, { backgroundColor: fillColor })
                             : spaces;
                         const fill = Array(innerHeight).fill(fillLine).join('\n');
                         output.write(x + borderLeft, y + borderTop, fill);
@@ -1485,7 +1523,11 @@ function renderNodeToOutput(node, output, options) {
             // Render border AFTER children to ensure it's not overwritten by child
             // clearing operations. When a child shrinks, it clears its old area,
             // which may overlap with where the parent's border now is.
-            renderBorder(x, y, node, output);
+            // A border's cells belong to the surface it frames: pass the node's
+            // effective background so they never fall back to the terminal default
+            // (a black frame around a colored surface, and a black hole where a
+            // Sixel raster is otherwise exposed by a border row or column).
+            renderBorder(x, y, node, output, node.style.backgroundColor ?? occlusionBackground ?? inheritedBackgroundColor);
         }
         else if (node.nodeName === 'ink-root') {
             renderChildren(node, output, x, y, hasRemovedChild, prevScreen, inheritedBackgroundColor);

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

@@ -13,6 +13,12 @@ export type RenderOptions = {
     /** Whether terminal graphics are active for this paint pass. */
     terminalImages?: boolean;
     imageReady?: (placement: TerminalImagePlacement) => boolean;
+    /**
+     * True when rasters paint over the cell grid (Sixel): image-owned cells
+     * carry the surface background instead of terminal-default blanks. See
+     * Output's `opaqueImageBacking`.
+     */
+    opaqueImageBacking?: boolean;
     prevFrameContaminated: boolean;
 };
 /** Renders the DOM tree into a frame for the given options. */

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

@@ -1 +1 @@
-{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/ink/renderer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAiC,MAAM,UAAU,CAAA;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAIvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAUjE,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAE1D,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,KAAK,CAAA;IACjB,SAAS,EAAE,KAAK,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,sBAAsB,KAAK,OAAO,CAAA;IAK3D,qBAAqB,EAAE,OAAO,CAAA;CAC/B,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,KAAK,CAAA;AAExD;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,SAAS,GACnB,QAAQ,CAmMV"}
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/ink/renderer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAiC,MAAM,UAAU,CAAA;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAIvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAUjE,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAE1D,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,KAAK,CAAA;IACjB,SAAS,EAAE,KAAK,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,sBAAsB,KAAK,OAAO,CAAA;IAC3D;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAK5B,qBAAqB,EAAE,OAAO,CAAA;CAC/B,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,KAAK,CAAA;AAExD;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,SAAS,GACnB,QAAQ,CAqMV"}

package/lib/types/ink/renderer.js

@@ -75,7 +75,7 @@ export default function createRenderer(node, stylePool) {
         const screen = backScreen ??
             createScreen(width, height, stylePool, charPool, hyperlinkPool);
         if (output) {
-            output.reset(width, height, screen, options.terminalImages, frontFrame.images, options.imageReady);
+            output.reset(width, height, screen, options.terminalImages, frontFrame.images, options.imageReady, options.opaqueImageBacking ?? false);
         }
         else {
             output = new Output({
@@ -86,6 +86,7 @@ export default function createRenderer(node, stylePool) {
                 terminalImages: options.terminalImages,
                 previousImages: frontFrame.images,
                 imageReady: options.imageReady,
+                opaqueImageBacking: options.opaqueImageBacking ?? false,
             });
         }
         resetLayoutShifted();