@vincemakes/kiso-tui 0.39.2 → 0.40.1

package/dist/compositor.d.ts

@@ -132,10 +132,13 @@ export declare class Body {
     toolProgress(callId: string, text: string): void;
     toolSucceeded(callId: string): void;
     toolFailed(callId: string, error: string): void;
+    /** `untimed`: 4c's replay settles a card from the durable log, whose
+     *  events carry no clock — the card then says nothing about time. */
     toolResult(callId: string, result: {
         content: string;
         isError: boolean;
         reason?: string | null;
+        untimed?: boolean;
     }): void;
     textAppend(text: string): void;
     textEnd(): void;
@@ -144,6 +147,18 @@ export declare class Body {
      *  CLI's wall-clocked thinking window. */
     endTurn(thoughtSeconds: number): void;
     terminal(label: string, statusLineText: string): void;
+    /**
+     * 4c — fold what `replay` puts on the body into ONE row. The replayed
+     * cells are the same cells a live run makes (the caller drives the
+     * ordinary mutations), moved out of the transcript into the fold cell:
+     * the row commits as one line and never expands on screen — so a resize
+     * reprint redraws one row however long the history — and the ctrl+r
+     * viewer reads them. Mutations only schedule frames, so nothing the
+     * replay adds can have committed before it is moved. Active bodies
+     * only: a pipe has no viewer to read a fold with (the caller prints the
+     * plain tail there).
+     */
+    fold(label: string, replay: () => void, summary?: string | null): void;
     notice(text: string): void;
     /** W20 — the task checklist as STATE, not events: the FIRST call of a
      *  turn creates the ONE live block (done:false — the commit loop only
@@ -220,6 +235,10 @@ export declare class Body {
         count: number;
         first: number;
     } | null;
+    visiblePickWindow(): {
+        first: number;
+        size: number;
+    } | null;
     /** SIGWINCH: clear the OLD live area (recorded geometry, ED only —
      *  zero LF, zero \x1b[3J — the shell history untouched), then the
      *  full-redraw path at the NEW geometry (O(height), zero replay).
@@ -339,8 +358,19 @@ export declare class Body {
      *  reads it — the marker math never desyncs by construction). */
     editCol(): number;
     /** The old dock's redraw — the editor's onRender target: mark + the
-     *  scheduler (16ms coalescing — the old sync draw coalesces the same). */
-    redraw(): void;
+     *  scheduler (16ms coalescing — the old sync draw coalesces the same).
+     *
+     *  Item 6: a KEY-originated redraw paints on the next tick and takes
+     *  the pending trailing frame with it. Keyboard input is the one
+     *  latency-sensitive source: the trailing window made every key wait
+     *  16 ms, and 40 ms on Terminal.app — where an IME commit erases the
+     *  terminal's marked text at once and the committed characters came
+     *  back a frame window later, a visible blink. Stream, tool and
+     *  spinner marks keep the trailing window exactly (the conservative
+     *  mode's throughput protection is for them). setImmediate, not a
+     *  synchronous paint: every mutation one chunk of keys makes still
+     *  lands in one frame. */
+    redraw(fromKey?: boolean): void;
     /** Teardown — flush a pending frame, stop the timers. */
     close(): void;
     /** The live region's scalar — the unit tests assert the cap directly
@@ -369,6 +399,12 @@ export declare class Dock {
         count: number;
         first: number;
     } | null;
+    /** B (review of this round): the pick panel's window for the frame last
+     *  drawn — what the digit keys must name. */
+    visiblePickWindow(): {
+        first: number;
+        size: number;
+    } | null;
     setStatus(text: string, hint?: string | null): void;
     setTail(tail: string): void;
     /** W21: bind the editor's panel state — the PanelSelect slot
@@ -403,5 +439,5 @@ export declare class Dock {
      *  the LineInput's own bindQueue). */
     bindQueue(state: () => readonly string[]): void;
     editCol(): number;
-    redraw(): void;
+    redraw(fromKey?: boolean): void;
 }

package/dist/compositor.js

@@ -52,6 +52,7 @@ import { leadWidth } from "./width.js"; // W23: the ONE width authority (the edi
 // for four reads, so an ask can never render half as an approval.
 import { panelFrameOf, panelLeadOf, panelStatusOf } from "./ask-panel.js";
 import { MOUSE_OFF } from "./editor.js";
+import { pickWindowOf } from "./approval-panel.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";
@@ -197,6 +198,10 @@ export class Body {
     #lastInputRows = 1;
     #lastAnchorRow = 0;
     #frameTimer = null;
+    #inputFrame = null;
+    /** Body mutations and non-key redraws so far — the input frame's
+     *  "did anything but typing change the screen?" */
+    #runMarks = 0;
     #spinnerTimer = null;
     #spinnerI = 0;
     #lastThinking = null;
@@ -520,6 +525,8 @@ export class Body {
             this.#write(`${p.red}  failed: ${escapeTerminal(error.slice(0, 160))}${p.reset}\n`);
         }
     }
+    /** `untimed`: 4c's replay settles a card from the durable log, whose
+     *  events carry no clock — the card then says nothing about time. */
     toolResult(callId, result) {
         const call = this.#pendingCalls.get(callId);
         if (call !== undefined) {
@@ -543,7 +550,7 @@ export class Body {
             cell.isError = result.isError;
             cell.resultText = result.content;
             cell.reason = result.reason ?? null;
-            cell.doneAt = Date.now();
+            cell.doneAt = result.untimed === true ? null : Date.now();
             cell.done = true;
         }
         this.#mark();
@@ -692,6 +699,31 @@ export class Body {
         this.#cells.push({ kind: "terminal", label: label.trim(), line: statusLineText, done: true });
         this.#mark();
     }
+    /**
+     * 4c — fold what `replay` puts on the body into ONE row. The replayed
+     * cells are the same cells a live run makes (the caller drives the
+     * ordinary mutations), moved out of the transcript into the fold cell:
+     * the row commits as one line and never expands on screen — so a resize
+     * reprint redraws one row however long the history — and the ctrl+r
+     * viewer reads them. Mutations only schedule frames, so nothing the
+     * replay adds can have committed before it is moved. Active bodies
+     * only: a pipe has no viewer to read a fold with (the caller prints the
+     * plain tail there).
+     */
+    fold(label, replay, summary = null) {
+        if (!this.#isActive())
+            return;
+        const start = this.#cells.length;
+        replay();
+        this.#closeOpenThinking();
+        this.#closeOpenText();
+        const children = this.#cells.splice(start);
+        for (const cell of children)
+            if (!cell.done)
+                cell.done = true; // a replay settles; nothing in a fold is live
+        this.#cells.push({ kind: "fold", label, children, summary, done: true });
+        this.#mark();
+    }
     notice(text) {
         if (!this.#isActive()) {
             this.#closeOpenThinking();
@@ -935,8 +967,15 @@ export class Body {
             const cell = this.#cells[idx];
             if (cell === undefined)
                 continue;
-            // R13 — the viewer's FOLD entry retired with the fold: every
-            // entry is now a card, and a card's entry is its own full body.
+            // 4c — the resumed history's fold: the head is its one row, the
+            // body is the replayed turns rendered at the viewer's width —
+            // the checkpoint's summary first when it is one.
+            if (cell.kind === "fold") {
+                out.push({ head: cellComponent(cell).render(inner, ctx)[0] ?? "", body: this.#foldBody(cell, inner, ctx) });
+                continue;
+            }
+            // R13 — every other entry is a card, and a card's entry is its
+            // own full body.
             if (cell.kind !== "tool")
                 continue;
             // the tool card's FULL body — the same rows its own ctrl+o
@@ -959,6 +998,24 @@ export class Body {
         }
         return out;
     }
+    /** 4c — a fold's children as the transcript would have shown them: each
+     *  cell's own render, spaced by the body's own formula (no blank between
+     *  two blocks of one message). */
+    #foldBody(cell, W, ctx) {
+        const out = [];
+        let prev = null;
+        let prevKind = null;
+        const cells = cell.summary === null ? cell.children : [{ kind: "raw", lines: cell.summary.split("\n"), done: true, wrap: "words" }, ...cell.children];
+        for (const child of cells) {
+            const rows = cellComponent(child).render(W, ctx);
+            if (rows.length === 0)
+                continue;
+            out.push(...(prevKind === "md" && child.kind === "md" ? rows : bodySpacing(prev, rows)));
+            prev = rows;
+            prevKind = child.kind;
+        }
+        return out;
+    }
     /** The viewer's band: its title, its list, its keys. */
     #viewerBand(W) {
         if (this.#viewer === null)
@@ -1185,6 +1242,13 @@ export class Body {
     panelOptionRows() {
         return this.#panelRowSpan;
     }
+    /** B (review of this round): the pick panel's window for the frame last
+     *  drawn — the renderer's own value, not a second derivation. `null` when
+     *  no pick panel was on screen. */
+    #pickWin = null;
+    visiblePickWindow() {
+        return this.#pickWin;
+    }
     /** SIGWINCH: clear the OLD live area (recorded geometry, ED only —
      *  zero LF, zero \x1b[3J — the shell history untouched), then the
      *  full-redraw path at the NEW geometry (O(height), zero replay).
@@ -1513,20 +1577,64 @@ export class Body {
         return 1 + leadWidth(lead) + st.cursor;
     }
     /** The old dock's redraw — the editor's onRender target: mark + the
-     *  scheduler (16ms coalescing — the old sync draw coalesces the same). */
-    redraw() {
+     *  scheduler (16ms coalescing — the old sync draw coalesces the same).
+     *
+     *  Item 6: a KEY-originated redraw paints on the next tick and takes
+     *  the pending trailing frame with it. Keyboard input is the one
+     *  latency-sensitive source: the trailing window made every key wait
+     *  16 ms, and 40 ms on Terminal.app — where an IME commit erases the
+     *  terminal's marked text at once and the committed characters came
+     *  back a frame window later, a visible blink. Stream, tool and
+     *  spinner marks keep the trailing window exactly (the conservative
+     *  mode's throughput protection is for them). setImmediate, not a
+     *  synchronous paint: every mutation one chunk of keys makes still
+     *  lands in one frame. */
+    redraw(fromKey = false) {
         if (!this.#isActive())
             return;
         this.#dirty = true;
+        if (fromKey) {
+            this.#scheduleInputFrame();
+            return;
+        }
+        this.#runMarks += 1; // a non-key redraw is not typing: it keeps the window
         this.#scheduleFrame();
     }
     // ---- the scheduler (event-driven; zero heartbeat timers) ----
     #mark() {
         if (!this.#isActive())
             return;
+        this.#runMarks += 1;
         this.#dirty = true;
         this.#scheduleFrame();
     }
+    #scheduleInputFrame() {
+        if (this.#inputFrame !== null)
+            return;
+        const marksAtKey = this.#runMarks;
+        this.#inputFrame = setImmediate(() => {
+            this.#inputFrame = null;
+            // A key whose consequence is run state (an approval verdict, a
+            // submit) mutates the body before this tick. That frame carries
+            // the run, so it keeps the run's trailing window, exactly as
+            // before: painting it now showed an approved write's transient
+            // live card for one frame before its result settled.
+            if (this.#runMarks !== marksAtKey) {
+                if (this.#dirty)
+                    this.#scheduleFrame();
+                return;
+            }
+            if (this.#frameTimer !== null) {
+                clearTimeout(this.#frameTimer);
+                this.#frameTimer = null;
+            }
+            if (this.#dirty) {
+                this.#dirty = false;
+                this.render();
+            }
+        });
+        this.#inputFrame.unref();
+    }
     #scheduleFrame() {
         if (this.#frameTimer !== null)
             return;
@@ -1574,6 +1682,10 @@ export class Body {
     }
     /** Teardown — flush a pending frame, stop the timers. */
     close() {
+        if (this.#inputFrame !== null) {
+            clearImmediate(this.#inputFrame);
+            this.#inputFrame = null;
+        }
         if (this.#frameTimer !== null) {
             clearTimeout(this.#frameTimer);
             this.#frameTimer = null;
@@ -1749,6 +1861,7 @@ export class Body {
         // at when they clicked, which is this one.
         this.#panelRowSpan =
             live.panelSpan === null ? null : { top: liveTop + live.panelSpan.offset, count: live.panelSpan.count, first: live.panelSpan.first };
+        this.#pickWin = live.pickWin ?? null;
         // 5. the frame bytes.
         this.#paint(W, H, liveTop, liveLines, liveRowsTotal, chrome);
     }
@@ -1849,7 +1962,11 @@ export class Body {
             // fires on it. W22: the queue band sits below the panel — the
             // cap shrinks by it.
             const frame = panelFrameOf(panel, W, capped);
-            return { lines: frame.rows, panelSpan: frame.options };
+            // B (review of this round): the pick window THIS frame draws. The size
+            // depends on the budget, so the renderer is the only producer — the
+            // digit keys are handed this value instead of deriving a second one.
+            const pick = panel.pick ?? null;
+            return { lines: frame.rows, panelSpan: frame.options, pickWin: pick === null ? null : pickWindowOf(panel.view, pick.cursor, pick.phase, capped) };
         }
         return { lines: this.#liveProjection(W, ctx, cap), panelSpan: null };
     }
@@ -2024,6 +2141,9 @@ export class Body {
         // oldest-first, so the newest cut is at the front.
         if (cell.kind === "tool" && lines.some((l) => l.includes("ctrl+o")))
             this.#collapsed.unshift(i);
+        // 4c: a fold is read in the viewer and nowhere else.
+        if (cell.kind === "fold")
+            this.#collapsed.unshift(i);
         this.#lineCache[i] = lines;
         const placed = this.#space(i, i > 0 ? this.#lineCache[i - 1] : null, lines);
         this.#committed += 1;
@@ -2762,6 +2882,11 @@ export class Dock {
     panelOptionRows() {
         return compositorRef?.panelOptionRows() ?? null;
     }
+    /** B (review of this round): the pick panel's window for the frame last
+     *  drawn — what the digit keys must name. */
+    visiblePickWindow() {
+        return compositorRef?.visiblePickWindow() ?? null;
+    }
     setStatus(text, hint) {
         compositorRef?.setStatus(text, hint ?? null);
     }
@@ -2848,8 +2973,8 @@ export class Dock {
     editCol() {
         return compositorRef?.editCol() ?? 1;
     }
-    redraw() {
-        compositorRef?.redraw();
+    redraw(fromKey = false) {
+        compositorRef?.redraw(fromKey);
     }
 }
 /** The one-compositor registry — the Dock façade routes to it. */

package/dist/context-ledger.d.ts

@@ -58,6 +58,11 @@ export interface ContextLedger {
  * the detail text rides after them, dim, and is cut by the caller's
  * width if it must be.
  */
+/** 0.40.0 — the ONE fill rule for a ▰▱ meter: `ratio` of `cells`, rounded,
+ *  clamped to the bar. The `/context` bar and the compacting row's bar both
+ *  draw through it, so the two cannot fill differently. Plain glyphs; the
+ *  caller styles them. */
+export declare function meterGlyphs(ratio: number, cells: number): string;
 export declare function contextRows(ledger: ContextLedger): string[];
 /** TUI2-R1 (E) — the honest fallback. The ledger is written PER REQUEST:
  *  a session that has not called the model yet has no sidecar, and the

package/dist/context-ledger.js

@@ -45,15 +45,24 @@ function k(n) {
  * the detail text rides after them, dim, and is cut by the caller's
  * width if it must be.
  */
+/** 0.40.0 — the ONE fill rule for a ▰▱ meter: `ratio` of `cells`, rounded,
+ *  clamped to the bar. The `/context` bar and the compacting row's bar both
+ *  draw through it, so the two cannot fill differently. Plain glyphs; the
+ *  caller styles them. */
+export function meterGlyphs(ratio, cells) {
+    const filled = Math.max(0, Math.min(cells, Math.round((Number.isFinite(ratio) ? ratio : 0) * cells)));
+    return `${"\u25b0".repeat(filled)}${"\u25b1".repeat(cells - filled)}`;
+}
 export function contextRows(ledger) {
     const p = palette();
     const used = ledger.systemPrompt + ledger.toolTable + ledger.skillsIndex + ledger.envelope + ledger.messages;
     const free = Math.max(0, ledger.window - used);
     const ratio = ledger.window > 0 ? Math.min(1, used / ledger.window) : 1;
-    const filled = Math.max(0, Math.min(BAR_CELLS, Math.round(ratio * BAR_CELLS)));
+    const bar = meterGlyphs(ratio, BAR_CELLS);
+    const filled = bar.indexOf("\u25b1") < 0 ? BAR_CELLS : bar.indexOf("\u25b1");
     const rows = [
         `${p.bold}context — ${k(used)} / ${k(ledger.window)} tokens (${Math.round(ratio * 100)}%)${p.reset}`,
-        `${p.bold}${"▰".repeat(filled)}${p.reset}${p.dim}${"▱".repeat(BAR_CELLS - filled)}${p.reset}`,
+        `${p.bold}${bar.slice(0, filled)}${p.reset}${p.dim}${bar.slice(filled)}${p.reset}`,
     ];
     /** One surface row: the label at 14 columns, the count right-aligned
      *  at 5, then the dim detail. */

package/dist/editor.d.ts

@@ -27,13 +27,20 @@ import { type PanelState, type PanelVerdict, type PanelView, type SaferAnswer }
 import { type AtItem, type AtMatch } from "./at-picker.js";
 import { type SessionCardView, type SessionPickState } from "./session-picker.js";
 /**
- * TUI2-R3v2 ② — the mouse-mode bytes, stated once.
+ * TUI2-R3v2 ②, corrected by the owner's ruling of 2026-09-21 (finding
+ * DC-56) — the mouse-mode bytes, stated once.
  *
  * ?1000 is the button-event report and ?1006 is the SGR encoding that
  * makes it parseable past column 95 (the legacy X10 encoding packs the
- * coordinate into one byte and simply breaks on a wide terminal). Both
- * 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.
+ * coordinate into one byte and simply breaks on a wide terminal). kiso
+ * still RESETS them — on entry (a previous process may have died with
+ * reporting left on) and on exit — but it no longer ENABLES them, because
+ * a terminal that is reporting stops scrolling its own scrollback: a
+ * surface that takes the mouse takes the history with it. kiso's
+ * transcript lives in that scrollback by design, and the first version of
+ * this feature locked it exactly where a person most wants to read back —
+ * under a blocking question. The history wins: no surface claims the
+ * mouse, and every surface keeps its keys.
  */
 /**
  * R5 — the viewer's key table, as a pure function of the input chunk.
@@ -45,7 +52,6 @@ import { type SessionCardView, type SessionPickState } from "./session-picker.js
  * 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 ";
 export declare const PROMPT_WIDTH: number;
@@ -65,7 +71,7 @@ export declare const MENU_ITEMS: readonly MenuItem[];
 export declare class Editor {
     #private;
     readonly closed: Promise<void>;
-    constructor(onRender: () => void);
+    constructor(onRender: (fromKey: boolean) => void);
     /**
      *  DC-7 — the terminal answering a question kiso asked it.
      *
@@ -153,6 +159,9 @@ export declare class Editor {
         items: readonly MenuItem[];
         selected: number;
     } | null;
+    /** 0.40.1 — bind the menu's extra entries (the CLI binds the installed
+     *  skills). A function, read per keystroke, never a snapshot. */
+    bindMenuExtras(extras: () => readonly MenuItem[]): void;
     /** KC3 §3 — bind the file source. The tui owns no file list and
      *  never touches a disk (input is data, output is bytes): the CLI
      *  feeds the paths, and until it does, the picker cannot open at
@@ -168,7 +177,7 @@ export declare class Editor {
         capped: boolean;
     } | null;
     /** Open the picker on a bound card source (PickInput, S5). */
-    beginPick(cards: () => readonly SessionCardView[], onPick: (id: string | null) => void): void;
+    beginPick(cards: () => readonly SessionCardView[], onPick: (id: string | null) => void, here?: string): void;
     pickState(): SessionPickState | null;
     /** One-shot question mode: the NEXT submit answers, not a turn. */
     question(_query: string, cb: (answer: string) => void): void;
@@ -218,6 +227,12 @@ export declare class Editor {
         count: number;
         first?: number;
     } | null) | null): void;
+    /** B: the pick window the last frame drew — the Dock's value, not the
+     *  editor's guess. Same pull-on-demand shape as `bindPanelRows`. */
+    bindPickWindow(fn: (() => {
+        first: number;
+        size: number;
+    } | null) | null): void;
     /** R3a — cross-session input history: seed the recall buffer and
      *  register the append sink. The cap and the adjacent-duplicate
      *  collapse are unchanged; the seed takes the TAIL of what the CLI