@vincemakes/kiso-tui 0.17.0 → 0.19.0

package/dist/compositor.d.ts

@@ -184,6 +184,49 @@ export declare class Body {
             isError: boolean;
         };
     } | null;
+    /**
+     * R4 (C4d) — THE APPEND-ONLY RE-WRAP.
+     *
+     * The owner's report: resize the window and the reference
+     * implementation's text re-wraps to the new width while kiso's does
+     * not. It is true, and it is not a bug to be fixed — it is the price
+     * of ADR-0046, and the price is worth naming precisely.
+     *
+     * A terminal can only reflow a SOFT-wrapped line: one long logical
+     * line the terminal itself wrapped as the cursor flowed past the last
+     * column. Every row kiso commits is either painted by cursor
+     * addressing (#emitDiff) or scrolled out by a bare LF (#emitScroll),
+     * and frames run with autowrap OFF — so no byte kiso commits can ever
+     * carry a continuation flag, and nothing downstream can rejoin rows an
+     * application hard-split. That same LF is what makes the transcript
+     * the TERMINAL's: it survives kiso's death, a pipe, and tmux. A
+     * product whose transcript reflows is a product that repaints its
+     * transcript from its own memory, and that transcript dies with it.
+     *
+     * What kiso can do — and this is all it can do — is APPEND. The
+     * committed cells are still in memory; re-render them at the current
+     * width and put them at the BOTTOM, where writing is allowed. Nothing
+     * above is rewritten, so ADR-0046 holds exactly.
+     *
+     * Scoped to PROSE. Text is what reads badly at the wrong width — a
+     * paragraph folded for 120 columns and read at 60 is the complaint.
+     * Tool rows, folds and chips are short, already carry their own
+     * width ladders, and re-printing them would duplicate work the folds
+     * exist to state once.
+     */
+    rewrap(): {
+        lines: string[];
+        blocks: number;
+        skipped: number;
+    };
+    /** Whether the viewer owns the live region right now. */
+    viewerOpen(): boolean;
+    /** ctrl+o — open on the newest fold, or close. */
+    viewerToggleMode(): void;
+    /** The viewer's keys. Everything the surface can do, a key does —
+     *  there is no pointer, so there is nothing a pointer could reach
+     *  that a keyboard cannot. */
+    viewerKey(cmd: "up" | "down" | "toggle" | "all" | "pageUp" | "pageDown" | "home" | "end"): void;
     expandNext(): {
         kind: "toggled";
     } | {
@@ -328,6 +371,13 @@ export declare class Dock {
     /** TUI2-R1 (D): bind the editor's keys-sheet flag — the slot read for
      *  the ? overlay (the menu/picker binding pattern). */
     bindSheet(state: () => boolean): void;
+    /** R5 — the transcript viewer's three doors, forwarded to the live
+     *  compositor. Unlike the other bindings there is no buffer: the
+     *  viewer cannot be open before a compositor exists, so a call with
+     *  no compositor is a no-op rather than a queued intent. */
+    viewerOpen(): boolean;
+    viewerToggleMode(): void;
+    viewerKey(cmd: "up" | "down" | "toggle" | "all" | "pageUp" | "pageDown" | "home" | "end"): void;
     bindInput(state: () => InputState, prompt: string): void;
     bindMenu(state: () => {
         items: readonly MenuItem[];

package/dist/compositor.js

@@ -52,9 +52,12 @@ import { MOUSE_OFF } from "./editor.js";
 import { atPanelRows, bandHeader } from "./at-picker.js";
 // TUI2-R2 ②: the session picker's rows — the band's third occupant.
 import { sessionPickerRows } from "./session-picker.js";
-import { Container, ROLLUP_NOUN, MOTION_FRAMES, MdStream, bodySpacing, boxBottom, boxTop, cellComponent, exploreCounts, foldCountsObjects, foldTerms, focusToken, exploreRows, foldLine, isExploreTool, pendingQueueRows, statusLine, stretchLine, turnFold, visibleWidth, twinkleFrame, } from "./components.js";
+import { ACT_SLOT_ROWS, Container, ROLLUP_NOUN, MOTION_FRAMES, MdStream, bodySpacing, boxBottom, boxTop, cellComponent, exploreCounts, foldCountsObjects, foldTerms, focusToken, exploreRows, foldLine, cutLine, isExploreTool, moreRunningRow, pendingQueueRows, slotPad, slotTail, statusLine, stretchLine, turnFold, visibleWidth, twinkleFrame, } from "./components.js";
 import { bannerLines, escapeTerminal, foldResult, foldThinking, palette, renderTerminalGap, renderToolSummary, toolTarget } from "./render.js";
 import { displayVerb, keysSheetRows } from "./strings.js";
+// R5 — the transcript viewer's PURE projection. The compositor supplies
+// the entries (it holds the cells); the arrangement lives there.
+import { VIEWER_GUTTER, viewerFlat, viewerHint, viewerInit, viewerMove, viewerRows, viewerScroll, viewerTitle, viewerToggle, viewerToggleAll, } from "./transcript.js";
 /** The cursor marker — an APC private sequence the focus component
  *  embeds at the edit position; the compositor strips it and moves
  *  relatively (it never reaches the terminal). */
@@ -314,7 +317,15 @@ export class Body {
     // rendered row carried the "ctrl+r" affordance; the expand key's
     // cycling pointer walks this list from the newest back.
     #collapsed = [];
-    #expandPtr = 0;
+    /** R4 (C1) — the ring walk is by IDENTITY, not by a modular pointer.
+     *  `#collapsed` is unshifted on every commit that carries the key, so
+     *  a numeric pointer's target silently CHANGED whenever a new fold
+     *  landed mid-cycle: the ring was not stable under itself, and the
+     *  next press opened something other than what the last press
+     *  implied. This set records what the current cycle has already
+     *  opened; the walk takes the newest entry not in it, and empties it
+     *  when every entry has been seen. */
+    #opened = new Set();
     // W14: the turn records — one per userLine, the fold-hold's state
     // machine (ended / hasText / folded) plus the folded-turn line's
     // counts (accumulated at toolStart). The cells carry the record's
@@ -341,6 +352,11 @@ export class Body {
      *  Unbound, the sheet cannot render and every frame is byte-identical
      *  to before the round. */
     #sheetState = null;
+    /** R5 — the transcript viewer's state, or null when it is closed. It
+     *  lives HERE rather than in the editor because its entries are the
+     *  compositor's cells; the editor only sends it commands. */
+    #viewer = null;
+    #viewerWasUp = false;
     /** TUI2-R1.5 7(a): the sheet's previous up/down state — a transition
      *  in either direction takes the full-redraw path. */
     #sheetWasUp = false;
@@ -1024,6 +1040,283 @@ export class Body {
         }
         return -1;
     }
+    /**
+     * R4 (C4d) — THE APPEND-ONLY RE-WRAP.
+     *
+     * The owner's report: resize the window and the reference
+     * implementation's text re-wraps to the new width while kiso's does
+     * not. It is true, and it is not a bug to be fixed — it is the price
+     * of ADR-0046, and the price is worth naming precisely.
+     *
+     * A terminal can only reflow a SOFT-wrapped line: one long logical
+     * line the terminal itself wrapped as the cursor flowed past the last
+     * column. Every row kiso commits is either painted by cursor
+     * addressing (#emitDiff) or scrolled out by a bare LF (#emitScroll),
+     * and frames run with autowrap OFF — so no byte kiso commits can ever
+     * carry a continuation flag, and nothing downstream can rejoin rows an
+     * application hard-split. That same LF is what makes the transcript
+     * the TERMINAL's: it survives kiso's death, a pipe, and tmux. A
+     * product whose transcript reflows is a product that repaints its
+     * transcript from its own memory, and that transcript dies with it.
+     *
+     * What kiso can do — and this is all it can do — is APPEND. The
+     * committed cells are still in memory; re-render them at the current
+     * width and put them at the BOTTOM, where writing is allowed. Nothing
+     * above is rewritten, so ADR-0046 holds exactly.
+     *
+     * Scoped to PROSE. Text is what reads badly at the wrong width — a
+     * paragraph folded for 120 columns and read at 60 is the complaint.
+     * Tool rows, folds and chips are short, already carry their own
+     * width ladders, and re-printing them would duplicate work the folds
+     * exist to state once.
+     */
+    rewrap() {
+        const W = this.#opts.width();
+        const H = this.#opts.height();
+        const ctx = { spinnerI: this.#spinnerI, now: Date.now(), height: H };
+        // two screens is the bound: enough to re-read what a resize just
+        // made awkward, short enough that the append is not its own wall
+        // of text. A silent cap would read as "this is all of it".
+        const budget = Math.max(H, 2 * H);
+        const chunks = [];
+        let rows = 0;
+        let blocks = 0;
+        let skipped = 0;
+        for (let i = this.#committed - 1; i >= 0; i -= 1) {
+            const cell = this.#cells[i];
+            if (cell.kind !== "md")
+                continue;
+            blocks += 1;
+            if (rows >= budget) {
+                skipped += 1;
+                continue;
+            }
+            const lines = cellComponent(cell).render(W, ctx);
+            chunks.unshift(lines);
+            rows += lines.length;
+        }
+        return { lines: chunks.flat(), blocks: blocks - skipped, skipped };
+    }
+    /**
+     * R5 — the rows a fold stands for, as a PURE projection.
+     *
+     * Extracted from expandNext so the transcript viewer and the
+     * expand key open the same work by construction rather than by
+     * two copies agreeing. It renders cells; it mutates none of
+     * them beyond the head.rolled save/restore the rollup path has
+     * always used, which does not outlive this synchronous call.
+     */
+    #foldBody(seg, idx, W, ctx) {
+        const p = palette();
+        const rows = [];
+        let run = [];
+        const flush = () => {
+            if (run.length === 0)
+                return;
+            // the same threshold the commit-time rollup uses: below it a
+            // "run" is just some rows
+            if (run.length > 2) {
+                // the run renders through the ROLLUP's own projection —
+                // literally the same function the commit path uses — so
+                // a single-name run keeps W13's row and a mixed one gets
+                // the exploration line, exactly as they would have if the
+                // segment had never folded.
+                const head = run[0];
+                const saved = head.rolled;
+                head.rolled = rolledOf(run);
+                // the run OPENS. The fold's key already asked to see the
+                // work, so what lands is the same rows `ctrl+r` on the
+                // run itself would have opened — its title, then its
+                // detail — never its collapsed row, which would make the
+                // reader press a second time for what the first press
+                // was for.
+                rows.push(`  ${p.dim}${escapeTerminal(rolledTitle(head))}${p.reset}`);
+                rows.push(...rolledDetail(head, W));
+                head.rolled = saved;
+            }
+            else {
+                for (const c of run)
+                    rows.push(...cellComponent(c).render(W, ctx));
+            }
+            run = [];
+        };
+        // R3f — the expansion covers the WHOLE TURN, every segment.
+        //
+        // R3d moved the fold to the turn while the expansion kept
+        // walking one segment, so a turn that spoke between calls
+        // folded to a line claiming `3 reads · 1 edit · 1 shell` whose
+        // key opened only the reads: the edit and the shell were on no
+        // surface and reachable by no key. That is the one thing this
+        // round's own first gate forbids — the work is never
+        // unreachable — and it is worse than never folding, because the
+        // line names work it then withholds.
+        //
+        // A run still BREAKS at a non-explore cell, so the segment
+        // boundaries survive where they carry meaning (the write that
+        // splits two explore runs); they simply no longer bound what
+        // the key can reach.
+        // DECLARED SUPERSESSION (R3i phase 3) — the expansion covers THIS
+        // STRETCH, and only this stretch.
+        //
+        // R3f widened it to the whole turn, and had to: R3d had made
+        // the fold the TURN's while the expansion still walked one
+        // segment, so a line claiming `read 3 files · edited 1 file`
+        // opened only the reads — work named and then withheld, the one
+        // thing this file's first gate forbids. R3i moves the fold back
+        // to the stretch, so the pairing is exact again: every stretch
+        // has its OWN line and its own key, and each key opens the work
+        // its line named. Keeping the turn walk would break the same
+        // rule from the other side — two lines, each opening
+        // everything, each header describing rows the other also shows.
+        for (const j of seg.cells) {
+            if (j < idx)
+                continue;
+            const c = this.#cells[j];
+            if (c.kind === "tool" && isExploreTool(c.name)) {
+                run.push(c);
+                continue;
+            }
+            flush();
+            rows.push(...cellComponent(c).render(W, ctx));
+        }
+        flush();
+        return rows;
+    }
+    // ─── R5: the transcript viewer ──────────────────────────────────
+    //
+    // The viewer occupies the LIVE REGION, exactly as the keys sheet
+    // does. It is not the alternate buffer and never will be: while an
+    // overlay is up the window is frozen, no LF is emitted, nothing
+    // enters the scrollback, and the close takes the full-redraw path
+    // and restores every displaced row (TUI2-R1.5 7(a), and its gate).
+    /** Whether the viewer owns the live region right now. */
+    viewerOpen() {
+        return this.#viewer !== null;
+    }
+    /** ctrl+o — open on the newest fold, or close. */
+    viewerToggleMode() {
+        if (this.#viewer !== null) {
+            this.#viewer = null;
+        }
+        else {
+            const ctx = { spinnerI: this.#spinnerI, now: Date.now(), height: this.#opts.height() };
+            this.#viewer = viewerInit(this.#viewerEntries(this.#opts.width(), ctx));
+        }
+        this.#mark();
+    }
+    /** The viewer's keys. Everything the surface can do, a key does —
+     *  there is no pointer, so there is nothing a pointer could reach
+     *  that a keyboard cannot. */
+    viewerKey(cmd) {
+        if (this.#viewer === null)
+            return;
+        const W = this.#opts.width();
+        const ctx = { spinnerI: this.#spinnerI, now: Date.now(), height: this.#opts.height() };
+        const entries = this.#viewerEntries(W, ctx);
+        const rows = this.#viewerBandRows();
+        const s = this.#viewer;
+        switch (cmd) {
+            case "up":
+                this.#viewer = viewerMove(entries, s, -1, rows);
+                break;
+            case "down":
+                this.#viewer = viewerMove(entries, s, +1, rows);
+                break;
+            case "home":
+                this.#viewer = viewerMove(entries, s, -entries.length, rows);
+                break;
+            case "end":
+                this.#viewer = viewerMove(entries, s, entries.length, rows);
+                break;
+            case "pageUp":
+                this.#viewer = viewerScroll(entries, s, -rows, rows);
+                break;
+            case "pageDown":
+                this.#viewer = viewerScroll(entries, s, rows, rows);
+                break;
+            case "toggle":
+                this.#viewer = viewerToggle(entries, s, rows);
+                break;
+            case "all":
+                this.#viewer = viewerToggleAll(entries, s, rows);
+                break;
+        }
+        this.#mark();
+    }
+    /** How many rows the viewer's LIST gets: the content cap, less its
+     *  own title and hint rows. */
+    #viewerBandRows() {
+        const H = this.#opts.height();
+        const W = this.#opts.width();
+        const queueRows = this.#queueRows(W, H);
+        const inputExtra = this.#inputRows(W, H, this.#menuRows(W).length, queueRows.length).rows.length - 1;
+        return Math.max(1, H - 4 - inputExtra - queueRows.length - 2);
+    }
+    /**
+     * The expandable things in the transcript, oldest first.
+     *
+     * The set is `#collapsed` — the SAME ring `ctrl+r` walks — so the two
+     * mechanisms can never disagree about what is reachable. The ring is
+     * newest-first (it is unshifted on commit); reading order is the
+     * other way, so it is reversed here.
+     *
+     * Every entry is rendered at the CURRENT width, which is what makes
+     * this surface the answer to "I resized and want to re-read the
+     * history": the scrollback copy stays the immutable original at its
+     * original widths, and this is where you go to read it at today's.
+     */
+    #viewerEntries(W, ctx) {
+        const inner = Math.max(1, W - VIEWER_GUTTER);
+        const out = [];
+        for (const idx of [...this.#collapsed].reverse()) {
+            const cell = this.#cells[idx];
+            if (cell === undefined)
+                continue;
+            const seg = this.#segmentOf(idx);
+            if (seg !== null && seg.headCell === idx) {
+                out.push({
+                    head: stretchLine({ ...this.#stretchTerms(seg), phase: "settled" }, inner)[0] ?? "",
+                    body: this.#foldBody(seg, idx, inner, ctx),
+                });
+                continue;
+            }
+            if (cell.kind !== "tool")
+                continue;
+            // the tool card's FULL body — the same rows its own ctrl+r
+            // opens. The expanded flag is saved and restored inside this
+            // synchronous call, the pattern the rollup path has always
+            // used for head.rolled; it never outlives the render, so the
+            // committed geometry #committedLines derives can never see it.
+            const saved = cell.expanded;
+            cell.expanded = true;
+            const rows = cellComponent(cell).render(inner, ctx);
+            cell.expanded = saved;
+            out.push({ head: rows[0] ?? "", body: rows.slice(1) });
+        }
+        return out;
+    }
+    /** The viewer's band: its title, its list, its keys. */
+    #viewerBand(W) {
+        if (this.#viewer === null)
+            return [];
+        const p = palette();
+        const ctx = { spinnerI: this.#spinnerI, now: Date.now(), height: this.#opts.height() };
+        const entries = this.#viewerEntries(W, ctx);
+        const rows = this.#viewerBandRows();
+        const title = viewerTitle(entries);
+        const shown = viewerRows(entries, this.#viewer, W, rows);
+        const flat = viewerFlat(entries, this.#viewer).length;
+        const more = flat > rows ? ` · ${this.#viewer.top + 1}-${Math.min(flat, this.#viewer.top + rows)} of ${flat}` : "";
+        // the rule is MEASURED, not over-generated and cut — a title row
+        // ending in `…` says the title was truncated, which it was not.
+        const label = `── ${escapeTerminal(title)}${more} `;
+        const fill = "─".repeat(Math.max(0, W - visibleWidth(label)));
+        return [
+            cutLine(`${p.dim}${label}${fill}${p.reset}`, W),
+            ...shown,
+            cutLine(`${p.dim} ${viewerHint(this.#viewer, entries)}${p.reset}`, W),
+        ];
+    }
     expandNext() {
         for (let i = this.#cells.length - 1; i >= this.#committed; i -= 1) {
             const cell = this.#cells[i];
@@ -1045,8 +1338,14 @@ export class Body {
         }
         if (this.#collapsed.length === 0)
             return { kind: "none" };
-        const idx = this.#collapsed[this.#expandPtr % this.#collapsed.length];
-        this.#expandPtr += 1;
+        // R4 (C1) — the newest entry this cycle has not opened yet. When
+        // every entry has been seen the cycle restarts, so the walk is
+        // still "newest back" — it is simply immune to the ring growing
+        // underneath it.
+        if (this.#collapsed.every((i) => this.#opened.has(i)))
+            this.#opened.clear();
+        const idx = this.#collapsed.find((i) => !this.#opened.has(i)) ?? this.#collapsed[0];
+        this.#opened.add(idx);
         const cell = this.#cells[idx];
         // R3b — a folded SEGMENT expands to the work it stands for.
         //
@@ -1078,78 +1377,7 @@ export class Body {
             // stay two runs. Merging every explore tool of the segment
             // would have been simpler and would have quietly deleted that
             // rule.
-            const rows = [];
-            let run = [];
-            const flush = () => {
-                if (run.length === 0)
-                    return;
-                // the same threshold the commit-time rollup uses: below it a
-                // "run" is just some rows
-                if (run.length > 2) {
-                    // the run renders through the ROLLUP's own projection —
-                    // literally the same function the commit path uses — so
-                    // a single-name run keeps W13's row and a mixed one gets
-                    // the exploration line, exactly as they would have if the
-                    // segment had never folded.
-                    const head = run[0];
-                    const saved = head.rolled;
-                    head.rolled = rolledOf(run);
-                    // the run OPENS. The fold's key already asked to see the
-                    // work, so what lands is the same rows `ctrl+r` on the
-                    // run itself would have opened — its title, then its
-                    // detail — never its collapsed row, which would make the
-                    // reader press a second time for what the first press
-                    // was for.
-                    rows.push(`  ${p.dim}${escapeTerminal(rolledTitle(head))}${p.reset}`);
-                    rows.push(...rolledDetail(head, W));
-                    head.rolled = saved;
-                }
-                else {
-                    for (const c of run)
-                        rows.push(...cellComponent(c).render(W, ctx));
-                }
-                run = [];
-            };
-            // R3f — the expansion covers the WHOLE TURN, every segment.
-            //
-            // R3d moved the fold to the turn while the expansion kept
-            // walking one segment, so a turn that spoke between calls
-            // folded to a line claiming `3 reads · 1 edit · 1 shell` whose
-            // key opened only the reads: the edit and the shell were on no
-            // surface and reachable by no key. That is the one thing this
-            // round's own first gate forbids — the work is never
-            // unreachable — and it is worse than never folding, because the
-            // line names work it then withholds.
-            //
-            // A run still BREAKS at a non-explore cell, so the segment
-            // boundaries survive where they carry meaning (the write that
-            // splits two explore runs); they simply no longer bound what
-            // the key can reach.
-            // DECLARED SUPERSESSION (R3i phase 3) — the expansion covers THIS
-            // STRETCH, and only this stretch.
-            //
-            // R3f widened it to the whole turn, and had to: R3d had made
-            // the fold the TURN's while the expansion still walked one
-            // segment, so a line claiming `read 3 files · edited 1 file`
-            // opened only the reads — work named and then withheld, the one
-            // thing this file's first gate forbids. R3i moves the fold back
-            // to the stretch, so the pairing is exact again: every stretch
-            // has its OWN line and its own key, and each key opens the work
-            // its line named. Keeping the turn walk would break the same
-            // rule from the other side — two lines, each opening
-            // everything, each header describing rows the other also shows.
-            for (const j of seg.cells) {
-                if (j < idx)
-                    continue;
-                const c = this.#cells[j];
-                if (c.kind === "tool" && isExploreTool(c.name)) {
-                    run.push(c);
-                    continue;
-                }
-                flush();
-                rows.push(...cellComponent(c).render(W, ctx));
-            }
-            flush();
+            const rows = this.#foldBody(seg, idx, W, ctx);
             // the header NAMES the segment. When the segment is exactly one
             // explore run, "explored 8 files · 14 searches" is what that run
             // is called everywhere else in the product, and the header says
@@ -1176,9 +1404,13 @@ export class Body {
             return {
                 kind: "appended",
                 lines: [
+                    // R4a — the header names the fold in WORDS (its own terms
+                    // and how far back it is), not by an ordinal. The ordinal
+                    // existed to be typed and never was; the words were
+                    // always the part a reader could use.
                     `${p.bold}✦${p.reset} expanded · ${escapeTerminal(head.length === 0 ? "thinking" : head.join(" · "))} · ${back}`,
                     ...body,
-                    `  ${p.dim}└ end of expansion · ctrl+r opens the next fold${p.reset}`,
+                    `  ${p.dim}└ end of expansion · ctrl+r opens the one before it${p.reset}`,
                 ],
             };
         }
@@ -1680,7 +1912,21 @@ export class Body {
      * settle still produces the same fold it did before. That is the
      * charter's line between this phase and the next.
      */
-    #liveProjection(W, ctx) {
+    #liveProjection(W, ctx, cap) {
+        const rows = this.#project(W, ctx, ACT_SLOT_ROWS);
+        if (cap === undefined || rows.length <= cap)
+            return rows;
+        // R4 — the slot gives way BEFORE any cell is force-committed.
+        // A standing slot that could overflow the content cap would make
+        // the force-commit loop push REAL cells into the scrollback to
+        // relieve rows that are, at the bottom of the slot, blank padding.
+        // So the slot shrinks first, in the pinned order slotPad already
+        // implements (the pad rows are last, so they go first, then the
+        // tail, then the heads beyond the first) and the floor is one row.
+        return this.#project(W, ctx, Math.max(1, ACT_SLOT_ROWS - (rows.length - cap)));
+    }
+    /** R4 — one pass of the live projection at a given slot budget. */
+    #project(W, ctx, budget) {
         const out = [];
         const focus = this.#focusIndex();
         const turn = this.#turns[this.#turns.length - 1];
@@ -1688,30 +1934,29 @@ export class Body {
         const openSeg = open !== null && open.closedAt === null ? open : null;
         let prev = this.#committed > 0 ? this.#lineCache[this.#committed - 1] : null;
         let stretchDrawn = false;
-        let runningShown = 0;
-        let runningHidden = 0;
         for (let i = this.#committed; i < this.#cells.length; i += 1) {
             const cell = this.#cells[i];
             const inOpen = openSeg !== null && openSeg.cells.includes(i);
             if (inOpen) {
-                // the stretch's ONE line, drawn once, at its first cell
-                if (!stretchDrawn) {
-                    stretchDrawn = true;
-                    const rows = stretchLine({ ...this.#stretchTerms(openSeg), phase: this.#stretchPhase(openSeg), mark: twinkleFrame(this.#spinnerI) }, W);
-                    out.push(...this.#space(i, prev, rows));
-                    prev = rows;
-                }
-                // a DONE cell's row is gone; its count is on the line above.
-                // A cell still in flight keeps its row and its output —
-                // hiding the work in flight would be the opposite defect.
-                const flight = cell.kind === "tool" && !cell.done;
-                if (!flight)
-                    continue;
-                if (runningShown >= LIVE_ACT_HEADS) {
-                    runningHidden += 1;
+                // R4 — the open stretch is ONE contiguous block: its line
+                // plus the standing act slot, spaced once, at the segment's
+                // first live cell. Every other cell of the segment draws
+                // nothing; its work is counted on the line and its output,
+                // if it is the current thing, is in the slot.
+                //
+                // R3i drew the line here and then let each cell decide for
+                // itself whether it still had rows — which is why the
+                // region's height moved between every pair of calls.
+                if (stretchDrawn)
                     continue;
-                }
-                runningShown += 1;
+                stretchDrawn = true;
+                const rows = [
+                    ...stretchLine({ ...this.#stretchTerms(openSeg), liveNames: this.#liveNames(openSeg), phase: this.#stretchPhase(openSeg), mark: twinkleFrame(this.#spinnerI) }, W),
+                    ...this.#actSlot(openSeg, W, ctx, budget, focus),
+                ];
+                out.push(...this.#space(i, prev, rows));
+                prev = rows;
+                continue;
             }
             const rows = cellComponent(cell).render(W, ctx);
             // the head row carries the affordance; the tint lands on it and
@@ -1721,12 +1966,120 @@ export class Body {
             out.push(...this.#space(i, prev, rows));
             prev = rows;
         }
-        if (runningHidden > 0) {
-            const p = palette();
-            out.push(`  ${p.dim}└ +${runningHidden} more running${p.reset}`);
-        }
         return out;
     }
+    /**
+     * R4 — the standing act slot's rows. EXACTLY `budget` rows in every
+     * phase, so the live region's height changes twice per stretch (once
+     * when it opens, once when it folds) instead of twice per call.
+     *
+     * The phases, in the order they are tested:
+     *  - an EXPANDED live cell outranks the slot (W15 — "the user asked
+     *    for it"): it renders in full, variable height. This is also
+     *    DC-28's cure: mid-stretch `ctrl+r` had a target it toggled and
+     *    never drew, so the press did nothing visible now and changed a
+     *    later expansion's shape;
+     *  - CALLS IN FLIGHT: one head row each within the budget, the tail
+     *    of the LAST head shown filling what is left, and the overflow
+     *    row inside the slot. The tail belongs to the last head by
+     *    construction — never call N's output under call N+1's header;
+     *  - the GAP between two calls: the call that just finished keeps its
+     *    settled head and its tail. This is the frame R3i collapsed, and
+     *    collapsing it is most of the jump;
+     *  - THINKING, before any call: the thinking's own tail (R3i ruling
+     *    5, wired at last).
+     */
+    #actSlot(seg, W, ctx, budget, focus) {
+        const tint = (i, rows) => {
+            if (i === focus && rows.length > 0)
+                rows[0] = focusToken(rows[0], W);
+            return rows;
+        };
+        const live = seg.cells.filter((i) => i >= this.#committed);
+        const tools = [];
+        for (const i of live)
+            if (this.#cells[i]?.kind === "tool")
+                tools.push(i);
+        const toolAt = (i) => this.#cells[i];
+        // An APPROVAL and an EXPANSION both outrank the slot, for the same
+        // reason: their height is the human's business, not the renderer's.
+        // W21 gives a pending approval the live region wholesale — its
+        // diff is the thing being decided about, and a diff clamped to
+        // four rows is a decision made on partial evidence. W15 gives an
+        // expanded cell its full body — "the user asked for it". The slot
+        // exists to stop the height moving ON ITS OWN; a height a human
+        // asked for is not the oscillation it was built against.
+        //
+        // (The approval half is a regression this round caused and its
+        // gate caught: the first draft treated a pending approval as a
+        // call in flight, so `⏸ edit x.ts` lost its diff tail and the
+        // `ctrl+r to expand` note with it.)
+        const owned = tools.filter((i) => toolAt(i).expanded || toolAt(i).state === "approval");
+        if (owned.length > 0) {
+            // In CELL ORDER, so the frame reads the way the work happened:
+            // an owned cell in full, every OTHER call still in flight
+            // keeping its head row. An approval pausing one call must never
+            // hide the others — the v2d parallel-frame gate caught exactly
+            // that: with the shell running and asky_read at its panel, the
+            // first draft returned the panel alone and the running shell's
+            // `● shell sleep 1; echo hi · 1s` row vanished from the screen.
+            const shown = tools.filter((i) => owned.includes(i) || !toolAt(i).done);
+            const out = [];
+            let heads = 0;
+            for (const i of shown) {
+                const rows = tint(i, cellComponent(this.#cells[i]).render(W, ctx));
+                if (owned.includes(i)) {
+                    out.push(...rows);
+                    continue;
+                }
+                if (heads >= LIVE_ACT_HEADS)
+                    continue;
+                heads += 1;
+                out.push(rows[0] ?? "");
+            }
+            const hidden = shown.length - owned.length - heads;
+            if (hidden > 0)
+                out.push(moreRunningRow(hidden, W));
+            return out;
+        }
+        const flight = tools.filter((i) => !toolAt(i).done);
+        if (flight.length > 0) {
+            // the commonest frame — exactly one call, the full budget — is
+            // the W8 block verbatim, which is what 0.17.0 already drew.
+            if (flight.length === 1 && budget >= ACT_SLOT_ROWS)
+                return slotPad(tint(flight[0], cellComponent(this.#cells[flight[0]]).render(W, ctx)), budget);
+            const heads = flight.slice(0, Math.max(1, Math.min(flight.length, budget - 1, LIVE_ACT_HEADS)));
+            const hidden = flight.length - heads.length;
+            const rows = [];
+            for (const i of heads)
+                rows.push(tint(i, cellComponent(this.#cells[i]).render(W, ctx))[0] ?? "");
+            const rest = budget - rows.length - (hidden > 0 ? 1 : 0);
+            if (rest > 0)
+                rows.push(...slotTail(toolAt(heads[heads.length - 1]).resultText, W, rest));
+            if (hidden > 0)
+                rows.push(moreRunningRow(hidden, W));
+            return slotPad(rows, budget);
+        }
+        const settled = tools.length > 0 ? tools[tools.length - 1] : null;
+        if (settled !== null) {
+            const head = tint(settled, cellComponent(this.#cells[settled]).render(W, ctx))[0] ?? "";
+            return slotPad([head, ...slotTail(toolAt(settled).resultText, W, budget - 1)], budget);
+        }
+        const think = [...live].reverse().find((i) => this.#cells[i]?.kind === "thinking");
+        return slotPad(think === undefined ? [] : slotTail(this.#cells[think].text, W, budget), budget);
+    }
+    /** R4 — the tool names with a call still IN FLIGHT in this segment.
+     *  The stretch line's tense is per term, so a finished shell reads
+     *  `ran 1 shell command` while a read is still running. */
+    #liveNames(seg) {
+        const names = new Set();
+        for (const i of seg.cells) {
+            const c = this.#cells[i];
+            if (c !== undefined && c.kind === "tool" && !c.done)
+                names.add(c.name);
+        }
+        return [...names];
+    }
     /** R3i — the open stretch's phase. It is THINKING while a thinking
      *  cell of it is still open and no call has started; otherwise it is
      *  ACTING. The tense follows the phase, and the phase is what the
@@ -1781,6 +2134,13 @@ export class Body {
         // TUI2-R1 (D): the sheet occupies the live region, exactly like the
         // panel — the scalar must say so, or the cap arithmetic disagrees
         // with the screen.
+        // R5 — the viewer occupies the live region exactly like the sheet,
+        // so the scalar must say so, or the cap arithmetic disagrees with
+        // the screen (the same rule DC-27 was about).
+        if (this.#viewer !== null) {
+            const capV = Math.max(1, this.#opts.height() - 4 - inputExtra - queueRows.length);
+            return this.#viewerBand(this.#opts.width()).slice(0, capV).length + CHROME_ROWS + inputExtra + queueRows.length;
+        }
         if (sheet) {
             return (keysSheetRows(this.#opts.width()).slice(0, Math.max(1, this.#opts.height() - 4 - inputExtra - queueRows.length)).length +
                 CHROME_ROWS +
@@ -1796,16 +2156,25 @@ export class Body {
                 inputExtra +
                 queueRows.length);
         }
+        // DC-27 — the scalar measures the PROJECTION, not a second render
+        // of its own. This loop used to walk every live cell and render it
+        // in full: no open-segment collapse, no flight rule, no act-slot
+        // budget. After R3i that described a screen the compositor had
+        // stopped drawing — for an open stretch with five finished calls
+        // it counted five four-row blocks that were not there. Nothing
+        // broke, because the force-commit loop measures liveLines.length
+        // and the over-count is conservative; but the cap and geometry
+        // gates were asserting a property of a function nothing paints
+        // from, so a real regression in the region's height could not
+        // have moved them. The rule this file already states for the
+        // sheet ("the scalar must say so, or the cap arithmetic disagrees
+        // with the screen") is the same rule here.
         const ctx = { spinnerI: this.#spinnerI, now: Date.now(), height: this.#opts.height() };
         const W = this.#opts.width();
-        let lines = 0;
-        let prev = this.#committed > 0 ? this.#lineCache[this.#committed - 1] : null;
-        for (let i = this.#committed; i < this.#cells.length; i += 1) {
-            const rows = cellComponent(this.#cells[i]).render(W, ctx);
-            lines += this.#space(i, prev, rows).length;
-            prev = rows;
-        }
-        return lines + CHROME_ROWS + inputExtra + this.#menuRows(W).length + queueRows.length;
+        // the SAME content cap the force-commit loop applies, so the
+        // scalar sees the same slot budget the screen gets.
+        const rows = this.#liveProjection(W, ctx, this.#opts.height() - 4 - inputExtra - queueRows.length);
+        return rows.length + CHROME_ROWS + inputExtra + this.#menuRows(W).length + queueRows.length;
     }
     /** The lines committed THIS frame — the writes land in the frame's
      *  committed section (the rows just above the live region). */
@@ -1885,9 +2254,22 @@ export class Body {
         // not ours to rewrite. Measured: three rows per open on a full
         // screen. The overlay below displaces content on screen instead.
         const sheetUp = this.#sheetState?.() === true;
-        this.#overlayFrame = sheetUp || this.#sheetWasUp;
+        // R5 — the viewer is an overlay of exactly the same kind, so it
+        // joins the same flag. That one word is what buys it the whole
+        // zero-litter discipline below: the window freezes, #emitScroll
+        // is skipped, and the close repaints from #lastSkip.
+        const viewerUp = this.#viewer !== null;
+        this.#overlayFrame = sheetUp || this.#sheetWasUp || viewerUp || this.#viewerWasUp;
         this.#sheetWasUp = sheetUp;
-        if (sheetUp) {
+        this.#viewerWasUp = viewerUp;
+        if (viewerUp) {
+            // R5: the viewer REPLACES the live region — the same slot the
+            // sheet and the panel use, for the same reason (it is what the
+            // human is reading right now). It is opened only from an idle
+            // composer, so it cannot coexist with a panel.
+            liveLines = this.#viewerBand(W).slice(0, Math.max(1, H - 4 - inputExtra - queueRows.length));
+        }
+        else if (sheetUp) {
             // TUI2-R1 (D): the sheet REPLACES the live region — the same
             // slot the panel uses, for the same reason (it is what the
             // human is reading right now). It cannot coexist with a panel:
@@ -1914,7 +2296,7 @@ export class Body {
             // by construction), so the marker can never point at a cell the
             // key would not take — which is the only way a focus marker is
             // worth having.
-            liveLines = this.#liveProjection(W, ctx);
+            liveLines = this.#liveProjection(W, ctx, H - 4 - inputExtra - queueRows.length);
         }
         // 3. the FORCE commits — the live region's hard cap H−1: overflow
         //    commits the oldest live cell UNCONDITIONALLY (the one sharp
@@ -1935,7 +2317,7 @@ export class Body {
             this.#commitCell(this.#committed, W, ctx);
             // TUI2-R2 ⑤: the focus re-derives after a commit — the cell it
             // pointed at may have just left the live region.
-            liveLines = this.#liveProjection(W, ctx);
+            liveLines = this.#liveProjection(W, ctx, H - 4 - inputExtra - queueRows.length);
         }
         // 4. the geometry — the live region's first row:
         //    liveTop = min(totalCommitted, H - liveRows) + 1 — the screen
@@ -2122,8 +2504,25 @@ export class Body {
         // tool cell, and a segment's fold can be emitted at a thinking
         // cell — which would have left the whole segment unreachable by
         // the very key its own row advertises.
-        if ((cell.kind === "tool" || this.#segmentOf(i)?.headCell === i) && lines.some((l) => l.includes("ctrl+r")))
+        // R4a — the ring captures by IDENTITY, not by searching our own
+        // printed bytes.
+        //
+        // This used to require the rendered rows to contain the literal
+        // "ctrl+r", which made the affordance LOAD-BEARING: retiring the
+        // printed key (the owner's ruling) would have silently emptied the
+        // ring and taken the expand key with it — not a missing hint, a
+        // missing feature. A fold head is a fold head because the segment
+        // says so; a tool cell is expandable when it is hiding rows.
+        const isFoldHead = this.#segmentOf(i)?.headCell === i;
+        const hidesRows = cell.kind === "tool" && lines.some((l) => l.includes("ctrl+r"));
+        if (isFoldHead || hidesRows) {
             this.#collapsed.unshift(i);
+            // R4a — a new fold resets the walk, so the FIRST press after any
+            // new work always opens the most recent one. That is the whole
+            // of the owner's "which one does it open": the answer is always
+            // "the last one", and repeats walk back from there.
+            this.#opened.clear();
+        }
         this.#lineCache[i] = lines;
         const placed = this.#space(i, i > 0 ? this.#lineCache[i - 1] : null, lines);
         this.#committed += 1;
@@ -3158,6 +3557,19 @@ export class Dock {
         }
         compositorRef.bindSheet(state);
     }
+    /** R5 — the transcript viewer's three doors, forwarded to the live
+     *  compositor. Unlike the other bindings there is no buffer: the
+     *  viewer cannot be open before a compositor exists, so a call with
+     *  no compositor is a no-op rather than a queued intent. */
+    viewerOpen() {
+        return compositorRef !== null && compositorRef.viewerOpen();
+    }
+    viewerToggleMode() {
+        compositorRef?.viewerToggleMode();
+    }
+    viewerKey(cmd) {
+        compositorRef?.viewerKey(cmd);
+    }
     bindInput(state, prompt) {
         if (compositorRef === null) {
             dockBindings.state = state; // the live buffer — order-agnostic

package/dist/editor.d.ts

@@ -35,6 +35,16 @@ import { type SessionCardView, type SessionPickState } from "./session-picker.js
  * go on together and come off together; a terminal left with either one
  * set is a terminal that prints escape bytes at the shell prompt.
  */
+/**
+ * R5 — the viewer's key table, as a pure function of the input chunk.
+ *
+ * Pure so it can be gated without a terminal. Anything not in the table
+ * returns null and is SWALLOWED by the caller: a surface that owns the
+ * screen must not let stray bytes fall through into the composer behind
+ * it, which is the defect the sheet's whole-chunk dismissal avoids by a
+ * different route.
+ */
+export declare function viewerCommand(text: string): "up" | "down" | "toggle" | "all" | "pageUp" | "pageDown" | "home" | "end" | "close" | null;
 export declare const MOUSE_ON = "\u001B[?1000h\u001B[?1006h";
 export declare const MOUSE_OFF = "\u001B[?1000l\u001B[?1006l";
 export declare const PROMPT = "\u258C ";
@@ -92,6 +102,7 @@ export declare class Editor {
     bindQueue(state: () => readonly string[], pop: () => string | null): void;
     /** The whole buffer as text (the CLI's line()/clearLine()). */
     line(): string;
+    bindViewer(isUp: () => boolean, cb: (cmd: "open" | "up" | "down" | "toggle" | "all" | "pageUp" | "pageDown" | "home" | "end" | "close") => void): void;
     /** TUI2-R1 (D): whether the keys sheet is up — the compositor's slot
      *  read (bound like the menu and the picker). */
     sheetOpen(): boolean;

package/dist/editor.js

@@ -48,6 +48,47 @@ import { sessionFilter } from "./session-picker.js";
  * go on together and come off together; a terminal left with either one
  * set is a terminal that prints escape bytes at the shell prompt.
  */
+/**
+ * R5 — the viewer's key table, as a pure function of the input chunk.
+ *
+ * Pure so it can be gated without a terminal. Anything not in the table
+ * returns null and is SWALLOWED by the caller: a surface that owns the
+ * screen must not let stray bytes fall through into the composer behind
+ * it, which is the defect the sheet's whole-chunk dismissal avoids by a
+ * different route.
+ */
+export function viewerCommand(text) {
+    switch (text) {
+        case "\x1b[A":
+        case "k":
+            return "up";
+        case "\x1b[B":
+        case "j":
+            return "down";
+        case "\r":
+        case "\n":
+        case " ":
+            return "toggle";
+        case "a":
+            return "all";
+        case "\x1b[5~":
+            return "pageUp";
+        case "\x1b[6~":
+            return "pageDown";
+        case "\x1b[H":
+        case "g":
+            return "home";
+        case "\x1b[F":
+        case "G":
+            return "end";
+        case "\x1b":
+        case "q":
+        case "\x0f": // ctrl+o — the key that opens it also puts it away
+            return "close";
+        default:
+            return null;
+    }
+}
 export const MOUSE_ON = "\x1b[?1000h\x1b[?1006h";
 export const MOUSE_OFF = "\x1b[?1000l\x1b[?1006l";
 export const PROMPT = "▌ ";
@@ -61,6 +102,9 @@ export const MENU_ITEMS = [
     { name: "/resume", desc: "switch to another session; /resume <id> goes directly" },
     { name: "/think", desc: "show the last full thinking block" },
     { name: "/last", desc: "show the most recent tool call's input and output" },
+    // R4 (C4d): the committed transcript belongs to the terminal and can
+    // never be re-wrapped in place (ADR-0046); this appends it re-folded.
+    { name: "/rewrap", desc: "re-print the recent prose at the current width" },
     { name: "/status", desc: "show session id, event count, and context estimate" },
     // TUI2-R1 (E): the rent-ledger attribution — where the context went
     { name: "/context", desc: "show where the context went — the last request's rent ledger" },
@@ -386,6 +430,20 @@ export class Editor {
     line() {
         return String.fromCodePoint(...this.#chars);
     }
+    /** R5 — the transcript viewer's key routing. The editor owns no
+     *  viewer STATE (the compositor does, because the entries are its
+     *  cells); it only reports whether the viewer is up and forwards the
+     *  commands, the same shape the expand key already uses. */
+    #viewerUp = null;
+    #viewerCbs = new Set();
+    bindViewer(isUp, cb) {
+        this.#viewerUp = isUp;
+        this.#viewerCbs.add(cb);
+    }
+    #viewerSend(cmd) {
+        for (const cb of [...this.#viewerCbs])
+            cb(cmd);
+    }
     /** TUI2-R1 (D): whether the keys sheet is up — the compositor's slot
      *  read (bound like the menu and the picker). */
     sheetOpen() {
@@ -858,6 +916,18 @@ export class Editor {
             this.#onRender();
             return;
         }
+        // R5 — while the viewer is up it OWNS the keyboard. Unlike the
+        // sheet (which any key dismisses) this surface is INTERACTIVE, so
+        // the chunk is matched against its own bindings and anything
+        // unrecognised is swallowed rather than typed into the composer
+        // behind it. esc closes; ctrl+o closes too, so the key that opens
+        // it also puts it away.
+        if (this.#viewerUp?.() === true) {
+            const cmd = viewerCommand(text);
+            if (cmd !== null)
+                this.#viewerSend(cmd);
+            return;
+        }
         let i = 0;
         while (i < text.length) {
             const c = text[i];
@@ -1331,6 +1401,15 @@ export class Editor {
                     cb();
                 i += 1;
             }
+            else if (c === "\x0f" && this.#composerIdle() && this.#chars.length === 0) {
+                // R5 — ctrl+o opens the transcript viewer. Free in kiso, and
+                // the same key the reference implementation uses, so the
+                // muscle memory transfers even though what it opens is not
+                // the same surface. Idle composer only, exactly like `?`:
+                // mid-text it would be a keystroke stolen from the human.
+                this.#viewerSend("open");
+                i += 1;
+            }
             else if (c === "?" && this.#composerIdle() && this.#chars.length === 0) {
                 // TUI2-R1 (D): `?` opens the keys sheet — but ONLY on an
                 // empty composer with nobody else holding the keys. Mid-text

package/dist/transcript.d.ts

@@ -0,0 +1,88 @@
+/**
+ * R5 — THE TRANSCRIPT VIEWER, on the PRIMARY screen.
+ *
+ * The owner's question was never "how do I click" — it was "with that
+ * many folds, which one am I about to open?". R4 answered it with a
+ * printed ordinal and R4a retired that: a number you cannot type is not
+ * a selector. The real bind is narrower and has nothing to do with the
+ * mouse:
+ *
+ *   a COMMITTED row cannot be marked, because kiso never repaints it.
+ *
+ * So any "this one" marker has to live on a surface kiso DOES repaint.
+ * That surface is this viewer, and inside it a keyboard cursor answers
+ * the question completely — no mouse, no ordinal, no mode key to
+ * memorise per fold. The pointer becomes optional decoration rather
+ * than the mechanism, which is why this round ships without it.
+ *
+ * NOT the alternate buffer. The viewer occupies the live region exactly
+ * as the keys sheet does (TUI2-R1.5 7(a)): while an overlay is up the
+ * window is frozen, no LF is emitted, nothing enters the scrollback,
+ * and closing takes the full-redraw path and restores every displaced
+ * row. pi's viewer and the reference implementation's both take the
+ * alternate screen; kiso does not have to, and a kill -9 inside a
+ * primary-screen viewer leaves ordinary bytes and an intact scrollback
+ * where an alt-screen death would strand the reader in the wrong
+ * buffer.
+ *
+ * This module is PURE: entries + state + width → rows. It holds no
+ * cells, mutates nothing, and never touches `cell.expanded` — the
+ * viewer's expansion set is its OWN (see ViewerState.open). That is not
+ * tidiness: the compositor recomputes `#committedLines` from cell
+ * renders on every full redraw, and that number feeds the scroll floor,
+ * so a viewer that expanded a committed cell in place would corrupt the
+ * window arithmetic for the rest of the session.
+ */
+/** The gutter every viewer row carries: the cursor mark and its space. */
+export declare const VIEWER_GUTTER = 3;
+/** One expandable thing in the transcript. The compositor renders these
+ *  from its committed cells at W − VIEWER_GUTTER; the viewer only
+ *  arranges them. */
+export interface ViewerEntry {
+    /** the fold's own committed row, as the reader saw it */
+    readonly head: string;
+    /** the rows it stands for */
+    readonly body: readonly string[];
+}
+export interface ViewerState {
+    /** which entry the cursor is on */
+    readonly cursor: number;
+    /** the first flat row shown — the scroll position */
+    readonly top: number;
+    /** the entries expanded IN THE VIEWER. Never a cell mutation. */
+    readonly open: ReadonlySet<number>;
+}
+export declare function viewerInit(entries: readonly ViewerEntry[]): ViewerState;
+/** The flat row model: every row the viewer would show if it had room,
+ *  each tagged with the entry it belongs to and whether it is that
+ *  entry's head. The window is a slice of this. */
+export declare function viewerFlat(entries: readonly ViewerEntry[], state: ViewerState): {
+    entry: number;
+    head: boolean;
+    text: string;
+}[];
+/** Move the cursor by `delta` entries, keeping it inside the window. */
+export declare function viewerMove(entries: readonly ViewerEntry[], state: ViewerState, delta: number, rows: number): ViewerState;
+/** Scroll by `delta` ROWS without moving the cursor's entry — PgUp/PgDn
+ *  and the wheel, if a pointer ever arrives. */
+export declare function viewerScroll(entries: readonly ViewerEntry[], state: ViewerState, delta: number, rows: number): ViewerState;
+/** Toggle the entry under the cursor. Viewer-local, always. */
+export declare function viewerToggle(entries: readonly ViewerEntry[], state: ViewerState, rows: number): ViewerState;
+/** `a` — every entry at once, or none if they are all already open. */
+export declare function viewerToggleAll(entries: readonly ViewerEntry[], state: ViewerState, rows: number): ViewerState;
+/**
+ * The viewer's rows, at most `rows` of them, every one exactly one
+ * physical row no wider than W (invariant ① — the same crash gate the
+ * live region obeys, because these rows go through the same emitter).
+ *
+ * The marks: `▸` the cursor on a closed entry, `▾` the cursor on an
+ * open one, `│` an open entry's body. Under NO_COLOR the marks ARE the
+ * state — the tint is emphasis over a fact the characters already
+ * carry (law 1.3), so a pipe of this surface loses nothing.
+ */
+export declare function viewerRows(entries: readonly ViewerEntry[], state: ViewerState, W: number, rows: number): string[];
+/** The viewer's affordance row — what the keys do, where they are
+ *  useful (the PICKER_HINT convention). */
+export declare function viewerHint(state: ViewerState, entries: readonly ViewerEntry[]): string;
+/** The viewer's band header — what surface this is, and how much of it. */
+export declare function viewerTitle(entries: readonly ViewerEntry[]): string;

package/dist/transcript.js

@@ -0,0 +1,192 @@
+/**
+ * R5 — THE TRANSCRIPT VIEWER, on the PRIMARY screen.
+ *
+ * The owner's question was never "how do I click" — it was "with that
+ * many folds, which one am I about to open?". R4 answered it with a
+ * printed ordinal and R4a retired that: a number you cannot type is not
+ * a selector. The real bind is narrower and has nothing to do with the
+ * mouse:
+ *
+ *   a COMMITTED row cannot be marked, because kiso never repaints it.
+ *
+ * So any "this one" marker has to live on a surface kiso DOES repaint.
+ * That surface is this viewer, and inside it a keyboard cursor answers
+ * the question completely — no mouse, no ordinal, no mode key to
+ * memorise per fold. The pointer becomes optional decoration rather
+ * than the mechanism, which is why this round ships without it.
+ *
+ * NOT the alternate buffer. The viewer occupies the live region exactly
+ * as the keys sheet does (TUI2-R1.5 7(a)): while an overlay is up the
+ * window is frozen, no LF is emitted, nothing enters the scrollback,
+ * and closing takes the full-redraw path and restores every displaced
+ * row. pi's viewer and the reference implementation's both take the
+ * alternate screen; kiso does not have to, and a kill -9 inside a
+ * primary-screen viewer leaves ordinary bytes and an intact scrollback
+ * where an alt-screen death would strand the reader in the wrong
+ * buffer.
+ *
+ * This module is PURE: entries + state + width → rows. It holds no
+ * cells, mutates nothing, and never touches `cell.expanded` — the
+ * viewer's expansion set is its OWN (see ViewerState.open). That is not
+ * tidiness: the compositor recomputes `#committedLines` from cell
+ * renders on every full redraw, and that number feeds the scroll floor,
+ * so a viewer that expanded a committed cell in place would corrupt the
+ * window arithmetic for the rest of the session.
+ */
+import { palette } from "./render.js";
+import { visibleWidth } from "./components.js";
+/** The gutter every viewer row carries: the cursor mark and its space. */
+export const VIEWER_GUTTER = 3;
+export function viewerInit(entries) {
+    // the cursor starts on the NEWEST fold — the one ctrl+r would have
+    // opened, so the two mechanisms agree on their first answer.
+    return { cursor: Math.max(0, entries.length - 1), top: 0, open: new Set() };
+}
+/** The flat row model: every row the viewer would show if it had room,
+ *  each tagged with the entry it belongs to and whether it is that
+ *  entry's head. The window is a slice of this. */
+export function viewerFlat(entries, state) {
+    const out = [];
+    for (const [i, e] of entries.entries()) {
+        out.push({ entry: i, head: true, text: e.head });
+        if (state.open.has(i))
+            for (const row of e.body)
+                out.push({ entry: i, head: false, text: row });
+    }
+    return out;
+}
+/** The flat index of an entry's head row. */
+function headRow(entries, state, entry) {
+    return viewerFlat(entries, state).findIndex((r) => r.entry === entry && r.head);
+}
+/** Move the cursor by `delta` entries, keeping it inside the window. */
+export function viewerMove(entries, state, delta, rows) {
+    if (entries.length === 0)
+        return state;
+    const cursor = Math.max(0, Math.min(entries.length - 1, state.cursor + delta));
+    const next = { ...state, cursor };
+    return { ...next, top: clampTop(entries, next, rows) };
+}
+/** Scroll by `delta` ROWS without moving the cursor's entry — PgUp/PgDn
+ *  and the wheel, if a pointer ever arrives. */
+export function viewerScroll(entries, state, delta, rows) {
+    const flat = viewerFlat(entries, state).length;
+    const top = Math.max(0, Math.min(Math.max(0, flat - rows), state.top + delta));
+    return { ...state, top };
+}
+/** Toggle the entry under the cursor. Viewer-local, always. */
+export function viewerToggle(entries, state, rows) {
+    const open = new Set(state.open);
+    if (open.has(state.cursor))
+        open.delete(state.cursor);
+    else
+        open.add(state.cursor);
+    const next = { ...state, open };
+    return { ...next, top: clampTop(entries, next, rows) };
+}
+/** `a` — every entry at once, or none if they are all already open. */
+export function viewerToggleAll(entries, state, rows) {
+    const all = entries.length > 0 && entries.every((_, i) => state.open.has(i));
+    const open = all ? new Set() : new Set(entries.map((_, i) => i));
+    const next = { ...state, open };
+    return { ...next, top: clampTop(entries, next, rows) };
+}
+/** Keep the cursor's head row inside the window. */
+function clampTop(entries, state, rows) {
+    const flat = viewerFlat(entries, state);
+    const at = headRow(entries, state, state.cursor);
+    if (at < 0)
+        return 0;
+    const maxTop = Math.max(0, flat.length - rows);
+    let top = Math.min(state.top, maxTop);
+    if (at < top)
+        top = at;
+    if (at >= top + rows)
+        top = at - rows + 1;
+    return Math.max(0, Math.min(top, maxTop));
+}
+/**
+ * The viewer's rows, at most `rows` of them, every one exactly one
+ * physical row no wider than W (invariant ① — the same crash gate the
+ * live region obeys, because these rows go through the same emitter).
+ *
+ * The marks: `▸` the cursor on a closed entry, `▾` the cursor on an
+ * open one, `│` an open entry's body. Under NO_COLOR the marks ARE the
+ * state — the tint is emphasis over a fact the characters already
+ * carry (law 1.3), so a pipe of this surface loses nothing.
+ */
+export function viewerRows(entries, state, W, rows) {
+    const p = palette();
+    const flat = viewerFlat(entries, state);
+    const out = [];
+    for (const line of flat.slice(state.top, state.top + rows)) {
+        const onCursor = line.entry === state.cursor && line.head;
+        const open = state.open.has(line.entry);
+        // The mark carries STATE, the weight carries the CURSOR. Two facts,
+        // two channels — and the first draft collapsed them: a non-cursor
+        // head printed a blank, so an entry that was OPEN stopped saying
+        // so the moment you moved off it. Law 1.3 wants the fact in the
+        // characters, and it is the characters that survive a pipe.
+        //
+        //   ▾  open        (always, cursor or not)
+        //   ▸  the cursor, on a closed entry
+        //   │  an open entry's body
+        //      a closed entry nobody is pointing at
+        const mark = line.head ? (open ? "▾" : onCursor ? "▸" : " ") : "│";
+        const gutter = onCursor ? `${p.bold}${mark}${p.reset} ` : `${p.dim}${mark}${p.reset} `;
+        const row = ` ${gutter}${line.text}`;
+        out.push(open ? shade(row, W) : cut(row, W));
+    }
+    return out;
+}
+/**
+ * An open entry's rows take the VERBATIM SURFACE — `wash`, the same
+ * background DC-3 gave the human's own words and inline code. It is
+ * ground-resolved already, and with no ground it degrades to reverse
+ * video, which is correct on any ground (ground.ts rung 4).
+ *
+ * Padded to the full width so the block reads as ONE thing rather than
+ * a ragged stack. Under NO_COLOR `wash` is empty and the row's bytes
+ * are untouched — the ▾ and │ marks carry the state on their own, which
+ * is law 1.3's requirement, not a consolation.
+ */
+function shade(row, W) {
+    const p = palette();
+    const body = cut(row, W);
+    if (p.wash === "")
+        return body;
+    return `${p.wash}${body}${" ".repeat(Math.max(0, W - visibleWidth(body)))}${p.washEnd}`;
+}
+/** The last resort — the row is cut at W rather than overflowing it. */
+function cut(row, W) {
+    if (visibleWidth(row) <= W)
+        return row;
+    let out = "";
+    let n = 0;
+    for (let i = 0; i < row.length;) {
+        if (row[i] === "\x1b") {
+            const j = row.indexOf("m", i);
+            if (j < 0)
+                break;
+            out += row.slice(i, j + 1);
+            i = j + 1;
+            continue;
+        }
+        if (n >= W - 1)
+            break;
+        out += row[i];
+        n += 1;
+        i += 1;
+    }
+    return `${out}…${palette().reset}`;
+}
+/** The viewer's affordance row — what the keys do, where they are
+ *  useful (the PICKER_HINT convention). */
+export function viewerHint(state, entries) {
+    const openHere = state.open.has(state.cursor);
+    return `↑↓ move · ⏎ ${openHere ? "collapses" : "expands"} · a ${entries.every((_, i) => state.open.has(i)) && entries.length > 0 ? "collapses all" : "expands all"} · esc closes`;
+}
+/** The viewer's band header — what surface this is, and how much of it. */
+export function viewerTitle(entries) {
+    return `transcript · ${entries.length} ${entries.length === 1 ? "fold" : "folds"}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tui",
-	"version": "0.17.0",
+	"version": "0.19.0",
 	"description": "kiso tui — the pure terminal layer (cell renderer, dock, raw editor, diff, palette). Zero runtime dependencies: input is data, output is bytes.",
 	"type": "module",
 	"license": "MIT",
@@ -35,6 +35,6 @@
 	},
 	"homepage": "https://github.com/vincemakes/kiso/tree/main/packages/tui#readme",
 	"dependencies": {
-		"@vincemakes/kiso-tui-cells": "0.17.0"
+		"@vincemakes/kiso-tui-cells": "0.19.0"
 	}
 }