@vincemakes/kiso-tui-cells 0.8.0 → 0.10.0

package/dist/components.js

@@ -18,6 +18,10 @@
  * tint, fold wording).
  */
 import { displayWidth } from "./width.js";
+// TUI2-R2pre ④: the ONE display-verb table (strings.ts, beside
+// KEY_BINDINGS). strings.js imports only render/width here, so this edge
+// adds no cycle.
+import { displayVerb } from "./strings.js";
 import { bannerLines, escapeTerminal, foldThinking, foldResult, colorInlineCode, renderTerminalGap, renderToolSummary, toolTarget, kUnit, palette, } from "./render.js";
 /** The spinner glyphs, cycled by the compositor's on-demand tick. */
 export const SPINNER = ["▖", "▘", "▝", "▗"];
@@ -251,6 +255,66 @@ class ThinkingFold {
  *  distinguishes the states at --plain; the UserMessage rail precedent,
  *  v5 #16f). The gutter carries its own SGR (e.g. the bold ✓). W21:
  *  exported for the approval panel's text args (the same │ gutter). */
+/**
+ * TUI2-R1.5 ⑨ (VD-10) — the WORD-aware fold, for text a human reads.
+ *
+ * foldLine is a hard character fold at the width. That is exactly right
+ * for verbatim tool output, where a byte is a byte and a break is a
+ * display artefact the reader knows to ignore; it is exactly wrong for
+ * prose, where the reader's eye has to reassemble "ex" + "pected" into a
+ * word it already knew. The walkthrough read three of those off one
+ * screen.
+ *
+ * The implementation is a wrapper, not a second engine: the text is cut
+ * at the last space that fits and each resulting segment is handed to
+ * foldLine, which keeps the SGR close/reopen discipline, the display-
+ * width arithmetic and the newline handling in ONE place. A word longer
+ * than the width falls through to foldLine's hard break — an
+ * overflowing row would violate invariant ①, and a word that cannot fit
+ * has to be broken somewhere.
+ */
+/** The SGR spans still open at the end of `text`, given those open at
+ *  its start. A reset closes everything; anything else stacks. */
+function spansOpenAfter(text, before) {
+    let open = [...before];
+    for (const m of text.matchAll(/\x1b\[[0-9;]*m/g)) {
+        if (m[0] === "\x1b[0m")
+            open = [];
+        else
+            open.push(m[0]);
+    }
+    return open;
+}
+export function foldWords(line, W) {
+    if (W < 1)
+        return [line];
+    const out = [];
+    for (const para of line.split("\n")) {
+        if (visibleWidth(para) <= W) {
+            out.push(para);
+            continue;
+        }
+        let rest = para;
+        // the spans open at the cut point, so each emitted row closes them
+        // and the next row reopens them — foldLine's own discipline, applied
+        // across the segments this function creates.
+        let open = [];
+        while (visibleWidth(rest) > W) {
+            // the widest prefix that fits, then back up to the last space in
+            // it — the SGR-aware cut keeps the spans intact
+            const head = widthCut(rest, W);
+            const at = head.lastIndexOf(" ");
+            if (at <= 0)
+                break; // one long word (or no space at all) — hard-break it
+            const cut = head.slice(0, at);
+            out.push(`${cut}${open.length > 0 || /\x1b\[[0-9;]*m/.test(cut) ? "\x1b[0m" : ""}`);
+            open = spansOpenAfter(cut, open);
+            rest = `${open.join("")}${rest.slice(cut.length + 1)}`;
+        }
+        out.push(...foldLine(rest, W));
+    }
+    return out.length > 0 ? out : [""];
+}
 export function gutterFold(gutter, line, W) {
     const textW = Math.max(1, W - 2);
     return foldLine(line, textW).map((r) => `${gutter}${r}`);
@@ -340,6 +404,21 @@ function settledMeta(c) {
  *  read/write/edit → the path, shell → the command, list_dir → path ??
  *  "(root)". Parsed from the FULL input — the folded summary is a
  *  truncated slice. */
+/** TUI2-R1.5 ④(a) (VD-4) — the header text for a cell that has NOT
+ *  settled yet (queued, awaiting approval, running).
+ *
+ *  These three states printed `c.input`: a 60-char slice of the call's
+ *  JSON, escapes and all. The done card printed the plain command
+ *  through toolTarget, so the SAME call read as
+ *  `shell {"command":"for i in 1 2 3 4 5 6; do echo \"step $i · compil`
+ *  while it ran and as `shell for i in 1 2 3 4 5 6; …` a second later.
+ *  One formatter now, for every state. A cell whose full input somehow
+ *  will not parse keeps the old slice — the header always says
+ *  something. */
+function liveTarget(c) {
+    const target = toolTargetOf(c);
+    return escapeTerminal(target === "?" ? c.input : target);
+}
 function toolTargetOf(c) {
     let input = {};
     try {
@@ -379,9 +458,24 @@ class ToolExecution {
     render(W, ctx) {
         const p = palette();
         const c = this.cell;
-        const verb = escapeTerminal(c.name.replace("_file", ""));
+        const verb = escapeTerminal(displayVerb(c.name));
         const verbCol = verb.length < 5 ? `${verb}${" ".repeat(5 - verb.length)}` : verb;
-        const summary = escapeTerminal(c.input);
+        const parts = c.rolled?.parts;
+        if (c.rolled !== null && parts !== undefined) {
+            // TUI2-R1 (B) — the exploration row: a run that spans more than
+            // one read-only tool. The counts are BOLD (what the reader is
+            // being told), the timing and the affordance dim — the
+            // prototype's placement. The affordance names what the key
+            // SHOWS here ("lists them"), because a group row's expand is a
+            // list of calls, not a body of output.
+            const r = c.rolled;
+            const counts = exploreCounts(parts);
+            const head = `${p.bold}✓${p.reset} explored ${p.bold}${counts}${p.reset}`;
+            const tail = ` (${r.elapsed}s)`;
+            const room = W - visibleWidth(head) - tail.length;
+            const affordance = " · ctrl+r lists them";
+            return [cutLine(`${head}${p.dim}${tail}${affordance.length <= room ? affordance : ""}${p.reset}`, W)];
+        }
         if (c.rolled !== null) {
             // W13 — the rolled-up group's ONE row + the target children:
             // the work order's claimed shape, verbatim — the verbCol's
@@ -408,45 +502,263 @@ class ToolExecution {
             // denial appends `· by <decidedBy>` — the aggregated head row
             // names the decider; a human denial (no decidedBy) has no tail.
             if (c.reason !== null) {
-                const by = c.verdict !== null && c.verdict.decidedBy !== undefined ? ` · by ${escapeTerminal(c.verdict.decidedBy)}` : "";
+                const by = attribution(c);
                 const out = gutterCut(`${p.red}✗${p.reset} `, `${p.red}${escapeTerminal(`${c.name} ${toolTargetOf(c)}`)} (${escapeTerminal(c.reason)}${by})${p.reset}`, W);
                 out.push(...toolBlockBody(c, W));
                 return out;
             }
             const elapsed = c.startedAt !== null && c.doneAt !== null ? ((c.doneAt - c.startedAt) / 1000).toFixed(1) : "?";
-            const meta = escapeTerminal(settledMeta(c));
+            // TUI2-R1.5 ⑤ (VD-6): the line count is stated EXACTLY ONCE. Every
+            // read card carried it twice — `(2 lines, 0.0s) · 2 lines · ctrl+r
+            // expands` — because the parens and the suffix were written by
+            // different rounds, each unaware the other was counting. The
+            // SUFFIX keeps it (it is the one that also names the key), so a
+            // meta that says only "<n> lines" drops out when a suffix will
+            // carry it. A meta that says something else — read_file's
+            // "200 of 250 lines", a diff's "+1 -1", a shell's "exit 0" — is a
+            // different fact and stays.
+            const rawMeta = settledMeta(c);
+            const dup = hiddenLines(c, W) !== null && new RegExp(`^${hiddenLines(c, W)} lines?$`).test(rawMeta);
+            const meta = dup ? "" : escapeTerminal(rawMeta);
             // A4: the target rides the settled head row — the verb's
             // summary column (W3's 5-char pad keeps the paths lined up).
             // A5: an extension's auto-approval appends `· approved by
             // <decidedBy>` — the "why wasn't I asked" answer; the human
             // approval (no decidedBy) leaves the row unchanged.
-            const approvedBy = c.verdict !== null && c.verdict.decidedBy !== undefined ? ` · approved by ${escapeTerminal(c.verdict.decidedBy)}` : "";
-            const out = c.isError
-                ? gutterCut(`${p.red}✗${p.reset} `, `${p.red}${verbCol} ${escapeTerminal(toolTargetOf(c))} (${meta}${approvedBy}, ${elapsed}s)${p.reset}`, W)
-                : gutterCut(`${p.bold}✓${p.reset} `, `${verbCol} ${escapeTerminal(toolTargetOf(c))} (${meta}${approvedBy}, ${elapsed}s)`, W);
+            const approvedBy = attribution(c);
+            // TUI2-R1 (A): the card names its own key — the suffix rides the
+            // settled head row.
+            // TUI2-R1.5 ④(c): the suffix is now RESERVED rather than given
+            // the leftovers. It used to take the width that happened to be
+            // left, so a long command spent it all and the row said nothing
+            // about the seven lines behind the key — tolerable while the
+            // body was on screen, a silence now that the body is not. The
+            // command is the cuttable span (the approval panel's option-2
+            // rule name is the same idea); the affordance is the semantics.
+            const hidden = hiddenLines(c, W);
+            // TUI2-R1.5 ⑤: the shortest tier is RESERVED — the affordance is
+            // the semantics. TUI2-R1.5 pin 4: and the parts give way in a
+            // PINNED ORDER, rather than whichever happened to be last.
+            const text = settledHeadText(verbCol, escapeTerminal(toolTargetOf(c)), meta, approvedBy, elapsed, W - 2 - (hidden === null ? 0 : SUFFIX_MIN));
+            const out = c.isError ? [`${p.red}✗${p.reset} ${p.red}${text}${p.reset}`] : [`${p.bold}✓${p.reset} ${text}`];
+            out[0] = appendSuffix(out[0], expandSuffix(hidden, W - visibleWidth(out[0])));
             out.push(...toolBlockBody(c, W));
             return out;
         }
         if (c.state === "approval") {
             // W2: the ⏸ is the GUTTER (the left edge), never the line's tail
-            const out = gutterCut(`${p.bold}⏸${p.reset} `, `${verbCol} ${summary}`, W);
+            const out = gutterCut(`${p.bold}⏸${p.reset} `, `${verbCol} ${liveTarget(c)}`, W);
             out.push(...toolBlockBody(c, W));
             return out;
         }
         if (c.state === "running") {
             // W2: the spinner IS the gutter (the left edge); the elapsed
-            // rides the summary's tail
+            // rides the summary's tail.
+            // TUI2-R1.5 ④(a) (VD-4): the duration is its OWN trailing segment.
+            // It used to be concatenated into the text BEFORE the cut, so a
+            // header wider than the row lost it entirely or, worse, kept it
+            // welded to the last surviving characters of a cut word
+            // ("compil 1s"). The head is cut against the room the duration
+            // leaves; the duration then rides the row, always legible.
             const elapsed = c.startedAt !== null ? Math.max(1, Math.round((ctx.now - c.startedAt) / 1000)) : 1;
-            const out = gutterCut(`${p.bold}${SPINNER[ctx.spinnerI % SPINNER.length]}${p.reset} `, `${verbCol} ${summary} ${elapsed}s`, W);
+            const dur = ` · ${elapsed}s`;
+            const out = gutterCut(`${p.bold}${SPINNER[ctx.spinnerI % SPINNER.length]}${p.reset} `, `${verbCol} ${liveTarget(c)}`, Math.max(4, W - dur.length));
+            out[0] = `${out[0]}${p.dim}${dur}${p.reset}`;
             out.push(...toolBlockBody(c, W));
             return out;
         }
         // W2: ◦ replaces → for QUEUED — · is the separator inside every
         // metadata group; a queued marker that is also the separator
         // glyph reads as noise
-        return gutterCut(`${p.dim}◦${p.reset} `, `${verbCol} ${summary}`, W);
+        return gutterCut(`${p.dim}◦${p.reset} `, `${verbCol} ${liveTarget(c)}`, W);
     }
 }
+// ---- TUI2-R1 (A): the self-naming expand affordance ----
+/**
+ * TUI2-R1 (A) — how many lines a COLLAPSED settled cell is hiding, or
+ * null when it hides nothing.
+ *
+ * The affordance is a statement about hidden content: a cell whose body
+ * is already whole on screen must not advertise a key that would show it
+ * the same thing, and a cell that already carries its own renderer cut
+ * (`└ +N earlier rows · ctrl+r`, `└ +N more · ctrl+r`) already teaches
+ * the key at the place the content stops. What is LEFT — and it is the
+ * common case — is every settled non-shell call, whose collapsed body is
+ * empty: the whole result sits behind the key with nothing on screen
+ * saying so.
+ *
+ * The count is the RESULT's own line count (the tool's truncation note
+ * included — it is a line the expand will show), never a row count and
+ * never a cap.
+ */
+function hiddenLines(c, W) {
+    if (c.expanded || c.state !== "done" || c.rolled !== null || c.reason !== null)
+        return null;
+    if (c.name === "delegate")
+        return null; // its body is the one-line summary, always whole
+    const n = countLines(c.resultText);
+    if (n === 0)
+        return null;
+    if (c.isError)
+        return null; // errorBody's own cut row is the affordance there
+    // TUI2-R1.5 ④(c) (VD-5): a settled shell renders NO body, so its whole
+    // output is behind the key exactly like every other settled call. The
+    // retired branch only claimed a suffix once the output passed the
+    // five-row cap, because below that the tail was on screen; there is no
+    // tail now, and a card hiding four lines while saying nothing is the
+    // silence TUI2-R1 (A) set out to remove.
+    return n; // every other settled call renders NO body — all of it is behind the key
+}
+/**
+ * TUI2-R1 (A) — the suffix, in the width that is LEFT.
+ *
+ * Three tiers, degrading: the full form teaches the key AND what it
+ * does, the terse form keeps the count and the key, the bare form keeps
+ * the key alone. Below that the row is left exactly as it is today — the
+ * affordance is worth a suffix, never worth cutting the path the row
+ * exists to name (invariant ① holds by construction: the tier is chosen
+ * against the room the row actually has).
+ */
+/** TUI2-R1.5 ⑤ — the cells a settled head row reserves for its
+ *  affordance: exactly the shortest tier, " · ctrl+r". The suffix used
+ *  to take whatever width happened to be left, so a long target spent it
+ *  all and the card said nothing about the lines behind the key. Every
+ *  row that fitted its head before still fits it; only a head that would
+ *  have eaten the whole row gives up its last nine cells. */
+const SUFFIX_MIN = " · ctrl+r".length;
+/**
+ * TUI2-R1.5 pin 4 — the settled head row's text, with a PINNED cut
+ * order.
+ *
+ * The row carries four things of very different value, and until now a
+ * single trailing widthCut decided between them by position: the parens
+ * came last, so the parens were what got cut. The walkthrough caught
+ * both consequences —
+ *
+ *   ✓ shell printf '…' 1 2 … 12 (exit 0 · approv… · ctrl+r
+ *   ✓ shell for i in 1 2 3 …                          … · ctrl+r
+ *
+ * — an UNCLOSED parenthesis, and a row that lost the exit code and the
+ * duration to a command string that had no claim on them. A cut that
+ * leaves `(exit 0 · approv…` has not shortened a fact, it has broken
+ * one: the reader is left holding the beginning of a sentence.
+ *
+ * The order, tightest last:
+ *   1. the affordance is already reserved by the caller (⑤);
+ *   2. the RESULT CORE — `(exit 0, 3.0s)`, `(+1 -1, 0.2s)` — renders
+ *      whole, closing paren included, or not at all;
+ *   3. the ATTRIBUTION segment drops before the core is touched: it is
+ *      a note about who decided, and the result is what happened;
+ *   4. the COMMAND/target truncates with `…`. It is the most
+ *      compressible thing on the row — a reader recognises a command
+ *      from its head — and it is the only part with a natural ellipsis.
+ */
+function settledHeadText(verbCol, target, meta, attr, elapsed, room) {
+    const core = `(${meta === "" ? "" : `${meta}, `}${elapsed}s)`;
+    const withAttr = `(${[meta, attr.replace(" · ", "")].filter((x) => x !== "").join(" · ")}${meta === "" && attr === "" ? "" : ", "}${elapsed}s)`;
+    const lead = `${verbCol} `;
+    const fit = (t, parens) => {
+        const line = `${lead}${t}${parens === "" ? "" : ` ${parens}`}`;
+        return visibleWidth(line) <= room ? line : null;
+    };
+    // 1. everything
+    const full = fit(target, withAttr);
+    if (full !== null)
+        return full;
+    // 2. the attribution gives way
+    const bare = fit(target, core);
+    if (bare !== null)
+        return bare;
+    // 3. the target truncates, the core stays whole
+    const budget = room - visibleWidth(lead) - visibleWidth(core) - 2; // the space + the ellipsis
+    if (budget >= 1)
+        return `${lead}${widthCut(target, budget)}… ${core}`;
+    // 4. below that even the core cannot ride: the row is the call's
+    //    identity and its affordance, and no half-open parenthesis.
+    return `${lead}${widthCut(target, Math.max(1, room - visibleWidth(lead)))}`;
+}
+/**
+ * TUI2-R1.5 ⑤ (VD-11) — approval attribution, about humans.
+ *
+ * A5 put the DECIDER on the settled head row to answer "why wasn't I
+ * asked". The walkthrough found the answer being given nine times in a
+ * row as `approved by mode:default` — and `mode:default` is not an
+ * answer. It is the runtime's own backfill (run.ts stamps it when no
+ * policy expressed an opinion at all), so the row was announcing the
+ * ambient default as though something had decided.
+ *
+ * The signal is inverted and reduced to the fact worth a human's eye:
+ * `decidedBy` PRESENT means a policy handled it — ambient, unremarkable,
+ * silent. `decidedBy` ABSENT means the human was asked and answered, and
+ * that is worth recording on the row: ` · approved`, ` · denied`.
+ */
+function attribution(c) {
+    if (c.verdict === null || c.verdict.decidedBy !== undefined)
+        return "";
+    return c.verdict.decision === "denied" ? " · denied" : " · approved";
+}
+export function expandSuffix(lines, room) {
+    if (lines === null)
+        return "";
+    const count = `${lines} line${lines === 1 ? "" : "s"}`;
+    for (const tier of [` · ${count} · ctrl+r expands`, ` · ${count} · ctrl+r`, " · ctrl+r"]) {
+        if (tier.length <= room)
+            return tier;
+    }
+    return "";
+}
+/** The suffix as the row's dim tail (the empty suffix leaves the row's
+ *  bytes untouched — a caller never has to branch). */
+function appendSuffix(row, suffix) {
+    if (suffix === "")
+        return row;
+    const p = palette();
+    return `${row}${p.dim}${suffix}${p.reset}`;
+}
+/**
+ * TUI2-R2 ⑤ (D, candidate 1) — the FOCUS tint.
+ *
+ * The cell the next ctrl+r will act on brightens its own `ctrl+r` token
+ * to the code tint; the rest of the suffix — the separator, the count —
+ * stays dim, because what is being marked is the KEY's target, not the
+ * row. Zero new rows, zero new columns: the affordance the cell already
+ * prints is the marker.
+ *
+ * Applied to a row rather than composed into it on purpose. The token is
+ * emitted from several places (the settled suffix, the renderer's own
+ * `└ +N … · ctrl+r` cut rows) and threading a flag through all of them
+ * would put the invariant "exactly one bright token" in as many hands as
+ * there are emitters. Here it has exactly one.
+ *
+ * NO_COLOR: p.code is empty, so the row's bytes are untouched.
+ */
+export function focusToken(row, W) {
+    const p = palette();
+    const at = row.lastIndexOf(CTRL_R);
+    if (at !== -1) {
+        // the row already names the key — brighten the token in place, and
+        // leave every other span exactly as it was
+        if (p.code === "")
+            return row;
+        return `${row.slice(0, at)}${p.code}${CTRL_R}${p.reset}${p.dim}${row.slice(at + CTRL_R.length)}`;
+    }
+    // A LIVE row does not carry the affordance today, and the live cell is
+    // the one ctrl+r takes FIRST (expandNext scans the live tail before
+    // the committed ring) — so the row the key is aimed at was the one row
+    // that never said the key existed. The affordance IS the marker here:
+    // it appears on the focused row and nowhere else, which is why no
+    // unfocused row's bytes move (every existing live-row assertion
+    // renders a cell with no focus and is untouched).
+    const room = W - visibleWidth(row);
+    if (room < SUFFIX_MIN)
+        return row; // never at the cost of invariant ①
+    return `${row}${p.dim} · ${p.reset}${p.code}${CTRL_R}${p.reset}`;
+}
+const CTRL_R = "ctrl+r";
+/** TUI2-R1 (A) — the expanded block's last row: the way back. The
+ *  rollup's expanded list carries a second clause (its members' full
+ *  outputs live in /last, which the group row cannot show). */
+const COLLAPSE_ROW = "ctrl+r collapses";
 /** W13 — the rollup opt-in table: which tools collapse, and the count
  *  NOUN (read_file calls → "5 files", list_dir → "5 dirs", search_text
  *  → "5 matches"). Only these tools opt in — a shell burst is never
@@ -457,6 +769,64 @@ export const ROLLUP_NOUN = {
     list_dir: "dirs",
     search_text: "matches",
 };
+// ---- TUI2-R1 (B): the exploration rollup ----
+/** TUI2-R1 (B) — the exploration row's nouns. Deliberately NOT
+ *  ROLLUP_NOUN: that table says what a SINGLE-tool rollup counts
+ *  ("5 matches"), and this row counts CALLS across tools, where
+ *  "14 searches" is what happened. Both tables stay — changing the
+ *  older one would move an assertion this round did not declare. */
+const EXPLORE_NOUN = {
+    read_file: ["file", "files"],
+    list_dir: ["dir", "dirs"],
+    search_text: ["search", "searches"],
+};
+/** TUI2-R1 (B) — the verb column of the expanded list names the ACT.
+ *  TUI2-R2pre ④: this used to be a private three-tool table saying the
+ *  same thing as the card head's `_file` strip, in a different way and
+ *  for a different set of tools. Both are `displayVerb` now — the whole
+ *  point of the ruling is that there is ONE answer to "what does the
+ *  screen call this". The cut note, which used to be the deliberate
+ *  exception here, moved with it (see toolCutNote). */
+/** Whether a tool joins an exploration run. Exactly the read-only set —
+ *  writes, edits, shells and extension tools never group (a burst of
+ *  side effects is a list of things that HAPPENED, and every row of it
+ *  carries meaning). */
+export function isExploreTool(name) {
+    return EXPLORE_NOUN[name] !== undefined;
+}
+/** "8 files · 14 searches" — the per-tool counts in first-call order. */
+export function exploreCounts(parts) {
+    return parts
+        .map((part) => {
+        const [singular, plural] = EXPLORE_NOUN[part.name] ?? ["call", "calls"];
+        return `${part.subjects.length} ${part.subjects.length === 1 ? singular : plural}`;
+    })
+        .join(" · ");
+}
+/** TUI2-R1 (B) — the expanded list: ONE row per tool, the verb column
+ *  then the distinct subjects in first-call order, a repeated subject
+ *  carrying its ×count, the first three shown and the rest counted.
+ *  A search's subject is its PATTERN (quoted — the thing that was
+ *  looked for); a read's or a list's is its path. */
+export function exploreRows(parts, W) {
+    const p = palette();
+    const rows = [];
+    for (const part of parts) {
+        const counts = new Map();
+        for (const s of part.subjects)
+            counts.set(s, (counts.get(s) ?? 0) + 1);
+        const shown = [...counts.entries()].slice(0, 3).map(([s, n]) => (n > 1 ? `${s} ×${n}` : s));
+        const more = counts.size > 3 ? ` (+${counts.size - 3})` : "";
+        const verb = displayVerb(part.name);
+        rows.push(cutLine(`${p.dim}${BODY_ROW}${escapeTerminal(`${verb.padEnd(6)} ${shown.join(" · ")}${more}`)}${p.reset}`, W));
+    }
+    // TUI2-R1.5 ① (VD-15): the footer used to promise "/last shows the full
+    // outputs". /last shows the LAST call only — for a nine-call burst that
+    // is one output out of nine, and a footer that sends the human to a
+    // place the content is not is worse than a footer that says nothing.
+    rows.push(cutLine(`${p.dim}${CUT_ROW}${COLLAPSE_ROW}${p.reset}`, W));
+    return rows;
+}
 /** The count term with the singular/plural forms — "no reads", "1 read",
  *  "5 reads". The noun's singular drops the plural suffix ("dirs" → "dir",
  *  "matches" → "match"). */
@@ -489,7 +859,7 @@ export function turnFold(t, W) {
             parts.push(countTerm(n, noun.endsWith("es") ? noun.slice(0, -2) : noun.slice(0, -1), noun));
         }
         else {
-            const verb = name.replace("_file", "");
+            const verb = displayVerb(name);
             parts.push(countTerm(n, verb, `${verb}s`));
         }
     }
@@ -556,19 +926,33 @@ function toolBlockBody(c, W) {
                 ? errorBody(c, W)
                 : c.name === "delegate"
                     ? delegateSettled(c, W)
-                    : c.name.startsWith("shell")
-                        ? shellTail(c.resultText, W)
-                        : []
+                    : // TUI2-R1.5 ④(c) (VD-5): a settled shell collapses like
+                        // every other settled call. It used to keep its last
+                        // rows plus a "+N earlier rows · ctrl+r" cut FOREVER —
+                        // six rows per call, so three shells owned a screen. The
+                        // approved R1 prototype's state 2 is one line; the head
+                        // row's own suffix already names the count and the key,
+                        // and ctrl+r shows the whole block, not a five-row window
+                        // of it.
+                        []
             : c.state === "running"
                 ? c.name === "delegate"
                     ? delegateRunning(c, W)
-                    : liveWindow(c.resultText, W)
+                    : c.name === "shell"
+                        ? shellLiveTail(c.resultText, W)
+                        : liveWindow(c.resultText, W)
                 : c.state === "approval"
                     ? diffBody(c.diff, W)
                     : [];
     const note = c.expanded ? null : toolCutNote(c.name, c.resultText);
     if (note !== null)
         rows.push(...foldLine(`${p.dim}${CUT_ROW}${note}${p.reset}`, W));
+    // TUI2-R1 (A): an EXPANDED block says how to put it back. The footer
+    // rides a block that HAS rows — an expanded delegate whose summary
+    // marker is missing renders nothing, and a lone footer under a head
+    // row would be an affordance for an empty block.
+    if (c.expanded && rows.length > 0)
+        rows.push(...foldLine(`${p.dim}${CUT_ROW}${COLLAPSE_ROW}${p.reset}`, W));
     blockMemo.set(c, { width: W, state, content, rows });
     return rows;
 }
@@ -639,6 +1023,49 @@ function liveWindow(text, W) {
     const cut = foldLine(`${p.dim}${CUT_ROW}+${rows.length - (CAP_LIVE_WINDOW - 1)} earlier rows · ctrl+r${p.reset}`, W);
     return [...rows.slice(rows.length - (CAP_LIVE_WINDOW - 1)), ...cut];
 }
+/**
+ * TUI2-R1 (C) — the RUNNING shell's live tail.
+ *
+ * The rows are the sidecar's last lines, NEWEST AT THE BOTTOM (a tail
+ * grows downward, and the row nearest the footer is the newest thing the
+ * command said). The window is the SAME three rows W8 fixed: two tail
+ * rows and the footer, blank-padded before the output fills them, so the
+ * block's height still changes exactly once — at settle.
+ *
+ * With nothing observed the shape is exactly today's "waiting for
+ * output": a sidecar that never appeared, a command that has not
+ * printed, and a temp dir that refused the write are indistinguishable
+ * from here, and all three mean the same thing — nothing to show.
+ *
+ * The footer names the state AND the two gestures that apply while a
+ * command runs, because this is precisely when a human wants them.
+ */
+function shellLiveTail(text, W) {
+    if (text === "")
+        return liveWindow("", W);
+    const p = palette();
+    // TUI2-R1.5 ④(b) (VD-4): the tail's first row is never a blank gutter.
+    // Two sources, both fixed here, and the W8 fixed-window height is kept
+    // by both fixes:
+    //  - leading empty lines in the sidecar (a 4096-byte tail can begin on
+    //    a line boundary, and the reader's .trimEnd only trims the other
+    //    end) are skipped;
+    //  - the short-output pad moved from the TOP to the BOTTOM. It exists
+    //    so the block's height never changes while the command runs (W8);
+    //    at the top it put an empty row above the command's very first
+    //    line, which is the frame the walkthrough filed. At the bottom the
+    //    output starts under its own header and grows downward, and the
+    //    height is just as fixed.
+    const all = blockRows(text, W);
+    const from = all.findIndex((r) => visibleWidth(r) > visibleWidth(BODY_ROW));
+    const rows = from < 0 ? [] : all.slice(from);
+    if (rows.length === 0)
+        return liveWindow("", W);
+    const kept = rows.slice(Math.max(0, rows.length - (CAP_LIVE_WINDOW - 1)));
+    while (kept.length < CAP_LIVE_WINDOW - 1)
+        kept.push(`${p.dim}${BODY_ROW}${p.reset}`);
+    return [...kept, cutLine(`${p.dim}${CUT_ROW}live tail · esc stop · alt+⏎ redirect${p.reset}`, W)];
+}
 /** W12: the delegate's child sessions collapse to the tool row plus ONE
  *  line — the height NEVER changes (running → settled replaces the row
  *  in place). The running row derives from the INPUT: the parent has no
@@ -730,14 +1157,22 @@ export function diffBody(diff, W, expanded = false) {
  *  offset=N", the output cap, list_dir's entry cap). The note reaches
  *  the MODEL and never the human — this row surfaces it. Detected in
  *  the result's TAIL (the note is appended at the end); returns null
- *  when the tool did not truncate. */
+ *  when the tool did not truncate.
+ *
+ *  TUI2-R2pre ④: the verb here is the DISPLAY one now. This row used to
+ *  be the sanctioned raw-name exception, on the reasoning that it names
+ *  the tool the model should call again — but the row is addressed to
+ *  the HUMAN (the model already has the note in its own transcript, which
+ *  is where it read it), and the ruling names this advisory family
+ *  explicitly. The `offset=N` it carries is the actionable half and is
+ *  untouched. */
 function toolCutNote(name, resultText) {
     const tail = resultText.slice(-300);
     const m = /offset=(\d+)/.exec(tail);
     if (m !== null)
-        return `capped by ${escapeTerminal(name)} · offset=${m[1]} for the rest`;
+        return `capped by ${escapeTerminal(displayVerb(name))} · offset=${m[1]} for the rest`;
     if (/…\[truncated\]/.test(tail) || /… \+?\d+ more (?:lines|entries)/.test(tail))
-        return `capped by ${escapeTerminal(name)} · /last for the rest`;
+        return `capped by ${escapeTerminal(displayVerb(name))} · /last for the rest`;
     return null;
 }
 /** The assistant body text — wrapped at W, the inline-code tint per
@@ -748,8 +1183,10 @@ class AssistantMessage {
         this.cell = cell;
     }
     render(W, _ctx) {
+        // TUI2-R1.5 9 (VD-10): the model's prose is the clearest case of
+        // text a human reads — it wraps at word boundaries.
         const text = escapeTerminal(this.cell.text);
-        const wrapped = foldLine(text, W);
+        const wrapped = foldWords(text, W);
         return wrapped.length > 0 ? wrapped.map((l) => colorInlineCode(l)) : [""];
     }
 }
@@ -760,7 +1197,8 @@ class ErrorLine {
         this.cell = cell;
     }
     render(W, _ctx) {
-        return foldLine(escapeTerminal(this.cell.text), W);
+        // TUI2-R1.5 9 (VD-10): a notice is a sentence addressed to a human.
+        return foldWords(escapeTerminal(this.cell.text), W);
     }
 }
 /** The CLI's pre-rendered blocks (the banner, the recap, slash-command
@@ -773,7 +1211,12 @@ class RawBlock {
         this.cell = cell;
     }
     render(W, _ctx) {
-        return this.cell.lines.flatMap((l) => foldLine(l, W));
+        // TUI2-R1.5 9 (VD-10): the raw channel carries BOTH kinds of text —
+        // /help's sentences and /last's verbatim tool output — so the
+        // CALLER says which it is. Verbatim is the default: a surface that
+        // has not thought about it must not have its bytes reflowed.
+        const fold = this.cell.wrap === "words" ? foldWords : foldLine;
+        return this.cell.lines.flatMap((l) => fold(l, W));
     }
 }
 /** The terminal label + the status line. W11: the rhythm gap blank is

package/dist/diff.d.ts

@@ -20,13 +20,33 @@ export interface DiffResult {
     lines: DiffLine[];
     added: number;
     removed: number;
+    /** TUI2-R1.5 ② (VD-2): the search is not in the file — the tool will
+     *  ERROR, so the panel shows the honest note carried in `lines` and
+     *  never a diff. Absent on every real diff. */
+    notFound?: true;
 }
 /** The RENDERER's truncation: head + "… N lines (/last for full)" + tail. */
 export declare function truncateDiff(diff: DiffLine[]): DiffLine[];
-/** edit_file: the search→replace windows replace in place — the changed
- *  region is KNOWN, so the diff is the old window vs the new window,
- *  context from the surrounding file. */
-export declare function editFileDiff(oldContent: string, search: string, replace: string): DiffResult;
+/** edit_file: the preview of a CHARACTER splice.
+ *
+ *  TUI2-R1.5 ② (VD-2): the locator is the tool's own, verbatim — the
+ *  workspace edit_file does `i = text.indexOf(search)` and writes
+ *  `text.slice(0, i) + replace + text.slice(i + search.length)`. This
+ *  function mirrors those two lines and diffs the result against the
+ *  original; it does not model the edit, it reproduces it.
+ *
+ *  The retired locator required the search to align to FULL LINES. A
+ *  mid-line search ("// OLD" inside "  // OLD") therefore missed, and
+ *  the miss branch rendered the WHOLE FILE as the old side: a one-line
+ *  edit was drawn as a catastrophic rewrite, on the approval panel, at
+ *  the moment a human was deciding whether to allow it. A preview that
+ *  can be that wrong is worse than no preview.
+ *
+ *  A genuine miss is now reported as a miss: the tool will return
+ *  `pattern not found in <path>` and change nothing, so the panel says
+ *  exactly that instead of inventing a diff for an edit that will not
+ *  happen. `path` names the file in that note. */
+export declare function editFileDiff(oldContent: string, search: string, replace: string, path?: string): DiffResult;
 /** write_file: a new file is all +; an existing file diffs row-level
  *  against its old content. */
 export declare function writeFileDiff(oldContent: string | null, newContent: string): DiffResult;