@vincemakes/kiso-tui-cells 0.24.5 → 0.26.0

package/dist/components.d.ts

@@ -40,18 +40,6 @@ export interface FrameCtx {
      *  the tier table reads H, so a resize RE-TIERS instead of
      *  re-folding frozen rows). */
     readonly height: number;
-    /** R7a — this cell is drawn UNDER an activity header that carries the
-     *  breathing mark, so its own head row wears a plain gutter.
-     *
-     *  The mark belongs to the ACTIVITY, not to each call in it. A
-     *  four-file burst drew four breathing marks, which is four marks
-     *  distinguishing nothing (law 1.3, the same ground R2 retired the
-     *  tick and cross on) — and worse, on a read that finishes in
-     *  200ms the mark is gone before the eye lands, so per-row it is
-     *  motion that never resolves into meaning. On the header it is lit
-     *  for the whole stretch, which is the fact it is there to carry:
-     *  work is in flight. Owner-ruled 2026-08-31. */
-    readonly grouped?: boolean;
     /** R13 E2 / DC-43 — how many PREVIEW rows a running card may take this
      *  frame. Undefined is the full window (`CAP_PREVIEW`); the compositor
      *  lowers it when the live region is tight, and 0 degrades the card to
@@ -77,7 +65,8 @@ export declare function foldLine(line: string, W: number): string[];
  *  renderer can measure without importing this module back — the
  *  re-export is verbatim, so every existing importer and the barrel see
  *  exactly what they saw. */
-export { visibleWidth } from "./width.js";
+export { visibleWidth, widthCut } from "./width.js";
+export { cutLine } from "./render.js";
 /** A component: render the display lines for one piece of state. */
 export interface Component {
     render(width: number, ctx: FrameCtx): string[];
@@ -90,7 +79,7 @@ export interface Component {
  *  `prev` is the previous sibling's OWN rows (raw — a cell's own blank
  *  must never count toward its height). The blank is a JOIN artifact:
  *  the cell's own render stays blank-free, so per-cell accounting
- *  (heights, the fold cache) never sees a fake row. */
+ *  (heights, the line cache) never sees a fake row. */
 export declare function bodySpacing(prev: readonly string[] | null, rows: readonly string[]): string[];
 /** The container — vertical concatenation with the W11 formula. No
  *  component decides its own spacing: every blank in the body is the
@@ -133,9 +122,9 @@ export type BodyCell = {
      *  rows and redraws them); a committed cell can never toggle
      *  (history is never rewritten — ADR-0046). */
     expanded: boolean;
-    /** W14: the turn boundary — the index of the turn record that
-     *  created this cell (the fold-hold's owner; −1 when no turn
-     *  exists yet — the pre-turn cells never hold). */
+    /** W14: the index of the turn record that created this cell
+     *  (−1 before the first turn). The checklist reads it: a task
+     *  list belongs to its turn. */
     turn: number;
     /** W19: a DENIED call's reason (the CLI extracted it from the
      *  result's "[Permission denied] " prefix, keyed on the "denied"
@@ -229,6 +218,24 @@ export declare function cellComponent(cell: BodyCell): Component;
  *  (the gutter's 2 cells), so a long line hard-folds INSIDE the chip
  *  and invariant ① holds on the band. */
 export declare function pendingQueueRows(lines: readonly string[], W: number): string[];
+/**
+ * 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.
+ */
 export declare function foldWords(line: string, W: number): string[];
 export declare function gutterFold(gutter: string, line: string, W: number): string[];
 /** A6: the tool-header variant — ONE cut row, never a fold. A wide
@@ -239,81 +246,7 @@ export declare function gutterFold(gutter: string, line: string, W: number): str
  *  full content. The budget: the gutter's own visible width + the
  *  ellipsis ride the row (the invariant ① cap holds). */
 export declare function gutterCut(gutter: string, line: string, W: number): string[];
-export declare function expandSuffix(lines: number | null, room: number): string;
-/**
- * TUI2-R2 ⑤ (D, candidate 1) — the FOCUS tint.
- *
- * The cell the next ctrl+o will act on brightens its own `ctrl+o` 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+o` 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.dim is empty, so the row's bytes are untouched.
- */
-export declare function focusToken(row: string, W: number): string;
-/** 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
- *  rolled up (its rows carry meaning). The folded-turn line (W14) reuses
- *  the plurals for its other-tool terms ("2 dirs", "1 match"). */
-export declare const ROLLUP_NOUN: Readonly<Record<string, string>>;
-/** 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 declare function isExploreTool(name: string): boolean;
-/** Does this tool's fold term count distinct targets rather than calls? */
-export declare function foldCountsObjects(name: string): boolean;
 export declare function foldTerms(reads: number, edits: number, others: readonly [string, number][]): string[];
-/**
- * R3i — THE STRETCH LINE: the turn's one working row, in three phases.
- *
- * A STRETCH is the run of thinking and tool calls between two blocks of
- * the model's prose. While it runs it is this line plus a bounded act
- * window; when it closes it commits as this same line, frozen, with its
- * key. The contract in one sentence: **the line you watch is the line
- * you keep** — the settle changes the mark, the tense and the key, and
- * nothing else.
- *
- *   thinking   ✧ thinking 4s
- *   acting     ✶ reading 6 files · running 4 shell commands
- *   settled    ✦ thought 9s · read 6 files · ran 4 shell commands · ctrl+o
- *
- * THE GIVE-WAY LADDER, in order, because at some width everything
- * cannot fit:
- *
- *   1. the human's WORDS (the A9 chip on a quiet turn) — they are on
- *      screen above, in the chip band;
- *   2. the NOUNS compact, cheapest word first, and stop as soon as the
- *      row fits — buying one cell must not spend every substitution;
- *   3. the COUNTS cut, with the honest "…";
- *   4. the TROUBLE CLAUSE cuts. The design first said it never gives
- *      way, and that was unimplementable: a long clause overflows after
- *      the counts have already cut to a bare "…", and invariant ①
- *      throws on that row;
- *   5. the KEY gives way NEVER. A fold with no key is the turn's work
- *      behind a line with no way back to it, which is the one thing
- *      this row must not be.
- *
- * `…` in this file means CUT HERE and nothing else — which is why the
- * live phases carry no trailing ellipsis for in-flight, though the
- * reference implementation uses one. The moving mark and the present
- * tense already say it twice.
- */
 /**
  * R3i phase 5 — THE ANSWERED QUESTION'S BLOCK.
  *
@@ -331,7 +264,7 @@ export declare function foldTerms(reads: number, edits: number, others: readonly
  * is emphasis, never information). A typed answer says `(typed)`,
  * because where an answer came from is a fact about it.
  *
- * It is WORDS, not work (law 1.7): it never folds into a stretch line,
+ * It is WORDS, not work (law 1.7): no summary ever stands for it,
  * because the one thing a summary must not do is speak for the human.
  *
  * A result that is not the ask's own JSON yields NOTHING. This renderer
@@ -339,113 +272,16 @@ export declare function foldTerms(reads: number, edits: number, others: readonly
  * would be a row the product cannot stand behind.
  */
 export declare function askedBlock(resultText: string, seconds: number, W: number): string[];
-export interface StretchTerms {
-    /** the segment's OWN measured thinking seconds; 0 drops the term */
-    readonly thoughtSeconds: number;
-    /** the segment's calls as [tool name, count], in first-call order.
-     *  Object-counting tools are deduped by target upstream (R3h). */
-    readonly calls: readonly (readonly [string, number])[];
-    /** the targets acted on — read only when the stretch made exactly
-     *  ONE call, where naming the target says everything the two rows it
-     *  replaces said (see the one-call rule below). */
-    readonly targets: readonly string[];
-    /** the trouble the stretch met: [kind, count, what it was]. */
-    readonly trouble: readonly (readonly ["failed" | "denied" | "interrupted", number, string])[];
-    /** R4 — the tool names that still have a call IN FLIGHT. The tense is
-     *  PER TERM, not per line: a stretch whose shell has finished while a
-     *  read runs says `ran 1 shell command · reading 1 file`. The whole
-     *  line used to go progressive, which the standing act slot made a
-     *  visible contradiction — the gap frame put `running npm run check`
-     *  directly above a row reading `(exit 0, 12.4s)`. Absent ⇒ every
-     *  term takes the line's own tense, which is what the settled line
-     *  wants. */
-    readonly liveNames?: readonly string[];
-    /** A9 — the human's words, on a QUIET turn's fold only. */
-    readonly words?: string;
-    /** the live mark; the caller passes the spinner's current frame. */
-    readonly mark?: string;
-}
 /** The caps — screen rows counted AFTER the fold, at the current width
  *  (the W7 table). The renderer-cut row is inside the cap. */
 /** R13 — ONE preview cap, every tool. It was the shell's alone while
  *  the shell was the only settled call with rows on screen. */
 export declare const CAP_PREVIEW = 5;
-/** DC-46 — the running window's ceiling is the SETTLED preview's, and a
- *  running card reaches it by growing rather than by being handed it.
- *  `LIVE_WINDOW` (CAP_PREVIEW + 1) retires with the allocation it sized. */
-/** The rows a card costs besides its window: two pads, the head, two
- *  blanks and the status row. Below this there is no card (DC-43). */
-export declare const CARD_CHROME = 6;
-/**
- * 0.24.2 ③ — the appended expansion, as a CARD.
- *
- * `ctrl+o` used to append bare ground under a `✦` — the turn recap's own
- * mark, one symbol for two meanings (§4.1) — in a page where every other
- * piece of machine work is a card. And it lands after the recap, so the
- * only tie to the call it came from was that mark's sentence.
- *
- * The card's head row names the call, which is the tie, so the mark is
- * not needed for it. The body is the WHOLE result: an expansion that
- * capped would be no expansion.
- *
- * Expanding IN PLACE is a different problem — committed rows are final
- * (§7.1) — and it waits for route B (DC-50).
- */
-export declare function expandedCard(verb: string, target: string, meta: string, sections: readonly string[], outcome: string, W: number): string[];
 /** 0.24.2 ② — the live region's `thinking…` placeholder: dim italic at
  *  column 2, no glyph, the SAME shape a thinking paragraph takes so that
  *  whatever arrives replaces it in place. Never committed — see the
  *  compositor's #project for why that is what makes it allowed. */
 export declare function thinkingRow(): string;
-/**
- * R4 — the standing act slot.
- *
- * The stretch's ONE line sits above it; this is the region under it,
- * and it STANDS: allocated when the stretch opens, released at the
- * fold.
- *
- * R3i built the same window INTERMITTENTLY — a running call got its
- * fixed 1+3 block (W8), a finished one got nothing — so the live
- * region's height was a function of how many calls happened to be in
- * flight this frame. Over one real stretch that is 2 rows, then 7,
- * then 2, then 17 for a three-call batch, then 2 again, and every
- * transition scrolls everything above it. The owner's report was that
- * the screen "keeps jumping", and it was an accurate description of
- * the design, not a defect in its execution.
- *
- * The cure is not a smaller window, it is a STANDING one: between two
- * calls the slot keeps the call that just finished rather than
- * collapsing, and before any call it keeps the thinking that is
- * producing them — which is R3i ruling 5 ("thinking belongs on the
- * stretch line, IN THE ACT WINDOW, and in full in expansions") finally
- * wired, since R3i stated it while building no window for the thinking
- * phase to live in.
- *
- * Four rows, deliberately the same 1+3 shape W8 gave a running call, so
- * the commonest frame — exactly one call in flight — renders byte-for-
- * byte what 0.17.0 shipped.
- */
-export declare const ACT_SLOT_ROWS = 4;
-/**
- * R4 — the slot's body rows: the tail of `text`, newest at the BOTTOM,
- * bottom-padded to exactly `rows`.
- *
- * The same dim │ gutter a running call's window uses (W2's table), and
- * the same two VD-4 rules: leading blank gutters are skipped, and the
- * short-output pad goes at the BOTTOM so output starts under its own
- * header and grows downward. The slot's CONTENTS change; its shape
- * does not.
- */
-export declare function slotTail(text: string, W: number, rows: number): string[];
-/** 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
- *  ever being the thing that trips the force-commit cap (a slot that
- *  could overflow would commit real cells to relieve blank rows). */
-export declare function slotPad(content: readonly string[], rows: number): string[];
-/** R4 — the slot's overflow row: the calls in flight beyond the head
- *  budget. It lives INSIDE the slot (it is one of the four rows), which
- *  is what keeps a parallel burst from growing the region. */
-export declare function moreRunningRow(n: number, W: number): string;
 /** The approval mini-diff (W7): capped at 12 folded rows — the head +
  *  the named middle (the renderer cut — what was cut, how to expand) +
  *  the tail. The rows are folded at the current width BEFORE the cap —
@@ -467,16 +303,6 @@ export declare function diffBody(diff: import("./diff.js").DiffLine[] | null, W:
  *  done-collapse. Every live row CUTS at W (never folds) — the block's
  *  height is its row count. */
 export declare const CAP_TASK_LIVE = 6;
-/** W20 — the live block's fixed-window row cut: an SGR-aware ONE-ROW
- *  truncation (foldLine wraps; a wrapped row would break the height
- *  cap — every live row is exactly one screen row at every width).
- *  A line that fits (≤ W) passes through whole; an overflow cuts the
- *  content at W−1 — the ellipsis's slot — and the ellipsis rides AFTER
- *  the reset (post-reset — the PTY needles' convention). The cut row
- *  never exceeds W (invariant ①). W21: exported for the approval
- *  panel's single-row lines (the rule line, the title, the divider,
- *  the options/affordance rows). */
-export declare function cutLine(line: string, W: number): string;
 /** W20 — the settled block's duration, the `2h 14m` form (the task
  *  narrative's long-horizon idiom): minutes+seconds under an hour,
  *  hours+minutes past it. */
@@ -503,11 +329,8 @@ export declare function formatDuration(totalSeconds: number): string;
  *  survives longest because it is the door to everything; `ctrl+r`
  *  outranks `↑ history` because pressing up is how a person finds the
  *  history by accident, and nothing finds ctrl+r 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. */
-export declare function widthCut(text: string, max: number): string;
+export declare function idleHint(room: number, expand?: "expand all" | "collapse all" | null): string;
+export declare function statusLine(status: string, tail: string, W: number, hint?: string, expand?: "expand all" | "collapse all" | null): string;
 /**
  * TUI2-R3v2 ① — THE selection bar. One engine, every selection surface.
  *