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

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

@@ -1,29 +1,70 @@
 import { type TerminalCellSize, type TerminalImagePlacement, type TerminalImageSource } from './terminal-image.js';
+/** Pixel rectangle of the uploaded raster to show (Kitty `x,y,w,h`). */
+export type KittySourceRect = {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+};
 export interface KittyGraphicsManagerOptions {
     /** Deterministic seed used by protocol tests; production chooses a random range. */
     readonly firstImageId?: number;
     /** Physical pixels per cell; defaults to a conventional 8×16 cell. */
     readonly cellSize?: TerminalCellSize;
+    /** Clock for the re-upload failure window; protocol tests pin it. */
+    readonly now?: () => number;
 }
 /**
  * Reconcile renderer image requests with Kitty image/placement state.
  *
  * Pixel content owns an image id while each DOM node owns a placement id.
  * Equal immutable RGBA content is uploaded once and can back several nodes;
- * geometry changes replace only that node's placement without flicker.
+ * geometry changes replace only that node's placement without flicker. An
+ * image no node places stays uploaded (dormant) within the retention budget,
+ * so content that scrolls back into view is re-placed, not re-sent.
  */
 export declare class KittyGraphicsManager {
     private readonly images;
     private readonly placements;
+    /**
+     * Ids given up by a re-upload. The ENOENT that triggered it may be stale
+     * (the id was re-sent in between), so the terminal can still hold data
+     * under the old id; it is deleted on the next frame (or at exit).
+     */
+    private readonly retiredImageIds;
     private readonly contentHashes;
     private nextImageId;
     private nextPlacementId;
     private cellSize;
+    private pass;
+    private readonly now;
     constructor(options?: KittyGraphicsManagerOptions);
     /** Update the physical cell ratio used by future image variants. */
     setCellSize(cellSize: TerminalCellSize): boolean;
     reconcile(placements: readonly TerminalImagePlacement[]): string;
-    /** A clear/screen swap invalidated terminal-side data; resend next frame. */
+    /**
+     * Forget images no node placed this pass once they are unusable (fitted for
+     * another cell geometry) or past the retention budget, oldest first.
+     */
+    private evictDormant;
+    /**
+     * Handle a Kitty graphics reply the renderer did not ask for. ENOENT for
+     * one of our images means the terminal evicted its data (its own quota is
+     * smaller than our retention budget): upload it again and re-place every
+     * node showing it on the next frame. A second ENOENT within
+     * REUPLOAD_FAILURE_WINDOW_MS of that re-upload means the terminal refuses
+     * the image outright, so it is left as is (never an upload loop); a new
+     * content or size variant is a new image and tries again. The re-upload
+     * takes a fresh image id: every placement of the old id may still answer
+     * ENOENT, and those late replies must not count as the re-upload failing.
+     * Returns whether a repaint is needed.
+     */
+    handleResponse(imageId: number, status: string): boolean;
+    /**
+     * A clear/screen swap invalidated terminal-side data; resend next frame.
+     * The terminal state an abandoned image was judged against is gone too, so
+     * it gets a fresh ENOENT budget; one clear still buys at most one retry.
+     */
     invalidateAll(): void;
     /** Delete every image owned by this renderer and forget their ids. */
     deleteAll(): string;
@@ -34,7 +75,7 @@ export declare class KittyGraphicsManager {
 }
 /** Zlib-compressed direct RGBA split into protocol-compliant base64 chunks. */
 export declare function transmitKittyRgba(imageId: number, source: TerminalImageSource): string;
-export declare function kittyPlacement(imageId: number, placementId: number, x: number, y: number, columns: number, rows: number, zIndex?: number): string;
+export declare function kittyPlacement(imageId: number, placementId: number, x: number, y: number, columns: number, rows: number, zIndex?: number, source?: KittySourceRect): string;
 export declare function deleteKittyPlacement(imageId: number, placementId: number): string;
 export declare function deleteKittyImage(imageId: number): string;
 export declare function kittyCommand(control: string, payload?: string): string;

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

@@ -1 +1 @@
-{"version":3,"file":"kitty-graphics.d.ts","sourceRoot":"","sources":["../../../src/ink/kitty-graphics.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAA;AAkC5B,MAAM,WAAW,2BAA2B;IAC1C,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CACrC;AAED;;;;;;GAMG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwC;IACnE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,QAAQ,CAAkB;gBAEtB,OAAO,GAAE,2BAAgC;IASrD,oEAAoE;IACpE,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO;IAYhD,SAAS,CAAC,UAAU,EAAE,SAAS,sBAAsB,EAAE,GAAG,MAAM;IA0GhE,6EAA6E;IAC7E,aAAa,IAAI,IAAI;IAOrB,sEAAsE;IACtE,SAAS,IAAI,MAAM;IASnB,OAAO,CAAC,QAAQ;IA+BhB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,mBAAmB;CAQ5B;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,mBAAmB,GAC1B,MAAM,CAER;AAoCD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,SAAgB,GACrB,MAAM,CAOR;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,SAAK,GAAG,MAAM,CAElE"}
+{"version":3,"file":"kitty-graphics.d.ts","sourceRoot":"","sources":["../../../src/ink/kitty-graphics.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAA;AAmE5B,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,WAAW,2BAA2B;IAC1C,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IACpC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwC;IACnE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAe;IAC/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,IAAI,CAAI;IAChB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;gBAEtB,OAAO,GAAE,2BAAgC;IAUrD,oEAAoE;IACpE,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO;IAYhD,SAAS,CAAC,UAAU,EAAE,SAAS,sBAAsB,EAAE,GAAG,MAAM;IAkHhE;;;OAGG;IACH,OAAO,CAAC,YAAY;IAmCpB;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAsBxD;;;;OAIG;IACH,aAAa,IAAI,IAAI;IAWrB,sEAAsE;IACtE,SAAS,IAAI,MAAM;IASnB,OAAO,CAAC,QAAQ;IAoChB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,mBAAmB;CAQ5B;AAyCD,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,mBAAmB,GAC1B,MAAM,CAER;AAoCD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,SAAgB,EACtB,MAAM,CAAC,EAAE,eAAe,GACvB,MAAM,CAUR;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,SAAK,GAAG,MAAM,CAElE"}

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

@@ -9,23 +9,54 @@ const ID_MAX_EXCLUSIVE = 0x7fffffff;
 const PLACEMENT_ID_MAX_EXCLUSIVE = 0x40000000;
 // Keep raster content behind terminal text and explicit panel backgrounds.
 const IMAGE_Z_INDEX = -0x80000000;
+/**
+ * Retention for uploaded images that no node places this frame. Leaving the
+ * viewport deletes only the placement (`d=i`), so scrolling back re-places
+ * the terminal-side data with one `a=p` instead of re-fitting, re-compressing
+ * and re-sending the whole raster — the protocol's intended use, and what
+ * mature terminal UIs do. Dormant images are evicted least-recently-used past
+ * either bound. The byte bound counts decoded RGBA (what the terminal keeps)
+ * and stays a small fraction of default terminal image quotas. A terminal
+ * configured with a smaller quota may still evict a dormant image, so
+ * placements report failures (`q=1`): an ENOENT reply marks the image for
+ * re-upload (see handleResponse).
+ */
+const DORMANT_MAX_IMAGES = 128;
+const RETAINED_MAX_BYTES = 64 * 1024 * 1024;
+/**
+ * An ENOENT this soon after re-uploading the same image means the terminal
+ * cannot keep it at all (e.g. the image exceeds its whole quota and the
+ * upload was refused): stop re-uploading instead of looping.
+ */
+const REUPLOAD_FAILURE_WINDOW_MS = 5000;
 /**
  * Reconcile renderer image requests with Kitty image/placement state.
  *
  * Pixel content owns an image id while each DOM node owns a placement id.
  * Equal immutable RGBA content is uploaded once and can back several nodes;
- * geometry changes replace only that node's placement without flicker.
+ * geometry changes replace only that node's placement without flicker. An
+ * image no node places stays uploaded (dormant) within the retention budget,
+ * so content that scrolls back into view is re-placed, not re-sent.
  */
 export class KittyGraphicsManager {
     images = new Map();
     placements = new Map();
+    /**
+     * Ids given up by a re-upload. The ENOENT that triggered it may be stale
+     * (the id was re-sent in between), so the terminal can still hold data
+     * under the old id; it is deleted on the next frame (or at exit).
+     */
+    retiredImageIds = [];
     contentHashes = new WeakMap();
     nextImageId;
     nextPlacementId = 1;
     cellSize;
+    pass = 0;
+    now;
     constructor(options = {}) {
         this.nextImageId = normalizeFirstId(options.firstImageId ?? randomInt(ID_MIN, ID_MAX_EXCLUSIVE));
         this.cellSize = normalizeTerminalCellSize(options.cellSize ?? DEFAULT_TERMINAL_CELL_SIZE);
+        this.now = options.now ?? Date.now;
     }
     /** Update the physical cell ratio used by future image variants. */
     setCellSize(cellSize) {
@@ -38,15 +69,17 @@ export class KittyGraphicsManager {
         return true;
     }
     reconcile(placements) {
+        this.pass += 1;
         const desiredNodes = new Set();
         const desiredImages = new Set();
         const desired = [];
-        const output = [];
+        const output = this.retiredImageIds.splice(0).map(deleteKittyImage);
         for (const placement of placements) {
             if (desiredNodes.has(placement.node))
                 continue;
             desiredNodes.add(placement.node);
             const image = this.imageFor(placement);
+            image.lastUsed = this.pass;
             desiredImages.add(image);
             desired.push({ placement, image });
         }
@@ -64,6 +97,7 @@ export class KittyGraphicsManager {
                     y: -1,
                     columns: 0,
                     rows: 0,
+                    crop: '',
                 };
                 this.placements.set(placement.node, state);
             }
@@ -79,16 +113,22 @@ export class KittyGraphicsManager {
                 output.push(transmitPreparedKittyRgba(image.imageId, image.payload));
                 image.uploaded = true;
             }
-            const moved = state.x !== placement.x ||
-                state.y !== placement.y ||
-                state.columns !== placement.columns ||
-                state.rows !== placement.rows;
+            const visible = visiblePlacement(placement, image.payload);
+            const crop = visible.source === undefined
+                ? ''
+                : `${visible.source.x},${visible.source.y},${visible.source.width},${visible.source.height}`;
+            const moved = state.x !== visible.x ||
+                state.y !== visible.y ||
+                state.columns !== visible.columns ||
+                state.rows !== visible.rows ||
+                state.crop !== crop;
             if (!state.placed || moved) {
-                output.push(kittyPlacement(image.imageId, state.placementId, placement.x, placement.y, placement.columns, placement.rows, state.zIndex));
-                state.x = placement.x;
-                state.y = placement.y;
-                state.columns = placement.columns;
-                state.rows = placement.rows;
+                output.push(kittyPlacement(image.imageId, state.placementId, visible.x, visible.y, visible.columns, visible.rows, state.zIndex, visible.source));
+                state.x = visible.x;
+                state.y = visible.y;
+                state.columns = visible.columns;
+                state.rows = visible.rows;
+                state.crop = crop;
                 state.placed = true;
             }
         }
@@ -101,31 +141,111 @@ export class KittyGraphicsManager {
             });
             this.placements.delete(node);
         }
+        // Deleting an image's data also removes its placements, so an evicted
+        // image needs no separate placement delete.
+        const evicted = this.evictDormant(desiredImages);
         for (const obsolete of obsoletePlacements) {
-            if (!desiredImages.has(obsolete.image))
+            if (evicted.has(obsolete.image))
                 continue;
             output.push(deleteKittyPlacement(obsolete.image.imageId, obsolete.placementId));
         }
-        for (const [key, image] of this.images) {
-            if (desiredImages.has(image))
-                continue;
+        for (const image of evicted)
             output.push(deleteKittyImage(image.imageId));
-            this.images.delete(key);
-        }
         return output.join('');
     }
-    /** A clear/screen swap invalidated terminal-side data; resend next frame. */
+    /**
+     * Forget images no node placed this pass once they are unusable (fitted for
+     * another cell geometry) or past the retention budget, oldest first.
+     */
+    evictDormant(desiredImages) {
+        const evicted = new Set();
+        const dormant = [];
+        let retainedBytes = 0;
+        for (const entry of this.images) {
+            const image = entry[1];
+            if (desiredImages.has(image)) {
+                retainedBytes += image.retainedBytes;
+            }
+            else if (image.cellSize.width !== this.cellSize.width ||
+                image.cellSize.height !== this.cellSize.height) {
+                evicted.add(image);
+            }
+            else {
+                retainedBytes += image.retainedBytes;
+                dormant.push(entry);
+            }
+        }
+        dormant.sort((a, b) => a[1].lastUsed - b[1].lastUsed);
+        let index = 0;
+        while (index < dormant.length &&
+            (dormant.length - index > DORMANT_MAX_IMAGES || retainedBytes > RETAINED_MAX_BYTES)) {
+            const image = dormant[index][1];
+            evicted.add(image);
+            retainedBytes -= image.retainedBytes;
+            index += 1;
+        }
+        for (const [key, image] of this.images) {
+            if (evicted.has(image))
+                this.images.delete(key);
+        }
+        return evicted;
+    }
+    /**
+     * Handle a Kitty graphics reply the renderer did not ask for. ENOENT for
+     * one of our images means the terminal evicted its data (its own quota is
+     * smaller than our retention budget): upload it again and re-place every
+     * node showing it on the next frame. A second ENOENT within
+     * REUPLOAD_FAILURE_WINDOW_MS of that re-upload means the terminal refuses
+     * the image outright, so it is left as is (never an upload loop); a new
+     * content or size variant is a new image and tries again. The re-upload
+     * takes a fresh image id: every placement of the old id may still answer
+     * ENOENT, and those late replies must not count as the re-upload failing.
+     * Returns whether a repaint is needed.
+     */
+    handleResponse(imageId, status) {
+        if (!status.startsWith('ENOENT'))
+            return false;
+        let image;
+        for (const candidate of this.images.values()) {
+            if (candidate.imageId === imageId)
+                image = candidate;
+        }
+        if (image === undefined || !image.uploaded || image.abandoned)
+            return false;
+        const now = this.now();
+        if (image.reuploadedAt !== 0 && now - image.reuploadedAt < REUPLOAD_FAILURE_WINDOW_MS) {
+            image.abandoned = true;
+            return false;
+        }
+        image.reuploadedAt = now;
+        this.retiredImageIds.push(image.imageId);
+        image.imageId = this.allocateImageId();
+        image.uploaded = false;
+        for (const state of this.placements.values()) {
+            if (state.image === image)
+                state.placed = false;
+        }
+        return true;
+    }
+    /**
+     * A clear/screen swap invalidated terminal-side data; resend next frame.
+     * The terminal state an abandoned image was judged against is gone too, so
+     * it gets a fresh ENOENT budget; one clear still buys at most one retry.
+     */
     invalidateAll() {
-        for (const image of this.images.values())
+        for (const image of this.images.values()) {
             image.uploaded = false;
+            image.abandoned = false;
+            image.reuploadedAt = 0;
+        }
         for (const state of this.placements.values()) {
             state.placed = false;
         }
     }
     /** Delete every image owned by this renderer and forget their ids. */
     deleteAll() {
-        const output = [...this.images.values()]
-            .map(image => deleteKittyImage(image.imageId))
+        const output = [...this.retiredImageIds.splice(0), ...[...this.images.values()].map(image => image.imageId)]
+            .map(deleteKittyImage)
             .join('');
         this.images.clear();
         this.placements.clear();
@@ -150,7 +270,12 @@ export class KittyGraphicsManager {
         const image = {
             imageId: this.allocateImageId(),
             payload: prepareKittyRgba(fitted),
+            retainedBytes: fitted.width * fitted.height * 4,
+            cellSize: this.cellSize,
             uploaded: false,
+            lastUsed: this.pass,
+            reuploadedAt: 0,
+            abandoned: false,
         };
         this.images.set(key, image);
         return image;
@@ -179,6 +304,39 @@ export class KittyGraphicsManager {
         return id;
     }
 }
+/**
+ * The cells a placement actually occupies and, when it is clipped, the part
+ * of the uploaded raster behind them. The raster has the full cell box's
+ * exact physical aspect (see fitTerminalImageSource), so a cell edge maps to
+ * a pixel edge proportionally; the start rounds down and the end up, so a
+ * partially covered pixel row is shown rather than dropped.
+ */
+function visiblePlacement(placement, payload) {
+    const clip = placement.clip;
+    if (clip === undefined ||
+        (clip.x === placement.x && clip.y === placement.y &&
+            clip.columns === placement.columns && clip.rows === placement.rows)) {
+        return { x: placement.x, y: placement.y, columns: placement.columns, rows: placement.rows };
+    }
+    const left = clip.x - placement.x;
+    const top = clip.y - placement.y;
+    const sourceX = Math.floor((payload.width * left) / placement.columns);
+    const sourceY = Math.floor((payload.height * top) / placement.rows);
+    const sourceRight = Math.min(payload.width, Math.ceil((payload.width * (left + clip.columns)) / placement.columns));
+    const sourceBottom = Math.min(payload.height, Math.ceil((payload.height * (top + clip.rows)) / placement.rows));
+    return {
+        x: clip.x,
+        y: clip.y,
+        columns: clip.columns,
+        rows: clip.rows,
+        source: {
+            x: sourceX,
+            y: sourceY,
+            width: Math.max(1, sourceRight - sourceX),
+            height: Math.max(1, sourceBottom - sourceY),
+        },
+    };
+}
 /** Zlib-compressed direct RGBA split into protocol-compliant base64 chunks. */
 export function transmitKittyRgba(imageId, source) {
     return transmitPreparedKittyRgba(imageId, prepareKittyRgba(source));
@@ -208,9 +366,12 @@ function transmitPreparedKittyRgba(imageId, payload) {
     })
         .join('');
 }
-export function kittyPlacement(imageId, placementId, x, y, columns, rows, zIndex = IMAGE_Z_INDEX) {
+export function kittyPlacement(imageId, placementId, x, y, columns, rows, zIndex = IMAGE_Z_INDEX, source) {
+    const crop = source === undefined
+        ? ''
+        : `,x=${source.x},y=${source.y},w=${source.width},h=${source.height}`;
     return (`\u001b[${y + 1};${x + 1}H` +
-        kittyCommand(`a=p,i=${imageId},p=${placementId},c=${columns},r=${rows},z=${zIndex},C=1,q=2`));
+        kittyCommand(`a=p,i=${imageId},p=${placementId},c=${columns},r=${rows}${crop},z=${zIndex},C=1,q=1`));
 }
 export function deleteKittyPlacement(imageId, placementId) {
     return kittyCommand(`a=d,d=i,i=${imageId},p=${placementId},q=2`);

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

@@ -85,7 +85,7 @@ type Options = {
     previousImages?: readonly TerminalImagePlacement[];
 };
 /** A queued paint operation: write, clip, unclip, blit, clear, shade, noSelect, or shift. */
-export type Operation = WriteOperation | ClipOperation | UnclipOperation | BlitOperation | ClearOperation | ShadeOperation | NoSelectOperation | ShiftOperation;
+export type Operation = WriteOperation | ClipOperation | UnclipOperation | BlitOperation | ClearOperation | ShadeOperation | NoSelectOperation | CopyRegionOperation | SoftWrapRowOperation | ShiftOperation;
 /**
  * Restyle the cells already in the region at this point of the paint
  * order: a modal layer's backdrop. Applied in sequence like a write, so
@@ -108,7 +108,8 @@ type WriteOperation = {
      * means line i is a continuation of line i-1 (the `\n` before it was
      * inserted by word-wrap, not in the source). Index 0 is always false.
      * Undefined means the producer didn't track wrapping (e.g. fills,
-     * raw-ansi) — the screen's per-row bitmap is left untouched.
+     * raw-ansi): the rows it paints are marked "not a continuation", since it
+     * replaced whatever was there — see the write case in `get()`.
      */
     softWrap?: boolean[];
 };
@@ -156,6 +157,19 @@ type NoSelectOperation = {
     type: 'noSelect';
     region: Rectangle;
 };
+/** Row `y` continues the row above, whose content ends at `contentEnd`. */
+type SoftWrapRowOperation = {
+    type: 'softWrapRow';
+    y: number;
+    contentEnd: number;
+};
+/** A region that copies as `text` (see Screen.copyRegion); paints nothing. */
+type CopyRegionOperation = {
+    type: 'copyRegion';
+    region: Rectangle;
+    text: string;
+    id: number;
+};
 /**
  * Collects write/blit/clear/clip operations from the render tree, then
  * applies them to a Screen buffer in get(). The Screen is what gets
@@ -250,6 +264,8 @@ export default class Output {
      * the mark wins regardless of what's blitted into the region.
      * @param region - the region to mark.
      */
+    /** Mark row `y` as a wrap continuation (see Styles.softWrapContinuation). */
+    softWrapRow(y: number, contentEnd: number): void;
     noSelect(region: Rectangle): void;
     /**
      * Record a fully visible, frame-budgeted image request. Rejected placements
@@ -272,6 +288,12 @@ export default class Output {
     getImages(): readonly TerminalImagePlacement[];
     /** Pixel ownership is determined by paint order, not just final text values. */
     imageBacking(node: DOMElement): void;
+    /**
+     * The admitted placement's backing colour, or undefined when the raster
+     * composites transparently: its cells are then blanks, not a painted
+     * surface, so whatever the terminal shows behind the UI stays visible.
+     */
+    imagePlacementBackground(node: DOMElement): string | undefined;
     /**
      * Queue a text write at a position, split across lines on newlines.
      * @param x - the left column.

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

@@ -4,7 +4,7 @@ import { getGraphemeSegmenter } from '../utils/intl.js';
 import sliceAnsi from '../utils/sliceAnsi.js';
 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 { blitRegion, cellRunSpan, createCellRun, extractHyperlinkFromStyles, filterOutHyperlinkStyles, allocateCopyRegionId, clearCopyRegionSpan, markCopyRegion, pruneCopyTexts, 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';
@@ -152,6 +152,22 @@ function isNodeInSubtree(node, root) {
     }
     return false;
 }
+/**
+ * One copy region id per image node for its lifetime, so rows captured
+ * during drag-to-scroll and rows still on screen name the same formula.
+ */
+const copyRegionIds = new WeakMap();
+/**
+ * Copy text reaches the clipboard without passing through cells, so it never
+ * met the render path's control-character rules. Drop C0/C1 (newlines
+ * excepted: a block formula's source is multi-line) and the
+ * interlinear-annotation code points, which the copy pipeline reserves for
+ * its own row metadata.
+ */
+const COPY_TEXT_STRIP = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f\uFFF9-\uFFFB]/g;
+function cleanCopyText(value) {
+    return value.replace(COPY_TEXT_STRIP, '');
+}
 /**
  * Slot-reuse ceiling: the clustered array is a second full memory image of
  * the line, and pathological single-line output (base64 blobs, minified
@@ -502,6 +518,10 @@ export default class Output {
      * the mark wins regardless of what's blitted into the region.
      * @param region - the region to mark.
      */
+    /** Mark row `y` as a wrap continuation (see Styles.softWrapContinuation). */
+    softWrapRow(y, contentEnd) {
+        this.operations.push({ type: 'softWrapRow', y, contentEnd });
+    }
     noSelect(region) {
         this.operations.push({ type: 'noSelect', region });
     }
@@ -525,7 +545,11 @@ export default class Output {
             return false;
         }
         const presentation = node.attributes.imagePresentation;
-        const canCrop = this.imageReady !== undefined && (presentation === 'preview' || presentation === 'transcript');
+        const transparent = node.attributes.imageTransparent === 'transparent';
+        // Both protocols crop a partially visible content image to its visible
+        // cells (Sixel re-encodes the slice, Kitty places a source rectangle), so
+        // scrolling past a viewport edge never flips it to its text fallback.
+        const canCrop = this.terminalImagesEnabled && (presentation === 'preview' || presentation === 'transcript');
         if (!canCrop && (left < 0 ||
             top < 0 ||
             left + width > this.width ||
@@ -559,6 +583,7 @@ export default class Output {
             rows: height,
             source,
             ...(presentation === 'preview' || presentation === 'transcript' ? { presentation } : {}),
+            ...(transparent ? { transparent: true } : {}),
             ...(canCrop ? { clip: { x: visibleLeft, y: visibleTop, columns: visibleRight - visibleLeft, rows: visibleBottom - visibleTop } } : {}),
             ...(background !== undefined ? { background } : {}),
         };
@@ -576,8 +601,9 @@ export default class Output {
      */
     reuseImages(node) {
         // A scrollable image's current clip is only known inside its ScrollBox.
-        // Descend first rather than admitting stale placements from an ancestor blit.
-        if (this.imageReady && this.previousImages.some(p => isNodeInSubtree(p.node, node)))
+        // Descend first rather than admitting stale placements from an ancestor
+        // blit: a crop computed without that clip would spill past the viewport.
+        if (this.terminalImagesEnabled && this.previousImages.some(p => isNodeInSubtree(p.node, node)))
             return false;
         let reusedAll = true;
         for (const placement of this.previousImages) {
@@ -650,11 +676,31 @@ export default class Output {
         const placement = this.imagePlacements.find(image => image.node === node);
         if (placement) {
             const visible = placement.clip ?? placement;
-            this.noSelect({ x: visible.x, y: visible.y, width: visible.columns, height: visible.rows });
+            const region = { x: visible.x, y: visible.y, width: visible.columns, height: visible.rows };
+            // An image's backing cells are blank; one with copy text (a formula's
+            // source) copies as that text, any other image is left out of copies.
+            const copyText = node.attributes['imageCopyText'];
+            const copied = typeof copyText === 'string' ? cleanCopyText(copyText) : '';
+            if (copied !== '') {
+                let id = copyRegionIds.get(node);
+                if (id === undefined)
+                    copyRegionIds.set(node, id = allocateCopyRegionId());
+                this.operations.push({ type: 'copyRegion', region, text: copied, id });
+            }
+            else
+                this.noSelect(region);
         }
         if (this.imageReady)
             this.imageBackingEnds.set(node, this.operations.length);
     }
+    /**
+     * The admitted placement's backing colour, or undefined when the raster
+     * composites transparently: its cells are then blanks, not a painted
+     * surface, so whatever the terminal shows behind the UI stays visible.
+     */
+    imagePlacementBackground(node) {
+        return this.imagePlacements.find(image => image.node === node)?.background;
+    }
     /**
      * Queue a text write at a position, split across lines on newlines.
      * @param x - the left column.
@@ -810,6 +856,24 @@ export default class Output {
                     shiftRows(screen, operation.top, operation.bottom, operation.n);
                     continue;
                 }
+                case 'softWrapRow': {
+                    // Paint order: the marker lands where the producer asked for it, and
+                    // the write case above resets it when a later operation repaints that
+                    // row. (This used to run in a pass after every write, which let a
+                    // marker outlive an overlay that overwrote the row.)
+                    if (operation.y > 0 && operation.y < screen.height) {
+                        screen.softWrap[operation.y] = Math.max(1, operation.contentEnd);
+                    }
+                    continue;
+                }
+                case 'copyRegion': {
+                    // In paint order: anything written over the image later (a menu,
+                    // an overlay) clears the cells it covers, so a copy reads what is
+                    // visible there rather than the formula beneath.
+                    const { x, y, width, height } = operation.region;
+                    markCopyRegion(screen, x, y, width, height, operation.text, operation.id);
+                    continue;
+                }
                 case 'shade': {
                     // Honour the active clip like a write: a backdrop inside an
                     // overflow-hidden ancestor must not shade cells outside it.
@@ -882,6 +946,9 @@ export default class Output {
                         }
                         const contentEnd = writeLineToScreen(screen, line, x, lineY, screenWidth, this.stylePool, this.charCache, this.streamingSlot, this.packedOwner);
                         writeCells += contentEnd - x;
+                        if (screen.copyTexts !== undefined && screen.copyTexts.size > 0) {
+                            clearCopyRegionSpan(screen, lineY, x, contentEnd);
+                        }
                         // See Screen.softWrap docstring for the encoding. contentEnd
                         // from writeLineToScreen is tab-expansion-aware, unlike
                         // x+stringWidth(line) which treats tabs as width 0.
@@ -890,6 +957,14 @@ export default class Output {
                             swBits[lineY] = isSW ? prevContentEnd : 0;
                             prevContentEnd = contentEnd;
                         }
+                        else {
+                            // Paint order: a producer that doesn't track wrapping (fills,
+                            // raw-ansi, overlays) still replaces the row it paints, so a
+                            // continuation marker an earlier softWrapRow set for this row
+                            // is stale — keep it and a copy would glue the overlay's text
+                            // onto the previous line.
+                            swBits[lineY] = 0;
+                        }
                         offsetY++;
                     }
                     continue;
@@ -907,6 +982,9 @@ export default class Output {
                 markNoSelectRegion(screen, x, y, width, height);
             }
         }
+        // Blits carry the previous frame's region texts; keep only the ones a
+        // cell still references, or the map grows by every redrawn formula.
+        pruneCopyTexts(screen);
         // Log blit/write ratio for debugging - high write count suggests blitting isn't working
         const totalCells = blitCells + writeCells;
         if (totalCells > 1000 && writeCells > blitCells) {