@vincemakes/kiso-tui 0.7.0 → 0.9.0

package/dist/editor.d.ts

@@ -23,7 +23,7 @@
  */
 import { charWidth, displayWidth, widthOf } from "./width.js";
 export { charWidth, displayWidth, widthOf };
-import { type PanelState, type PanelVerdict, type PanelView } from "./approval-panel.js";
+import type { PanelState, PanelVerdict, PanelView } from "./approval-panel.js";
 import { type AtItem, type AtMatch } from "./at-picker.js";
 export declare const PROMPT = "\u258C ";
 export declare const PROMPT_WIDTH: number;
@@ -60,6 +60,9 @@ export declare class Editor {
     bindQueue(state: () => readonly string[], pop: () => string | null): void;
     /** The whole buffer as text (the CLI's line()/clearLine()). */
     line(): string;
+    /** TUI2-R1 (D): whether the keys sheet is up — the compositor's slot
+     *  read (bound like the menu and the picker). */
+    sheetOpen(): boolean;
     clearLine(): void;
     /** The dock's input-row state — ADDITIVE (§5): `line` + `cursor` keep
      *  their legacy meaning (the CURSOR LINE's visible slice and the

package/dist/editor.js

@@ -26,7 +26,9 @@ import { charWidth, displayWidth, leadWidth, widthOf } from "./width.js";
 // authority) — re-exported so the editor's public surface is unchanged.
 export { charWidth, displayWidth, widthOf };
 import { palette } from "./render.js";
-import { panelLead } from "./approval-panel.js";
+// KC3.5: the panel-slot dispatchers — the ask branch folded into the
+// W21 lead/rows, so this file keeps ONE panel and one key owner.
+import { askCommitCustom, askKey, askStart, panelLead } from "./ask-panel.js";
 import { AT_VISIBLE, atFilter } from "./at-picker.js";
 // TUI v4 #16d: the input row is the blue brick + the edit area — the
 // "you>" text is gone (the brick IS the prompt; the pipe path's readline
@@ -40,6 +42,8 @@ export const MENU_ITEMS = [
     { name: "/think", desc: "show the last full thinking block" },
     { name: "/last", desc: "show the most recent tool call's input and output" },
     { 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" },
     { name: "/help", desc: "print this list of commands" },
 ];
 /** KC1 §3 — the newline code point. Every source (paste, Ctrl+J, the
@@ -107,6 +111,12 @@ export class Editor {
     // coexist; the editor never interprets the key itself.
     #expandCbs = [];
     #onRender;
+    /** TUI2-R1 (D): the keys sheet — a static one-screen overlay opened by
+     *  `?` on an empty composer and closed by the next key, whatever it
+     *  is. Deliberately a BOOLEAN and not a panel: the panel machinery
+     *  exists for interactions (a lead, a status, a reducer, a stashed
+     *  buffer), and the sheet has no interaction to speak of. */
+    #sheetOpen = false;
     #menuOpen = false; // v3 §04: the slash-command menu
     #menuSel = 0;
     // KC3 §3 — the @ file picker. THREE fields and no more: the armed
@@ -192,6 +202,11 @@ export class Editor {
     line() {
         return String.fromCodePoint(...this.#chars);
     }
+    /** TUI2-R1 (D): whether the keys sheet is up — the compositor's slot
+     *  read (bound like the menu and the picker). */
+    sheetOpen() {
+        return this.#sheetOpen;
+    }
     clearLine() {
         this.#chars = [];
         this.#cursor = 0;
@@ -439,6 +454,7 @@ export class Editor {
             view,
             phase: "options",
             sel: 0,
+            ask: view.ask === undefined ? null : askStart(view.ask),
             amend: "yes",
             onCommit,
             stash: { chars: this.#chars, cursor: this.#cursor, scroll: this.#scroll },
@@ -463,7 +479,7 @@ export class Editor {
         const panel = this.#panel;
         if (panel === null)
             return null;
-        return { view: panel.view, phase: panel.phase, sel: panel.sel };
+        return { view: panel.view, phase: panel.phase, sel: panel.sel, ...(panel.ask === null ? {} : { ask: panel.ask }) };
     }
     enter() {
         if (this.#entered)
@@ -493,7 +509,7 @@ export class Editor {
         // W21: the panel's lead owns the row while up (the brick returns
         // when the panel closes).
         const panel = this.#panel;
-        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel) : `${p.bold}${PROMPT}${p.reset}`;
+        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel, panel.ask ?? undefined) : `${p.bold}${PROMPT}${p.reset}`;
         // W23: the ONE width authority — leadWidth(lead), the ANSI-stripped
         // visible width (the styled panel lead / the styled brick measure
         // the same as their plain text — a lead can never measure
@@ -507,6 +523,17 @@ export class Editor {
     feed(raw) {
         const text = this.#pending + this.#decoder.decode(raw, { stream: true });
         this.#pending = "";
+        // TUI2-R1 (D): the sheet is up — ANY key closes it, and the key
+        // that closed it is CONSUMED. The whole chunk goes, deliberately:
+        // an arrow key is three bytes, and closing on the first while
+        // letting `[A` fall through as literal text would be a sheet that
+        // types into your composer on the way out. A dismissal costs one
+        // keystroke; that is the entire contract.
+        if (this.#sheetOpen) {
+            this.#sheetOpen = false;
+            this.#onRender();
+            return;
+        }
         let i = 0;
         while (i < text.length) {
             const c = text[i];
@@ -520,6 +547,45 @@ export class Editor {
                 // text); ctrl-c still rides the SIGINT handler (which
                 // cancels the panel).
                 const panel = this.#panel;
+                // KC3.5: an ASK panel routes its own keys — the digits pick
+                // (single-select advances, multi toggles), space toggles at
+                // the cursor, `t` opens the type-your-own line (the
+                // rule-input phase's shape: the buffer is the editor's, so
+                // only esc and enter are intercepted while typing), esc
+                // declines the whole call. Everything else falls through to
+                // the ordinary editing chain below.
+                if (panel.ask !== null) {
+                    const typing = panel.ask.phase === "custom";
+                    if (c === "\x1b" && !text.slice(i + 1).startsWith("[") && !text.slice(i + 1).startsWith("O")) {
+                        this.#askStep("esc");
+                        i += 1;
+                        continue;
+                    }
+                    if (c === "\x0d" || c === "\x0a") {
+                        this.#askStep(typing ? "commit" : "enter");
+                        i += 1;
+                        continue;
+                    }
+                    if (!typing && (c === " " || (c !== undefined && c >= "1" && c <= "4") || c === "t" || c === "T")) {
+                        this.#askStep(c === " " ? "space" : c === "T" ? "t" : c);
+                        i += 1;
+                        continue;
+                    }
+                    // an ask at rest swallows stray PRINTABLE keys — the panel
+                    // owns them, and a typed "/" or "@" must not arm the menu
+                    // or the picker underneath. Two things are never
+                    // swallowed: the CSI/SS3 introducer, because ←/↑/↓ are
+                    // the ask's own keys and the parser below routes them
+                    // (the T-Q1 red), and the CONTROL characters, because
+                    // ctrl-c must still reach the SIGINT handler that
+                    // cancels the panel — W21's own rule, and what the T-Q6
+                    // race red caught: an abort with the panel up did
+                    // nothing at all.
+                    if (!typing && c !== undefined && c >= " " && c !== "\x7f") {
+                        i += 1;
+                        continue;
+                    }
+                }
                 if (c === "\x1b" && !text.slice(i + 1).startsWith("[") && !text.slice(i + 1).startsWith("O")) {
                     this.#panelEsc();
                     i += 1;
@@ -710,6 +776,17 @@ export class Editor {
                     cb();
                 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
+                // it is the question mark a human is typing, and #composerIdle
+                // already encodes "no panel, no menu, no picker, no browse".
+                // The precedence can only ever ADD: every state that used to
+                // insert a `?` still inserts one.
+                this.#sheetOpen = true;
+                this.#onRender();
+                i += 1;
+            }
             else if (c !== undefined && c < " ") {
                 i += 1; // other control — ignored
             }
@@ -760,7 +837,10 @@ export class Editor {
             // panel owns the keys while up (↑↓ do nothing — the panel has no
             // ↑↓ role).
             if (this.#panel !== null) {
-                /* the panel owns the keys */
+                // W21: the panel owns the keys. KC3.5: an ask uses ↑↓ for
+                // the option cursor (the approval panel still has no ↑↓ role).
+                if (this.#panel.ask !== null && this.#panel.ask.phase === "options")
+                    this.#askStep(final === "A" ? "up" : "down");
             }
             else if (this.#menuOpen) {
                 if (final === "A")
@@ -798,7 +878,12 @@ export class Editor {
             this.#onRender();
         }
         else if (final === "D") {
-            this.#move(-1);
+            // KC3.5: ← walks the ask BACK a question (the ‹ n/m › walk); at
+            // question one it stays put — esc is the decline, never ←.
+            if (this.#panel?.ask != null && this.#panel.ask.phase === "options")
+                this.#askStep("left");
+            else
+                this.#move(-1);
         }
         else if (final === "C") {
             this.#move(1);
@@ -913,6 +998,33 @@ export class Editor {
         else if (panel.sel === 3)
             this.#panelClose({ action: "deny", reason: "" });
     }
+    /**
+     * KC3.5 — one ask key: the pure reducer decides, this method applies.
+     * The buffer is cleared on every phase change so the type-your-own
+     * line starts empty and its text never leaks back into the options
+     * (the rule-input phase's own discipline). A step that produced a
+     * RESULT closes the panel with it — the stash/restore is the W21
+     * path, identical for an answer and for a decline.
+     */
+    #askStep(key) {
+        const panel = this.#panel;
+        if (panel === null || panel.ask === null)
+            return;
+        const spec = panel.view.ask;
+        const before = panel.ask.phase;
+        const step = key === "commit" ? askCommitCustom(spec, panel.ask, this.line()) : askKey(spec, panel.ask, key);
+        panel.ask = step.state;
+        if (step.state.phase !== before) {
+            this.#chars = [];
+            this.#cursor = 0;
+            this.#scroll = 0;
+        }
+        if (step.result !== undefined) {
+            this.#panelClose({ action: "answers", result: step.result });
+            return;
+        }
+        this.#onRender();
+    }
     #panelClose(verdict) {
         const panel = this.#panel;
         if (panel === null)
@@ -1162,7 +1274,7 @@ export class Editor {
         // W23: the ONE width authority — leadWidth(lead) — the cap follows
         // the lead the editor itself renders (the panel lead when the panel
         // owns the keys, the brick otherwise): maxW = W − walls − lead.
-        const lead = this.#panel !== null ? panelLead(this.#panel.view, this.#panel.phase, this.#panel.sel) : PROMPT;
+        const lead = this.#panel !== null ? panelLead(this.#panel.view, this.#panel.phase, this.#panel.sel, this.#panel.ask ?? undefined) : PROMPT;
         const leadW = leadWidth(lead);
         const maxW = Math.max(1, W - leadW - 4); // W6: the box's walls (2+2) — the visible line fits the box's inner width; the "…" rides inside
         // KC1: the scroll is the CURSOR LINE's own offset — a single-line

package/dist/index.d.ts

@@ -7,10 +7,13 @@
  */
 export { Body, Dock, CURSOR_MARKER, type BodyOptions } from "./compositor.js";
 export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, type PanelArgs, type PanelFlavor, type PanelPhase, type PanelSel, type PanelState, type PanelVerdict, type PanelView, } from "./approval-panel.js";
-export { Container, foldLine, visibleWidth, SPINNER, type Component, type FrameCtx } from "./components.js";
+export { Container, foldLine, foldWords, visibleWidth, SPINNER, type Component, type FrameCtx } from "./components.js";
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, type MenuItem, } from "./editor.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, type Palette, type PathResolver, type RecapStats, type ResumeMeta, type RenderInput, type RenderResult, type RunUsage, } from "./render.js";
 export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResult } from "./diff.js";
-export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.js";
+export { STATUS_GLYPHS, cacheHitPct, idleStatus, runningStatus, type StatusMeter } from "./status.js";
+export { contextRows, contextUnavailableRows, type ContextLedger } from "./context-ledger.js";
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, type TrustArtifact } from "./strings.js";
 export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, longestRun, type AtItem, type AtMatch } from "./at-picker.js";
+export { ASK_HEADER_CAP, ASK_MAX_OPTIONS, ASK_MAX_QUESTIONS, ASK_MIN_OPTIONS, askAffordance, askAnswers, askBlockRows, askCommitCustom, askDeclineAll, askDeclineList, askKey, askLeadPlain, askStart, askStatus, askView, type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, type AskStep, } from "./ask-panel.js";
+export { KEY_BINDINGS, PANEL_KEYS_ROW, extensionsBannerText, helpRows, keysHelpRow, keysSheetRows, unansweredAskView, type BannerExtension, type KeyBinding } from "./strings.js";

package/dist/index.js

@@ -10,13 +10,16 @@ export { Body, Dock, CURSOR_MARKER } from "./compositor.js";
 // that replaces the running tool's live window while a human-chain
 // approval is pending (the shape authority is the committed preview).
 export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, } from "./approval-panel.js";
-export { Container, foldLine, visibleWidth, SPINNER } from "./components.js";
+export { Container, foldLine, foldWords, visibleWidth, SPINNER } from "./components.js";
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, } from "./editor.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.js";
 export { editFileDiff, truncateDiff, writeFileDiff } from "./diff.js";
 // KC2 §5: the status rows' formatters — the CLI keeps the state and the
 // repaint, the terminal layer owns what the row says.
-export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.js";
+export { STATUS_GLYPHS, cacheHitPct, idleStatus, runningStatus } from "./status.js";
+// TUI2-R1 (E): /context's attribution rows — a pure function of the
+// counts the trace sidecar already records (the CLI reads, this renders).
+export { contextRows, contextUnavailableRows } from "./context-ledger.js";
 // KC3 §1 (the extraction): the human-facing strings — the prompt, the
 // project-trust listing/view/note, the uncertain execution's view. The
 // FLOW (who is asked, what a verdict means) stays in the cli.
@@ -24,3 +27,12 @@ export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrusted
 // KC3 §3/§5: the @ file picker's pure half — the subsequence filter, the
 // deterministic rank, and the ONE cap the CLI's file source shares.
 export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, longestRun } from "./at-picker.js";
+// KC3.5 (the ask round): the ask view — the panel machinery generalized.
+// The cli composes the view and hands the answers to the tool; the keys,
+// the rows and the walk are the terminal layer's.
+export { ASK_HEADER_CAP, ASK_MAX_OPTIONS, ASK_MAX_QUESTIONS, ASK_MIN_OPTIONS, askAffordance, askAnswers, askBlockRows, askCommitCustom, askDeclineAll, askDeclineList, askKey, askLeadPlain, askStart, askStatus, askView, } from "./ask-panel.js";
+// KC3.5 §4: the interrupted-ask copy — the SAME uncertainty gate, said
+// honestly for a question nobody answered (the ① probe's surface).
+// TUI2-R1 (D): the keys sheet + THE key table — one source for the ?
+// overlay and /help's keys row.
+export { KEY_BINDINGS, PANEL_KEYS_ROW, extensionsBannerText, helpRows, keysHelpRow, keysSheetRows, unansweredAskView } from "./strings.js";

package/dist/status.d.ts

@@ -33,6 +33,36 @@ export declare const STATUS_GLYPHS: readonly ["▖", "▘", "▝", "▗"];
  * because it is on screen exactly when the gesture is useful.
  */
 export declare function runningStatus(glyph: string, since: number, outTokens: number | null, ctxRatio: number): string;
+/**
+ * TUI2-R1 (E) — the idle row's meter: what the session has SPENT, next
+ * to what it has left.
+ *
+ * Both fields are optional and both are omitted when unknown, because
+ * the row's job is to be true rather than complete:
+ *
+ *   - `cacheHitPct` is cacheRead / (fresh + cacheRead) — the E2
+ *     denominator (the pinned sentence: it cannot exceed 100%). A
+ *     session with no usage yet has no cache hit rate, and an
+ *     unmeasured cache is NOT a 0% cache, so it renders nothing.
+ *   - `costUsd` is the CANONICAL cost, which is null whenever the
+ *     pricing table has no rate for the route. Null renders nothing.
+ *     No rate table, no number — kiso does not invent a price.
+ */
+export interface StatusMeter {
+    readonly cacheHitPct: number | null;
+    readonly costUsd: number | null;
+}
 /** The IDLE row: the approval tier as the CALLER names it, the /mode
- *  hint, the model driving the session, and the ctx estimate. */
-export declare function idleStatus(tier: string, model: string, ctxRatio: number): string;
+ *  hint, the model driving the session, the TUI2-R1 meter when there is
+ *  one, and the ctx estimate. Called without a meter — or with one that
+ *  knows nothing — the row is byte-identical to the pre-round row. */
+export declare function idleStatus(tier: string, model: string, ctxRatio: number, meter?: StatusMeter): string;
+/** TUI2-R1 (E) — the cache hit rate the status row shows, from the usage
+ *  the CLI already tracks. The denominator is the TOTAL the model was
+ *  given (fresh + cacheRead), which is the E2 ruling's own: cacheRead
+ *  over fresh alone once rendered 923%. No input at all → null, never a
+ *  zero. */
+export declare function cacheHitPct(usage: {
+    in: number | null;
+    cache: number | null;
+}): number | null;

package/dist/status.js

@@ -46,7 +46,28 @@ export function runningStatus(glyph, since, outTokens, ctxRatio) {
     return `${glyph} working ${seconds}s${out} · esc stop · alt+⏎ redirect · ctx left ~${ctxLeft(ctxRatio)}%`;
 }
 /** The IDLE row: the approval tier as the CALLER names it, the /mode
- *  hint, the model driving the session, and the ctx estimate. */
-export function idleStatus(tier, model, ctxRatio) {
-    return `▸ ${tier} · /mode to switch · ${model} · ctx left ~${ctxLeft(ctxRatio)}%`;
+ *  hint, the model driving the session, the TUI2-R1 meter when there is
+ *  one, and the ctx estimate. Called without a meter — or with one that
+ *  knows nothing — the row is byte-identical to the pre-round row. */
+export function idleStatus(tier, model, ctxRatio, meter) {
+    const parts = [`▸ ${tier}`, "/mode to switch", model];
+    if (meter?.cacheHitPct != null)
+        parts.push(`CH ${Math.round(meter.cacheHitPct)}%`);
+    if (meter?.costUsd != null)
+        parts.push(`$${meter.costUsd.toFixed(4)}`);
+    parts.push(`ctx left ~${ctxLeft(ctxRatio)}%`);
+    return parts.join(" · ");
+}
+/** TUI2-R1 (E) — the cache hit rate the status row shows, from the usage
+ *  the CLI already tracks. The denominator is the TOTAL the model was
+ *  given (fresh + cacheRead), which is the E2 ruling's own: cacheRead
+ *  over fresh alone once rendered 923%. No input at all → null, never a
+ *  zero. */
+export function cacheHitPct(usage) {
+    const fresh = usage.in;
+    const cached = usage.cache;
+    if (fresh === null || cached === null)
+        return null;
+    const total = fresh + cached;
+    return total > 0 ? (cached / total) * 100 : null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tui",
-  "version": "0.7.0",
+  "version": "0.9.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.7.0"
+    "@vincemakes/kiso-tui-cells": "0.9.0"
   }
 }