@kolisachint/hoocode-tui 0.5.68 → 0.5.71

package/dist/tui.js

@@ -284,6 +284,35 @@ export class TUI extends Container {
     previousViewportTop = 0; // Track previous viewport top for resize-aware cursor moves
     fullRedrawCount = 0;
     stopped = false;
+    /**
+     * The filler that keeps the app the size of the screen.
+     *
+     * ## Why the app is full-screen at all
+     *
+     * This renderer appends: a frame is the whole component tree flattened into
+     * a line buffer, written from wherever the cursor happens to be. On a fresh
+     * session that buffer is a dozen rows, so the banner sat halfway up a
+     * terminal with the prompt under it and forty rows of the user's shell
+     * history above — and the prompt walked down the screen as the conversation
+     * grew, only reaching the bottom row once the session was long enough to
+     * scroll. Two different layouts for the same app, and the one you meet first
+     * is the one that does not look like an app.
+     *
+     * ## What this does
+     *
+     * Before the frame is diffed, the root measures it and gives the leftover
+     * rows to one designated child. The buffer is therefore never shorter than
+     * the terminal, so the terminal's last row is always the buffer's last row:
+     * the header stays at the top, the prompt and the footer stay on the bottom,
+     * and everything between them is conversation. Nothing else changes — this
+     * is still the normal screen, so scrollback, selection and search all still
+     * work, and the session is still on screen after you quit.
+     *
+     * Set to `undefined` (no flex child) and the old append-only behaviour is
+     * exactly what you get back, which is what the tests that predate this and
+     * any embedder outside the app rely on.
+     */
+    flexSpacer;
     /**
      * The pinned viewport.
      *
@@ -362,6 +391,64 @@ export class TUI extends Container {
     setScrollStatusFormatter(formatter) {
         this.scrollStatusFormatter = formatter;
     }
+    /**
+     * 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.
+     */
+    setFlexSpacer(spacer) {
+        this.flexSpacer = spacer;
+    }
+    /**
+     * Give the flex child whatever the frame did not use, at `height` rows.
+     *
+     * Returns true when the height moved, meaning the caller has to flatten
+     * again — the measurement can only be made from a finished frame, so the
+     * 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 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.
+     */
+    fitFlexSpacer(lines, height, repaint = false) {
+        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));
+    }
     /**
      * The screen rows a pinned window shows, the last one being the indicator.
      *
@@ -373,9 +460,13 @@ export class TUI extends Container {
         return Math.max(1, this.terminal.rows - 1);
     }
     /** Rows available to scroll through — the live buffer while live, the
-     * measured one while pinned. */
+     * measured one while pinned. The filler is not transcript: counting it would
+     * let a session with nothing above the fold pin itself one row off the
+     * bottom and paint a screen of blanks. */
     transcriptLength() {
-        return this.scrollOffset === null ? this.previousLines.length : this.scrollTotalLines;
+        if (this.scrollOffset !== null)
+            return this.scrollTotalLines;
+        return this.previousLines.length - (this.flexSpacer?.currentHeight ?? 0);
     }
     /**
      * Move the view by `delta` rows; negative is towards the start.
@@ -1502,6 +1593,10 @@ export class TUI extends Container {
     renderScrollView() {
         const width = this.terminal.columns;
         const height = this.terminal.rows;
+        // No fill while pinned: the window is already the height of the screen,
+        // and blank rows in the buffer would be rows of the transcript the reader
+        // has to scroll past. The next live frame puts it back.
+        this.flexSpacer?.setHeight(0);
         let lines = this.render(width);
         // A patch computed while pinned describes rows nothing painted to the
         // normal screen, so the live path must never be handed it.
@@ -1591,6 +1686,15 @@ export class TUI extends Container {
         // Render all components to get new lines. The root render() reports what
         // it changed via lastPatch; consume it here (it is per-frame state).
         let newLines = this.render(width);
+        // The frame has to exist before its leftover rows can be counted, so the
+        // fill is settled by re-flattening rather than predicted. The second pass
+        // 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)) {
+            newLines = this.render(width);
+            this.lastPatch = "full";
+        }
         const patch = this.lastPatch;
         this.lastPatch = "full";
         // Composite overlays into the rendered lines (before differential compare)