@vincemakes/kiso-tui 0.18.0 → 0.19.0

package/dist/compositor.d.ts

@@ -219,6 +219,14 @@ export declare class Body {
         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";
     } | {
@@ -363,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 { ACT_SLOT_ROWS, Container, ROLLUP_NOUN, MOTION_FRAMES, MdStream, bodySpacing, boxBottom, boxTop, cellComponent, exploreCounts, foldCountsObjects, foldTerms, focusToken, exploreRows, foldLine, isExploreTool, moreRunningRow, pendingQueueRows, slotPad, slotTail, 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). */
@@ -179,7 +182,7 @@ function openSegment(turn, now) {
     const last = turn.segments[turn.segments.length - 1];
     if (last !== undefined && last.closedAt === null)
         return last;
-    const fresh = { openedAt: now, closedAt: null, reads: 0, edits: 0, others: new Map(), seen: new Map(), thinkingMs: 0, thinkingSince: null, folded: false, spilled: false, headCell: null, foldKey: null, cells: [] };
+    const fresh = { openedAt: now, closedAt: null, reads: 0, edits: 0, others: new Map(), seen: new Map(), thinkingMs: 0, thinkingSince: null, folded: false, spilled: false, headCell: null, cells: [] };
     turn.segments.push(fresh);
     return fresh;
 }
@@ -323,8 +326,6 @@ export class Body {
      *  opened; the walk takes the newest entry not in it, and empties it
      *  when every entry has been seen. */
     #opened = new Set();
-    /** R4 (C1) — the session's fold counter. Monotonic, never reused. */
-    #foldSeq = 0;
     // 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
@@ -351,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;
@@ -1091,15 +1097,225 @@ export class Body {
         }
         return { lines: chunks.flat(), blocks: blocks - skipped, skipped };
     }
-    /** R4 (C1) — what the NEXT press will open, by name. The walk is
-     *  deterministic (newest unopened first), so this is a promise the
-     *  key keeps rather than a guess. */
-    #nextFoldHint() {
-        const pending = this.#collapsed.filter((i) => !this.#opened.has(i));
-        const ring = pending.length > 0 ? pending : this.#collapsed;
-        const idx = ring[0];
-        const key = idx === undefined ? null : (this.#segmentOf(idx)?.foldKey ?? null);
-        return key === null ? "ctrl+r opens the next fold" : `ctrl+r opens fold ${key}`;
+    /**
+     * 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) {
@@ -1161,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
@@ -1259,12 +1404,13 @@ export class Body {
             return {
                 kind: "appended",
                 lines: [
-                    // R4 (C1): the expansion names the fold it opened, in the
-                    // same ordinal the fold row printed — the answer to "which
-                    // one did that open", stated rather than inferred.
-                    `${p.bold}✦${p.reset} expanded${seg.foldKey === null ? "" : ` ${seg.foldKey}`} · ${escapeTerminal(head.length === 0 ? "thinking" : head.join(" · "))} · ${back}`,
+                    // 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 · ${this.#nextFoldHint()}${p.reset}`,
+                    `  ${p.dim}└ end of expansion · ctrl+r opens the one before it${p.reset}`,
                 ],
             };
         }
@@ -1988,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 +
@@ -2101,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:
@@ -2338,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;
@@ -2666,12 +2849,6 @@ export class Body {
                     seg.folded = true;
                     seg.headCell = i;
                     turn.folded = true;
-                    // R4 (C1): the ordinal is assigned HERE, before the row
-                    // is rendered, because the settled line always carries
-                    // the key — so the number is known without guessing
-                    // whether the row will earn an affordance.
-                    this.#foldSeq += 1;
-                    seg.foldKey = this.#foldSeq;
                     // DECLARED SUPERSESSION (R3i phase 3) — A9 NARROWS: the
                     // fold carries WORK, never the human's words.
                     //
@@ -2683,7 +2860,7 @@ export class Body {
                     // the fold directly beneath it. The band is the record of
                     // what was asked; this line is the record of what was
                     // done. One fact, one row, each.
-                    return stretchLine({ ...this.#stretchTerms(seg), phase: "settled", foldKey: seg.foldKey }, W);
+                    return stretchLine({ ...this.#stretchTerms(seg), phase: "settled" }, W);
                 }
                 return [];
             }
@@ -3380,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 = "▌ ";
@@ -389,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() {
@@ -861,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];
@@ -1334,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.18.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.18.0"
+		"@vincemakes/kiso-tui-cells": "0.19.0"
 	}
 }