@kolisachint/hoocode-tui 0.5.72 → 0.5.74

package/dist/tui.js

@@ -8,8 +8,8 @@ import { performance } from "node:perf_hooks";
 import { stripVTControlCharacters } from "node:util";
 import { isKeyRelease, matchesKey } from "./keys.js";
 import { mouseSequenceLength, parseMouseEvent } from "./mouse.js";
-import { deleteKittyImage, getCapabilities, isImageLine, setCellDimensions } from "./terminal-image.js";
-import { extractSegments, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, truncateToWidth, visibleWidth, } from "./utils.js";
+import { allocateImageId, deleteKittyImage, getCapabilities, isImageLine, setCellDimensions, } from "./terminal-image.js";
+import { extractSegments, hyperlinkAt, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, truncateToWidth, visibleWidth, } from "./utils.js";
 const KITTY_SEQUENCE_PREFIX = "\x1b_G";
 function extractKittyImageIds(line) {
     const sequenceStart = line.indexOf(KITTY_SEQUENCE_PREFIX);
@@ -31,6 +31,39 @@ function extractKittyImageIds(line) {
     }
     return [];
 }
+/**
+ * Transmit the same image under a different id.
+ *
+ * Only the first chunk of a chunked transmission carries the parameter list,
+ * and that is the one `extractKittyImageIds` reads, so rewriting it is enough
+ * to make the whole sequence a second, independently deletable copy.
+ */
+function retagKittyImageId(line, id) {
+    const sequenceStart = line.indexOf(KITTY_SEQUENCE_PREFIX);
+    if (sequenceStart === -1)
+        return null;
+    const paramsStart = sequenceStart + KITTY_SEQUENCE_PREFIX.length;
+    const paramsEnd = line.indexOf(";", paramsStart);
+    if (paramsEnd === -1)
+        return null;
+    const params = line.slice(paramsStart, paramsEnd);
+    const retagged = params.replace(/(^|,)i=\d+/, `$1i=${id}`);
+    if (retagged === params)
+        return null;
+    return line.slice(0, paramsStart) + retagged + line.slice(paramsEnd);
+}
+/**
+ * How far above its own row an image line's picture reaches.
+ *
+ * `Image` renders an n-row picture as n-1 blank lines and one line that moves
+ * the cursor back up and draws, so the leading `CSI <n> A` is the whole block's
+ * height minus one — and the top edge of the picture is that many rows above
+ * wherever the line itself is painted.
+ */
+function imageRowOffset(line) {
+    const match = /^\x1b\[(\d+)A/.exec(line);
+    return match ? Number(match[1]) : 0;
+}
 /** Type guard to check if a component implements Focusable */
 export function isFocusable(component) {
     return component !== null && "focused" in component;
@@ -265,6 +298,20 @@ export class TUI extends Container {
      * per-frame full-buffer scan (collectKittyImageIds) is skipped entirely —
      * the common case for a pure-text session. */
     sawImageLine = false;
+    /**
+     * Live kitty image id -> the id the pinned window transmits its own copy
+     * under, and the copies currently placed on the alternate screen.
+     *
+     * The pinned window repaints whole, so a placement from the previous scroll
+     * position has to be deleted or it hangs over the new one. Deleting a kitty
+     * image deletes *every* placement of it, though, including the one on the
+     * normal screen — which the differential frame on the way back out has no
+     * reason to repaint, so the picture would simply be gone. The window
+     * therefore transmits a second copy under an id of its own and only ever
+     * deletes that one.
+     */
+    scrollImageIds = new Map();
+    scrollPlacedImages = new Set();
     static EMPTY_KITTY_IDS = new Set();
     previousWidth = 0;
     previousHeight = 0;
@@ -313,6 +360,18 @@ export class TUI extends Container {
      * any embedder outside the app rely on.
      */
     flexSpacer;
+    /** Where the left button went down, for telling a click from a drag. */
+    pressedCell;
+    /** What the pinned window painted last, so a click on it can be placed. */
+    scrollViewLines;
+    /**
+     * Open the URL behind a clicked hyperlink. Unset, clicks do nothing.
+     *
+     * The TUI resolves *which* link was clicked and deliberately stops there:
+     * opening a URL is spawning a process, which is the embedder's policy to
+     * make, not a rendering library's.
+     */
+    onHyperlink;
     /**
      * The pinned viewport.
      *
@@ -394,9 +453,10 @@ export class TUI extends Container {
     /**
      * Nominate the child that absorbs the leftover rows (see `flexSpacer`).
      *
-     * It must already be a child of the root, and it should sit between the part
-     * of the tree that flows from the top and the chrome that hangs off the
-     * bottom — everything after it is what gets pinned to the foot of the screen.
+     * It must already be a child of the root, and it belongs at the *top* of the
+     * tree: everything after it is pushed to the foot of the screen, so the app
+     * reads bottom-up the way a terminal does — the newest row next to the
+     * prompt, and whatever room is left over above the first thing drawn.
      */
     setFlexSpacer(spacer) {
         this.flexSpacer = spacer;
@@ -409,45 +469,26 @@ export class TUI extends Container {
      * frame that answers it is always the second one. Both passes are cheap
      * after the first: every other child returns its memoized array untouched.
      *
-     * Two cases, and the second one is the one with a bug behind it.
-     *
-     * **The frame fits on the screen.** Fill it out to the screen's height and
-     * the frame starts on the first row, which is the whole point of the fill.
+     * The whole rule is one line, and it is the same one in both directions:
+     * the buffer is never shorter than the screen. A session that fits gets the
+     * difference as blank rows, which — with the spacer at the top of the tree —
+     * land *above* the first thing drawn, so the transcript always ends against
+     * the prompt. A session too long to fit gets nothing, because the terminal's
+     * own scroll is already holding the last row on the last row.
      *
-     * **The frame is taller than the screen.** Then the fill is not what puts
-     * the prompt on the floor — the terminal's own scroll is, and the buffer's
-     * last row *is* the screen's last row. So a buffer that gets *shorter*
-     * takes the prompt up the screen with it: the renderer clears the rows that
-     * came off the end and there is nothing it can do to scroll the transcript
-     * back down into them, because those rows are in the terminal's scrollback
-     * and only the terminal can move them. That is a picker closing, a
-     * notification fading, a task ledger emptying — the prompt stranded
-     * mid-screen with a band of blank rows under it, and it stays stranded
-     * until enough output arrives to push it back down.
-     *
-     * So the fill takes what the shrinking content gave up, which keeps the
-     * buffer the length it already was and the last row where it already is.
-     * The blank band ends up *above* the chrome instead of below it, where it
-     * reads as room rather than as a layout that came apart, and the next
-     * output to arrive lands in it rather than scrolling the screen. Capped at
-     * a screenful: a fill longer than the screen is rows nobody can see, and it
-     * is given up altogether on the frames that repaint the whole screen anyway.
+     * It deliberately does not bank rows a shrinking frame gave up. That kept
+     * the prompt on the floor, but it paid for it with a band of blank rows
+     * between the conversation and the prompt — a screenful of it when a view
+     * dial folded the transcript — which is the thing the fill exists to avoid.
+     * A buffer that has to move back over the screen is repainted instead; see
+     * the window-repaint branch in `doRender`.
      */
-    fitFlexSpacer(lines, height, repaint = false) {
+    fitFlexSpacer(lines, height) {
         const spacer = this.flexSpacer;
         if (!spacer)
             return false;
         const content = lines.length - spacer.currentHeight;
-        if (content < height)
-            return spacer.setHeight(height - content);
-        // A frame that is about to be repainted from the top of a cleared screen
-        // has no floor to hold: the resize already threw the old screen away, and
-        // holding its length would only bank a band of blank rows into the middle
-        // of the new one.
-        if (repaint)
-            return spacer.setHeight(0);
-        const held = Math.min(this.previousLines.length - content, height);
-        return spacer.setHeight(Math.max(0, held));
+        return spacer.setHeight(Math.max(0, height - content));
     }
     /**
      * The screen rows a pinned window shows, the last one being the indicator.
@@ -523,6 +564,7 @@ export class TUI extends Container {
             return false;
         this.scrollOffset = null;
         this.scrollSearch = null;
+        this.releaseScrollImages();
         this.terminal.setAlternateScreen(false);
         // `?1049l` restores the normal screen, its scrollback and the cursor
         // exactly as they were at `?1049h`, and the snapshot taken on the way in
@@ -534,6 +576,7 @@ export class TUI extends Container {
         // the wrong ones.
         this.flatCache = undefined;
         this.lastCursorPos = undefined;
+        this.scrollViewLines = undefined;
         this.requestRender();
         return true;
     }
@@ -946,6 +989,7 @@ export class TUI extends Container {
         // the cursor relative to content that lives on the normal screen.
         if (this.scrollOffset !== null) {
             this.scrollOffset = null;
+            this.releaseScrollImages();
             this.terminal.setAlternateScreen(false);
         }
         this.stopped = true;
@@ -1113,12 +1157,20 @@ export class TUI extends Container {
         return out.length > 0 ? out : null;
     }
     /**
-     * What the mouse does.
+     * What the mouse does: the wheel scrolls, and a click opens a link.
+     *
+     * The click is here because capturing the mouse took it away. A terminal
+     * resolves a click on an OSC 8 hyperlink itself right up until an app turns
+     * reporting on, at which point the report comes to the app and the link stops
+     * working — so the app owes the user an answer. It is the same answer the
+     * terminal would have given: the URL under the pointer, handed to whoever set
+     * `onHyperlink`. Anything else is still swallowed, because a click that fell
+     * through to the focused component would arrive as raw report text typed into
+     * whatever field has focus.
      *
-     * Only the wheel is acted on. Clicks are swallowed rather than handled:
-     * reporting is on for the wheel's sake, and a click that fell through to the
-     * focused component would arrive as the raw report text in whatever field
-     * has focus.
+     * Press and release both have to land on the same cell. A drag that happens
+     * to end on a link is someone selecting text, not someone asking for a
+     * browser.
      */
     handleMouseEvent(event) {
         if (event.kind === "wheelUp") {
@@ -1127,7 +1179,44 @@ export class TUI extends Container {
         }
         if (event.kind === "wheelDown") {
             this.scrollByLines(WHEEL_LINES);
+            return;
+        }
+        if (event.kind === "press") {
+            this.pressedCell = event.button === 0 ? { row: event.row, column: event.column } : undefined;
+            return;
         }
+        if (event.kind !== "release")
+            return;
+        const pressed = this.pressedCell;
+        this.pressedCell = undefined;
+        if (!this.onHyperlink || !pressed)
+            return;
+        if (pressed.row !== event.row || pressed.column !== event.column)
+            return;
+        const url = this.hyperlinkAtScreenCell(event.row, event.column);
+        if (url)
+            this.onHyperlink(url);
+    }
+    /**
+     * The link on the screen cell a mouse report names, if there is one.
+     *
+     * Screen rows are turned into line-buffer rows through the window the last
+     * frame painted — `scrollOffset` while pinned, `previousViewportTop` live —
+     * so this answers from exactly what the terminal is showing. A live buffer
+     * shorter than the screen is declined rather than guessed at: nothing pins
+     * where such a frame starts on screen, and a wrong row is a click on the
+     * wrong link.
+     */
+    hyperlinkAtScreenCell(row, column) {
+        const pinned = this.scrollOffset !== null;
+        const lines = pinned ? this.scrollViewLines : this.previousLines;
+        if (!lines || lines.length === 0)
+            return undefined;
+        if (!pinned && lines.length < this.terminal.rows)
+            return undefined;
+        const top = pinned ? (this.scrollOffset ?? 0) : this.previousViewportTop;
+        const line = lines[top + row - 1];
+        return line === undefined ? undefined : hyperlinkAt(line, column - 1);
     }
     /** Run a requested render now, bypassing the coalescing delay. Used for
      * input-driven frames where echo latency matters more than batching. */
@@ -1612,18 +1701,24 @@ export class TUI extends Container {
         // only where it is set.
         const top = Math.min(Math.max(0, this.scrollOffset ?? 0), maxOffset);
         this.scrollOffset = top;
+        // Kept so a click on the pinned window can be placed against what it is
+        // showing. Same array the render returned, so it costs a reference.
+        this.scrollViewLines = lines;
         let buffer = "\x1b[?2026h"; // Begin synchronized output
         buffer += HIDE_CURSOR;
         // Autowrap off for the paint: a full-width row would otherwise wrap into
         // the row below it and shift the rest of the window down by one.
         buffer += "\x1b[?7l";
+        // A kitty placement is not text and `CSI 2 K` does not touch it, so last
+        // frame's pictures come off before this frame's rows go down.
+        buffer += this.clearScrollImages();
         this.refreshScrollSearch(lines.length);
         const query = this.scrollSearch?.query ?? "";
         for (let row = 0; row < viewHeight; row++) {
             buffer += `\x1b[${row + 1};1H\x1b[2K`;
             const line = lines[top + row];
             if (line !== undefined)
-                buffer += this.emitScrollLine(line, query);
+                buffer += this.emitScrollLine(line, row, query);
         }
         buffer += `\x1b[${height};1H\x1b[2K`;
         buffer += this.scrollStatusFormatter({
@@ -1645,24 +1740,70 @@ export class TUI extends Container {
         // its full-redraw branch — which is exactly right, because the normal
         // screen `?1049l` restored was drawn at the old size.
     }
+    /** Take the pinned window's own copies of the images off the screen. */
+    clearScrollImages() {
+        if (this.scrollPlacedImages.size === 0)
+            return "";
+        const buffer = this.deleteKittyImages(this.scrollPlacedImages);
+        this.scrollPlacedImages.clear();
+        return buffer;
+    }
+    /**
+     * On the way off the alternate screen: free the copies and the ids with
+     * them, while there is still a screen to write to. The live ids are never
+     * touched, so the normal screen comes back with its pictures intact.
+     */
+    releaseScrollImages() {
+        const buffer = this.clearScrollImages();
+        if (buffer)
+            this.terminal.write(buffer);
+        this.scrollImageIds.clear();
+    }
     /**
      * One transcript row, ready for the pinned window.
      *
-     * Images are named rather than drawn. A kitty or iTerm image is placed by
-     * the cursor and sized in pixels, so the same escape replayed at a different
-     * screen row lands somewhere the window did not ask for and survives the
-     * frame that was supposed to replace it — a smear across the view that no
-     * later repaint can clear.
+     * `row` is where in the window the line lands, which decides whether an image
+     * on it can be drawn at all: a picture reaches `imageRowOffset` rows *above*
+     * its line, and a terminal will not draw above the first row — it clamps,
+     * putting the picture over rows that are not its own and leaving it there.
+     * A block hanging off the top of the window is named instead of drawn, so
+     * scrolling one into view shows a placeholder until all of it is on screen.
      */
-    emitScrollLine(line, query = "") {
+    emitScrollLine(line, row, query = "") {
         if (isImageLine(line))
-            return "\x1b[2m[image]\x1b[0m";
+            return this.emitScrollImage(line, row);
         const marker = line.indexOf(CURSOR_MARKER);
         let text = marker === -1 ? line : line.slice(0, marker) + line.slice(marker + CURSOR_MARKER.length);
         if (query.length > 0)
             text = this.highlightScrollMatches(text, query);
         return normalizeTerminalOutput(text) + TUI.SEGMENT_RESET;
     }
+    static IMAGE_PLACEHOLDER = "\x1b[2m[image]\x1b[0m";
+    /** An image line in the pinned window: drawn if all of it fits, named if not. */
+    emitScrollImage(line, row) {
+        if (imageRowOffset(line) > row)
+            return TUI.IMAGE_PLACEHOLDER;
+        // iTerm2 paints into the cells it covers, so the next frame's `CSI 2 K`
+        // clears it like any other row and there is nothing to track.
+        if (!line.includes(KITTY_SEQUENCE_PREFIX))
+            return line;
+        const [liveId] = extractKittyImageIds(line);
+        // A kitty placement with no id can never be deleted on its own, and the
+        // only alternative deletes the live screen's pictures with it.
+        if (liveId === undefined)
+            return TUI.IMAGE_PLACEHOLDER;
+        let pinnedId = this.scrollImageIds.get(liveId);
+        if (pinnedId === undefined) {
+            pinnedId = allocateImageId();
+            this.scrollImageIds.set(liveId, pinnedId);
+        }
+        const retagged = retagKittyImageId(line, pinnedId);
+        if (retagged === null)
+            return TUI.IMAGE_PLACEHOLDER;
+        this.scrollPlacedImages.add(pinnedId);
+        this.sawImageLine = true;
+        return retagged;
+    }
     doRender() {
         if (this.stopped)
             return;
@@ -1691,7 +1832,7 @@ export class TUI extends Container {
         // invalidates the first's patch — it describes the buffer from before the
         // splice — so fall back to the full scan, which is always correct and only
         // runs on frames where the content height actually changed.
-        if (this.fitFlexSpacer(newLines, height, widthChanged || heightChanged)) {
+        if (this.fitFlexSpacer(newLines, height)) {
             newLines = this.render(width);
             this.lastPatch = "full";
         }
@@ -1840,6 +1981,57 @@ export class TUI extends Container {
             lastChanged = this.expandLastChangedForKittyImages(firstChanged, lastChanged);
         }
         const appendStart = appendedLines && firstChanged === prevLineCount && firstChanged > 0;
+        // The window has to move *back* over the buffer.
+        //
+        // On a session long enough to have scrolled, the terminal's own scroll is
+        // what holds the buffer's last row on the screen's last row, and the screen
+        // is the buffer's last `height` rows. Shrink the buffer — a picker closing,
+        // a notification fading, a view dial folding a run of tool calls — and that
+        // window slides back: the same last row, and rows the reader has not seen
+        // since they scrolled past arriving at the top. Nothing can scroll a
+        // terminal's own content *down* to bring them in, so the append-only path
+        // cannot express this frame at all: it clears the rows that came off the end
+        // and strands the prompt mid-screen with blanks under it.
+        //
+        // So the visible window is painted in place — one screenful, absolutely
+        // addressed, which the app may do here precisely because a buffer taller
+        // than the screen owns every row of it. It costs a screen of writes and no
+        // clear, where the honest alternative is `\x1b[3J` and the whole transcript.
+        // Only trees with a flex spacer take this path; an embedder without one
+        // keeps the append-only frame it has always had.
+        const windowTop = Math.max(0, newLines.length - height);
+        if (this.flexSpacer && newLines.length < prevLineCount && windowTop < prevViewportTop) {
+            // Two frames this cannot draw: a buffer that no longer fills the screen
+            // (the rows below the window are not ours to leave stale) and a buffer
+            // carrying images, which are placed against the screen and smear when the
+            // rows under them move. Both are the case a full repaint is for.
+            if (newLines.length < height || this.sawImageLine) {
+                logRedraw(`window moved back (${prevViewportTop} -> ${windowTop})`);
+                fullRender(true);
+                return;
+            }
+            let buffer = "\x1b[?2026h";
+            // A row painted to the last column would wrap, and the bottom row would
+            // wrap into a scroll — the one thing this frame must not do.
+            buffer += "\x1b[?7l";
+            for (let row = 0; row < height; row++) {
+                buffer += `\x1b[${row + 1};1H\x1b[2K`;
+                buffer += this.emitLine(newLines[windowTop + row] ?? "");
+            }
+            buffer += "\x1b[?7h";
+            this.cursorRow = newLines.length - 1;
+            this.hardwareCursorRow = newLines.length - 1;
+            buffer += this.buildHardwareCursorMove(cursorPos, newLines.length);
+            buffer += "\x1b[?2026l";
+            this.terminal.write(buffer);
+            this.previousLines = newLines;
+            this.previousKittyImageIds = this.collectKittyImageIds(newLines);
+            this.previousWidth = width;
+            this.previousHeight = height;
+            this.previousViewportTop = windowTop;
+            this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
+            return;
+        }
         // No changes - but still need to update hardware cursor position if it moved
         if (firstChanged === -1) {
             this.positionHardwareCursor(cursorPos, newLines.length);