@zergai/ztc 0.5.0-beta.1 → 0.6.0-beta.1

package/dist/ui/terminal_image.js

@@ -0,0 +1,516 @@
+/**
+ * Terminal image previews for the transcript.
+ *
+ * In a terminal that speaks the Kitty graphics protocol (Ghostty, Kitty) the
+ * transcript shows the image itself. The image is sent to the terminal once
+ * and placed with Kitty's Unicode placeholders: cells of U+10EEEE whose
+ * foreground colour names the image and whose diacritics give the cell's row
+ * and column. The terminal draws the image over those cells, so they travel
+ * as ordinary transcript text: they scroll into history and survive redraws
+ * like any other row.
+ *
+ * Everywhere else an image is drawn with Unicode half blocks: each cell shows
+ * two vertically stacked pixels, the top one as the `▀` glyph's 24-bit
+ * foreground and the bottom one as its background. The output is ordinary SGR
+ * text, so every renderer that already draws ZTC's coloured transcript rows
+ * (ztc-tui, zmux, zterm) shows it unchanged, whichever model produced the image.
+ *
+ * Decoding is synchronous because transcript rendering is. Each source is
+ * decoded once into a small thumbnail, plus the pixels a Kitty terminal is
+ * sent; renders at any width resample or place those.
+ */
+import { createHash } from 'node:crypto';
+import { statSync, readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { deflateSync } from 'node:zlib';
+import jpeg from 'jpeg-js';
+import { GifReader } from 'omggif';
+import { PNG } from 'pngjs';
+import { readDurableSessionImageSync } from '../session_media.js';
+/** Largest preview, in terminal cells. */
+export const TRANSCRIPT_IMAGE_MAX_COLS = 80;
+export const TRANSCRIPT_IMAGE_MAX_ROWS = 20;
+/** Files larger than this are not read for a preview. */
+const MAX_SOURCE_BYTES = 20 * 1024 * 1024;
+/** Decoders refuse images larger than this many megapixels. */
+const MAX_MEGAPIXELS = 50;
+const MAX_HELD_IMAGES = 256;
+/** Pixel alpha at or above this draws; below it the terminal background shows. */
+const OPAQUE_ALPHA = 128;
+/** Held Kitty pixels past this many base64 bytes evict the oldest images. */
+const MAX_HELD_GRAPHIC_BYTES = 128 * 1024 * 1024;
+/** Image placements remembered for uploading, most recent last. */
+const MAX_PLACEMENTS = 1024;
+/** The renderer refuses larger images; ZTC's previews stay far below it. */
+const MAX_GRAPHIC_SIDE = 8192;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Decode a PNG, JPEG or GIF (first frame). Anything else, or corrupt data, is null. */
+export function decodeImage(bytes) {
+    const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    try {
+        if (buffer.length >= 8 && buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+            // Size from the IHDR chunk first: decoding a small file that claims 8000x8000 inflates about 1 GB.
+            if (buffer.length < 24 || buffer.toString('latin1', 12, 16) !== 'IHDR'
+                || buffer.readUInt32BE(16) * buffer.readUInt32BE(20) > MAX_MEGAPIXELS * 1_000_000)
+                return null;
+            const png = PNG.sync.read(buffer);
+            return { width: png.width, height: png.height, data: new Uint8Array(png.data.buffer, png.data.byteOffset, png.data.byteLength) };
+        }
+        if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+            const decoded = jpeg.decode(buffer, { useTArray: true, formatAsRGBA: true, maxResolutionInMP: MAX_MEGAPIXELS, maxMemoryUsageInMB: 512 });
+            return { width: decoded.width, height: decoded.height, data: decoded.data };
+        }
+        if (buffer.length >= 6 && ['GIF87a', 'GIF89a'].includes(buffer.subarray(0, 6).toString('latin1'))) {
+            const reader = new GifReader(buffer);
+            if (reader.numFrames() === 0 || reader.width * reader.height > MAX_MEGAPIXELS * 1_000_000)
+                return null;
+            const data = new Uint8Array(reader.width * reader.height * 4);
+            reader.decodeAndBlitFrameRGBA(0, data);
+            return { width: reader.width, height: reader.height, data };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Area-average `image` down to fit `maxWidth` x `maxHeight` pixels, keeping its
+ * aspect ratio. Colour is averaged weighted by alpha so transparent pixels do
+ * not darken edges. Never upscales.
+ */
+function fit(image, maxWidth, maxHeight) {
+    const scale = Math.min(1, maxWidth / image.width, maxHeight / image.height);
+    const width = Math.max(1, Math.min(maxWidth, Math.round(image.width * scale)));
+    const height = Math.max(1, Math.min(maxHeight, Math.round(image.height * scale)));
+    if (width === image.width && height === image.height)
+        return image;
+    const data = new Uint8Array(width * height * 4);
+    for (let y = 0; y < height; y++) {
+        const y0 = Math.floor(y * image.height / height);
+        const y1 = Math.max(y0 + 1, Math.floor((y + 1) * image.height / height));
+        for (let x = 0; x < width; x++) {
+            const x0 = Math.floor(x * image.width / width);
+            const x1 = Math.max(x0 + 1, Math.floor((x + 1) * image.width / width));
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            for (let sy = y0; sy < y1; sy++) {
+                let offset = (sy * image.width + x0) * 4;
+                for (let sx = x0; sx < x1; sx++, offset += 4) {
+                    const alpha = image.data[offset + 3];
+                    r += image.data[offset] * alpha;
+                    g += image.data[offset + 1] * alpha;
+                    b += image.data[offset + 2] * alpha;
+                    a += alpha;
+                }
+            }
+            const out = (y * width + x) * 4;
+            const count = (y1 - y0) * (x1 - x0);
+            if (a > 0) {
+                data[out] = Math.round(r / a);
+                data[out + 1] = Math.round(g / a);
+                data[out + 2] = Math.round(b / a);
+            }
+            data[out + 3] = Math.round(a / count);
+        }
+    }
+    return { width, height, data };
+}
+/**
+ * Draw `image` as at most `maxRows` rows of at most `maxCols` half-block cells.
+ * Each row is self-contained SGR text ending in a reset.
+ */
+export function imageToTerminalRows(image, maxCols, maxRows) {
+    if (maxCols < 1 || maxRows < 1 || image.width < 1 || image.height < 1)
+        return [];
+    const fitted = fit(image, maxCols, maxRows * 2);
+    const { width, height, data } = fitted;
+    const rows = [];
+    for (let y = 0; y < height; y += 2) {
+        let row = '';
+        let fg = '';
+        let bg = '';
+        const setFg = (code) => { if (fg !== code) {
+            row += `\x1b[${code}m`;
+            fg = code;
+        } };
+        const setBg = (code) => { if (bg !== code) {
+            row += `\x1b[${code}m`;
+            bg = code;
+        } };
+        for (let x = 0; x < width; x++) {
+            const top = (y * width + x) * 4;
+            const bottom = top + width * 4;
+            const topShown = data[top + 3] >= OPAQUE_ALPHA;
+            const bottomShown = y + 1 < height && data[bottom + 3] >= OPAQUE_ALPHA;
+            const colour = (offset) => `${data[offset]};${data[offset + 1]};${data[offset + 2]}`;
+            if (topShown && bottomShown) {
+                setFg(`38;2;${colour(top)}`);
+                setBg(`48;2;${colour(bottom)}`);
+                row += '▀';
+            }
+            else if (topShown) {
+                setFg(`38;2;${colour(top)}`);
+                setBg('49');
+                row += '▀';
+            }
+            else if (bottomShown) {
+                setFg(`38;2;${colour(bottom)}`);
+                setBg('49');
+                row += '▄';
+            }
+            else {
+                setBg('49');
+                row += ' ';
+            }
+        }
+        rows.push(`${row}\x1b[0m`);
+    }
+    return rows;
+}
+/** A cell's shape when the terminal does not report it: about twice as tall as wide. */
+const DEFAULT_CELL_PIXELS = { width: 10, height: 20 };
+let imageMode = 'blocks';
+let cellPixels = DEFAULT_CELL_PIXELS;
+/**
+ * Whether the terminal ZTC runs in draws Kitty graphics with Unicode
+ * placeholders: Ghostty and Kitty. A multiplexer in between (tmux, screen)
+ * drops the upload, and a terminal started from a Ghostty shell inherits
+ * Ghostty's variables without being Ghostty, so its own TERM_PROGRAM decides.
+ * `ZTC_IMAGE_PROTOCOL=kitty` or `=blocks` overrides the detection.
+ */
+export function kittyGraphicsTerminal(env) {
+    const override = env.ZTC_IMAGE_PROTOCOL?.toLowerCase();
+    if (override === 'kitty')
+        return true;
+    if (override === 'blocks' || override === 'none' || override === '0')
+        return false;
+    const term = (env.TERM ?? '').toLowerCase();
+    const program = (env.TERM_PROGRAM ?? '').toLowerCase();
+    if (env.TMUX || term.startsWith('tmux') || term.startsWith('screen'))
+        return false;
+    if (program)
+        return program === 'ghostty' || program === 'kitty';
+    return term === 'xterm-ghostty' || term === 'xterm-kitty' || Boolean(env.KITTY_WINDOW_ID) || Boolean(env.GHOSTTY_RESOURCES_DIR);
+}
+/**
+ * Draw transcript images as `mode` from now on. `cell` is the cell size the
+ * renderer measured, when the terminal reports one. Previews of files are read
+ * again, so they carry (or drop) the pixels a Kitty terminal is sent; a tool
+ * image already held keeps the form it was decoded in.
+ */
+export function setTerminalImageMode(mode, cell) {
+    imageMode = mode;
+    cellPixels = cell && cell.width > 0 && cell.height > 0 ? cell : DEFAULT_CELL_PIXELS;
+    for (const key of [...thumbnails.keys()]) {
+        if (!key.startsWith('inline:'))
+            forget(key);
+    }
+}
+/** Least-recently-used thumbnails, by source identity. */
+const thumbnails = new Map();
+let heldGraphicBytes = 0;
+function forget(key) {
+    const held = thumbnails.get(key);
+    if (held?.graphic)
+        heldGraphicBytes -= held.graphic.data.length;
+    thumbnails.delete(key);
+}
+function remember(key, thumbnail) {
+    if (thumbnails.has(key)) {
+        // Re-inserting moves the entry to the newest end without recounting it.
+        thumbnails.delete(key);
+    }
+    else if (thumbnail?.graphic) {
+        heldGraphicBytes += thumbnail.graphic.data.length;
+    }
+    thumbnails.set(key, thumbnail);
+    while (thumbnails.size > MAX_HELD_IMAGES || heldGraphicBytes > MAX_HELD_GRAPHIC_BYTES) {
+        const oldest = thumbnails.keys().next();
+        if (oldest.done || oldest.value === key)
+            break;
+        forget(oldest.value);
+    }
+    return thumbnail;
+}
+function recall(key) {
+    const held = thumbnails.get(key);
+    if (held !== undefined)
+        remember(key, held);
+    return held;
+}
+function thumbnailOf(key, bytes) {
+    const image = decodeImage(bytes);
+    if (!image)
+        return null;
+    return {
+        key,
+        image: fit(image, TRANSCRIPT_IMAGE_MAX_COLS, TRANSCRIPT_IMAGE_MAX_ROWS * 2),
+        width: image.width,
+        height: image.height,
+        ...(imageMode === 'kitty' ? { graphic: kittyGraphic(image) } : {}),
+    };
+}
+/** The pixels for the largest box the transcript places an image in; the terminal scales them to each placement. */
+function kittyGraphic(image) {
+    const fitted = fit(image, Math.min(MAX_GRAPHIC_SIDE, TRANSCRIPT_IMAGE_MAX_COLS * cellPixels.width), Math.min(MAX_GRAPHIC_SIDE, TRANSCRIPT_IMAGE_MAX_ROWS * cellPixels.height));
+    const pixels = Buffer.from(fitted.data.buffer, fitted.data.byteOffset, fitted.data.byteLength);
+    return { width: fitted.width, height: fitted.height, data: deflateSync(pixels).toString('base64') };
+}
+function fileThumbnail(path) {
+    let key;
+    try {
+        const stats = statSync(path);
+        if (!stats.isFile() || stats.size > MAX_SOURCE_BYTES)
+            return null;
+        // A rewritten file at the same path is a different image.
+        key = `file:${path}:${stats.size}:${stats.mtimeMs}`;
+    }
+    catch {
+        return null;
+    }
+    const held = recall(key);
+    if (held !== undefined)
+        return held;
+    try {
+        return remember(key, thumbnailOf(key, readFileSync(path)));
+    }
+    catch {
+        return remember(key, null);
+    }
+}
+/**
+ * Hold a tool result's image bytes for transcript rendering and return the
+ * reference to keep in message metadata. Null when the data is not a
+ * displayable image.
+ */
+export function rememberInlineImage(base64) {
+    const ref = createHash('sha256').update(base64).digest('hex');
+    const key = `inline:${ref}`;
+    const held = recall(key);
+    if (held !== undefined)
+        return held ? ref : null;
+    return remember(key, thumbnailOf(key, Buffer.from(base64, 'base64'))) ? ref : null;
+}
+/**
+ * Turn a tool group's images into metadata references, holding inline bytes
+ * in memory. Images that do not decode are listed by label so the transcript
+ * can say they are unavailable.
+ */
+export function transcriptImagesForToolOutput(images) {
+    return (images ?? []).map(image => {
+        if (!('data' in image))
+            return { label: image.label, path: image.path };
+        // The held bytes are exactly what the tool returned; the path, when there
+        // is one, lets a resumed session redraw the image after they are gone.
+        return { label: image.label, ref: rememberInlineImage(image.data) ?? '', ...(image.path ? { path: image.path } : {}) };
+    });
+}
+function attachmentThumbnail(attachment) {
+    // The session checkpoint owns a durable copy; prefer it over a path that
+    // may since have been deleted or rewritten.
+    if (attachment.durable) {
+        const key = `durable:${attachment.durable.sha256}`;
+        const held = recall(key);
+        if (held !== undefined)
+            return held;
+        try {
+            const durable = readDurableSessionImageSync(attachment);
+            if (durable)
+                return remember(key, thumbnailOf(key, durable.data));
+        }
+        catch {
+            // Fall back to the local path below.
+        }
+    }
+    return attachment.localPath ? fileThumbnail(attachment.localPath) : null;
+}
+function preview(label, thumbnail, maxCols) {
+    if (!thumbnail)
+        return { caption: `[image] ${label} · unavailable`, rows: [] };
+    const cols = Math.min(maxCols, TRANSCRIPT_IMAGE_MAX_COLS);
+    return {
+        caption: `[image] ${label} · ${thumbnail.width}×${thumbnail.height}`,
+        rows: imageMode === 'kitty' && thumbnail.graphic && cols >= 1
+            ? kittyPlacementRows(thumbnail, cols, TRANSCRIPT_IMAGE_MAX_ROWS)
+            : imageToTerminalRows(thumbnail.image, cols, TRANSCRIPT_IMAGE_MAX_ROWS),
+    };
+}
+/**
+ * Kitty's row and column diacritics (rowcolumn-diacritics.txt in the Kitty
+ * repository): entry n marks row or column n of a placeholder cell.
+ */
+const PLACEHOLDER_DIACRITICS = [
+    0x0305, 0x030D, 0x030E, 0x0310, 0x0312, 0x033D, 0x033E, 0x033F, 0x0346, 0x034A, 0x034B, 0x034C,
+    0x0350, 0x0351, 0x0352, 0x0357, 0x035B, 0x0363, 0x0364, 0x0365, 0x0366, 0x0367, 0x0368, 0x0369,
+    0x036A, 0x036B, 0x036C, 0x036D, 0x036E, 0x036F, 0x0483, 0x0484, 0x0485, 0x0486, 0x0487, 0x0592,
+    0x0593, 0x0594, 0x0595, 0x0597, 0x0598, 0x0599, 0x059C, 0x059D, 0x059E, 0x059F, 0x05A0, 0x05A1,
+    0x05A8, 0x05A9, 0x05AB, 0x05AC, 0x05AF, 0x05C4, 0x0610, 0x0611, 0x0612, 0x0613, 0x0614, 0x0615,
+    0x0616, 0x0617, 0x0657, 0x0658, 0x0659, 0x065A, 0x065B, 0x065D, 0x065E, 0x06D6, 0x06D7, 0x06D8,
+    0x06D9, 0x06DA, 0x06DB, 0x06DC, 0x06DF, 0x06E0, 0x06E1, 0x06E2, 0x06E4, 0x06E7, 0x06E8, 0x06EB,
+    0x06EC, 0x0730, 0x0732, 0x0733, 0x0735, 0x0736, 0x073A, 0x073D, 0x073F, 0x0740, 0x0741, 0x0743,
+    0x0745, 0x0747, 0x0749, 0x074A, 0x07EB, 0x07EC, 0x07ED, 0x07EE, 0x07EF, 0x07F0, 0x07F1, 0x07F3,
+    0x0816, 0x0817, 0x0818, 0x0819, 0x081B, 0x081C, 0x081D, 0x081E, 0x081F, 0x0820, 0x0821, 0x0822,
+    0x0823, 0x0825, 0x0826, 0x0827, 0x0829, 0x082A, 0x082B, 0x082C, 0x082D, 0x0951, 0x0953, 0x0954,
+    0x0F82, 0x0F83, 0x0F86, 0x0F87, 0x135D, 0x135E, 0x135F, 0x17DD, 0x193A, 0x1A17, 0x1A75, 0x1A76,
+    0x1A77, 0x1A78, 0x1A79, 0x1A7A, 0x1A7B, 0x1A7C, 0x1B6B, 0x1B6D, 0x1B6E, 0x1B6F, 0x1B70, 0x1B71,
+    0x1B72, 0x1B73, 0x1CD0, 0x1CD1, 0x1CD2, 0x1CDA, 0x1CDB, 0x1CE0, 0x1DC0, 0x1DC1, 0x1DC3, 0x1DC4,
+    0x1DC5, 0x1DC6, 0x1DC7, 0x1DC8, 0x1DC9, 0x1DCB, 0x1DCC, 0x1DD1, 0x1DD2, 0x1DD3, 0x1DD4, 0x1DD5,
+    0x1DD6, 0x1DD7, 0x1DD8, 0x1DD9, 0x1DDA, 0x1DDB, 0x1DDC, 0x1DDD, 0x1DDE, 0x1DDF, 0x1DE0, 0x1DE1,
+    0x1DE2, 0x1DE3, 0x1DE4, 0x1DE5, 0x1DE6, 0x1DFE, 0x20D0, 0x20D1, 0x20D4, 0x20D5, 0x20D6, 0x20D7,
+    0x20DB, 0x20DC, 0x20E1, 0x20E7, 0x20E9, 0x20F0, 0x2CEF, 0x2CF0, 0x2CF1, 0x2DE0, 0x2DE1, 0x2DE2,
+    0x2DE3, 0x2DE4, 0x2DE5, 0x2DE6, 0x2DE7, 0x2DE8, 0x2DE9, 0x2DEA, 0x2DEB, 0x2DEC, 0x2DED, 0x2DEE,
+    0x2DEF, 0x2DF0, 0x2DF1, 0x2DF2, 0x2DF3, 0x2DF4, 0x2DF5, 0x2DF6, 0x2DF7, 0x2DF8, 0x2DF9, 0x2DFA,
+    0x2DFB, 0x2DFC, 0x2DFD, 0x2DFE, 0x2DFF, 0xA66F, 0xA67C, 0xA67D, 0xA6F0, 0xA6F1, 0xA8E0, 0xA8E1,
+    0xA8E2, 0xA8E3, 0xA8E4, 0xA8E5, 0xA8E6, 0xA8E7, 0xA8E8, 0xA8E9, 0xA8EA, 0xA8EB, 0xA8EC, 0xA8ED,
+    0xA8EE, 0xA8EF, 0xA8F0, 0xA8F1, 0xAAB0, 0xAAB2, 0xAAB3, 0xAAB7, 0xAAB8, 0xAABE, 0xAABF, 0xAAC1,
+    0xFE20, 0xFE21, 0xFE22, 0xFE23, 0xFE24, 0xFE25, 0xFE26, 0x10A0F, 0x10A38, 0x1D185, 0x1D186, 0x1D187,
+    0x1D188, 0x1D189, 0x1D1AA, 0x1D1AB, 0x1D1AC, 0x1D1AD, 0x1D242, 0x1D243, 0x1D244,
+].map(code => String.fromCodePoint(code));
+const PLACEHOLDER = '\u{10EEEE}';
+/** A placeholder run's colour, which names its image. */
+const PLACEMENT_COLOUR = /\x1b\[38;2;(\d+);(\d+);(\d+)m\u{10EEEE}/gu;
+/** Placements drawn recently, by image id, so their uploads can be built from the rows that use them. */
+const placements = new Map();
+/**
+ * Rows of placeholder cells for `thumbnail`: at one image pixel per screen
+ * pixel when that fits, otherwise scaled down into the box, keeping its shape.
+ * Each size of each image is its own placement, with an id derived from both,
+ * so the same image at the same width keeps its id across redraws.
+ */
+function kittyPlacementRows(thumbnail, maxCols, maxRows) {
+    const boxCols = Math.min(maxCols, PLACEHOLDER_DIACRITICS.length);
+    const boxRows = Math.min(maxRows, PLACEHOLDER_DIACRITICS.length);
+    const scale = Math.min(1, boxCols * cellPixels.width / thumbnail.width, boxRows * cellPixels.height / thumbnail.height);
+    const cols = Math.max(1, Math.min(boxCols, Math.round(thumbnail.width * scale / cellPixels.width)));
+    const rows = Math.max(1, Math.min(boxRows, Math.round(thumbnail.height * scale / cellPixels.height)));
+    const id = createHash('sha256').update(`${thumbnail.key}|${cols}x${rows}`).digest().readUIntBE(0, 3) || 1;
+    placements.delete(id);
+    placements.set(id, { key: thumbnail.key, cols, rows });
+    while (placements.size > MAX_PLACEMENTS) {
+        const oldest = placements.keys().next();
+        if (oldest.done)
+            break;
+        placements.delete(oldest.value);
+    }
+    const colour = `\x1b[38;2;${(id >> 16) & 255};${(id >> 8) & 255};${id & 255}m`;
+    return Array.from({ length: rows }, (_, row) => {
+        let text = colour;
+        for (let column = 0; column < cols; column++) {
+            text += PLACEHOLDER + PLACEHOLDER_DIACRITICS[row] + PLACEHOLDER_DIACRITICS[column];
+        }
+        return `${text}\x1b[0m`;
+    });
+}
+/**
+ * Which images the terminal still needs before transcript rows that place
+ * them are written. A Kitty terminal keeps an uploaded image until it is
+ * deleted, through screen and history clears, so each is sent once per
+ * renderer.
+ */
+export class KittyImageUploads {
+    sent = new Set();
+    /** Forget what the terminal holds; every image is sent again when next placed. */
+    reset() {
+        this.sent.clear();
+    }
+    /** The images `texts` place that the terminal has not been sent, in order, now counted as sent. */
+    pending(texts) {
+        const uploads = [];
+        for (const text of texts) {
+            if (!text.includes(PLACEHOLDER))
+                continue;
+            for (const match of text.matchAll(PLACEMENT_COLOUR)) {
+                const id = (Number(match[1]) << 16) | (Number(match[2]) << 8) | Number(match[3]);
+                if (this.sent.has(id))
+                    continue;
+                const placement = placements.get(id);
+                const graphic = placement ? recall(placement.key)?.graphic : undefined;
+                // An image no longer held leaves its cells blank rather than failing the transcript.
+                if (!placement || !graphic)
+                    continue;
+                this.sent.add(id);
+                uploads.push({ id, cols: placement.cols, rows: placement.rows, width: graphic.width, height: graphic.height, data: graphic.data });
+            }
+        }
+        return uploads;
+    }
+}
+/** Previews of a user message's image attachments. */
+export function attachmentImagePreviews(attachments, maxCols) {
+    if (!Array.isArray(attachments))
+        return [];
+    return attachments
+        .filter(attachment => attachment?.kind === 'image')
+        .map(attachment => preview(attachmentLabel(attachment), attachmentThumbnail(attachment), maxCols));
+}
+function attachmentLabel(attachment) {
+    const name = typeof attachment.name === 'string' && attachment.name ? attachment.name
+        : attachment.localPath ? basename(attachment.localPath) : 'image';
+    return name.replace(/[\u0000-\u001f\u007f]/g, ' ');
+}
+/**
+ * `[image PATH]`: the composer's token for a path-only image badge, which is
+ * how a clipboard paste is sent. The request encoder turns the same token into
+ * an image block, so whatever the model is shown, the transcript draws.
+ */
+const IMAGE_TOKEN = /\[image ([^\]]+)\]/g;
+const WHOLE_LINE_IMAGE_TOKEN = /^\[image ([^\]]+)\]$/;
+/**
+ * Split a user message's image tokens from its text. A token on a line of its
+ * own (as the composer writes a pasted image) is removed; one inside a sentence
+ * is shortened to the file name so the sentence still reads. Paths are returned
+ * in order of appearance.
+ */
+export function extractImageTokens(content) {
+    const paths = [];
+    const lines = [];
+    for (const line of content.split('\n')) {
+        const whole = WHOLE_LINE_IMAGE_TOKEN.exec(line.trim());
+        if (whole) {
+            paths.push(whole[1].trim());
+            continue;
+        }
+        lines.push(line.replace(IMAGE_TOKEN, (_token, path) => {
+            paths.push(path.trim());
+            return `[image ${basename(path.trim())}]`;
+        }));
+    }
+    if (paths.length === 0)
+        return { text: content, paths };
+    return { text: lines.join('\n').replace(/^\n+|\n+$/g, ''), paths };
+}
+/** Previews of image files named by `[image PATH]` tokens. */
+export function imagePathPreviews(paths, maxCols) {
+    return paths.map(path => preview(basename(path).replace(/[\u0000-\u001f\u007f]/g, ' '), fileThumbnail(path), maxCols));
+}
+/**
+ * Previews of a tool message's images. `images` comes from persisted message
+ * metadata, so anything that is not a well-formed reference is skipped.
+ */
+export function toolImagePreviews(images, maxCols) {
+    if (!Array.isArray(images))
+        return [];
+    const previews = [];
+    for (const image of images) {
+        if (!image || typeof image !== 'object')
+            continue;
+        const { label, path, ref } = image;
+        if (typeof label !== 'string')
+            continue;
+        const clean = label.replace(/[\u0000-\u001f\u007f]/g, ' ');
+        const held = typeof ref === 'string' ? recall(`inline:${ref}`) ?? null : null;
+        if (held) {
+            previews.push(preview(clean, held, maxCols));
+        }
+        else if (typeof path === 'string' && path) {
+            previews.push(preview(clean, fileThumbnail(path), maxCols));
+        }
+        else if (typeof ref === 'string') {
+            previews.push(preview(clean, null, maxCols));
+        }
+    }
+    return previews;
+}

package/dist/ui/transcript_render_cache.d.ts

@@ -11,10 +11,10 @@
  *
  * This cache keys each rendered message by the inputs that change its
  * rendering: content, timestamp, role, the render-relevant metadata flags
- * (`reasoning`, `recap`, `toolOutput` identity), streaming state, and the
- * layout config key (columns + thinking visibility). Everything else about the
- * message object — attachments, widget data, unrelated metadata — is not read
- * by the renderer and must not invalidate it.
+ * (`reasoning`, `recap`, `toolOutput` identity), image attachments (drawn as
+ * previews), streaming state, and the layout config key (columns + thinking
+ * visibility). Everything else about the message object — widget data,
+ * unrelated metadata — is not read by the renderer and must not invalidate it.
  *
  * Entries are bounded by a total rendered-line budget; the oldest entries are
  * dropped first. A dropped message simply re-renders on its next rebuild.

package/dist/ui/transcript_render_cache.js

@@ -11,10 +11,10 @@
  *
  * This cache keys each rendered message by the inputs that change its
  * rendering: content, timestamp, role, the render-relevant metadata flags
- * (`reasoning`, `recap`, `toolOutput` identity), streaming state, and the
- * layout config key (columns + thinking visibility). Everything else about the
- * message object — attachments, widget data, unrelated metadata — is not read
- * by the renderer and must not invalidate it.
+ * (`reasoning`, `recap`, `toolOutput` identity), image attachments (drawn as
+ * previews), streaming state, and the layout config key (columns + thinking
+ * visibility). Everything else about the message object — widget data,
+ * unrelated metadata — is not read by the renderer and must not invalidate it.
  *
  * Entries are bounded by a total rendered-line budget; the oldest entries are
  * dropped first. A dropped message simply re-renders on its next rebuild.
@@ -80,6 +80,7 @@ export class TranscriptRenderCache {
             timestampMs: message.timestamp instanceof Date ? message.timestamp.getTime() : -1,
             timestampRef: message.timestamp,
             toolOutput: toolOutputIdentity(message),
+            attachments: message.attachments,
         };
         const replaced = this.entries.get(message.id);
         if (replaced !== undefined)
@@ -106,6 +107,8 @@ export class TranscriptRenderCache {
             return false;
         if (entry.toolOutput !== toolOutputIdentity(message))
             return false;
+        if (entry.attachments !== message.attachments)
+            return false;
         if (entry.turnKey !== turnRenderKey(message))
             return false;
         if (entry.timestampRef !== message.timestamp) {

package/dist/ui/views/app.d.ts

@@ -12,7 +12,6 @@ interface AppViewProps {
     messages: Message[];
     agentState: AgentState;
     inputState: InputState;
-    canYank?: boolean;
     sessionId: string;
     /** User-set session name (`/rename` or `--name`); shown as a left-side status badge. */
     sessionName?: string;
@@ -48,6 +47,8 @@ interface AppViewProps {
     /** Structured widget view for surfaces that need real terminal styling. */
     widgetView?: LayoutNode | null;
     compactWidget?: boolean;
+    /** Rows the transcript holds, when known: a compact widget follows them (see AppLayoutMetricsProps). */
+    transcriptRows?: number;
     isRecording?: boolean;
     recordingDevice?: string | null;
     audioLevel?: number;
@@ -79,6 +80,8 @@ interface AppViewProps {
      * Ink-rendered message list.
      */
     externalTranscript?: boolean;
+    /** Where a short conversation sits in ZTC's own frame (see buildMessageListView). */
+    transcriptAnchor?: 'top' | 'bottom';
     agentActive?: boolean;
 }
 interface AppLayoutMetricsProps {
@@ -95,10 +98,11 @@ interface AppLayoutMetricsProps {
     externalTranscript?: boolean;
     compactWidget?: boolean;
     widgetContentRows?: number;
+    transcriptRows?: number;
     agentActive?: boolean;
     statusLine?: StatusLineSettings;
 }
-export declare function getAppLayoutMetrics({ rows, cols, inputState, commands, completion, showHeader, showTodos, todoCount, widgetActive, queueTotal, externalTranscript, compactWidget, widgetContentRows, agentActive, statusLine, }: AppLayoutMetricsProps): {
+export declare function getAppLayoutMetrics({ rows, cols, inputState, commands, completion, showHeader, showTodos, todoCount, widgetActive, queueTotal, externalTranscript, compactWidget, widgetContentRows, transcriptRows, agentActive, statusLine, }: AppLayoutMetricsProps): {
     contentAreaY: number;
     contentAreaHeight: number;
     chromeHeight: number;
@@ -109,5 +113,5 @@ export declare function getAppLayoutMetrics({ rows, cols, inputState, commands,
     widgetHeight: number;
     transcriptHeight: number;
 };
-export declare function buildAppView({ messages, agentState, inputState, canYank, sessionId, sessionName, cols, rows, commands, completion, hasApiKey, version, contextLength, contextEstimated, contextStatus, provider, model, emulationId, inputMode, escapeHint, toast, spinnerLabel, spinnerFrame, lastEventAt, stallHintMs, debug, expandToolOutputs, showThinking, showTurnMetadata, renderer, showHeader, showMessages, isRecording, recordingDevice, audioLevel, partialTranscript, todos, showTodos, activeTask, taskStartedAt, mode, authEmail, authWorkspace, backgroundRunning, widgetContent, widgetView: providedWidgetView, queuePreview, queueTotal, queueSelectedIndex, externalTranscript, compactWidget, agentActive, statusLine, effort, unsupportedEffort, }: AppViewProps): LayoutNode;
+export declare function buildAppView({ messages, agentState, inputState, sessionId, sessionName, cols, rows, commands, completion, hasApiKey, version, contextLength, contextEstimated, contextStatus, provider, model, emulationId, inputMode, escapeHint, toast, spinnerLabel, spinnerFrame, lastEventAt, stallHintMs, debug, expandToolOutputs, showThinking, showTurnMetadata, renderer, showHeader, showMessages, isRecording, recordingDevice, audioLevel, partialTranscript, todos, showTodos, activeTask, taskStartedAt, mode, authEmail, authWorkspace, backgroundRunning, widgetContent, widgetView: providedWidgetView, queuePreview, queueTotal, queueSelectedIndex, externalTranscript, transcriptAnchor, compactWidget, transcriptRows, agentActive, statusLine, effort, unsupportedEffort, }: AppViewProps): LayoutNode;
 export {};