@cruxy/cli 1.3.0 → 1.4.0

package/dist/tui/renderer.js

@@ -8,7 +8,8 @@ import { createFrameClock, spinnerGlyph, } from "../render/motion.js";
 import { planChecklist } from "../render/plan-view.js";
 import { testResultLines } from "../render/test-view.js";
 import { ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, phaseIdentity, } from "../render/state.js";
-import { budgetColumns, bodyRows, composeScreen, droppedForWidth, fitOverlay, overlayRows, stackPanels, CLOSABLE_PANELS, } from "./layout.js";
+import { budgetColumns, bodyRows, composeScreen, droppedForWidth, fitOverlay, overlayRows, scrollNotice, scrollWindow, stackPanels, CLOSABLE_PANELS, } from "./layout.js";
+import { CONVERSATION_VIEW, cycleView, navLines, } from "./views.js";
 import { contextPanelLines, gitPanelLines, headerModel, mainWelcome, modelPanelLines, railBlocks, sidebarLines, toolsPanelLines, } from "./panels.js";
 /**
  * The full-viewport renderer (P1) — the fourth {@link StreamRenderer}, and the
@@ -35,8 +36,21 @@ import { contextPanelLines, gitPanelLines, headerModel, mainWelcome, modelPanelL
  */
 /** Coalescing window for repaints (~30fps). */
 export const PAINT_INTERVAL_MS = 33;
+/**
+ * How often a selected view that reports itself {@link ViewSource.live} gets
+ * repainted with no other event to prompt it (P7 track 5).
+ *
+ * 2fps, not 30: this exists so a background job's log tail advances while the
+ * foreground sits idle at the prompt, and a log line arriving half a second
+ * late is imperceptible where a full-screen redraw thirty times a second for
+ * the duration of a long job is not free. The pulse only runs while such a view
+ * is the one on screen.
+ */
+export const VIEW_PULSE_MS = 500;
 /** Logical lines of scrollback kept in memory. Older lines roll off. */
 export const SCROLLBACK_LINES = 1_000;
+/** Lines a Page Up/Down keeps in common across the jump, so context survives. */
+export const SCROLL_PAGE_OVERLAP = 2;
 export class TuiRenderer {
     caps;
     theme;
@@ -63,8 +77,18 @@ export class TuiRenderer {
     overlay = null;
     /** Panels the user has open. `main` is a column, not a panel, and always paints. */
     open = new Set(CLOSABLE_PANELS);
-    /** Per-panel rail content, filled in by the P4 tracks as each lands. */
-    railState = {};
+    /**
+     * Display lines the main column is scrolled back from the live tail (P7
+     * track 1). `0` is the home position and the default, and at `0` this
+     * renderer composes exactly what it composed before scrolling existed.
+     */
+    scrollOffset = 0;
+    /** Registered main-pane views (P7 track 2); conversation is not among them. */
+    views = [];
+    /** Which view owns the main column. Always a real id — see {@link setView}. */
+    selectedView = CONVERSATION_VIEW;
+    /** Whether the sidebar nav holds the keyboard rather than the input line. */
+    sidebarFocused = false;
     /** Working-tree state for the git panel (P4 track 2); absent → panel unwired. */
     git;
     /** Context-budget reading for the context panel (P4 track 3); absent → unwired. */
@@ -88,6 +112,8 @@ export class TuiRenderer {
     unsubscribeFrame = null;
     unsubscribeResize = null;
     paintTimer = null;
+    /** The self-changing-view pulse (P7 track 5); null when nothing needs one. */
+    viewPulseTimer = null;
     lastPaintAt = 0;
     dirty = false;
     closed = false;
@@ -95,7 +121,15 @@ export class TuiRenderer {
     headerRight = "";
     /** Provider name for the composed header (P4 track 4). */
     provider = "";
-    /** Saved sessions shown in the sidebar (P2), and which one is running. */
+    /**
+     * Saved sessions shown in the sidebar (P2), and which one is running.
+     *
+     * Populated only by {@link setSessions}, never at construction. The running
+     * session has to be listed, and its meta line does not exist until the
+     * session log is open — which happens after the renderer is built. A
+     * constructor argument could therefore only ever carry the list from BEFORE
+     * this run, i.e. a sidebar missing the very session the user is in.
+     */
     sessions = [];
     activeSessionId;
     constructor(caps, out, opts = {}) {
@@ -105,13 +139,11 @@ export class TuiRenderer {
         this.highlighter = createStreamHighlighter(this.theme);
         this.print = this.newPrinter();
         this.headerRight = opts.headerRight ?? "";
-        this.sessions = opts.sessions ?? [];
-        this.activeSessionId = opts.activeSessionId;
         this.git = opts.git;
         this.provider = opts.provider ?? "";
         this.initialModel = opts.model;
         this.tools = opts.tools;
-        this.buffer = mainWelcome(this.theme, opts.hint ?? "/help for commands · /exit to quit");
+        this.buffer = mainWelcome(this.theme, "/help for commands · /exit to quit");
         this.frame = createFrame((text) => this.out.write(text), caps);
         // The single shared clock (U.10): an inert clock under reduced motion, so
         // the spinner is drawn once statically and no timer is ever scheduled.
@@ -208,13 +240,150 @@ export class TuiRenderer {
         });
         return tools;
     }
-    /** Replace one rail panel's content (P4). Absent state renders as "not wired yet". */
-    setRailPanel(id, lines) {
+    // ── views (P7 track 2) ────────────────────────────────────────────────────
+    /**
+     * Register the main-pane views. Set after construction for the same reason
+     * the context gauge is: a view reads session-scoped state, and the session is
+     * built with this renderer as one of its arguments.
+     *
+     * Re-attaching replaces the set. If the selected view is not in the new set
+     * the selection falls back to the conversation rather than pointing at
+     * nothing — an unresolvable id would paint an empty main column with no way
+     * for the user to tell a missing view from a broken one.
+     */
+    attachViews(sources) {
         if (this.closed)
             return;
-        this.railState = { ...this.railState, [id]: lines };
+        this.views = [...sources];
+        if (this.selectedView !== CONVERSATION_VIEW &&
+            !this.views.some((v) => v.id === this.selectedView)) {
+            this.selectedView = CONVERSATION_VIEW;
+        }
         this.schedulePaint();
     }
+    /** The registered views, conversation excluded (it is built in). */
+    viewSources() {
+        return this.views;
+    }
+    /** Which view owns the main column. */
+    view() {
+        return this.selectedView;
+    }
+    /**
+     * The tier the gateway last said actually served a request, or undefined
+     * before the first answer (P4 track 4).
+     *
+     * Published so the Overview view can report the same tier the model panel and
+     * the status line do. `SessionStatus.servedTier` has existed and been rendered
+     * since P6 track 4 with nothing ever supplying it — this renderer was the only
+     * object that knew the value, and it had no way to hand it over.
+     */
+    servedTier() {
+        return this.served?.tier;
+    }
+    /**
+     * Select a view. Returns false for an unknown id — the caller reports it,
+     * rather than this silently selecting something the user did not ask for.
+     *
+     * THE SCROLL POSITION RESETS. Offsets are display-line counts into whatever
+     * content is in the pane, and two views share no coordinate system: carrying
+     * one across would land at an arbitrary place in the other. One offset that
+     * always means "into what you are looking at" is simpler to reason about than
+     * per-view bookkeeping, and cheaper to be right about.
+     */
+    setView(id) {
+        if (this.closed)
+            return false;
+        if (id !== CONVERSATION_VIEW && !this.views.some((v) => v.id === id)) {
+            return false;
+        }
+        if (this.selectedView === id)
+            return true;
+        this.selectedView = id;
+        this.scrollOffset = 0;
+        this.schedulePaint();
+        return true;
+    }
+    /** Move `steps` around the view ring and select what lands. */
+    cycleView(steps) {
+        const next = cycleView(this.selectedView, this.views, steps);
+        this.setView(next);
+        return next;
+    }
+    /**
+     * Give the sidebar nav the keyboard, or take it back. Returns false when
+     * focus could not move, which is how the caller learns to say why.
+     *
+     * Refused while the sidebar is not on screen — closed by the user, or dropped
+     * by the width budget. Focus you cannot see is the worst kind: the arrow keys
+     * would quietly change meaning with nothing on screen accounting for it.
+     */
+    focusSidebar(focused) {
+        if (this.closed)
+            return false;
+        if (focused && !this.sidebarVisible())
+            return false;
+        if (this.sidebarFocused === focused)
+            return false;
+        this.sidebarFocused = focused;
+        this.schedulePaint();
+        return true;
+    }
+    /** Whether the sidebar nav currently holds the keyboard. */
+    sidebarHasFocus() {
+        return this.sidebarFocused;
+    }
+    /** Open AND wide enough to paint — the same test `/open` reports against. */
+    sidebarVisible() {
+        if (!this.open.has("sidebar"))
+            return false;
+        return budgetColumns(this.viewportWidth(), this.open).sidebar > 0;
+    }
+    // ── scrollback (P7 track 1) ───────────────────────────────────────────────
+    /**
+     * Scroll the main column by `delta` display lines — positive is BACK, into
+     * history; negative is forward, toward the live tail. Returns whether the
+     * position actually moved, so a caller can leave a key unhandled (and let
+     * something else claim it) rather than swallowing a no-op.
+     *
+     * Only the lower bound is applied here. The upper one needs the wrapped line
+     * count at the current width, which is composed per paint — so `viewModel`
+     * clamps and writes the real value back. Pressing Page Up at the top of a
+     * short buffer therefore reports movement once and then stops, instead of
+     * silently banking offset that Page Down would have to unwind.
+     */
+    scrollBy(delta) {
+        if (this.closed)
+            return false;
+        const next = Math.max(0, this.scrollOffset + delta);
+        if (next === this.scrollOffset)
+            return false;
+        this.scrollOffset = next;
+        this.schedulePaint();
+        return true;
+    }
+    /**
+     * Scroll by one screenful, keeping {@link SCROLL_PAGE_OVERLAP} lines of
+     * context across the jump. A page that turns cleanly loses the sentence
+     * straddling the boundary, and in a conversation that is usually the one
+     * being read.
+     */
+    scrollPage(direction) {
+        const page = Math.max(1, bodyRows(this.caps.height) - SCROLL_PAGE_OVERLAP);
+        return this.scrollBy(direction * page);
+    }
+    /** Return to the live tail. Returns false when already there. */
+    scrollToLive() {
+        if (this.closed || this.scrollOffset === 0)
+            return false;
+        this.scrollOffset = 0;
+        this.schedulePaint();
+        return true;
+    }
+    /** Whether the main column is showing history rather than the live tail. */
+    isScrolledBack() {
+        return this.scrollOffset > 0;
+    }
     // ── app-owned surfaces ────────────────────────────────────────────────────
     /**
      * Replace the sidebar's session list (P2). Called once the session log is
@@ -470,6 +639,7 @@ export class TuiRenderer {
         this.context?.sample();
         this.paintNow();
         this.refreshGit();
+        this.refreshViews();
     }
     /**
      * Re-probe the working tree, off the paint path, and repaint when it lands.
@@ -490,6 +660,34 @@ export class TuiRenderer {
             this.schedulePaint();
         });
     }
+    /**
+     * Let each view re-probe what it reads (P7 track 3), on the same post-turn
+     * trigger and under the same rules as the rail's git cache: not awaited, and
+     * a failure leaves the pane as it was.
+     *
+     * EVERY view refreshes, not just the selected one. A probe exists so that
+     * SELECTING a view shows something true immediately; refreshing only the
+     * visible one would mean every switch lands on a stale pane and then flickers
+     * — which is the "checking…" state the tri-state was added to be honest
+     * about, shown at the one moment it is avoidable.
+     */
+    refreshViews() {
+        if (this.closed)
+            return;
+        for (const source of this.views) {
+            const refresh = source.refresh;
+            if (refresh === undefined)
+                continue;
+            void Promise.resolve(refresh.call(source))
+                .then(() => {
+                if (!this.closed)
+                    this.schedulePaint();
+            })
+                // A view that cannot re-probe keeps its last value; it must never take
+                // the shell down with an unhandled rejection.
+                .catch(() => { });
+        }
+    }
     close() {
         if (this.closed)
             return;
@@ -499,6 +697,10 @@ export class TuiRenderer {
             clearTimeout(this.paintTimer);
             this.paintTimer = null;
         }
+        if (this.viewPulseTimer !== null) {
+            clearTimeout(this.viewPulseTimer);
+            this.viewPulseTimer = null;
+        }
         this.unsubscribeResize?.();
         this.unsubscribeResize = null;
         this.unsubscribeModel?.();
@@ -533,6 +735,26 @@ export class TuiRenderer {
         this.partial = "";
     }
     pushLines(lines) {
+        // Hold the scrolled view still (P7 track 1). The offset is measured from
+        // the END of the document, so appending would otherwise slide the content
+        // up under the reader by exactly the number of lines that arrived — the
+        // failure this compensation exists to prevent, and the reason scrollback is
+        // worth having DURING a stream rather than only after one.
+        //
+        // Counted in DISPLAY lines, at the width the window is composed at, because
+        // that is the unit the offset is in. Skipped entirely at the live tail,
+        // where following the newest output is the whole point.
+        // Only while the conversation is the thing being scrolled. A view's offset
+        // indexes ITS lines, so nudging it because the conversation grew behind the
+        // pane would scroll a document that did not change.
+        if (this.scrollOffset > 0 && this.selectedView === CONVERSATION_VIEW) {
+            const cols = this.mainWidth();
+            let added = 0;
+            for (const line of lines) {
+                added += line === "" ? 1 : reflow(line, cols).length;
+            }
+            this.scrollOffset += added;
+        }
         this.buffer.push(...lines);
         if (this.buffer.length > SCROLLBACK_LINES) {
             this.buffer = this.buffer.slice(this.buffer.length - SCROLLBACK_LINES);
@@ -612,6 +834,34 @@ export class TuiRenderer {
         const width = this.viewportWidth();
         const height = this.caps.height;
         this.frame.render(composeScreen(this.viewModel(width, height), width, height, this.open, this.theme));
+        this.armViewPulse();
+    }
+    /**
+     * Keep repainting a selected view that says its content is moving on its own
+     * (P7 track 5) — a background job appending to its log while the foreground
+     * waits at the prompt.
+     *
+     * Armed from `paintNow` rather than from an event, because the condition it
+     * watches has no event: the pulse paints, that paint re-arms, and the chain
+     * ends by itself the moment the view stops being selected or stops being live.
+     * Nothing else in this class needs to know the pulse exists.
+     */
+    armViewPulse() {
+        if (this.viewPulseTimer !== null || this.closed)
+            return;
+        const active = this.views.find((v) => v.id === this.selectedView);
+        // `live` is optional and false by default: every view whose content only
+        // moves when a turn, a key or a `refresh` moved it already repaints.
+        if (active?.live?.() !== true)
+            return;
+        this.viewPulseTimer = setTimeout(() => {
+            this.viewPulseTimer = null;
+            if (!this.closed)
+                this.schedulePaint();
+        }, VIEW_PULSE_MS);
+        // Never hold the process open for a pulse — the same rule as `paintTimer`.
+        // A pending repaint must not be why `cruxy` fails to exit.
+        this.viewPulseTimer.unref?.();
     }
     /** The live-state line, composed by the shared U.4 mapping. */
     /**
@@ -690,13 +940,55 @@ export class TuiRenderer {
         // height and which `fitBlock`'s tail rule would otherwise decapitate.
         const drawer = fitOverlay(this.overlay ?? [], overlayRows(height));
         const rows = Math.max(1, bodyRows(height) - drawer.length);
-        const mainCols = budgetColumns(width, this.open).main;
-        // Wrap only the tail we could possibly show. Rewrapping 1,000 lines on
-        // every frame would be the one genuinely hot cost in this path.
-        const slice = this.buffer.slice(Math.max(0, this.buffer.length - rows * 4));
-        const live = this.partial === "" ? [] : [this.partial];
+        const columns = budgetColumns(width, this.open);
+        const mainCols = columns.main;
+        // Focus cannot outlive the thing holding it (P7 track 2). `/close sidebar`
+        // and a narrowing terminal both take the nav off screen, and either would
+        // otherwise leave the arrow keys silently rebound to a column that is not
+        // there. Dropped here rather than in the two call sites because this is
+        // where "on screen" is actually decided.
+        if (this.sidebarFocused &&
+            (!this.open.has("sidebar") || columns.sidebar === 0)) {
+            this.sidebarFocused = false;
+        }
+        const scrolled = this.scrollOffset > 0;
+        // A registered view owns the main column outright (P7 track 2). Its lines
+        // are recomposed every paint from its own state — this class never learns
+        // what they mean — and none of the conversation machinery below applies:
+        // there is no partial line to hold back, no plan to pin, and no append to
+        // compensate for, because a view does not accumulate.
+        const active = this.selectedView === CONVERSATION_VIEW
+            ? undefined
+            : this.views.find((v) => v.id === this.selectedView);
+        // AT THE LIVE TAIL, wrap only the tail we could possibly show. Rewrapping
+        // 1,000 lines on every frame would be the one genuinely hot cost in this
+        // path, and this is the path every streaming frame takes.
+        //
+        // SCROLLED BACK, wrap the whole retained buffer instead. The offset is in
+        // display lines and it has to be clamped against the real total, which a
+        // slice cannot supply — and a conservative bound would stop short of the
+        // oldest line, making content unreachable rather than merely slow. The cost
+        // is bounded by SCROLLBACK_LINES and only paid while a human is reading
+        // history, which is not a hot path.
+        //
+        // Skipped entirely while a view owns the pane: the conversation keeps
+        // accumulating behind it, but composing what nobody is looking at would
+        // make every other view pay the conversation's cost.
+        const source = active !== undefined
+            ? []
+            : scrolled
+                ? this.buffer
+                : this.buffer.slice(Math.max(0, this.buffer.length - rows * 4));
+        // The streaming partial line belongs to the LIVE view only. While scrolled
+        // it is excluded, which is what makes the offset arithmetic exact: the
+        // document then changes only through `pushLines`, which compensates. It is
+        // also the honest reading — scrollback is committed output, and a line still
+        // being written is not committed.
+        const live = active !== undefined || scrolled || this.partial === ""
+            ? []
+            : [this.partial];
         const wrapped = [];
-        for (const line of [...slice, ...live]) {
+        for (const line of [...source, ...live]) {
             if (line === "") {
                 wrapped.push("");
                 continue;
@@ -710,7 +1002,16 @@ export class TuiRenderer {
         // cap below is what stops a 40-step plan from evicting the conversation
         // entirely, and `planChecklist` windows around the running step and says
         // how many it hid.
-        const plan = this.planSteps === null || this.planSteps.length === 0
+        //
+        // Pinned to the LIVE tail, not to the column: while scrolled back it is
+        // absent, for the same reason the partial line is. It is re-rendered from
+        // mutable state on every paint rather than committed to the buffer, so
+        // leaving it in a scrolled view would let it change length underneath a
+        // reader and shift the history they are holding still.
+        const plan = active !== undefined ||
+            scrolled ||
+            this.planSteps === null ||
+            this.planSteps.length === 0
             ? []
             : planChecklist(this.planSteps, this.theme, Math.max(2, Math.floor(rows / 2)), mainCols);
         // The rail is a STACK of fixed panels, not a feed: it is composed to the
@@ -732,8 +1033,10 @@ export class TuiRenderer {
         const toolRows = this.tools === undefined || !this.open.has("tools")
             ? undefined
             : this.startTools(this.tools).current();
+        // Composed fresh each paint from the panels' own typed state. There is no
+        // stored blob to merge over: every panel owns its source, so a key can only
+        // appear here by being derived below.
         const railState = {
-            ...this.railState,
             ...(model === undefined
                 ? {}
                 : { model: modelPanelLines(this.theme, model) }),
@@ -749,6 +1052,40 @@ export class TuiRenderer {
         };
         const stacked = stackPanels(railBlocks(this.theme, railState, this.open), rows, this.theme);
         this.railDropped = stacked.dropped;
+        // Window the conversation (P7 track 1). At the live tail this is the tail
+        // view `fitBlock` already produced — `scrollWindow` agrees with it
+        // line-for-line at offset 0 — so the default path is unchanged and the
+        // notice costs nothing. Scrolled back, one row goes to the notice, which is
+        // why the window is asked for `rows - 1`.
+        //
+        // The clamp is written back because only this pass knows the wrapped total;
+        // `scrollBy` bounds the keypress from below and leaves the ceiling here.
+        // The one place the two content sources meet. Everything downstream —
+        // windowing, the notice, `fitBlock` — treats them identically, which is
+        // what "a view is just lines" has to mean to be worth anything.
+        //
+        // A view's lines are reflowed here rather than trusted at `mainCols`: the
+        // contract asks a view to lay out to the width it is given, and reflow makes
+        // that a courtesy rather than a rule it can break the grid by ignoring.
+        const body = active !== undefined
+            ? active
+                .lines(this.theme, mainCols)
+                .flatMap((line) => (line === "" ? [""] : reflow(line, mainCols)))
+            : plan.length === 0
+                ? wrapped
+                : [...wrapped, "", ...plan];
+        let main = body;
+        if (scrolled) {
+            const win = scrollWindow(body, Math.max(1, rows - 1), this.scrollOffset);
+            this.scrollOffset = win.offset;
+            // The clamp can land on 0 — a resize that grew the pane past the content,
+            // or scrollback that rolled off underneath the offset. That is the live
+            // view again, and it must not keep a notice claiming lines below it.
+            main =
+                win.offset === 0
+                    ? body
+                    : [...win.lines, scrollNotice(win.hiddenBelow, this.theme)];
+        }
         return {
             headerLeft: "cruxy",
             // Recomposed each paint, so a served tier that arrives (or changes under
@@ -757,8 +1094,16 @@ export class TuiRenderer {
             headerRight: model === undefined
                 ? this.headerRight
                 : headerModel(this.theme, this.provider, model),
-            sidebar: sidebarLines(this.theme, this.sessions, this.activeSessionId),
-            main: plan.length === 0 ? wrapped : [...wrapped, "", ...plan],
+            // Nav first, then the session list P2 put here. Two blocks rather than
+            // one because they answer different questions — "where am I" and "what
+            // else have I run" — and because the sessions list is destined to become
+            // a view of its own, at which point this reduces to the nav.
+            sidebar: [
+                ...navLines(this.theme, this.views, this.selectedView, this.sidebarFocused),
+                "",
+                ...sidebarLines(this.theme, this.sessions, this.activeSessionId),
+            ],
+            main,
             rail: stacked.lines,
             status: this.statusLine(width),
             input: this.inputLine,