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

package/lib/types/ink/components/Image.d.ts

@@ -12,8 +12,21 @@ export interface ImageProps {
     readonly height: number;
     /** Text alternative. Use an empty string for a decorative image. */
     readonly alt: string;
+    /**
+     * What a fullscreen copy yields for this image, e.g. a formula's source.
+     * Without it the image's cells are left out of copied text.
+     */
+    readonly copyText?: string;
     /** Opt into Sixel for a modal or scrollable transcript. Default keeps Kitty only. */
     readonly presentation?: 'preview' | 'transcript';
+    /**
+     * Float on whatever the terminal shows behind the image: the raster is
+     * emitted without a backing colour and its coverage becomes a hard mask
+     * (Sixel has no partial alpha). Formulas and artwork with transparent
+     * margins use this; photographs and anything sitting on a painted surface
+     * leave it unset and composite onto that surface instead.
+     */
+    readonly transparent?: boolean;
     /** Same-size terminal-cell fallback rendered when graphics are unavailable. */
     readonly children?: ReactNode;
 }
@@ -24,5 +37,5 @@ export interface ImageProps {
  * Yoga leaf; the Ink host decides after layout whether to paint its fallback
  * children or attach a terminal-graphics placement over the same cells.
  */
-export default function Image({ source, width, height, alt, presentation, children, }: ImageProps): React.ReactNode;
+export default function Image({ source, width, height, alt, copyText, presentation, transparent, children, }: ImageProps): React.ReactNode;
 //# sourceMappingURL=Image.d.ts.map

package/lib/types/ink/components/Image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Image.d.ts","sourceRoot":"","sources":["../../../../src/ink/components/Image.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAO/D,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAA;IACrC,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,GAAG,YAAY,CAAA;IAChD,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,EAC5B,MAAM,EACN,KAAK,EACL,MAAM,EACN,GAAG,EACH,YAAY,EACZ,QAAQ,GACT,EAAE,UAAU,GAAG,KAAK,CAAC,SAAS,CA4B9B"}
+{"version":3,"file":"Image.d.ts","sourceRoot":"","sources":["../../../../src/ink/components/Image.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAO/D,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAA;IACrC,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,GAAG,YAAY,CAAA;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,EAC5B,MAAM,EACN,KAAK,EACL,MAAM,EACN,GAAG,EACH,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,QAAQ,GACT,EAAE,UAAU,GAAG,KAAK,CAAC,SAAS,CA8B9B"}

package/lib/types/ink/components/Image.js

@@ -8,11 +8,11 @@ import Text from './Text.js';
  * Yoga leaf; the Ink host decides after layout whether to paint its fallback
  * children or attach a terminal-graphics placement over the same cells.
  */
-export default function Image({ source, width, height, alt, presentation, children, }) {
+export default function Image({ source, width, height, alt, copyText, presentation, transparent, children, }) {
     const [columns, rows] = normalizeSize(width, height);
     const image = isTerminalImageSource(source, presentation) ? source : undefined;
     const alternative = cleanAlternative(alt);
-    return (_jsx("ink-image", { imageData: image?.data, imageWidth: image?.width, imageHeight: image?.height, imageAlt: alternative, imagePresentation: presentation, style: {
+    return (_jsx("ink-image", { imageData: image?.data, imageWidth: image?.width, imageHeight: image?.height, imageAlt: alternative, imagePresentation: presentation, imageCopyText: copyText, imageTransparent: transparent === true ? 'transparent' : undefined, style: {
             width: columns,
             height: rows,
             flexGrow: 0,

package/lib/types/ink/events/input-event.js

@@ -47,9 +47,9 @@ function parseKey(keypress) {
     if (keypress.ctrl && input === 'space') {
         input = ' ';
     }
-    // Suppress unrecognized escape sequences that were parsed as function keys
-    // (matched by FN_KEY_RE) but have no name in the keyName map.
-    // Examples: ESC[25~ (F13/Right Alt on Windows), ESC[26~ (F14), etc.
+    // Suppress unrecognized function keys and other complete CSI sequences
+    // that have a protocol code but no mapped key name.
+    // Examples: ESC[25~ (F13/Right Alt on Windows), ESC[1;2;3;1A, etc.
     // Without this, the ESC prefix is stripped below and the remainder (e.g.,
     // "[25~") leaks into the input as literal text.
     if (keypress.code && !keypress.name) {

package/lib/types/ink/hooks/use-terminal-images.d.ts

@@ -3,8 +3,20 @@ interface TerminalImages {
     subscribe(listener: () => void): () => void;
     getSnapshot(): boolean;
     getCellSize?(): TerminalCellSize | undefined;
+    getProtocol?(): TerminalImageProtocolName | undefined;
     request(): () => void;
 }
+/** The graphics protocol the renderer paints images with. */
+export type TerminalImageProtocolName = 'kitty' | 'sixel';
+/**
+ * The protocol images are painted with, or undefined without graphics.
+ *
+ * Kitty provides persistent placements; Sixel paints rasters into the
+ * renderer-managed transcript surface. Both may host inline media as long as
+ * the placement joins the normal image lifecycle (a `presentation` of
+ * `'transcript'` or `'preview'`), which is the real capability boundary.
+ */
+export declare function useTerminalImageProtocol(): TerminalImageProtocolName | undefined;
 /** Only measured pixels qualify for an original-pixel (100%) image view. */
 export declare function useTerminalImageCellSize(): TerminalCellSize | undefined;
 export declare const TerminalImagesContext: import("react").Context<TerminalImages>;

package/lib/types/ink/hooks/use-terminal-images.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-terminal-images.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-terminal-images.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,UAAU,cAAc;IACtB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C,WAAW,IAAI,OAAO,CAAA;IACtB,WAAW,CAAC,IAAI,gBAAgB,GAAG,SAAS,CAAA;IAC5C,OAAO,IAAI,MAAM,IAAI,CAAA;CACtB;AAID,4EAA4E;AAC5E,wBAAgB,wBAAwB,IAAI,gBAAgB,GAAG,SAAS,CAGvE;AAED,eAAO,MAAM,qBAAqB,yCAIhC,CAAA;AAEF,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,SAAS,UAAO,GAAG,OAAO,CAO3D"}
+{"version":3,"file":"use-terminal-images.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-terminal-images.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,UAAU,cAAc;IACtB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C,WAAW,IAAI,OAAO,CAAA;IACtB,WAAW,CAAC,IAAI,gBAAgB,GAAG,SAAS,CAAA;IAC5C,WAAW,CAAC,IAAI,yBAAyB,GAAG,SAAS,CAAA;IACrD,OAAO,IAAI,MAAM,IAAI,CAAA;CACtB;AAED,6DAA6D;AAC7D,MAAM,MAAM,yBAAyB,GAAG,OAAO,GAAG,OAAO,CAAA;AAKzD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,yBAAyB,GAAG,SAAS,CAGhF;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,IAAI,gBAAgB,GAAG,SAAS,CAGvE;AAED,eAAO,MAAM,qBAAqB,yCAIhC,CAAA;AAEF,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,SAAS,UAAO,GAAG,OAAO,CAO3D"}

package/lib/types/ink/hooks/use-terminal-images.js

@@ -1,5 +1,18 @@
 import { createContext, useContext, useEffect, useSyncExternalStore } from 'react';
 const noCellSize = () => undefined;
+const noProtocol = () => undefined;
+/**
+ * The protocol images are painted with, or undefined without graphics.
+ *
+ * Kitty provides persistent placements; Sixel paints rasters into the
+ * renderer-managed transcript surface. Both may host inline media as long as
+ * the placement joins the normal image lifecycle (a `presentation` of
+ * `'transcript'` or `'preview'`), which is the real capability boundary.
+ */
+export function useTerminalImageProtocol() {
+    const images = useContext(TerminalImagesContext);
+    return useSyncExternalStore(images.subscribe, images.getProtocol ?? noProtocol);
+}
 /** Only measured pixels qualify for an original-pixel (100%) image view. */
 export function useTerminalImageCellSize() {
     const images = useContext(TerminalImagesContext);

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

@@ -518,6 +518,12 @@ export default class Ink {
     private writeRaw;
     private setCursorDeclaration;
     private setAppRef;
+    /**
+     * Kitty placements report failures; an ENOENT means the terminal evicted a
+     * dormant image under a quota smaller than our retention budget. Repaint so
+     * the next reconcile uploads it again.
+     */
+    private handleUnsolicitedResponse;
     render(node: ReactNode): void;
     unmount(error?: Error | number | null): void;
     waitUntilExit(): Promise<void>;

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

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

package/lib/types/ink/ink.js

@@ -97,6 +97,7 @@ export default class Ink {
         getSnapshot: () => this.altScreenActive && (this.kittyGraphicsSupported || this.sixelGraphicsSupported) &&
             !this.isPaused && !this.terminalQueriesSuspended && !this.isUnmounted,
         getCellSize: () => this.measuredImageCellSize,
+        getProtocol: () => !this.terminalImages.getSnapshot() ? undefined : this.kittyGraphicsSupported ? 'kitty' : 'sixel',
         request: () => {
             if (this.isUnmounted)
                 return noop;
@@ -845,7 +846,7 @@ export default class Ink {
         if (this.altScreenActive) {
             selActive = hasSelection(this.selection);
             if (selActive) {
-                applySelectionOverlay(frame.screen, this.selection, this.stylePool);
+                applySelectionOverlay(frame.screen, this.selection, this.stylePool, frame.images);
             }
             // Commit-consistency guard: hash the rows under the highlight on the
             // frame the copy would actually read. An uncoordinated change since
@@ -2484,7 +2485,21 @@ export default class Ink {
     };
     setAppRef(app) {
         this.app = app;
+        if (app !== null)
+            app.querier.onUnsolicited = this.handleUnsolicitedResponse;
     }
+    /**
+     * Kitty placements report failures; an ENOENT means the terminal evicted a
+     * dormant image under a quota smaller than our retention budget. Repaint so
+     * the next reconcile uploads it again.
+     */
+    handleUnsolicitedResponse = (response) => {
+        if (response.type !== 'kittyGraphics' || this.isUnmounted)
+            return;
+        if (this.kittyGraphicsManager.handleResponse(response.imageId, response.status)) {
+            this.scheduleRender();
+        }
+    };
     render(node) {
         this.currentNode = node;
         const tree = _jsx(App, { ref: this.setAppRef, stdin: this.options.stdin, stdout: this.options.stdout, stderr: this.options.stderr, exitOnCtrlC: this.options.exitOnCtrlC, onExit: this.unmount, terminalColumns: this.terminalColumns, terminalRows: this.terminalRows, selection: this.selection, onSelectionChange: this.notifySelectionChange, onClickAt: this.dispatchClick, onContextMenuAt: this.dispatchContextMenu, onHoverAt: this.dispatchHover, onWheelAt: this.dispatchWheelAt, getHyperlinkAt: this.getHyperlinkAt, onOpenHyperlink: this.openHyperlink, onMultiClick: this.handleMultiClick, onSelectionDrag: this.handleSelectionDrag, onDragTargetAt: this.findDragTargetAt, onDragDispatch: this.dispatchDrag, onPointerGestureChange: this.setPointerGestureActive, onProtocolCandidateChange: this.setProtocolCandidateActive, onReleaseTail: this.drainReleaseTail, onClickProbe: this.clickProbeAtBatchTail, onStdinResume: this.reassertTerminalModes, onTerminalFocus: this.handleTerminalFocusProbe, onCursorDeclaration: this.setCursorDeclaration, dispatchKeyboardEvent: this.dispatchKeyboardEvent, children: _jsx(TerminalWriteProvider, { value: this.writeRaw, children: _jsx(TerminalImagesContext.Provider, { value: this.terminalImages, children: node }) }) });

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`);