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

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

@@ -76,6 +76,37 @@ export type SelectionState = {
      *  were on, xterm.js would have consumed the event for native selection
      *  and we'd never receive it. Used by the footer to show the right hint. */
     lastPressHadAlt: boolean;
+    /** Rolling fingerprint (hash) of the rows under the highlight. Ink's
+     *  render loop refreshes it every frame; a change between frames
+     *  WITHOUT a paired follow-shift means screen content was replaced in
+     *  place under a stationary selection (a streaming transcript
+     *  overwriting the rows the highlight covers), and a copy from these
+     *  coordinates would read whatever text now sits there — not what the
+     *  user highlighted. Null until the first frame observes the
+     *  selection. */
+    coveredFingerprint: number | null;
+    /** The text `getSelectedText` emitted for `coveredFingerprint`'s frame.
+     *  The fingerprint is a cheap per-frame pre-filter: it hashes the covered
+     *  cells plus the two soft-wrap inputs that decide how those cells lay out,
+     *  so it can move while the COPIED TEXT stays byte-identical (flipping the
+     *  next row's wrap bit from 0 to a value past the selection's last column
+     *  only toggles trailing-blank trimming, which is invisible when the
+     *  selected columns are already full). Judging staleness on that hash alone
+     *  refused legitimate copies — "content under the selection changed; copy
+     *  cancelled" while a streaming tail wrote somewhere else entirely. The
+     *  verdict therefore re-checks the emitted text, exactly the bytes the copy
+     *  would ship, and only latches when THEY differ. Null until baselined. */
+    coveredText: string | null;
+    /** Geometry key (start/end row:col) the fingerprint was taken at. Any
+     *  user-driven geometry change (drag motion, word/line extension,
+     *  keyboard pan, multi-click) re-baselines instead of judging — the
+     *  guard only ever indicts a STATIONARY highlight whose text was
+     *  swapped underneath. Owned by refreshSelectionFingerprint. */
+    coveredGeometry: string | null;
+    /** Sticky once the covered rows changed without follow coordination.
+     *  Commit-time copy (copySelectionNoClear) refuses and clears instead
+     *  of shipping the replaced text. Cleared on start/clear. */
+    stale: boolean;
 };
 /**
  * Create a new selection state with no active selection.
@@ -379,6 +410,63 @@ export declare function selectionBounds(s: SelectionState): {
  * @returns true when the cell lies inside the selection range.
  */
 export declare function isCellSelected(s: SelectionState, col: number, row: number): boolean;
+/**
+ * Rehash the rows under the highlight and latch `stale` when they changed
+ * without a coordinated shift this frame.
+ *
+ * Copy reads whatever text occupies the highlight's screen coordinates at
+ * commit time. When the transcript REPLACES those rows in place while the
+ * highlight sits still (streaming output overwriting folded rows, a card
+ * collapsing under the anchor), the copied text is whatever moved in —
+ * visibly wrong text, not mojibake from a width bug. The follow/resize
+ * shifts keep the highlight anchored to text that MOVES; this guard catches
+ * the complementary case: stationary coordinates, moving content.
+ *
+ * Called once per rendered frame (post-render, pre-swap) on the frame the
+ * copy would read. The hash covers every visible cell of every covered row
+ * (same visibility rules as getSelectedText: noSelect and spacer cells
+ * skipped) via the cell's TEXT — `charPool.get(charId)` — not its pool
+ * index, plus the two soft-wrap inputs that decide how those cells are laid
+ * out into lines (the row's own `softWrap[row]`, and the `softWrap[row + 1]`
+ * extractRowText reads as this row's content end). styleId is excluded so
+ * the selection overlay and syntax highlighting themselves cannot trip the
+ * guard.
+ *
+ * Why content and not charId: a charId is an index into a generational
+ * CharPool, not a stable identity. Ink.resetPools() (ink.tsx) swaps in a
+ * fresh CharPool every ~5 minutes and re-interns the front frame through
+ * migrateScreenPools, so the SAME glyph comes back under a different
+ * number. Hashing ids would read that renumbering as "the covered rows
+ * changed" and refuse a perfectly legitimate copy with the stale-content
+ * notice — a false positive on a screen where nothing was replaced. The
+ * pool lookup is an array index plus a 1-2 code-unit hash loop, measured
+ * at ~0.05ms for a full 200x50 selection (~0.14ms at 200x200), i.e. no
+ * worse than hashing the ids themselves.
+ *
+ * The hash is only a PRE-FILTER; the verdict is the copied text. Hashing the
+ * wrap inputs keeps a cheap screen-signature, but those inputs can move while
+ * the bytes a copy would ship stay identical: flipping the next row's wrap bit
+ * from 0 to a value past the selection's last column only toggles
+ * trailing-blank trimming, which is invisible when the selected columns are
+ * already full (measured live: a streaming tail wrote a row far below the
+ * highlight, the wrap bookkeeping moved, and the guard refused a legitimate
+ * copy — the "content under the selection changed" toast with the highlight
+ * still sitting on exactly the right text). So when the hash moves, this
+ * compares `getSelectedText` against the baselined text and latches only when
+ * THE BYTES differ — the same expression the copy itself ships, which makes
+ * the verdict complete (no real replacement is missed) and sound (no
+ * unchanged text is refused). The text is compared, not stored per frame: the
+ * extraction runs on a geometry change (once per drag motion) and on a
+ * suspected change, never on the steady-state frame.
+ *
+ * @param s - the selection state to fingerprint.
+ * @param screen - the frame's screen buffer.
+ * @param coordinated - true when this frame translated the selection
+ *   endpoints (follow-shift or viewport resize); a fingerprint change in
+ *   such a frame is the expected content scroll, not an overwrite.
+ * @returns true when an uncoordinated change latched `stale` this call.
+ */
+export declare function refreshSelectionFingerprint(s: SelectionState, screen: Screen, coordinated: boolean): boolean;
 /**
  * Extract text from the screen buffer within the selection range.
  * Rows are joined with newlines unless the screen's softWrap bitmap

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

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

package/lib/types/ink/selection.js

@@ -26,6 +26,10 @@ export function createSelectionState() {
         scrolledOffAboveSW: [],
         scrolledOffBelowSW: [],
         lastPressHadAlt: false,
+        coveredFingerprint: null,
+        coveredText: null,
+        coveredGeometry: null,
+        stale: false,
     };
 }
 /**
@@ -52,6 +56,10 @@ export function startSelection(s, col, row) {
     s.virtualFocusRow = undefined;
     s.dragBounds = undefined;
     s.lastPressHadAlt = false;
+    s.coveredFingerprint = null;
+    s.coveredText = null;
+    s.coveredGeometry = null;
+    s.stale = false;
 }
 /**
  * Track the drag position: update focus to (col, row). No-op while not
@@ -120,6 +128,10 @@ export function clearSelection(s) {
     s.virtualFocusRow = undefined;
     s.dragBounds = undefined;
     s.lastPressHadAlt = false;
+    s.coveredFingerprint = null;
+    s.coveredText = null;
+    s.coveredGeometry = null;
+    s.stale = false;
 }
 // Unicode-aware word character matcher: letters (any script), digits,
 // and the punctuation set iTerm2 treats as word-part by default.
@@ -969,6 +981,158 @@ function joinRows(lines, text, sw) {
         lines.push(text);
     }
 }
+/**
+ * Rehash the rows under the highlight and latch `stale` when they changed
+ * without a coordinated shift this frame.
+ *
+ * Copy reads whatever text occupies the highlight's screen coordinates at
+ * commit time. When the transcript REPLACES those rows in place while the
+ * highlight sits still (streaming output overwriting folded rows, a card
+ * collapsing under the anchor), the copied text is whatever moved in —
+ * visibly wrong text, not mojibake from a width bug. The follow/resize
+ * shifts keep the highlight anchored to text that MOVES; this guard catches
+ * the complementary case: stationary coordinates, moving content.
+ *
+ * Called once per rendered frame (post-render, pre-swap) on the frame the
+ * copy would read. The hash covers every visible cell of every covered row
+ * (same visibility rules as getSelectedText: noSelect and spacer cells
+ * skipped) via the cell's TEXT — `charPool.get(charId)` — not its pool
+ * index, plus the two soft-wrap inputs that decide how those cells are laid
+ * out into lines (the row's own `softWrap[row]`, and the `softWrap[row + 1]`
+ * extractRowText reads as this row's content end). styleId is excluded so
+ * the selection overlay and syntax highlighting themselves cannot trip the
+ * guard.
+ *
+ * Why content and not charId: a charId is an index into a generational
+ * CharPool, not a stable identity. Ink.resetPools() (ink.tsx) swaps in a
+ * fresh CharPool every ~5 minutes and re-interns the front frame through
+ * migrateScreenPools, so the SAME glyph comes back under a different
+ * number. Hashing ids would read that renumbering as "the covered rows
+ * changed" and refuse a perfectly legitimate copy with the stale-content
+ * notice — a false positive on a screen where nothing was replaced. The
+ * pool lookup is an array index plus a 1-2 code-unit hash loop, measured
+ * at ~0.05ms for a full 200x50 selection (~0.14ms at 200x200), i.e. no
+ * worse than hashing the ids themselves.
+ *
+ * The hash is only a PRE-FILTER; the verdict is the copied text. Hashing the
+ * wrap inputs keeps a cheap screen-signature, but those inputs can move while
+ * the bytes a copy would ship stay identical: flipping the next row's wrap bit
+ * from 0 to a value past the selection's last column only toggles
+ * trailing-blank trimming, which is invisible when the selected columns are
+ * already full (measured live: a streaming tail wrote a row far below the
+ * highlight, the wrap bookkeeping moved, and the guard refused a legitimate
+ * copy — the "content under the selection changed" toast with the highlight
+ * still sitting on exactly the right text). So when the hash moves, this
+ * compares `getSelectedText` against the baselined text and latches only when
+ * THE BYTES differ — the same expression the copy itself ships, which makes
+ * the verdict complete (no real replacement is missed) and sound (no
+ * unchanged text is refused). The text is compared, not stored per frame: the
+ * extraction runs on a geometry change (once per drag motion) and on a
+ * suspected change, never on the steady-state frame.
+ *
+ * @param s - the selection state to fingerprint.
+ * @param screen - the frame's screen buffer.
+ * @param coordinated - true when this frame translated the selection
+ *   endpoints (follow-shift or viewport resize); a fingerprint change in
+ *   such a frame is the expected content scroll, not an overwrite.
+ * @returns true when an uncoordinated change latched `stale` this call.
+ */
+export function refreshSelectionFingerprint(s, screen, coordinated) {
+    if (s.stale)
+        return false;
+    const b = selectionBounds(s);
+    if (!b) {
+        s.coveredFingerprint = null;
+        s.coveredText = null;
+        s.coveredGeometry = null;
+        return false;
+    }
+    // Any geometry change re-baselines: drag motion, word/line extension,
+    // keyboard pan, multi-click — the user redefined what is highlighted, so
+    // the next copy legitimately reads the new band's CURRENT text. Only a
+    // stationary highlight can go stale.
+    const geometry = `${b.start.row}:${b.start.col}-${b.end.row}:${b.end.col}`;
+    if (geometry !== s.coveredGeometry) {
+        s.coveredGeometry = geometry;
+        s.coveredFingerprint = null;
+        s.coveredText = null;
+    }
+    const { cells, noSelect, width, height, charPool, softWrap } = screen;
+    let h = 0x811c9dc5;
+    for (let row = b.start.row; row <= b.end.row; row++) {
+        if (row < 0 || row >= height)
+            continue;
+        const rowOff = row * width;
+        // Column bounds mirror getSelectedText exactly: the boundary rows hash
+        // only from start.col / through end.col. Streaming text appended to a
+        // covered row OUTSIDE the selected column range (stable head selected,
+        // live tail still writing) must not latch stale — the copy would not
+        // read those columns anyway.
+        const colStart = row === b.start.row ? b.start.col : 0;
+        const colEnd = row === b.end.row ? b.end.col : width - 1;
+        for (let col = colStart; col <= colEnd; col++) {
+            const ci = (rowOff + col) * 2;
+            // word1's low 2 bits are the cell width; SpacerTail/SpacerHead carry
+            // no text of their own.
+            if ((cells[ci + 1] & 3) >= 2 /* CellWidth.SpacerTail */)
+                continue;
+            if (noSelect[rowOff + col] === 1)
+                continue;
+            // Resolve the id through the pool and hash the actual characters —
+            // the exact string getSelectedText would emit for this cell. Two
+            // pools holding the same glyph hash identically, so a generational
+            // pool swap is invisible here; a different glyph is not.
+            const ch = charPool.get(cells[ci]);
+            for (let k = 0; k < ch.length; k++) {
+                h = Math.imul(h ^ ch.charCodeAt(k), 0x01000193);
+            }
+        }
+        // Row separator + the row's soft-wrap bit: getSelectedText joins a
+        // wrapped row onto the previous line with NO newline (softWrap[row]>0)
+        // but emits a real newline otherwise — identical cells with a flipped
+        // wrap bit produce a different copy, so the fingerprint must see it.
+        h = Math.imul(h ^ 0x9e3779b9 ^ (softWrap[row] > 0 ? 0x51ed270b : 0), 0x85ebca6b);
+        // The row BELOW is an input to THIS row's copy. extractRowText reads
+        // softWrap[row + 1] as this row's content end: > 0 means the row wraps
+        // into the next one, which both clamps the last column to
+        // min(colEnd, contentEnd - 1) and suppresses the trailing-blank trim.
+        // Flipping only the next row's wrap bit therefore rewrites the last
+        // covered line's trailing columns ("A" → "A         ") with every
+        // covered CELL unchanged — the guard has to see the wrap, not just the
+        // cells. Hash exactly what extractRowText consumes (0 = not wrapped) so
+        // a contentEnd change that does not move the clamp stays invisible
+        // instead of becoming a false positive.
+        const contentEnd = row + 1 < height ? softWrap[row + 1] : 0;
+        const wrapClamp = contentEnd > 0 ? Math.min(colEnd, contentEnd - 1) + 1 : 0;
+        h = Math.imul(h ^ 0x27d4eb2f ^ wrapClamp, 0x165667b1);
+    }
+    if (s.coveredFingerprint === null) {
+        // First frame observing this selection: baseline, no verdict. The text is
+        // captured here too — it is the ground truth the next hash change is
+        // judged against, and it can only be read while the baselined frame is
+        // still on screen.
+        s.coveredFingerprint = h;
+        s.coveredText = getSelectedText(s, screen);
+        return false;
+    }
+    if (h === s.coveredFingerprint)
+        return false;
+    // The hash moved: decide on the emitted text, not on the hash. A wrap-bit
+    // flip below the selection (or any other term that does not change the
+    // bytes the copy would ship) must not refuse a legitimate copy.
+    const text = getSelectedText(s, screen);
+    if (text === s.coveredText) {
+        // Same bytes, different layout bookkeeping: accept and re-baseline.
+        s.coveredFingerprint = h;
+        return false;
+    }
+    s.coveredFingerprint = h;
+    s.coveredText = text;
+    if (coordinated)
+        return false;
+    s.stale = true;
+    return true;
+}
 /**
  * Extract text from the screen buffer within the selection range.
  * Rows are joined with newlines unless the screen's softWrap bitmap

package/lib/types/ink/sixel-graphics.d.ts

@@ -19,6 +19,8 @@ export declare class SixelGraphicsManager {
     private desired;
     private displayed;
     private nextDisplay;
+    /** Rects kept on screen this frame (replacement pending or covered). */
+    private readonly held;
     private readonly repaint;
     private worker;
     private workerKeys;
@@ -35,7 +37,23 @@ export declare class SixelGraphicsManager {
     beginFrame(columns: number, rows: number): void;
     readonly prepare: (placement: TerminalImagePlacement) => boolean;
     private variant;
-    /** Reconcile ALL old rectangles before diffing, with only one baseline copy. */
+    /**
+     * Reconcile ALL old rectangles before diffing, with only one baseline copy.
+     *
+     * A rect is erased only when this frame replaces it (a ready raster at a new
+     * key/geometry, erased and drawn in the same write) or drops it entirely.
+     * Rects whose replacement is still being encoded, or which a later paint
+     * covers, are held: erasing them without drawing a replacement in the same
+     * frame is exactly the black flash seen while scrolling and the vanishing
+     * image under an overlay. {@link paint} folds the held rects back into
+     * `displayed`, and the frame that finally replaces one forces a repaint
+     * through the `held` marker.
+     *
+     * A held rect that an overlay PARTLY covers still has to give up the covered
+     * cells: its pixels outlive cell writes (a background-only space cell diffs
+     * as unchanged, so the frame never rewrites it) and would show through the
+     * overlay. Those sub-rects are erased with the placement's surface color.
+     */
     reconcile(screen: Screen, previous: Screen, placements?: readonly TerminalImagePlacement[]): {
         erase: string;
         baseline: Screen;

package/lib/types/ink/sixel-graphics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sixel-graphics.d.ts","sourceRoot":"","sources":["../../../src/ink/sixel-graphics.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAA2C,MAAM,kBAAkB,CAAA;AAChH,OAAO,EAIL,KAAK,gBAAgB,EAAE,KAAK,sBAAsB,EACnD,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAatC,KAAK,OAAO,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAA;AAOpE,oFAAoF;AACpF,qBAAa,oBAAoB;IAuBnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAAc,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAtB3E,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoC;IACxD,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwC;IAC9D,OAAO,CAAC,WAAW,CAAI;IACvB,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,YAAY,CAAuC;IAC3D,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,IAAI,CAAI;IAChB,OAAO,CAAC,cAAc,CAAQ;gBAED,OAAO,EAAE,MAAM,IAAI,EAAmB,OAAO,CAAC,EAAE,OAAO,YAAA;IAEpF,IAAI,QAAQ,IAAI,OAAO,CAAgE;IAEvF,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAKtC,WAAW,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO;IAQ5C,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAO/C,QAAQ,CAAC,OAAO,GAAI,WAAW,sBAAsB,KAAG,OAAO,CAc9D;IAED,OAAO,CAAC,OAAO;IAgDf,gFAAgF;IAChF,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,sBAAsB,EAAE,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IA6ChI,iFAAiF;IACjF,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;IAgBzB,aAAa,IAAI,IAAI;IAErB,KAAK,IAAI,MAAM;IAUf,OAAO,IAAI,MAAM;IAajB,OAAO,CAAC,KAAK;IASb,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,UAAU;IAwBlB,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,cAAc;CAkEvB"}
+{"version":3,"file":"sixel-graphics.d.ts","sourceRoot":"","sources":["../../../src/ink/sixel-graphics.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAA2C,MAAM,kBAAkB,CAAA;AAChH,OAAO,EAIL,KAAK,gBAAgB,EAAE,KAAK,sBAAsB,EACnD,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAwBtC,KAAK,OAAO,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAA;AAiBpE,oFAAoF;AACpF,qBAAa,oBAAoB;IAyBnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAAc,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAxB3E,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoC;IACxD,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwC;IAC9D,OAAO,CAAC,WAAW,CAAI;IACvB,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,WAAW,CAAmC;IACtD,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmC;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,YAAY,CAAuC;IAC3D,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,IAAI,CAAI;IAChB,OAAO,CAAC,cAAc,CAAQ;gBAED,OAAO,EAAE,MAAM,IAAI,EAAmB,OAAO,CAAC,EAAE,OAAO,YAAA;IAEpF,IAAI,QAAQ,IAAI,OAAO,CAAgE;IAEvF,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAKtC,WAAW,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO;IAQ5C,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAO/C,QAAQ,CAAC,OAAO,GAAI,WAAW,sBAAsB,KAAG,OAAO,CAc9D;IAED,OAAO,CAAC,OAAO;IAgDf;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,sBAAsB,EAAE,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAwGhI,iFAAiF;IACjF,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;IAmBzB,aAAa,IAAI,IAAI;IAErB,KAAK,IAAI,MAAM;IAWf,OAAO,IAAI,MAAM;IAajB,OAAO,CAAC,KAAK;IAiBb,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAwBlB,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,cAAc;CAkEvB"}

package/lib/types/ink/sixel-graphics.js

@@ -2,10 +2,21 @@ import { Worker } from 'node:worker_threads';
 import { DEFAULT_TERMINAL_CELL_SIZE, normalizeTerminalCellSize, TERMINAL_IMAGE_MAX_EDGE, TERMINAL_IMAGE_MAX_BYTES, TERMINAL_IMAGE_PREVIEW_MAX_EDGE, TERMINAL_IMAGE_PREVIEW_MAX_BYTES, SIXEL_MAX_ENCODED_BYTES, SIXEL_THUMBNAIL_FRAME_BYTES, SIXEL_CACHE_BYTES, SIXEL_CACHE_ENTRIES, } from './terminal-image.js';
 import { cellAt, clearRegion } from './screen.js';
 import { stringWidth } from './stringWidth.js';
+import { backgroundOpenCode } from './colorize.js';
 function overlaps(a, b) {
     return a.x < b.x + b.columns && a.x + a.columns > b.x &&
         a.y < b.y + b.rows && a.y + a.rows > b.y;
 }
+/** Intersection of two cell rects, or undefined when they do not overlap. */
+function intersectRects(a, b) {
+    const x = Math.max(a.x, b.x);
+    const y = Math.max(a.y, b.y);
+    const right = Math.min(a.x + a.columns, b.x + b.columns);
+    const bottom = Math.min(a.y + a.rows, b.y + b.rows);
+    if (right <= x || bottom <= y)
+        return undefined;
+    return { x, y, columns: right - x, rows: bottom - y };
+}
 /** Viewport-owned pixels. Encoding is shared; placement/erasure is per DOM node. */
 export class SixelGraphicsManager {
     onReady;
@@ -22,6 +33,8 @@ export class SixelGraphicsManager {
     desired = new Set();
     displayed = new Map();
     nextDisplay = new Map();
+    /** Rects kept on screen this frame (replacement pending or covered). */
+    held = new Map();
     repaint = new Set();
     worker;
     workerKeys = new Set();
@@ -119,22 +132,59 @@ export class SixelGraphicsManager {
                 crop: { left, top, width: cropWidth, height: cropHeight } },
         };
     }
-    /** Reconcile ALL old rectangles before diffing, with only one baseline copy. */
+    /**
+     * Reconcile ALL old rectangles before diffing, with only one baseline copy.
+     *
+     * A rect is erased only when this frame replaces it (a ready raster at a new
+     * key/geometry, erased and drawn in the same write) or drops it entirely.
+     * Rects whose replacement is still being encoded, or which a later paint
+     * covers, are held: erasing them without drawing a replacement in the same
+     * frame is exactly the black flash seen while scrolling and the vanishing
+     * image under an overlay. {@link paint} folds the held rects back into
+     * `displayed`, and the frame that finally replaces one forces a repaint
+     * through the `held` marker.
+     *
+     * A held rect that an overlay PARTLY covers still has to give up the covered
+     * cells: its pixels outlive cell writes (a background-only space cell diffs
+     * as unchanged, so the frame never rewrites it) and would show through the
+     * overlay. Those sub-rects are erased with the placement's surface color.
+     */
     reconcile(screen, previous, placements) {
         const actual = placements ? new Map(placements.map(p => [p.node, p])) : undefined;
         const visible = [];
         this.desired = new Set();
         this.nextDisplay.clear();
+        this.held.clear();
         this.repaint.clear();
+        // Nodes whose raster this frame drops (the paint no longer registers an
+        // image, or a later paint covers every visible cell): their pixels must be
+        // erased, unlike the ones merely held below.
+        const dropped = new Set();
         for (const [node, variant] of this.frame) {
             const placement = actual?.get(node);
-            if ((actual && !placement) || placement?.occluded)
+            if (actual && !placement) {
+                dropped.add(node);
+                continue;
+            }
+            if (placement?.occludedFully) {
+                dropped.add(node);
                 continue;
+            }
             visible.push(variant);
             this.desired.add(variant.key);
+            // Partially covered: drawing would pierce the overlay that covers it, so
+            // keep the pixels already on screen and wait for the cover to clear.
+            if (placement?.occluded)
+                continue;
             const raster = this.cache.get(variant.key);
             if (variant.ready && raster && placement?.graphicsReady !== false && this.isUncovered(variant.rect, screen)) {
-                this.nextDisplay.set(node, { ...variant.rect, key: variant.key, raster });
+                const background = variant.placement.background;
+                this.nextDisplay.set(node, {
+                    ...variant.rect,
+                    key: variant.key,
+                    raster,
+                    ...(background === undefined ? {} : { background }),
+                });
             }
         }
         const unique = new Map();
@@ -145,27 +195,71 @@ export class SixelGraphicsManager {
         this.pending = [...unique.values()].sort((a, b) => Number(b.placement.presentation === 'preview') - Number(a.placement.presentation === 'preview'));
         this.drain();
         const erased = [];
+        let coverErase = '';
         for (const [node, old] of this.displayed) {
             const next = this.nextDisplay.get(node);
-            if (!next || this.dirty || old.key !== next.key || old.x !== next.x || old.y !== next.y)
-                erased.push(old);
+            if (next !== undefined) {
+                if (this.dirty || old.key !== next.key || old.x !== next.x || old.y !== next.y)
+                    erased.push(old);
+                continue;
+            }
+            // Still requested this frame, but its replacement raster is not ready
+            // (scrolling re-crops per row and the encoder is async) or a later paint
+            // covers it. Erasing here would leave a hole with no draw in the same
+            // frame — the black flash while scrolling and the vanishing image under
+            // a tooltip. Keep the pixels already on screen until a replacement can
+            // be drawn in the same write.
+            if (!this.dirty && this.frame.has(node) && !dropped.has(node)) {
+                const placement = actual?.get(node);
+                const coveredRects = placement?.coveredRects;
+                const coveredKey = coveredRects === undefined || coveredRects.length === 0
+                    ? undefined
+                    : coveredRects.map(rect => `${rect.x},${rect.y},${rect.width},${rect.height}`).join(';');
+                if (coveredKey !== undefined && coveredKey !== old.covered) {
+                    // The overlay paints these cells, but only the ones whose style
+                    // changes get a write: an unchanged background-only space keeps the
+                    // raster's pixels. Erase the covered cells (with the surface color,
+                    // so they match the cell model) and leave the rest held.
+                    const visibleRect = { x: old.x, y: old.y, columns: old.columns, rows: old.rows };
+                    for (const rect of coveredRects) {
+                        const clipped = intersectRects(visibleRect, { x: rect.x, y: rect.y, columns: rect.width, rows: rect.height });
+                        if (clipped !== undefined)
+                            coverErase += this.erase(clipped, old.background);
+                    }
+                }
+                this.held.set(node, coveredKey === undefined
+                    ? { ...old, held: true }
+                    : { ...old, held: true, covered: coveredKey });
+                continue;
+            }
+            erased.push(old);
         }
         for (const [node, next] of this.nextDisplay) {
             const old = this.displayed.get(node);
-            if (!old || this.dirty || old.key !== next.key || old.x !== next.x || old.y !== next.y ||
+            if (!old || this.dirty || old.held === true ||
+                old.key !== next.key || old.x !== next.x || old.y !== next.y ||
                 erased.some(rect => overlaps(rect, next)))
                 this.repaint.add(node);
         }
-        if (erased.length === 0)
-            return { erase: '', baseline: previous };
+        if (erased.length === 0) {
+            return coverErase === ''
+                ? { erase: '', baseline: previous }
+                : { erase: coverErase + '\x1b[H', baseline: previous };
+        }
         const cells = previous.cells.slice();
         const baseline = { ...previous, cells, cells64: new BigInt64Array(cells.buffer), noSelect: previous.noSelect.slice() };
         let erase = '';
         for (const rect of erased) {
             clearRegion(baseline, rect.x, rect.y, rect.columns, rect.rows);
+            // Erase at the terminal default, never at the placement's surface color:
+            // clearRegion just reset these cells to a default blank in the model, so
+            // the frame writes back everything it has to show and leaves the rest
+            // alone — an erase filled with the surface color would keep that color
+            // on screen with no write to correct it (the white card of a closed
+            // light-theme preview, cleared only when unrelated text scrolls past).
             erase += this.erase(rect);
         }
-        return { erase: erase + '\x1b[H', baseline };
+        return { erase: coverErase + erase + '\x1b[H', baseline };
     }
     /** Unchanged images have zero transport cost, including unrelated text ticks. */
     paint(diff) {
@@ -181,6 +275,10 @@ export class SixelGraphicsManager {
             draw += `\x1b[${next.y + 1};${next.x + 1}H${next.raster.data}`;
         }
         this.displayed = new Map(this.nextDisplay);
+        // Rects held this frame stay on screen: they were neither erased nor
+        // redrawn, so the terminal still shows them.
+        for (const [node, entry] of this.held)
+            this.displayed.set(node, entry);
         this.dirty = false;
         if (draw === '')
             return '';
@@ -191,6 +289,7 @@ export class SixelGraphicsManager {
         const output = [...this.displayed.values()].map(rect => this.erase(rect)).join('');
         this.displayed.clear();
         this.nextDisplay.clear();
+        this.held.clear();
         this.frame.clear();
         this.desired.clear();
         this.pending = [];
@@ -208,21 +307,34 @@ export class SixelGraphicsManager {
         this.workerKeys.clear();
         return output;
     }
-    erase(rect) {
+    erase(rect, background) {
         const columns = Math.min(rect.columns, this.columns - rect.x);
         const rows = Math.min(rect.rows, this.rows - rect.y);
         if (columns <= 0 || rows <= 0)
             return '';
-        let data = '\x1b[0m';
+        // Erase-Character fills with the cell's current background and is the only
+        // way to drop pixels a frame never rewrites. The surface color is for the
+        // one rect the frame cannot correct afterwards — cells a later paint
+        // covers while keeping their style (see reconcile); every caller that
+        // hands those cells back to the diff passes no color.
+        // The placement carries the raw color string; Color is its renderer form.
+        const open = background === undefined ? '' : backgroundOpenCode(background);
+        let data = `\x1b[0m${open}`;
         for (let y = rect.y; y < rect.y + rows; y++)
             data += `\x1b[${y + 1};${rect.x + 1}H\x1b[${columns}X`;
+        if (open !== '')
+            data += '\x1b[0m';
         return data;
     }
     isUncovered(rect, screen) {
+        // Any visible glyph under the raster blocks it; background-only cells do
+        // not. Image-owned cells carry the surface background in Sixel mode (an
+        // opaque backing is required there), and comparing against the empty
+        // style would reject the raster's own backing.
         for (let y = rect.y; y < rect.y + rect.rows; y++) {
             for (let x = rect.x; x < rect.x + rect.columns; x++) {
                 const cell = cellAt(screen, x, y);
-                if (cell && (cell.char !== ' ' || cell.styleId !== screen.emptyStyleId))
+                if (cell && cell.char !== ' ' && cell.char !== '')
                     return false;
             }
         }

package/lib/types/ink/terminal-image.d.ts

@@ -1,4 +1,5 @@
 import type { DOMElement } from './dom.js';
+import type { Rectangle } from './layout/geometry.js';
 /** Hard bounds for one decoded image admitted to the terminal renderer. */
 export declare const TERMINAL_IMAGE_MAX_EDGE = 1024;
 export declare const TERMINAL_IMAGE_MAX_BYTES: number;
@@ -60,8 +61,24 @@ export interface TerminalImagePlacement {
     readonly background?: string;
     /** False while a protocol-specific raster is pending or unavailable. */
     readonly graphicsReady?: boolean;
-    /** Later paint operations cover this backing, including blank overlays. */
+    /** Later paint operations cover part of this raster's visible cells. */
     readonly occluded?: boolean;
+    /**
+     * Later paint operations cover every visible cell of this raster, so it is
+     * unreachable and must be erased rather than kept (a blank `opaque` overlay
+     * would otherwise be pierced by the pixels beneath it). Partial coverage
+     * sets {@link occluded} only.
+     */
+    readonly occludedFully?: boolean;
+    /**
+     * The later paint operations that cover PART of this raster, in absolute
+     * screen cells. A protocol whose pixels outlive cell writes must erase these
+     * rects itself: with Sixel, a background-only space cell over the raster has
+     * the same style as the image's own backing cell, so the frame diff emits no
+     * write for it and the old pixels keep showing through the overlay (the white
+     * block between "100%" and "原像素" in a preview tooltip).
+     */
+    readonly coveredRects?: readonly Rectangle[];
 }
 /**
  * Normalize terminal-reported cell pixels before they reach allocation math.

package/lib/types/ink/terminal-image.d.ts.map

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