@vincemakes/kiso-tui-cells 0.20.0 → 0.20.2

package/dist/approval-panel.d.ts

@@ -215,9 +215,13 @@ export interface PickOption {
 export interface PickSpec {
     readonly header: string;
     readonly options: readonly PickOption[];
-    /** the `t` row \u2014 typing it directly is always available, because a
-     *  list of profiles is never the list of models that exist */
-    readonly typeHint: string;
+    /** the `t` row — typing directly. OPTIONAL, and its absence means the
+     *  option list is the WHOLE world: `/model`'s profiles never are (a
+     *  model that exists but is not configured has to be typeable), and
+     *  `/mode`'s five tiers always are. Offering a `t` row over a closed
+     *  set is a row that carries no fact — §1.3 — and it is what made
+     *  the owner read the mode panel as "type the answer". */
+    readonly typeHint?: string;
     /** shown INSTEAD of the options when there are none. The copy is the
      *  caller's and is reproduced verbatim. */
     readonly emptyNote?: string;
@@ -432,4 +436,12 @@ export declare function pickAffordance(state: PickRuntime): string;
 /** Compose a pick view. The flavor/name/title/args fields exist for the
  *  approval path and are given inert values here \u2014 the pick block
  *  reads none of them. */
+/** DC-36 — the same shell for the MODE picker.
+ *
+ *  `/model` learned to pick in TUI2-R2 ④; `/mode` never did, and the
+ *  five tiers are a CLOSED set — the one case where making a human
+ *  type the answer is least defensible. The pick block reads only
+ *  `pick` and `statusText`, so a second flavour is a name and a
+ *  fallback question, not a second mechanism. */
+export declare function modePickView(spec: PickSpec, statusText: string): PanelView;
 export declare function modelPickView(spec: PickSpec, statusText: string): PanelView;

package/dist/approval-panel.js

@@ -543,8 +543,10 @@ export function pickBlockRows(view, state, W, maxRows) {
         }
     }
     const typing = state.phase === "custom";
-    const tText = cutLine(`${typing ? p.bold : ""}${typing ? "\u2192" : " "} t ${p.reset}${p.dim}${escapeTerminal(spec.typeHint)}${p.reset}`, room);
-    rows.push(typing ? selectionBar(tText, visibleWidth(tText), W) : ` ${tText}`);
+    if (spec.typeHint !== undefined) {
+        const tText = cutLine(`${typing ? p.bold : ""}${typing ? "\u2192" : " "} t ${p.reset}${p.dim}${escapeTerminal(spec.typeHint)}${p.reset}`, room);
+        rows.push(typing ? selectionBar(tText, visibleWidth(tText), W) : ` ${tText}`);
+    }
     rows.push(`  ${p.dim}${cutLine(pickAffordance(state), room)}${p.reset}`);
     rows.push(`${p.dim}${"\u2500".repeat(Math.max(0, W))}${p.reset}`);
     return rows;
@@ -571,11 +573,36 @@ export function pickStatus(view) {
     return view.statusText;
 }
 export function pickAffordance(state) {
-    return state.phase === "custom" ? "enter commits \u00b7 esc backs out" : "digits pick \u00b7 \u23ce confirms \u00b7 esc";
+    // DC-36 — the row NAMES the arrows. TUI2-R2 ④ bound ↑↓ to the pick's
+    // cursor and the keys sheet has said `panels: ↑↓ move` ever since,
+    // but this row — the one a human is actually looking at while the
+    // panel is up — advertised only the digits. The owner read it as
+    // "type the answer", which is the same lesson DC-30 filed: a hint
+    // that omits the gesture is why the gesture goes unused.
+    return state.phase === "custom" ? "enter commits \u00b7 esc backs out" : "\u2191\u2193 move \u00b7 digits pick \u00b7 \u23ce confirms \u00b7 esc";
 }
 /** Compose a pick view. The flavor/name/title/args fields exist for the
  *  approval path and are given inert values here \u2014 the pick block
  *  reads none of them. */
+/** DC-36 — the same shell for the MODE picker.
+ *
+ *  `/model` learned to pick in TUI2-R2 ④; `/mode` never did, and the
+ *  five tiers are a CLOSED set — the one case where making a human
+ *  type the answer is least defensible. The pick block reads only
+ *  `pick` and `statusText`, so a second flavour is a name and a
+ *  fallback question, not a second mechanism. */
+export function modePickView(spec, statusText) {
+    return {
+        flavor: "simple",
+        name: "mode",
+        title: "mode",
+        speaker: "you",
+        statusText,
+        args: { kind: "text", lines: [] },
+        fallbackQuestion: "switch mode? (name) ",
+        pick: spec,
+    };
+}
 export function modelPickView(spec, statusText) {
     return {
         flavor: "simple",

package/dist/components.d.ts

@@ -508,6 +508,21 @@ export declare function formatDuration(totalSeconds: number): string;
  *  W21: the question param is gone — the old question slot retires; a
  *  pending approval's status IS the panel's (the compositor derives
  *  it from the bound panel state). */
+/** R8b — THE IDLE HINT GIVES WAY IN ORDER, and `ctrl+o` is on it.
+ *
+ *  The transcript viewer shipped in 0.19.0 and was reachable only from
+ *  the `?` sheet: not on the banner's key line, not here. A feature
+ *  whose only advertisement is a screen you have to already know to
+ *  open is DC-30's lesson pointing the other way.
+ *
+ *  It cannot simply be appended, because this hint is dropped WHOLE
+ *  when it does not fit — a longer string would take `/ commands` down
+ *  with it on a narrow terminal. So the forms are a ladder, and the
+ *  order says which affordance is least replaceable: `/ commands`
+ *  survives longest because it is the door to everything; `ctrl+o`
+ *  outranks `↑ history` because pressing up is how a person finds the
+ *  history by accident, and nothing finds ctrl+o by accident. */
+export declare function idleHint(room: number): string;
 export declare function statusLine(status: string, tail: string, W: number, hint?: string): string;
 /** The display-width prefix of a plain (SGR-free) text. W21: exported
  *  for the approval panel's option-2 rule-name cut. */

package/dist/components.js

@@ -1018,8 +1018,10 @@ export function exploreRows(parts, W) {
     // 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;
+    // R8a: the footer is an in-block note — the same indent, no glyph —
+    // and the corner opens the block's first row, like every other one.
+    rows.push(cutLine(`${p.dim}${NOTE_ROW}${COLLAPSE_ROW}${p.reset}`, W));
+    return openBlock(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",
@@ -1518,8 +1520,43 @@ const CAP_ERROR = 3; // the error text head
  *  block's body, └ the block's last row — what was cut, where the rest
  *  is — at the LEFT EDGE (the gutter column: the left edge alone
  *  distinguishes the states at --plain). Structural (constraint 1). */
-const BODY_ROW = "│ ";
+/** R8a — A TOOL BLOCK'S ROWS ARE INDENTED, NOT GUTTERED.
+ *
+ *  `│ ` on every row drew a bar down the left of every multi-row
+ *  output, which is what the owner kept pointing at. The fact the bar
+ *  carried — "these rows are the call's output, not prose" — is real
+ *  and law 1.2 requires it survive a pipe, so it moves into the
+ *  INDENT: four columns, one level deeper than the header (2) and than
+ *  prose (2). Bytes still tell them apart; no column of glyphs.
+ *
+ *  `└` survives as the mark that OPENS the block, once, on its first
+ *  row (see openBlock). In-block notes take NOTE_ROW — the same indent,
+ *  no glyph — because a second `└` inside one block would be the same
+ *  mark meaning two things (§4.1). CUT_ROW is unchanged for the
+ *  surfaces that are not a tool block: the fold row's target list, the
+ *  slot's overflow count. */
+const BODY_ROW = "    ";
+const NOTE_ROW = "    ";
 const CUT_ROW = "└ ";
+/** R8a — stamp `└` on a block's FIRST row, after every slice and note
+ *  has been assembled, so the mark is always on the first row actually
+ *  emitted rather than on one a cap may have dropped. */
+function openBlock(rows) {
+    // the corner goes on the first row that HAS something on it. A cap
+    // or a blank leading output line can put an empty row first, and a
+    // corner there would be a mark on a row with nothing to mark — law
+    // 1.3, which is the rule this whole change is serving.
+    const i = rows.findIndex((r) => visibleWidth(r) > visibleWidth(BODY_ROW));
+    if (i < 0)
+        return rows;
+    const first = rows[i];
+    const at = first.indexOf(BODY_ROW);
+    if (at < 0)
+        return rows;
+    // the corner REPLACES two of the four indent columns, so the text
+    // stays in the same column as every other row of the block.
+    return [...rows.slice(0, i), `${first.slice(0, at)}  \u2514 ${first.slice(at + BODY_ROW.length)}`, ...rows.slice(i + 1)];
+}
 const blockMemo = new WeakMap();
 /** The block's body rows below the header (memoized, W9). */
 function toolBlockBody(c, W) {
@@ -1566,15 +1603,16 @@ function toolBlockBody(c, 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));
+        rows.push(...foldLine(`${p.dim}${NOTE_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;
+        rows.push(...foldLine(`${p.dim}${NOTE_ROW}${COLLAPSE_ROW}${p.reset}`, W));
+    const opened = openBlock(rows);
+    blockMemo.set(c, { width: W, state, content, rows: opened });
+    return opened;
 }
 /** Fold result text into dim body rows (the BODY_ROW prefix): escape,
  *  split, fold each line at W−prefix; trailing empty rows (the result's
@@ -1601,7 +1639,7 @@ function shellTail(text, W) {
     if (rows.length <= CAP_SHELL_SETTLED)
         return rows;
     const kept = CAP_SHELL_SETTLED - 1;
-    const cut = foldLine(`${p.dim}${CUT_ROW}+${rows.length - kept} earlier rows · ctrl+r${p.reset}`, W);
+    const cut = foldLine(`${p.dim}${NOTE_ROW}+${rows.length - kept} earlier rows · ctrl+r${p.reset}`, W);
     return [...rows.slice(rows.length - kept), ...cut];
 }
 /** The error text head: the FIRST rows, capped at 3 — the answer is at
@@ -1621,7 +1659,7 @@ function errorBody(c, W) {
     const rows = blockRows(c.resultText.split("\n").slice(skipFirst).join("\n"), W);
     if (rows.length <= CAP_ERROR)
         return rows;
-    const cut = foldLine(`${p.dim}${CUT_ROW}+${rows.length - (CAP_ERROR - 1)} more · ctrl+r${p.reset}`, W);
+    const cut = foldLine(`${p.dim}${NOTE_ROW}+${rows.length - (CAP_ERROR - 1)} more · ctrl+r${p.reset}`, W);
     return [...rows.slice(0, CAP_ERROR - 1), ...cut];
 }
 /** The running tool's FIXED-height window (W8): exactly 3 rows from
@@ -1640,7 +1678,7 @@ function liveWindow(text, W) {
         // blanks below it — VD-4's own rule ("the output starts under its
         // own header and grows downward"), which the gutter rows used to
         // satisfy by accident and blanks made visible as a two-row gap.
-        return [`${p.dim}${CUT_ROW}waiting for output${p.reset}`, "", ""];
+        return [`${p.dim}${NOTE_ROW}waiting for output${p.reset}`, "", ""];
     }
     const rows = blockRows(text, W);
     if (rows.length <= CAP_LIVE_WINDOW) {
@@ -1648,7 +1686,7 @@ function liveWindow(text, W) {
             rows.push(""); // R7a: blank, not a bar
         return rows;
     }
-    const cut = foldLine(`${p.dim}${CUT_ROW}+${rows.length - (CAP_LIVE_WINDOW - 1)} earlier rows · ctrl+r${p.reset}`, W);
+    const cut = foldLine(`${p.dim}${NOTE_ROW}+${rows.length - (CAP_LIVE_WINDOW - 1)} earlier rows · ctrl+r${p.reset}`, W);
     return [...rows.slice(rows.length - (CAP_LIVE_WINDOW - 1)), ...cut];
 }
 /**
@@ -1692,7 +1730,7 @@ function shellLiveTail(text, W) {
     const kept = rows.slice(Math.max(0, rows.length - (CAP_LIVE_WINDOW - 1)));
     while (kept.length < CAP_LIVE_WINDOW - 1)
         kept.push(""); // R7a: blank, not a bar
-    return [...kept, cutLine(`${p.dim}${CUT_ROW}live tail · esc stop · alt+⏎ redirect${p.reset}`, W)];
+    return [...kept, cutLine(`${p.dim}${NOTE_ROW}live tail · esc stop · alt+⏎ redirect${p.reset}`, W)];
 }
 /**
  * R4 — the standing act slot.
@@ -1743,7 +1781,8 @@ export function slotTail(text, W, rows) {
     // R7a: no pad. The slot stopped padding (see slotPad) and this was
     // the same pad by another route — three blank rows under a call with
     // nothing to say yet, which is the hole a7's blank-run guard prices.
-    return body.slice(Math.max(0, body.length - rows));
+    // R8a: the corner opens whatever slice survives the cap.
+    return openBlock(body.slice(Math.max(0, body.length - rows)));
 }
 /** R4 — clamp or pad assembled slot rows to EXACTLY `rows`. The padding
  *  is what makes the slot stand; the clamp is what keeps the slot from
@@ -2000,7 +2039,11 @@ export function cutLine(line, W) {
         width += cw;
         i += 1;
     }
-    return `${out}\x1b[0m…`;
+    // R8a: the reset comes from the PALETTE, not hardcoded. `\x1b[0m`
+    // here put an escape into every cut row under NO_COLOR and behind a
+    // pipe — the one context COLOR_OFF exists to keep clean (§1.2). A
+    // coloured palette is byte-identical, because its reset IS `\x1b[0m`.
+    return `${out}${palette().reset}…`;
 }
 /** W20 — the settled block's duration, the `2h 14m` form (the task
  *  narrative's long-horizon idiom): minutes+seconds under an hour,
@@ -2085,6 +2128,33 @@ class Checklist {
  *  W21: the question param is gone — the old question slot retires; a
  *  pending approval's status IS the panel's (the compositor derives
  *  it from the bound panel state). */
+/** R8b — THE IDLE HINT GIVES WAY IN ORDER, and `ctrl+o` is on it.
+ *
+ *  The transcript viewer shipped in 0.19.0 and was reachable only from
+ *  the `?` sheet: not on the banner's key line, not here. A feature
+ *  whose only advertisement is a screen you have to already know to
+ *  open is DC-30's lesson pointing the other way.
+ *
+ *  It cannot simply be appended, because this hint is dropped WHOLE
+ *  when it does not fit — a longer string would take `/ commands` down
+ *  with it on a narrow terminal. So the forms are a ladder, and the
+ *  order says which affordance is least replaceable: `/ commands`
+ *  survives longest because it is the door to everything; `ctrl+o`
+ *  outranks `↑ history` because pressing up is how a person finds the
+ *  history by accident, and nothing finds ctrl+o by accident. */
+export function idleHint(room) {
+    // The third rung is today's hint, kept so that NO width loses
+    // something that used to fit: without it, a room of 24-30 columns
+    // fell all the way to `/ commands` even though the old form fitted.
+    // So the ladder is not a strict ranking of the three affordances —
+    // it is the widest honest form at each room, and ctrl+o is on the
+    // first two rungs rather than on all of them.
+    for (const form of [" / commands · ↑ history · ctrl+o transcript", " / commands · ctrl+o transcript", " / commands · ↑ history", " / commands"]) {
+        if (visibleWidth(form) <= room)
+            return form;
+    }
+    return "";
+}
 export function statusLine(status, tail, W, hint) {
     const p = palette();
     const text = `${status}${tail === "" ? "" : ` · ${tail}`}`;
@@ -2092,13 +2162,13 @@ export function statusLine(status, tail, W, hint) {
     // "esc to cancel" (the same one-line-bounded shape as W12's delegate
     // row; the #16g rule still cuts the HINT first, then the status with
     // a "…" — never a fold).
-    const hintText = hint ?? " / commands · ↑ history";
     const statusW = visibleWidth(text);
     if (statusW > W) {
         return `${p.dim}${widthCut(text, W - 1)}…${p.reset}`;
     }
+    const hintText = hint ?? idleHint(Math.max(0, W - statusW));
     const hintW = visibleWidth(hintText);
-    if (statusW + hintW > W)
+    if (hintW === 0 || statusW + hintW > W)
         return `${p.dim}${text}${p.reset}`;
     return `${p.dim}${text}${" ".repeat(Math.max(0, W - statusW - hintW))}${hintText}${p.reset}`;
 }

package/dist/strings.d.ts

@@ -176,6 +176,13 @@ export declare const PANEL_KEYS_ROW = "panels: \u2191\u2193 move \u00B7 \u23CE c
  * screens pretending to be one. A narrow terminal shows fewer columns
  * of the same truth, which is the honest degradation.
  */
+/** R8b — the band's own opening row: a labelled rule at full width.
+ *
+ *  Moved here from the @ picker, unchanged in every byte, because the
+ *  keys sheet needs it too and `components.ts` already imports this
+ *  module — the dependency only runs one way. `at-picker.ts` re-exports
+ *  it, so every existing import site is untouched. */
+export declare function bandHeader(label: string, W: number): string;
 export declare function keysSheetRows(W: number): string[];
 /** TUI2-R1 (D) — the keys as ONE line, for /help. The same table the
  *  sheet renders, joined — so the two can disagree only by deleting a

package/dist/strings.js

@@ -18,7 +18,7 @@
  * looked up here.
  */
 import { escapeTerminal, palette } from "./render.js";
-import { displayWidth } from "./width.js";
+import { displayWidth, visibleWidth } from "./width.js";
 /** v2a: the interactive prompt — the identity accent. readline owns the
  *  echo of what the user types; we own the prompt's color. (v2c: the
  *  readline prompt keeps "you> " — the brick ▌ is the dock's row only;
@@ -296,6 +296,27 @@ const SHEET_STOPS = [
  * screens pretending to be one. A narrow terminal shows fewer columns
  * of the same truth, which is the honest degradation.
  */
+/** R8b — the band's own opening row: a labelled rule at full width.
+ *
+ *  Moved here from the @ picker, unchanged in every byte, because the
+ *  keys sheet needs it too and `components.ts` already imports this
+ *  module — the dependency only runs one way. `at-picker.ts` re-exports
+ *  it, so every existing import site is untouched. */
+export function bandHeader(label, W) {
+    const p = palette();
+    const head = `\u2500\u2500\u2500 ${label} `;
+    const line = `${head}${"\u2500".repeat(Math.max(1, W - head.length))}`;
+    let out = "";
+    let w = 0;
+    for (const ch of line) {
+        const cw = displayWidth(ch);
+        if (w + cw > Math.max(1, W))
+            break;
+        out += ch;
+        w += cw;
+    }
+    return `${p.dim}${out}${p.reset}`;
+}
 export function keysSheetRows(W) {
     const p = palette();
     const cell = (i) => {
@@ -309,7 +330,14 @@ export function keysSheetRows(W) {
         const b = KEY_BINDINGS[i];
         return b === undefined ? "" : `${b.keys} ${b.what}`;
     };
-    const rows = [`${p.bold}keys${p.reset}`];
+    // R8b — THE SHEET NAMES ITSELF, in the band vocabulary.
+    //
+    // Every other overlay does: `─── commands ───`, `─── files ───`,
+    // `─── sessions ───`, `── transcript · N folds ──`. This one opened
+    // with a bare bold word at column 0, which is the exact condition
+    // TUI2-R1.5 ⑦(b) named when it made the rule — with scrollback
+    // behind an overlay, nothing said where the surface began.
+    const rows = [bandHeader("keys", W)];
     for (let r = 0; r < SHEET_GRID.length; r += 1) {
         const indexes = SHEET_GRID[r];
         let row = "";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tui-cells",
-	"version": "0.20.0",
+	"version": "0.20.2",
 	"description": "kiso tui-cells — the components cell renderer (components, diff, width, the render slice). Zero runtime dependencies: input is data, output is bytes.",
 	"type": "module",
 	"license": "MIT",