@vincemakes/kiso-tui 0.16.2 → 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";
@@ -293,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;
@@ -306,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
@@ -1101,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
                 }

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.2",
-	"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.2"
+		"@vincemakes/kiso-tui-cells": "0.16.3"
 	}
 }