@vincemakes/kiso-tui 0.8.0 → 0.10.0

package/dist/index.js

@@ -9,25 +9,36 @@ export { Body, Dock, CURSOR_MARKER } from "./compositor.js";
 // W21 (the v8 approval round): the approval panel — the bounded block
 // 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 { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, 
+// TUI2-R2 ④: the pick payload — the panel slot's third occupant.
+PICK_MAX, modelPickView, pickAffordance, pickBlockRows, pickLeadPlain, } 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 { 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.
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView } from "./strings.js";
 // 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";
+export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, bandHeader, longestRun } from "./at-picker.js";
+// TUI2-R2 ①–③: the session picker's pure half — the durability badge,
+// the row (picked or printed), the band, and the filter. The CARDS are
+// the cli's projection (session-cards.ts); this turns them into bytes.
+export { BADGE_GLYPH, idColumn, sessionAge, sessionBadge, sessionCounterRow, sessionFilter, sessionListFooter, sessionListRow, sessionNote, sessionPickerRows, sessionRow, } from "./session-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).
-export { extensionsBannerText, helpRows, unansweredAskView } from "./strings.js";
+// 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, displayVerb, extensionsBannerText, helpRows, keysHelpRow, keysSheetRows, unansweredAskView } from "./strings.js";

package/dist/session-picker.d.ts

@@ -0,0 +1,113 @@
+/**
+ * TUI2-R2 slices ①–③ — the session picker's PURE half: the durability
+ * badge, the row, the band, and the filter.
+ *
+ * The badge is the round's whole argument. kiso's claim is that a
+ * session survives kill -9 and resumes from its durable prefix; until
+ * now that claim was a sentence in a README. A badge per row makes it a
+ * thing you can SEE before you pick: this one completed, this one was
+ * cut mid-run and will resume exactly, this one is holding a question
+ * for you.
+ *
+ * The vocabulary (the palette's functional set — no new colour):
+ *
+ *   ✓ green   the run's terminal event says completed
+ *   ✗ red     the terminal says anything else
+ *   ▌ bold    no terminal event — interrupted mid-run
+ *   ? warn    the uncertain ledger is not empty (overrides ▌)
+ *   ◌ dim     a permission request nobody has answered
+ *
+ * Purity, as everywhere in this package: the cards are DATA the CLI
+ * projects (session-cards.ts) and this module turns them into bytes. It
+ * never reads a session, never asks the runtime anything, and holds no
+ * state — which is what lets the picker band and the `kiso sessions`
+ * listing render from ONE definition instead of two that drift.
+ */
+/** The projected card — structurally what apps/cli/src/session-cards.ts
+ *  produces. Declared here as the tui's INPUT contract (the package
+ *  imports nothing from the runtime, by rule). */
+export interface SessionCardView {
+    readonly id: string;
+    readonly badge: "uncertain" | "ask" | "interrupted" | "completed" | "failed";
+    readonly turns: number;
+    readonly updatedAt: number;
+    readonly uncertain: number;
+    readonly asks: number;
+    readonly outcome: string | null;
+}
+/** The glyph per state — one cell each, so the badge column never
+ *  shifts the id column (a column that moves per row reads as damage). */
+export declare const BADGE_GLYPH: Readonly<Record<SessionCardView["badge"], string>>;
+/** The badge, styled. The colour IS the meaning here (the mono
+ *  discipline's three functional exceptions), so NO_COLOR degrades to
+ *  the glyph alone — which is why the glyphs are distinct shapes and
+ *  not three coloured dots. */
+export declare function sessionBadge(badge: SessionCardView["badge"]): string;
+/**
+ * What the row SAYS about the state. The interrupted note is the
+ * product's promise stated in the place the promise matters: the run
+ * continues from its durable prefix, so picking this row costs nothing
+ * that was already paid for.
+ *
+ * The ✗ note names the OUTCOME rather than flattening six endings into
+ * one word — "aborted" and "max turns" are different things to have
+ * happened, and a picker that calls both "failed" teaches the user
+ * nothing.
+ */
+export declare function sessionNote(card: SessionCardView): string;
+/** The compact age — the picker's column, not the banner's sentence.
+ *  `relativeTime` says "3d ago"; a column of ages does not need the
+ *  word repeated on every row. */
+export declare function sessionAge(updatedAt: number, now: number): string;
+/** The id column's width — computed over EVERY card, never over the
+ *  filtered subset, so the columns do not jump while the user types
+ *  (the whole reason a filter-as-you-type picker is usable). */
+export declare function idColumn(cards: readonly SessionCardView[]): number;
+/**
+ * The filter — the @ picker's muscle, aimed at the session id: a
+ * case-insensitive SUBSEQUENCE, ranked by the longest contiguous run,
+ * then by id length, then lexically. Identical determinism, identical
+ * feel; a row under the cursor never moves because two ids tied.
+ *
+ * An empty query matches everything and keeps the caller's order (the
+ * listing's newest-first), because "no query" is not a search — it is
+ * the list.
+ */
+export declare function sessionFilter(cards: readonly SessionCardView[], query: string): SessionCardView[];
+/**
+ * ONE picker row. The selection is a FULL-ROW reverse bar — the R1.5
+ * ⑧ ruling's shape, shared with the @ picker and the user chip: a
+ * two-cell marker in an eighty-column row is a selection you have to
+ * hunt for.
+ *
+ * The inner spans close with rvEnd inside the bar (never SGR 0, which
+ * would punch a hole in it) — the same composition atRow uses.
+ */
+export declare function sessionRow(card: SessionCardView, selected: boolean, W: number, now: number, idCol: number): string;
+/** The counter row — the SELECTION's 1-based place in the whole
+ *  filtered list, which the visible window cannot tell the user. */
+export declare function sessionCounterRow(selected: number, total: number, W: number): string;
+/** The picker's bound state — the editor owns it, the compositor reads
+ *  it (the @ picker's contract, one surface over). */
+export interface SessionPickState {
+    readonly cards: readonly SessionCardView[];
+    readonly matches: readonly SessionCardView[];
+    readonly selected: number;
+}
+/**
+ * The whole band: the `sessions` header (R1.5 ⑦(b) — a band names
+ * itself or it reads as more scrollback), at most AT_VISIBLE windowed
+ * rows, then the counter. Returned as plain strings for the menu-rows
+ * channel, which already accounts them in chromeRows — the picker needs
+ * no geometry of its own, which is the entire reason it rides that
+ * channel.
+ */
+export declare function sessionPickerRows(state: SessionPickState, W: number, now: number): string[];
+/** Slice ③ — the `kiso sessions` TTY row: the SAME projection, printed
+ *  rather than picked. No selection bar (nothing is selected on a
+ *  listing) and no leading indent: this row starts at column 1 like
+ *  every other line a shell command prints. */
+export declare function sessionListRow(card: SessionCardView, W: number, now: number, idCol: number): string;
+/** Slice ③ — the listing's last line: the count, and the one thing the
+ *  user can do next. */
+export declare function sessionListFooter(count: number, W: number): string;

package/dist/session-picker.js

@@ -0,0 +1,249 @@
+/**
+ * TUI2-R2 slices ①–③ — the session picker's PURE half: the durability
+ * badge, the row, the band, and the filter.
+ *
+ * The badge is the round's whole argument. kiso's claim is that a
+ * session survives kill -9 and resumes from its durable prefix; until
+ * now that claim was a sentence in a README. A badge per row makes it a
+ * thing you can SEE before you pick: this one completed, this one was
+ * cut mid-run and will resume exactly, this one is holding a question
+ * for you.
+ *
+ * The vocabulary (the palette's functional set — no new colour):
+ *
+ *   ✓ green   the run's terminal event says completed
+ *   ✗ red     the terminal says anything else
+ *   ▌ bold    no terminal event — interrupted mid-run
+ *   ? warn    the uncertain ledger is not empty (overrides ▌)
+ *   ◌ dim     a permission request nobody has answered
+ *
+ * Purity, as everywhere in this package: the cards are DATA the CLI
+ * projects (session-cards.ts) and this module turns them into bytes. It
+ * never reads a session, never asks the runtime anything, and holds no
+ * state — which is what lets the picker band and the `kiso sessions`
+ * listing render from ONE definition instead of two that drift.
+ */
+import { escapeTerminal, palette } from "./render.js";
+import { visibleWidth, widthCut } from "./components.js";
+import { atEmbed, bandHeader, longestRun, AT_VISIBLE, atWindow } from "./at-picker.js";
+/** The glyph per state — one cell each, so the badge column never
+ *  shifts the id column (a column that moves per row reads as damage). */
+export const BADGE_GLYPH = {
+    completed: "✓", // ✓
+    failed: "✗", // ✗
+    interrupted: "▌", // ▌ — the input brick: this session is mid-sentence
+    uncertain: "?",
+    ask: "◌", // ◌ — the dotted circle: a question with no answer in it yet
+};
+/** The badge, styled. The colour IS the meaning here (the mono
+ *  discipline's three functional exceptions), so NO_COLOR degrades to
+ *  the glyph alone — which is why the glyphs are distinct shapes and
+ *  not three coloured dots. */
+export function sessionBadge(badge) {
+    const p = palette();
+    const g = BADGE_GLYPH[badge];
+    if (badge === "completed")
+        return `${p.green}${g}${p.reset}`;
+    if (badge === "failed")
+        return `${p.red}${g}${p.reset}`;
+    if (badge === "interrupted")
+        return `${p.bold}${g}${p.reset}`;
+    if (badge === "uncertain")
+        return `${p.warn}${g}${p.reset}`;
+    return `${p.dim}${g}${p.reset}`;
+}
+/**
+ * What the row SAYS about the state. The interrupted note is the
+ * product's promise stated in the place the promise matters: the run
+ * continues from its durable prefix, so picking this row costs nothing
+ * that was already paid for.
+ *
+ * The ✗ note names the OUTCOME rather than flattening six endings into
+ * one word — "aborted" and "max turns" are different things to have
+ * happened, and a picker that calls both "failed" teaches the user
+ * nothing.
+ */
+export function sessionNote(card) {
+    switch (card.badge) {
+        case "uncertain":
+            return `${card.uncertain} uncertain — needs your verdict`;
+        case "ask":
+            return `${card.asks} ask${card.asks === 1 ? "" : "s"} pending`;
+        case "interrupted":
+            return "interrupted mid-run — resumes exactly";
+        case "completed":
+            return "completed clean";
+        default:
+            return card.outcome === null || card.outcome === "error" ? "failed" : card.outcome.replaceAll("_", " ");
+    }
+}
+/** The compact age — the picker's column, not the banner's sentence.
+ *  `relativeTime` says "3d ago"; a column of ages does not need the
+ *  word repeated on every row. */
+export function sessionAge(updatedAt, now) {
+    const s = Math.max(0, now - updatedAt) / 1000;
+    if (s < 60)
+        return "now";
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h`;
+    const d = Math.floor(h / 24);
+    if (d < 7)
+        return `${d}d`;
+    return `${Math.floor(d / 7)}w`;
+}
+/** The id column's width — computed over EVERY card, never over the
+ *  filtered subset, so the columns do not jump while the user types
+ *  (the whole reason a filter-as-you-type picker is usable). */
+export function idColumn(cards) {
+    let w = 0;
+    for (const c of cards)
+        w = Math.max(w, visibleWidth(escapeTerminal(c.id)));
+    return Math.min(Math.max(w, 1), 24);
+}
+/**
+ * The filter — the @ picker's muscle, aimed at the session id: a
+ * case-insensitive SUBSEQUENCE, ranked by the longest contiguous run,
+ * then by id length, then lexically. Identical determinism, identical
+ * feel; a row under the cursor never moves because two ids tied.
+ *
+ * An empty query matches everything and keeps the caller's order (the
+ * listing's newest-first), because "no query" is not a search — it is
+ * the list.
+ */
+export function sessionFilter(cards, query) {
+    if (query === "")
+        return [...cards];
+    const lower = query.toLowerCase();
+    const scored = [];
+    for (const card of cards) {
+        const hit = atEmbed(card.id.toLowerCase(), lower);
+        if (hit === null)
+            continue;
+        scored.push({ card, run: longestRun(hit) });
+    }
+    scored.sort((a, b) => {
+        if (a.run !== b.run)
+            return b.run - a.run;
+        if (a.card.id.length !== b.card.id.length)
+            return a.card.id.length - b.card.id.length;
+        return a.card.id < b.card.id ? -1 : a.card.id > b.card.id ? 1 : 0;
+    });
+    return scored.map((s) => s.card);
+}
+/**
+ * The row's spans, built against a HARD budget — the badge, the id
+ * column, the metadata, the note.
+ *
+ * The spans are appended in order of what the row is FOR and each one
+ * is dropped whole rather than half-drawn when the budget runs out:
+ * the badge and the id are the row's identity, the age/turns say
+ * whether it is the one, and the note is the sentence that explains
+ * the badge. A narrow terminal loses them from the right.
+ *
+ * The running width is the authority — never a formula computed up
+ * front. That is what the invariant-① sweep across five widths in the
+ * gate is for: a row that overflows does not truncate quietly here, it
+ * CRASHES the compositor, so the arithmetic has to be provably right at
+ * every width rather than right at eighty.
+ */
+function rowSpans(card, budget, now, idCol) {
+    const p = palette();
+    let text = "";
+    let w = 0;
+    /** append a styled span iff its VISIBLE cells still fit */
+    const put = (plain, styled) => {
+        const cells = visibleWidth(plain);
+        if (w + cells > budget)
+            return;
+        text += styled;
+        w += cells;
+    };
+    // the badge: one glyph + one space, styled as a unit (the glyph's own
+    // SGR spans make it unmeasurable by `put`'s plain/styled pair)
+    if (w + 2 <= budget) {
+        text += `${sessionBadge(card.badge)} `;
+        w += 2;
+    }
+    const id = widthCut(escapeTerminal(card.id), Math.max(1, Math.min(idCol, budget - w)));
+    put(id, id);
+    // the column pad only survives while there is room for what follows
+    const pad = Math.max(0, Math.min(idCol - visibleWidth(id), budget - w));
+    put(" ".repeat(pad), " ".repeat(pad));
+    const meta = `  ${sessionAge(card.updatedAt, now)} · ${card.turns} turn${card.turns === 1 ? "" : "s"}`;
+    put(meta, `${p.dim}${meta}${p.reset}`);
+    const note = widthCut(sessionNote(card), Math.max(0, budget - w - 3));
+    if (note !== "") {
+        // the ? note carries the warn tint — the row's own words are what
+        // the user acts on, and the one that demands an action says so
+        put(" · ", `${p.dim} · ${p.reset}`);
+        put(note, card.badge === "uncertain" ? `${p.warn}${note}${p.reset}` : `${p.dim}${note}${p.reset}`);
+    }
+    return { text, width: w };
+}
+/**
+ * ONE picker row. The selection is a FULL-ROW reverse bar — the R1.5
+ * ⑧ ruling's shape, shared with the @ picker and the user chip: a
+ * two-cell marker in an eighty-column row is a selection you have to
+ * hunt for.
+ *
+ * The inner spans close with rvEnd inside the bar (never SGR 0, which
+ * would punch a hole in it) — the same composition atRow uses.
+ */
+export function sessionRow(card, selected, W, now, idCol) {
+    const p = palette();
+    // both forms spend two cells of the width on their frame — the
+    // unselected row's indent, the bar's own leading/trailing cell — so
+    // the spans are built against the same budget either way and the
+    // selection cannot change the columns
+    const { text, width } = rowSpans(card, Math.max(0, W - 2), now, idCol);
+    if (!selected)
+        return `  ${text}`;
+    const inner = text.replaceAll(p.reset, `${p.reset}${p.rv}`);
+    return `${p.rv} ${inner}${" ".repeat(Math.max(0, W - width - 2))} ${p.rvEnd}`;
+}
+/** The counter row — the SELECTION's 1-based place in the whole
+ *  filtered list, which the visible window cannot tell the user. */
+export function sessionCounterRow(selected, total, W) {
+    const p = palette();
+    return `${p.dim}${widthCut(total === 0 ? "  (0/0)" : `  (${selected + 1}/${total})`, W)}${p.reset}`;
+}
+/**
+ * The whole band: the `sessions` header (R1.5 ⑦(b) — a band names
+ * itself or it reads as more scrollback), at most AT_VISIBLE windowed
+ * rows, then the counter. Returned as plain strings for the menu-rows
+ * channel, which already accounts them in chromeRows — the picker needs
+ * no geometry of its own, which is the entire reason it rides that
+ * channel.
+ */
+export function sessionPickerRows(state, W, now) {
+    const rows = [bandHeader("sessions", W)];
+    const col = idColumn(state.cards);
+    if (state.matches.length === 0) {
+        const p = palette();
+        rows.push(`${p.dim}${widthCut("  no session matches", W)}${p.reset}`);
+        rows.push(sessionCounterRow(0, 0, W));
+        return rows;
+    }
+    const { first, count } = atWindow(state.matches.length, state.selected, AT_VISIBLE);
+    for (let i = first; i < first + count; i += 1)
+        rows.push(sessionRow(state.matches[i], i === state.selected, W, now, col));
+    rows.push(sessionCounterRow(state.selected, state.matches.length, W));
+    return rows;
+}
+/** Slice ③ — the `kiso sessions` TTY row: the SAME projection, printed
+ *  rather than picked. No selection bar (nothing is selected on a
+ *  listing) and no leading indent: this row starts at column 1 like
+ *  every other line a shell command prints. */
+export function sessionListRow(card, W, now, idCol) {
+    return rowSpans(card, W, now, idCol).text;
+}
+/** Slice ③ — the listing's last line: the count, and the one thing the
+ *  user can do next. */
+export function sessionListFooter(count, W) {
+    const p = palette();
+    return `${p.dim}${widthCut(`${count} session${count === 1 ? "" : "s"} · kiso resume picks interactively`, W)}${p.reset}`;
+}

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.8.0",
+  "version": "0.10.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.8.0"
+    "@vincemakes/kiso-tui-cells": "0.10.0"
   }
 }