@vincemakes/kiso-tui 0.32.2 → 0.33.0

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { Container, foldLine, foldWords, visibleWidth, SPINNER, type Component,
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, type MenuItem, } from "./editor.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 "./lines.js";
 export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResult } from "./diff.js";
-export { STATUS_GLYPHS, cacheHitPct, idleStatus, runningStatus, type StatusMeter } from "./status.js";
+export { STATUS_GLYPHS, cacheHitPct, decodeRate, idleStatus, runningStatus, type StatusMeter } from "./status.js";
 export { contextRows, contextUnavailableRows, type ContextLedger } from "./context-ledger.js";
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, verifyOfferView, type TrustArtifact } from "./strings.js";
 export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, bandHeader, longestRun, type AtItem, type AtMatch } from "./at-picker.js";

package/dist/index.js

@@ -19,7 +19,7 @@ export { bannerLines, COLOR_OFF, COLOR_ON, currentGround, setGround, escapeTermi
 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, cacheHitPct, idleStatus, runningStatus } from "./status.js";
+export { STATUS_GLYPHS, cacheHitPct, decodeRate, 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";

package/dist/status.d.ts

@@ -36,6 +36,25 @@
  * Glyphs only, no colour: intact under NO_COLOR and on any ground.
  */
 export declare const STATUS_GLYPHS: readonly ["✧", "✦", "✶", "✸", "✺", "✸", "✦"];
+/**
+ * TPS-1 — the settled DECODE rate of one model call: its output tokens
+ * over the seconds from the call's first streamed event to its usage
+ * event. TTFT is excluded on purpose; this is the speed of the text
+ * arriving, which is what "tokens per second" means to the person
+ * watching it.
+ *
+ * The null rule, and every branch of it is the same principle: a number
+ * on this row is a MEASUREMENT or it is absent. No output count (the
+ * provider reported no usage) is not a zero. Under half a second of
+ * decoding is a sample too short to divide by. A non-positive elapsed is
+ * a clock, not a rate. And a call that decoded NOTHING has no rate to
+ * report: `0 tok/s` would read as a measured speed and it is not one — it
+ * is the absence of output, which the transcript already shows. The
+ * condition is on the RENDERED INTEGER rather than on the token count, so
+ * a slow trickle that rounds to the same `0` reaches the same absence for
+ * the same reason.
+ */
+export declare function decodeRate(outputTokens: number | null, elapsedMs: number): number | null;
 /**
  * The RUNNING row: the rotating glyph, the wall seconds since `since`
  * (never below 1 — a run that just started still reads "1s", so the row
@@ -46,7 +65,7 @@ export declare const STATUS_GLYPHS: readonly ["✧", "✦", "✶", "✸", "✺",
  * — stop, and do THIS instead. The row is where the gesture is taught,
  * 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;
+export declare function runningStatus(glyph: string, since: number, outTokens: number | null, ctxRatio: number, tokPerSec?: number | null): string;
 /**
  * TUI2-R1 (E) — the idle row's meter: what the session has SPENT, next
  * to what it has left.
@@ -71,12 +90,42 @@ export interface StatusMeter {
      *  (trace ledger, /context); the field is kept so callers need not
      *  change shape, and it renders NOTHING. */
     readonly costUsd: number | null;
+    /** TPS-1 — the decode rate of the LAST settled call, carried into the
+     *  idle row so the figure a person watched during the turn is still
+     *  there when the turn ends. Null renders nothing (see `decodeRate`);
+     *  a new model binding starts with none, exactly as the cache figure
+     *  does (DF-0311-F1: an unmeasured binding has no measurement). */
+    readonly tokPerSec: number | null;
 }
-/** The IDLE row: the approval tier as the CALLER names it, the /mode
- *  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;
+/**
+ * The IDLE row: the approval tier as the CALLER names it, the /mode 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.
+ *
+ * DF-0330-F1 — THE DROP ORDER. `W` is the row's budget; given one, the row
+ * gives ground in a fixed order rather than letting invariant ① cut its
+ * end off. Found the hard way: at 100 columns the ` · N tok/s` segment
+ * never appeared and at 140 it did, because the row was 102 columns wide
+ * and the segment TPS-1 added sat last.
+ *
+ *   1. the MODEL ID is elided in its middle. It is the only segment that
+ *      varies, it is the one that grew (the owner's is 35 columns of a
+ *      90-column row), and eliding it gives the row back a budget instead
+ *      of re-allocating a deficit;
+ *   2. `/mode to switch` is dropped. It teaches a gesture; `/mode` and `?`
+ *      still exist and the row is not the only place they are taught;
+ *   3. the FACTS are never dropped and never cut — the tier, CH, the ctx
+ *      estimate and the rate. A row that silently drops a measurement is
+ *      the defect this rule exists to prevent.
+ *
+ * The elision is ON THE ROW only. `/model`, the session log and the trace
+ * ledger all keep the id whole — the row is a view, never the record.
+ *
+ * No `W` means no dropping, which is what the callers that do not know
+ * their width should get: today's row, unchanged.
+ */
+export declare function idleStatus(tier: string, model: string, ctxRatio: number, meter?: StatusMeter, W?: number): 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

package/dist/status.js

@@ -23,6 +23,7 @@
  */
 import { kUnit } from "./lines.js";
 import { TWINKLE } from "@vincemakes/kiso-tui-cells/render";
+import { displayWidth } from "@vincemakes/kiso-tui-cells/width";
 /**
  * R3 (design §5.2) — the working glyph family is the TWINKLE, and the
  * CLI's 200ms spinner walks it exactly as it walked the four quadrant
@@ -45,6 +46,32 @@ export const STATUS_GLYPHS = TWINKLE;
 function ctxLeft(ratio) {
     return Number.isFinite(ratio) ? Math.round((1 - ratio) * 100) : null;
 }
+/**
+ * TPS-1 — the settled DECODE rate of one model call: its output tokens
+ * over the seconds from the call's first streamed event to its usage
+ * event. TTFT is excluded on purpose; this is the speed of the text
+ * arriving, which is what "tokens per second" means to the person
+ * watching it.
+ *
+ * The null rule, and every branch of it is the same principle: a number
+ * on this row is a MEASUREMENT or it is absent. No output count (the
+ * provider reported no usage) is not a zero. Under half a second of
+ * decoding is a sample too short to divide by. A non-positive elapsed is
+ * a clock, not a rate. And a call that decoded NOTHING has no rate to
+ * report: `0 tok/s` would read as a measured speed and it is not one — it
+ * is the absence of output, which the transcript already shows. The
+ * condition is on the RENDERED INTEGER rather than on the token count, so
+ * a slow trickle that rounds to the same `0` reaches the same absence for
+ * the same reason.
+ */
+export function decodeRate(outputTokens, elapsedMs) {
+    if (outputTokens === null)
+        return null;
+    if (!Number.isFinite(elapsedMs) || elapsedMs < 500)
+        return null;
+    const rate = Math.round(outputTokens / (elapsedMs / 1000));
+    return rate > 0 ? rate : null;
+}
 /**
  * The RUNNING row: the rotating glyph, the wall seconds since `since`
  * (never below 1 — a run that just started still reads "1s", so the row
@@ -55,22 +82,101 @@ function ctxLeft(ratio) {
  * — stop, and do THIS instead. The row is where the gesture is taught,
  * because it is on screen exactly when the gesture is useful.
  */
-export function runningStatus(glyph, since, outTokens, ctxRatio) {
+export function runningStatus(glyph, since, outTokens, ctxRatio, tokPerSec = null) {
     const out = outTokens !== null ? ` ↓ ${kUnit(outTokens)} tokens` : "";
+    // TPS-1: after each call SETTLES within the turn, between the tokens
+    // segment and the stop hint. The default is null and that is the honest
+    // rule spelled as a default — the recovery flow has no per-call timing
+    // state, so its row says nothing rather than guessing.
+    const rate = tokPerSec !== null ? ` · ${tokPerSec} tok/s` : "";
     const seconds = Math.max(1, Math.round((Date.now() - since) / 1000));
-    return `${glyph} working ${seconds}s${out} · esc stop · alt+⏎ redirect · ctx left ~${ctxLeft(ctxRatio)}%`;
+    return `${glyph} working ${seconds}s${out}${rate} · esc stop · alt+⏎ redirect · ctx left ~${ctxLeft(ctxRatio)}%`;
+}
+/** DF-0330-F1 — how far the model id may be squeezed on the ROW. Twenty
+ *  visible columns keeps a head and a tail: `deepseek-v…s-on-0910` still
+ *  says which binding is driving, and the tail is where the parts that
+ *  distinguish one id from its neighbours live (`-flash`, `-0910`). */
+const MODEL_ON_ROW = 20;
+/** Elide in the MIDDLE, keeping the head and the tail. A string already
+ *  within budget is returned untouched, so this is a no-op for every
+ *  ordinary model name.
+ *
+ *  Budgeted in DISPLAY COLUMNS, not code points. A first version sliced
+ *  code points and a wide-character id came out at 28 columns while the
+ *  function claimed 20 — which would have put the row straight back over
+ *  its budget and handed it to invariant ①'s cut, the exact defect this
+ *  whole change exists to prevent. No such model id exists today; the
+ *  guarantee should not depend on that staying true. */
+function elideMiddle(text, max) {
+    if (displayWidth(text) <= max)
+        return text;
+    const chars = [...text];
+    const room = max - 1; // the ellipsis costs one column
+    const headBudget = Math.ceil(room / 2);
+    let head = "";
+    for (const c of chars) {
+        if (displayWidth(head + c) > headBudget)
+            break;
+        head += c;
+    }
+    let tail = "";
+    const tailBudget = room - displayWidth(head);
+    for (let i = chars.length - 1; i >= 0; i -= 1) {
+        if (displayWidth(chars[i] + tail) > tailBudget)
+            break;
+        tail = chars[i] + tail;
+    }
+    return `${head}…${tail}`;
 }
-/** The IDLE row: the approval tier as the CALLER names it, the /mode
- *  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)}%`);
-    // costUsd deliberately NOT rendered — see StatusMeter.costUsd.
-    parts.push(`ctx left ~${ctxLeft(ctxRatio)}%`);
-    return parts.join(" · ");
+/**
+ * The IDLE row: the approval tier as the CALLER names it, the /mode 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.
+ *
+ * DF-0330-F1 — THE DROP ORDER. `W` is the row's budget; given one, the row
+ * gives ground in a fixed order rather than letting invariant ① cut its
+ * end off. Found the hard way: at 100 columns the ` · N tok/s` segment
+ * never appeared and at 140 it did, because the row was 102 columns wide
+ * and the segment TPS-1 added sat last.
+ *
+ *   1. the MODEL ID is elided in its middle. It is the only segment that
+ *      varies, it is the one that grew (the owner's is 35 columns of a
+ *      90-column row), and eliding it gives the row back a budget instead
+ *      of re-allocating a deficit;
+ *   2. `/mode to switch` is dropped. It teaches a gesture; `/mode` and `?`
+ *      still exist and the row is not the only place they are taught;
+ *   3. the FACTS are never dropped and never cut — the tier, CH, the ctx
+ *      estimate and the rate. A row that silently drops a measurement is
+ *      the defect this rule exists to prevent.
+ *
+ * The elision is ON THE ROW only. `/model`, the session log and the trace
+ * ledger all keep the id whole — the row is a view, never the record.
+ *
+ * No `W` means no dropping, which is what the callers that do not know
+ * their width should get: today's row, unchanged.
+ */
+export function idleStatus(tier, model, ctxRatio, meter, W) {
+    const compose = (label, hint) => {
+        const parts = [`▸ ${tier}`];
+        if (hint)
+            parts.push("/mode to switch");
+        parts.push(label);
+        if (meter?.cacheHitPct != null)
+            parts.push(`CH ${Math.round(meter.cacheHitPct)}%`);
+        // costUsd deliberately NOT rendered — see StatusMeter.costUsd.
+        parts.push(`ctx left ~${ctxLeft(ctxRatio)}%`);
+        if (meter?.tokPerSec != null)
+            parts.push(`${meter.tokPerSec} tok/s`); // TPS-1: last, after the ctx estimate
+        return parts.join(" · ");
+    };
+    const full = compose(model, true);
+    if (W === undefined || displayWidth(full) <= W)
+        return full;
+    const squeezed = compose(elideMiddle(model, MODEL_ON_ROW), true);
+    if (displayWidth(squeezed) <= W)
+        return squeezed;
+    return compose(elideMiddle(model, MODEL_ON_ROW), false);
 }
 /** 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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tui",
-	"version": "0.32.2",
+	"version": "0.33.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.32.2"
+		"@vincemakes/kiso-tui-cells": "0.33.0"
 	}
 }