@kolisachint/hoocode-tui 0.5.67 → 0.5.69

package/dist/tui.d.ts

@@ -1,6 +1,7 @@
 /**
  * Minimal TUI implementation with differential rendering
  */
+import type { FlexSpacer } from "./components/spacer.js";
 import type { Terminal } from "./terminal.js";
 /**
  * Component interface - all components must implement this
@@ -51,6 +52,34 @@ export declare function isFocusable(component: Component | null): component is C
  * TUI finds and strips this marker, then positions the hardware cursor there.
  */
 export declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
+/** What the scroll indicator is told about the pinned view. */
+export interface ScrollStatus {
+    /** 1-based transcript row at the top of the view. */
+    top: number;
+    /** 1-based transcript row at the bottom of the view. */
+    bottom: number;
+    /** Rows in the whole transcript. */
+    total: number;
+    /** Rows the view shows at once. */
+    viewHeight: number;
+    atTop: boolean;
+    /** True only when the very last row is in view — the point where the pin lets go. */
+    atBottom: boolean;
+    /** Columns the indicator may fill. */
+    width: number;
+    /** Present while a search is running; the indicator becomes its query line. */
+    search?: ScrollSearchStatus;
+}
+export interface ScrollSearchStatus {
+    query: string;
+    /** Rows containing a match. */
+    count: number;
+    /** 1-based position among the matches, or 0 when there are none. */
+    index: number;
+    /** True while the query is still being typed. */
+    typing: boolean;
+}
+export type ScrollStatusFormatter = (status: ScrollStatus) => string;
 /**
  * Anchor position for overlays
  */
@@ -125,6 +154,60 @@ export declare class Container implements Component {
     removeChild(component: Component): void;
     clear(): void;
     invalidate(): void;
+    /**
+     * Where each direct child's output starts, in rows, from the last render.
+     *
+     * Read off the memo rather than recomputed, so asking is a walk over the
+     * children's cached line arrays and never a re-render. Undefined before the
+     * first render, or at a different width than the caller has in mind — both
+     * cases mean "no answer", not "zero".
+     *
+     * This is what lets something outside the tree point at a row inside it: a
+     * component's offset within its container, plus that container's offset at
+     * the root, is its absolute row in the buffer the viewport windows over.
+     */
+    childRowOffsets(width: number): number[] | undefined;
+    render(width: number): string[];
+}
+/**
+ * A child that can be taken off screen without disturbing the diff.
+ *
+ * Hiding a component naively — returning `[]` from its render — is one of the
+ * more expensive things you can do to this renderer. `Container.render` and the
+ * root's flat cache both decide "did this subtree change" by **array identity**,
+ * so a fresh `[]` every frame reads as a change every frame: the memo is
+ * dropped, the buffer is re-flattened, and a dirty range is reported for a
+ * component that is not even drawn. One frozen array, returned every time,
+ * makes a hidden slot free instead.
+ *
+ * The child is not rendered at all while hidden, which is the other half of the
+ * saving — a hidden footer costs nothing to keep hidden. That means a child
+ * whose `render` advances an animation or maintains a cache will be paused, not
+ * merely invisible; it catches up when shown again. Chrome (footers, panels,
+ * status rows) is fine with that. A spinner is not, so do not wrap one.
+ */
+export declare class Slot implements Component {
+    private component;
+    /** Shared across every hidden slot: identity is all the caches compare. */
+    private static readonly EMPTY;
+    private hidden;
+    constructor(component: Component);
+    /** Whoever is in the slot right now. */
+    get child(): Component;
+    /**
+     * Swap the occupant, keeping the slot itself in place.
+     *
+     * An extension replacing the footer used to remove one root child and append
+     * another, which both moved the footer to the end of the tree — behind the
+     * widgets meant to sit below it — and handed the root's per-child cache a
+     * changed child list every time. The slot is the stable root child; only what
+     * is inside it changes.
+     */
+    setChild(component: Component): boolean;
+    get visible(): boolean;
+    /** Returns whether this changed anything, so callers can skip a render. */
+    setVisible(visible: boolean): boolean;
+    invalidate(): void;
     render(width: number): string[];
 }
 /**
@@ -169,10 +252,201 @@ export declare class TUI extends Container {
     private previousViewportTop;
     private fullRedrawCount;
     private stopped;
+    /**
+     * 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.
+     */
+    private flexSpacer?;
+    /**
+     * The pinned viewport.
+     *
+     * ## What is wrong with letting the terminal do it
+     *
+     * This renderer keeps the entire transcript in its line buffer and writes it
+     * to the normal screen, so "scrolling" has always meant the terminal's own
+     * scrollback. That works exactly as long as the app does not repaint — and
+     * this one repaints the whole buffer whenever a line *above* the viewport
+     * changes, because a positional diff cannot address a row that has scrolled
+     * out of reach. The repaint is `\x1b[2J\x1b[H\x1b[3J` followed by the
+     * transcript again, and the `\x1b[3J` throws away the scrollback the reader
+     * was sitting in. From the reader's side the screen simply jumps to the
+     * bottom, for no reason they can see, at a moment they did not choose.
+     *
+     * ## What this does instead
+     *
+     * `scrollOffset` is the transcript row drawn at the top of the screen, and
+     * `null` means "follow the tail", which is the normal live behaviour and the
+     * path everything else in this file was written for. The moment it is a
+     * number the TUI switches to the alternate screen and paints a window of the
+     * buffer itself: a fixed grid, addressed row by row, with no scrollback for
+     * anything to fight over. New output still arrives and still lands in the
+     * buffer — it just does not move the window, which is the whole point. The
+     * indicator on the last row says how far down the transcript the window is,
+     * because a view that cannot move on its own needs to say where it stopped.
+     *
+     * Going back to live leaves the alternate screen, which restores the normal
+     * screen *and its scrollback* exactly as they were, and the next frame is an
+     * ordinary differential one that writes only what arrived while the reader
+     * was away — see `scrollToLive` for what has to be true for that to be safe.
+     * Not a clear-and-replay: on a long session that is a visible flash, a burst
+     * of output, and the loss of the scrollback that had just been handed back.
+     */
+    private scrollOffset;
+    /** Transcript length measured by the last pinned paint; what clamping uses. */
+    private scrollTotalLines;
+    private scrollStatusFormatter;
+    /** The running search: its query, the rows it matched, and where in them. */
+    private scrollSearch;
+    /**
+     * Whether the view may pin right now.
+     *
+     * The wheel is answered wherever it is turned, including with a picker on
+     * screen — and a picker that lost its arrow keys to a pinned view it did not
+     * know about would be far worse than a wheel that did nothing. The app sets
+     * this because only the app knows which of its surfaces is asking a question.
+     * Unset means always.
+     */
+    canPinScroll?: () => boolean;
     private focusOrderCounter;
     private overlayStack;
     constructor(terminal: Terminal, showHardwareCursor?: boolean);
     get fullRedraws(): number;
+    /** True while the view is pinned rather than following the tail. */
+    get scrollPinned(): boolean;
+    /** Where the pinned window sits, or null while live. */
+    getScrollPosition(): {
+        top: number;
+        total: number;
+        viewHeight: number;
+    } | null;
+    /** Let the app paint the indicator in its own theme. */
+    setScrollStatusFormatter(formatter: ScrollStatusFormatter): void;
+    /**
+     * 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: FlexSpacer | undefined): void;
+    /**
+     * 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.
+     */
+    private fitFlexSpacer;
+    /**
+     * The screen rows a pinned window shows, the last one being the indicator.
+     *
+     * The indicator is not optional: a pinned view looks exactly like a live one
+     * that has gone quiet, and a reader who cannot tell the two apart will wait
+     * for output that is arriving perfectly well just out of sight.
+     */
+    private scrollViewHeight;
+    /** Rows available to scroll through — the live buffer while live, the
+     * 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. */
+    private transcriptLength;
+    /**
+     * Move the view by `delta` rows; negative is towards the start.
+     *
+     * Returns whether anything moved, so a caller can let the key fall through
+     * to whatever else wants it when there is nothing to scroll.
+     */
+    scrollByLines(delta: number): boolean;
+    /**
+     * Move by pages, keeping two rows of overlap.
+     *
+     * A page that moves a full screen leaves nothing in common between before
+     * and after, and the reader has to find their place again on every press.
+     * The two kept rows are what makes the jump readable.
+     */
+    scrollByPages(delta: number): boolean;
+    /** Pin the view to the very start of the transcript. */
+    scrollToTop(): boolean;
+    /** Release the pin and follow the tail again. */
+    scrollToLive(): boolean;
+    /**
+     * Find rows containing `query`, and pin the view to the nearest one above.
+     *
+     * Searching *backwards* first is the `ctrl+r` convention and it is the right
+     * one here: what you are looking for in a session is nearly always behind
+     * you, and the most recent occurrence is nearly always the one you meant.
+     *
+     * Matching is over the visible text, so it finds what the screen shows
+     * rather than the escape sequences underneath it — a query containing a
+     * colour code is not something anyone ever means.
+     *
+     * Returns how many rows matched.
+     */
+    setScrollSearch(query: string, options?: {
+        typing?: boolean;
+    }): number;
+    /**
+     * Step to the next match, `-1` being further back through the session.
+     *
+     * Wraps, because a search that stops dead at the last match makes you
+     * retype it to get back to the first.
+     */
+    scrollSearchStep(direction: 1 | -1): boolean;
+    /** Stop typing the query but keep the matches, so n/N can step them. */
+    commitScrollSearch(): void;
+    /** Drop the search, leaving the view where it is. */
+    clearScrollSearch(): void;
+    get scrollSearchActive(): boolean;
+    /** The query being searched for, or "" when there is no search. */
+    get scrollSearchQuery(): string;
+    private scrollSearchStatus;
+    /**
+     * Rows whose visible text contains `query`, case-insensitively.
+     *
+     * One pass over the buffer, run when the query changes rather than per
+     * frame. The results are re-measured if the transcript has grown since —
+     * rare while someone is reading, and wrong in a way people notice if skipped.
+     */
+    private findScrollMatches;
+    /** Re-run the search if the buffer grew under it. */
+    private refreshScrollSearch;
+    /**
+     * Mark the query where it appears in a row about to be painted.
+     *
+     * Done at paint time, over the handful of rows on screen, rather than stored
+     * per match — highlighting the whole buffer to show a screenful would be the
+     * same work multiplied by the session's length.
+     *
+     * The row is sliced by display column so the styling already in it survives:
+     * a match inside a coloured span keeps its colour and gains the marker.
+     */
+    private highlightScrollMatches;
+    private setScrollOffset;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
     getClearOnShrink(): boolean;
@@ -182,6 +456,28 @@ export declare class TUI extends Container {
      * When false, empty rows remain (reduces redraws on slower terminals).
      */
     setClearOnShrink(enabled: boolean): void;
+    /** The component keystrokes are currently going to. */
+    get focused(): Component | null;
+    /**
+     * The root's own child offsets, which the flat cache already tracks.
+     *
+     * The base implementation reads `Container.renderMemo`, which the root does
+     * not keep — it has `flatCache` instead, holding exactly this. Falling
+     * through to the base would quietly return undefined forever.
+     */
+    childRowOffsets(width: number): number[] | undefined;
+    /**
+     * Pin the view so `row` is on screen, without demanding it be at the top.
+     *
+     * A jump that always parks its target on the first row throws away whatever
+     * led up to it, and what led up to a message is most of what makes it
+     * readable. A row already comfortably in view is left where it is, so
+     * stepping through nearby landmarks does not make the screen lurch for each
+     * one.
+     */
+    scrollToRow(row: number, options?: {
+        context?: number;
+    }): boolean;
     setFocus(component: Component | null): void;
     /**
      * Show an overlay component with configurable positioning and sizing.
@@ -205,6 +501,24 @@ export declare class TUI extends Container {
     requestRender(force?: boolean): void;
     private scheduleRender;
     private handleInput;
+    /**
+     * Act on every mouse report in `data` and return what is left of it.
+     *
+     * Returns null when the chunk was nothing but reports. Reports arrive
+     * coalesced — a flick of the wheel delivers a run of them in one read, and a
+     * keystroke pressed during the flick rides along behind — so they are peeled
+     * off one at a time instead of the chunk being classified as a whole.
+     */
+    private consumeMouseReports;
+    /**
+     * What the mouse does.
+     *
+     * 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.
+     */
+    private handleMouseEvent;
     /** Run a requested render now, bypassing the coalescing delay. Used for
      * input-driven frames where echo latency matters more than batching. */
     private expediteRender;
@@ -256,6 +570,27 @@ export declare class TUI extends Container {
      * or the child list changed.
      */
     render(width: number): string[];
+    /**
+     * Paint the pinned window onto the alternate screen.
+     *
+     * Deliberately not differential. The alternate screen is `rows` tall and
+     * nothing else writes to it, so a whole frame is at most a screenful of
+     * cells inside one synchronized-output pair — cheaper to emit than the
+     * bookkeeping a diff would need, and with nothing to get out of step with.
+     * The differential renderer's state is left exactly as the last live frame
+     * left it, because `scrollToLive` throws it away rather than resuming from it.
+     */
+    private renderScrollView;
+    /**
+     * 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.
+     */
+    private emitScrollLine;
     private doRender;
     /**
      * Build the escape sequence that parks the hardware cursor for this frame.