@vincemakes/kiso-tui 0.16.1 → 0.16.3

package/dist/compositor.d.ts

@@ -52,7 +52,7 @@ export interface AtPanelState {
     readonly selected: number;
     readonly capped: boolean;
 }
-import { type ResumeMeta } from "./render.js";
+import { type BannerMeta, type ResumeMeta } from "./render.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). */
@@ -171,7 +171,7 @@ export declare class Body {
      *  list re-gates with the tier (BIG only) and re-times with the
      *  frame. The inactive path keeps the historical bytes (no resume —
      *  the pipe contract). */
-    banner(version: string, extensionsText: string, resume?: ResumeMeta[]): void;
+    banner(version: string, extensionsText: string, resume?: ResumeMeta[], meta?: BannerMeta | undefined): void;
     raw(lines: string[], wrap?: "words"): void;
     /** The last COMPLETE thinking block, for /think. */
     lastThinking(): string | null;
@@ -239,6 +239,20 @@ export declare class Body {
      * that choice here, and has to pay carefully.
      */
     onResize(): void;
+    /**
+     * DC-3 — the ground arrived, so every colour on the held screen is
+     * stale.
+     *
+     * The terminal answers `OSC 11` a few milliseconds after startup, by
+     * which time the first frame is already painted with the no-ground
+     * palette. Rather than delay the opening to wait for an answer that
+     * may never come, the frame is painted at once and repainted when the
+     * answer lands. Invalidating the held screen is exactly what a resize
+     * does, for exactly the same reason — every row's bytes are wrong —
+     * so it rides the settle the resize already owns and costs one
+     * repaint, once per session.
+     */
+    onGroundChange(): void;
     /** W18: the status row's right-aligned hint is part of the status
      *  state — the compacting row passes "esc to cancel" (the affordance
      *  must survive repaints). */
@@ -295,6 +309,8 @@ export declare class Dock {
     enter(): void;
     exit(): void;
     onResize(): void;
+    /** DC-3 — the terminal answered what its background is; repaint. */
+    onGroundChange(): void;
     /** TUI2-R3v2 ②: where the last frame put the panel's clickable option
      *  rows (absolute screen rows). The editor binds this and does no row
      *  arithmetic of its own. */

package/dist/compositor.js

@@ -706,21 +706,21 @@ export class Body {
      *  list re-gates with the tier (BIG only) and re-times with the
      *  frame. The inactive path keeps the historical bytes (no resume —
      *  the pipe contract). */
-    banner(version, extensionsText, resume = []) {
+    banner(version, extensionsText, resume = [], meta) {
         if (!this.#isActive()) {
             this.#closeOpenThinking();
             this.#closeOpenText();
             const W = this.#opts.width() || 80; // a 0-size pty falls back
             const H = this.#opts.height();
             const p = palette();
-            for (const r of bannerLines(W, H, version, extensionsText))
+            for (const r of bannerLines(W, H, version, extensionsText, [], Date.now(), meta))
                 this.#write(`${p.dim}${r}${p.reset}\n`);
             this.#write("\n");
             return;
         }
         this.#closeOpenThinking();
         this.#closeOpenText();
-        this.#cells.push({ kind: "banner", version, extensionsText, resume, done: true });
+        this.#cells.push({ kind: "banner", version, extensionsText, resume, meta, done: true });
         this.#mark();
     }
     raw(lines, wrap) {
@@ -1092,6 +1092,23 @@ export class Body {
         if (this.#resizeTimer.unref !== undefined)
             this.#resizeTimer.unref();
     }
+    /**
+     * DC-3 — the ground arrived, so every colour on the held screen is
+     * stale.
+     *
+     * The terminal answers `OSC 11` a few milliseconds after startup, by
+     * which time the first frame is already painted with the no-ground
+     * palette. Rather than delay the opening to wait for an answer that
+     * may never come, the frame is painted at once and repainted when the
+     * answer lands. Invalidating the held screen is exactly what a resize
+     * does, for exactly the same reason — every row's bytes are wrong —
+     * so it rides the settle the resize already owns and costs one
+     * repaint, once per session.
+     */
+    onGroundChange() {
+        this.#screen = [];
+        this.onResize();
+    }
     /** The one repaint a drag earns, once its signals have stopped. */
     #settleResize() {
         if (!this.#resizePending || !this.#isActive())
@@ -2323,6 +2340,10 @@ export class Dock {
     onResize() {
         compositorRef?.onResize();
     }
+    /** DC-3 — the terminal answered what its background is; repaint. */
+    onGroundChange() {
+        compositorRef?.onGroundChange();
+    }
     /** TUI2-R3v2 ②: where the last frame put the panel's clickable option
      *  rows (absolute screen rows). The editor binds this and does no row
      *  arithmetic of its own. */

package/dist/editor.d.ts

@@ -56,6 +56,15 @@ export declare class Editor {
     #private;
     readonly closed: Promise<void>;
     constructor(onRender: () => void);
+    /**
+     *  DC-7 — the terminal answering a question kiso asked it.
+     *
+     *  The body is everything between `ESC ]` and the terminator, verbatim
+     *  and unparsed (`11;rgb:ffff/ffff/ffff`). The editor's job ends at
+     *  keeping it out of the draft; deciding what a report MEANS belongs to
+     *  whoever asked the question.
+     */
+    onOsc(cb: (body: string) => void): void;
     onLine(cb: (line: string) => void): void;
     onSigint(cb: () => void): void;
     onEot(cb: () => void): void;

package/dist/editor.js

@@ -81,6 +81,11 @@ const TAB = 0x09;
  *  the geometry stays legal down to the compositor's enter gate (H = 4
  *  ⇒ one row, exactly today's minimum). */
 const N_MAX = 6;
+/** DC-7 — the longest OSC kiso will hold while waiting for a terminator.
+ *  The reports it reads are tens of bytes; anything past this is a
+ *  payload for someone else, and holding it is how the editor goes
+ *  deaf. */
+const OSC_MAX = 1024;
 /** The dim "…" — the ONE truncation mark: the horizontal scroll's
  *  prefix (unchanged) and the viewport's hidden-rows markers. */
 const ELLIPSIS = "\x1b[2m…\x1b[0m";
@@ -270,6 +275,19 @@ export class Editor {
     #history = [];
     #historyIdx = null;
     #preBrowse = [];
+    // UD-1: minimal draft undo. Two stacks of FROZEN snapshots beside
+    // the one mutable buffer (the KC1 flat-buffer discipline holds —
+    // the stacks are history, never a second projection). A checkpoint
+    // is pushed only by a gesture about to discard ≥1 code point (the
+    // kills, the menu-esc clear, each queue-pop replacement, the
+    // @-apply splice); typing and single backspace push nothing — v1
+    // is loss-recovery, not char-granular edit history. ctrl+z
+    // restores text+cursor exactly; ctrl+y mirrors; undo never
+    // discards (what it replaces always lands on the redo stack).
+    // Both stacks clear on submit/clearLine — a sent turn is in the
+    // durable log and the ↑ history, not a loss.
+    #undoStack = [];
+    #redoStack = [];
     // W22: the pending-turn queue's bound state — the CLI's live slots
     // (chat.ts). ↑ pops the LAST queued message into the buffer and
     // enters the pop-mode (the walk: repeated ↑ pop older ones, each
@@ -280,7 +298,9 @@ export class Editor {
     #queueState = () => [];
     #queuePop = null;
     #queuePopMode = false;
-    #pending = ""; // an incomplete ESC/CSI prefix across chunks
+    #pending = ""; // an incomplete ESC/CSI/OSC prefix across chunks
+    /** DC-7: the terminal's own reports (OSC). Never a keystroke. */
+    #oscCb = null;
     #decoder = new TextDecoder();
     #entered = false;
     #onData;
@@ -293,6 +313,17 @@ export class Editor {
             this.#closedResolve = resolve;
         });
     }
+    /**
+     *  DC-7 — the terminal answering a question kiso asked it.
+     *
+     *  The body is everything between `ESC ]` and the terminator, verbatim
+     *  and unparsed (`11;rgb:ffff/ffff/ffff`). The editor's job ends at
+     *  keeping it out of the draft; deciding what a report MEANS belongs to
+     *  whoever asked the question.
+     */
+    onOsc(cb) {
+        this.#oscCb = cb;
+    }
     onLine(cb) {
         this.#lineCb = cb;
         // Flush submits that arrived before the handler was wired (typed
@@ -355,6 +386,8 @@ export class Editor {
         return this.#sheetOpen;
     }
     clearLine() {
+        this.#undoStack.length = 0; // UD-1
+        this.#redoStack.length = 0;
         this.#chars = [];
         this.#cursor = 0;
         this.#scroll = 0;
@@ -577,6 +610,8 @@ export class Editor {
         if (view === null)
             return;
         const insert = [...`@${view.matches[view.selected].path} `].map((ch) => ch.codePointAt(0));
+        if (this.#cursor - view.start >= 1)
+            this.#checkpoint(); // UD-1
         this.#chars.splice(view.start, this.#cursor - view.start, ...insert);
         this.#cursor = view.start + insert.length;
         this.#atClose();
@@ -1084,6 +1119,32 @@ export class Editor {
                     this.#csi(m[1], m[2]);
                     i += m[0].length + 1;
                 }
+                else if (rest.startsWith("]")) {
+                    // DC-7: an OSC is a message FROM the terminal — a background
+                    // colour answer, a theme-change notice, a clipboard report.
+                    // There was no branch for it, so the bytes fell through to
+                    // the literal-text path and the answer was typed into the
+                    // draft. The terminator is BEL **or** ST: Apple Terminal
+                    // answers `ESC ] 11 ; rgb:… BEL`, and ST is the standard.
+                    const end = /\x07|\x1b\\/.exec(rest);
+                    if (end === null) {
+                        const tail = text.slice(i);
+                        // The unterminated case is the SGR-1006 hazard by another
+                        // door: park it and a stream that never terminates grows
+                        // #pending forever until the editor goes deaf. A report
+                        // long enough to be a payload (OSC 52 carries a whole
+                        // clipboard) is not one we read, so past the cap it is
+                        // dropped rather than held.
+                        if (tail.length > OSC_MAX) {
+                            i = text.length;
+                            break;
+                        }
+                        this.#pending = tail; // incomplete OSC — wait for more
+                        break;
+                    }
+                    this.#oscCb?.(rest.slice(1, end.index));
+                    i += 1 + end.index + end[0].length;
+                }
                 else if (rest.startsWith("O")) {
                     i += 3; // SS3 (function keys) — ignored
                 }
@@ -1102,6 +1163,8 @@ export class Editor {
                     // v3 §04: Esc closes the menu and clears the buffer.
                     // CA-4: the closing esc consumes its burst (the `i += 1`
                     // convention) — a double-esc can never abort the turn.
+                    if (this.#chars.length > 0)
+                        this.#checkpoint(); // UD-1
                     this.#chars = [];
                     this.#cursor = 0;
                     this.#scroll = 0;
@@ -1201,6 +1264,14 @@ export class Editor {
                 this.#killWord();
                 i += 1;
             }
+            else if (c === "\x1a" || c === "\x1f") {
+                this.#undoOp(); // UD-1: ctrl+z (and the readline ctrl+_)
+                i += 1;
+            }
+            else if (c === "\x19") {
+                this.#redoOp(); // UD-1: ctrl+y
+                i += 1;
+            }
             else if (c === "\x01") {
                 this.#cursor = this.#cursorBounds().start; // A3: line-local (a single line starts at 0 — unchanged)
                 this.#reflow();
@@ -1891,8 +1962,66 @@ export class Editor {
         if (!this.#pasting)
             this.#onRender();
     }
+    // ---- UD-1: the undo machinery ----
+    /** The caps: entries and total code points (a D13-class 260KB paste
+     *  fits with room). Evict oldest; both stacks share the shape. */
+    static #UNDO_CAP = 64;
+    static #UNDO_CP_CAP = 2 * 1024 * 1024;
+    #snap() {
+        return { chars: [...this.#chars], cursor: this.#cursor };
+    }
+    #sameSnap(a, b) {
+        return a.cursor === b.cursor && a.chars.length === b.chars.length && a.chars.every((c, i) => c === b.chars[i]);
+    }
+    #capStack(stack) {
+        while (stack.length > _a.#UNDO_CAP)
+            stack.shift();
+        let total = stack.reduce((n, s) => n + s.chars.length, 0);
+        while (stack.length > 1 && total > _a.#UNDO_CP_CAP)
+            total -= stack.shift().chars.length;
+    }
+    /** Push the CURRENT state before a destructive gesture. Always
+     *  clears the redo stack (a new destruction forks history); the
+     *  push itself is deduped against the top. */
+    #checkpoint() {
+        this.#redoStack.length = 0;
+        const cur = this.#snap();
+        const top = this.#undoStack.at(-1);
+        if (top !== undefined && this.#sameSnap(top, cur))
+            return;
+        this.#undoStack.push(cur);
+        this.#capStack(this.#undoStack);
+    }
+    #restoreSnap(s) {
+        this.#chars = [...s.chars];
+        this.#cursor = s.cursor;
+        this.#scroll = 0;
+        this.#verticalGoalCol = null;
+        this.#reflow();
+        this.#refreshMenu();
+        if (!this.#pasting)
+            this.#onRender();
+    }
+    #undoOp() {
+        const prev = this.#undoStack.pop();
+        if (prev === undefined)
+            return;
+        this.#redoStack.push(this.#snap());
+        this.#capStack(this.#redoStack);
+        this.#restoreSnap(prev);
+    }
+    #redoOp() {
+        const next = this.#redoStack.pop();
+        if (next === undefined)
+            return;
+        this.#undoStack.push(this.#snap());
+        this.#capStack(this.#undoStack);
+        this.#restoreSnap(next);
+    }
     #killToStart() {
         const { start } = this.#cursorBounds(); // A3: line-local (0 on a single line — unchanged)
+        if (this.#cursor > start)
+            this.#checkpoint(); // UD-1
         this.#chars.splice(start, this.#cursor - start);
         this.#cursor = start;
         this.#reflow();
@@ -1901,6 +2030,8 @@ export class Editor {
     }
     #killToEnd() {
         const { end } = this.#cursorBounds(); // A3: line-local (the buffer's end on a single line — unchanged)
+        if (end > this.#cursor)
+            this.#checkpoint(); // UD-1
         this.#chars.splice(this.#cursor, end - this.#cursor);
         this.#reflow();
         if (!this.#pasting)
@@ -1915,6 +2046,8 @@ export class Editor {
             i -= 1; // trailing spaces
         while (i > 0 && this.#chars[i - 1] !== 0x20)
             i -= 1; // the word
+        if (i < this.#cursor)
+            this.#checkpoint(); // UD-1
         this.#chars.splice(i, this.#cursor - i);
         this.#cursor = i;
         this.#reflow();
@@ -2029,6 +2162,8 @@ export class Editor {
     }
     #takeLine() {
         const line = String.fromCodePoint(...this.#chars);
+        this.#undoStack.length = 0; // UD-1: a sent turn is not a loss
+        this.#redoStack.length = 0;
         this.#chars = [];
         this.#cursor = 0;
         this.#scroll = 0;
@@ -2196,6 +2331,8 @@ export class Editor {
         const line = this.#queuePop();
         if (line === null)
             return;
+        if (this.#chars.length > 0)
+            this.#checkpoint(); // UD-1: a mid-walk edit is recoverable
         this.#chars = [...line].map((ch) => ch.codePointAt(0));
         this.#cursor = this.#chars.length;
         this.#scroll = 0;

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { Body, Dock, CURSOR_MARKER, type BodyOptions } from "./compositor.js";
 export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, PICK_MAX, modelPickView, pickAffordance, pickBlockRows, pickLeadPlain, type PickOption, type PickResult, type PickRuntime, type PickSpec, type PanelArgs, type PanelFlavor, type PanelPhase, deletionRiskHint, SAFER_BACK, SAFER_DEGRADED, SAFER_DEGRADED_TRUNCATED, saferDegradedNote, type SaferAnswer, type SaferFailure, type SaferOption, type SaferRuntime, panelOptions, type PanelOption, type PanelOptionKind, type PanelState, type PanelVerdict, type PanelView, } from "./approval-panel.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 { bannerLines, COLOR_OFF, COLOR_ON, currentGround, setGround, 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, cacheHitPct, idleStatus, runningStatus, type StatusMeter } from "./status.js";
 export { contextRows, contextUnavailableRows, type ContextLedger } from "./context-ledger.js";
@@ -18,4 +18,5 @@ export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrusted
 export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, bandHeader, longestRun, type AtItem, type AtMatch } from "./at-picker.js";
 export { BADGE_GLYPH, idColumn, sessionAge, sessionBadge, sessionCounterRow, sessionFilter, sessionListFooter, sessionListRow, sessionNote, sessionPickerRows, sessionRow, type SessionCardView, type SessionPickState, } from "./session-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 { resolveGround, type Ground } from "@vincemakes/kiso-tui-cells";
 export { KEY_BINDINGS, PANEL_KEYS_ROW, displayVerb, extensionsBannerText, helpRows, keysHelpRow, keysSheetRows, unansweredAskView, type BannerExtension, type KeyBinding } from "./strings.js";

package/dist/index.js

@@ -15,7 +15,7 @@ export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWi
 PICK_MAX, modelPickView, pickAffordance, pickBlockRows, pickLeadPlain, deletionRiskHint, SAFER_BACK, SAFER_DEGRADED, SAFER_DEGRADED_TRUNCATED, saferDegradedNote, panelOptions, } from "./approval-panel.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 { bannerLines, COLOR_OFF, COLOR_ON, currentGround, setGround, 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.
@@ -42,4 +42,5 @@ export { ASK_HEADER_CAP, ASK_MAX_OPTIONS, ASK_MAX_QUESTIONS, ASK_MIN_OPTIONS, as
 // 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 { resolveGround } from "@vincemakes/kiso-tui-cells";
 export { KEY_BINDINGS, PANEL_KEYS_ROW, displayVerb, extensionsBannerText, helpRows, keysHelpRow, keysSheetRows, unansweredAskView } from "./strings.js";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@vincemakes/kiso-tui",
-	"version": "0.16.1",
-	"description": "kiso tui \u2014 the pure terminal layer (cell renderer, dock, raw editor, diff, palette). Zero runtime dependencies: input is data, output is bytes.",
+	"version": "0.16.3",
+	"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",
 	"exports": {
@@ -35,6 +35,6 @@
 	},
 	"homepage": "https://github.com/vincemakes/kiso/tree/main/packages/tui#readme",
 	"dependencies": {
-		"@vincemakes/kiso-tui-cells": "0.16.1"
+		"@vincemakes/kiso-tui-cells": "0.16.3"
 	}
 }