@vincemakes/kiso-tui-cells 0.16.2 → 0.16.3

package/dist/approval-panel.js

@@ -193,7 +193,8 @@ function panelRuleText(view) {
     const base = view.amended === true
         ? `${head}${p.dim}needs approval · (amended) — asked by${p.reset}${tail}`
         : `${head}${p.dim}needs approval — asked by${p.reset}${tail}`;
-    return hint ? `${base}${p.dim} ·${p.reset} ${p.code}${escapeTerminal(hint)}${p.reset}` : base;
+    // DC-3: the fix hint is metadata — it borrowed the inline-code tint.
+    return hint ? `${base}${p.dim} · ${escapeTerminal(hint)}${p.reset}` : base;
 }
 /**
  * TUI2-R3v2 ① — ONE ROW PER OPTION, and the cursor's row is a bar.

package/dist/components.d.ts

@@ -17,7 +17,7 @@
  * (untouched); render.ts supplies the original text (palette, escape,
  * tint, fold wording).
  */
-import { foldThinking, foldResult, renderToolSummary, type ResumeMeta } from "./render.js";
+import { foldThinking, foldResult, renderToolSummary, type ResumeMeta, type BannerMeta } from "./render.js";
 import { type MdBlock } from "./md.js";
 export { MdStream, renderBlock, renderMarkdown, type MdBlock, type MdKind } from "./md.js";
 /** The spinner glyphs, cycled by the compositor's on-demand tick. */
@@ -168,6 +168,7 @@ export type BodyCell = {
     version: string;
     extensionsText: string;
     resume: ResumeMeta[];
+    meta?: BannerMeta | undefined;
     done: true;
 } | {
     kind: "raw";
@@ -244,7 +245,7 @@ export declare function expandSuffix(lines: number | null, room: number): string
  * 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.
+ * 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
@@ -374,11 +375,21 @@ export declare function widthCut(text: string, max: number): string;
  * keeps the columns from moving as the bar walks the list.
  */
 export declare function selectionBar(styled: string, visible: number, W: number): string;
-/** W6 — the box: the chrome's top rail. The two ╌ dotted rows become
- *  a rounded box (the box already says "input lives here"); the rails
- *  stay dim, the width is still the full W (the box is a rail with
- *  corners — the menu/gap rows above and the status below are
- *  untouched). */
+/**
+ * R2 — the composer's rails, and the ONE edge vocabulary.
+ *
+ * W6 turned two ╌ dotted rows into a rounded box, reasoning that "the
+ * box already says input lives here". That is reversed here, and the
+ * reason is not taste: a rule is a DELIMITER and a box is a CONTAINER,
+ * and the screen was carrying six edge vocabularies at once (this box,
+ * the panel's │ gutter and └── tail, the diff gutter, the quote's ▏, the
+ * table's ├─┼─┤ rails, the markdown rule's ─). One dashed rule replaces
+ * the ones that separate; the │ gutter survives where it SCOPES.
+ *
+ * Row-neutral by construction: CHROME_ROWS is still 4, so every gate
+ * keyed on H − 4 is untouched, and the input row gains the two columns
+ * the walls were taking.
+ */
 export declare function boxTop(W: number): string;
 /** W6 — the box: the chrome's bottom rail. */
 export declare function boxBottom(W: number): string;

package/dist/components.js

@@ -206,22 +206,32 @@ class UserMessage {
         // was a 3000-line turn writing 260,298 bytes in one frame.
         const paras = this.cell.text.split("\n");
         let truncated = false;
+        // DC-6: the folded CONTENT first, then ONE width over all of it.
+        // The pad used to be computed per source paragraph, so a message
+        // with two lines drew as two bars of two different lengths — a
+        // ragged right edge on a block that is one block. A single
+        // paragraph was always correct, which is why it survived: the
+        // shape only appears once a message has a second line.
+        const content = [];
         for (const para of paras) {
-            if (rows.length >= USER_CHIP_ROWS) {
+            if (content.length >= USER_CHIP_ROWS) {
                 truncated = true;
                 break;
             }
-            const folded = foldLine(escapeTerminal(para), chipW);
-            const inner = Math.max(...folded.map((r) => displayWidth(r)));
-            for (const row of folded) {
-                if (rows.length >= USER_CHIP_ROWS) {
+            for (const row of foldLine(escapeTerminal(para), chipW)) {
+                if (content.length >= USER_CHIP_ROWS) {
                     truncated = true;
                     break;
                 }
-                const pad = inner - displayWidth(row);
-                rows.push(`${p.rv} ${row}${" ".repeat(pad)} ${p.rvEnd}`);
+                content.push(row);
             }
         }
+        // displayWidth stays the padding authority (never `length`): a CJK
+        // row is two cells per character and pads by cells.
+        const inner = content.length === 0 ? 0 : Math.max(...content.map((r) => displayWidth(r)));
+        for (const row of content) {
+            rows.push(`${p.rv} ${row}${" ".repeat(inner - displayWidth(row))} ${p.rvEnd}`);
+        }
         if (!truncated)
             return rows;
         // The notice is OUTSIDE the chip's reverse video, in the cut-row
@@ -758,7 +768,7 @@ function appendSuffix(row, suffix) {
  * 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.
+ * NO_COLOR: p.dim is empty, so the row's bytes are untouched.
  */
 export function focusToken(row, W) {
     const p = palette();
@@ -766,9 +776,17 @@ export function focusToken(row, W) {
     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 === "")
+        if (p.dim === "")
             return row;
-        return `${row.slice(0, at)}${p.code}${CTRL_R}${p.reset}${p.dim}${row.slice(at + CTRL_R.length)}`;
+        // DC-3: the marker takes the WASH. It used to take the inline-code
+        // tint and inherited its 1.54:1 — the cue naming the key that
+        // reveals a cell was itself the least readable thing on a white
+        // terminal. The wash is right for a second reason: this token has
+        // to be UNIQUE on the frame ("exactly one bright token"), and an
+        // attribute like bold is spent everywhere. It closes with washEnd
+        // rather than a reset, so the surrounding dim survives instead of
+        // having to be re-applied.
+        return `${row.slice(0, at)}${p.wash}${CTRL_R}${p.washEnd}${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
@@ -780,7 +798,7 @@ export function focusToken(row, W) {
     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}`;
+    return `${row}${p.dim} · ${p.reset}${p.wash}${CTRL_R}${p.washEnd}`;
 }
 const CTRL_R = "ctrl+r";
 /** TUI2-R1 (A) — the expanded block's last row: the way back. The
@@ -1270,7 +1288,7 @@ class Banner {
     }
     render(W, ctx) {
         const p = palette();
-        const rows = bannerLines(W, ctx.height, this.cell.version, this.cell.extensionsText, this.cell.resume, ctx.now);
+        const rows = bannerLines(W, ctx.height, this.cell.version, this.cell.extensionsText, this.cell.resume, ctx.now, this.cell.meta);
         return rows.map((r) => `${p.dim}${r}${p.reset}`);
     }
 }
@@ -1460,17 +1478,27 @@ export function selectionBar(styled, visible, W) {
     const inner = styled.replaceAll(p.reset, `${p.reset}${p.rv}`);
     return `${p.rv} ${inner}${" ".repeat(Math.max(0, W - visible - 2))} ${p.rvEnd}`;
 }
-/** W6 — the box: the chrome's top rail. The two ╌ dotted rows become
- *  a rounded box (the box already says "input lives here"); the rails
- *  stay dim, the width is still the full W (the box is a rail with
- *  corners — the menu/gap rows above and the status below are
- *  untouched). */
+/**
+ * R2 — the composer's rails, and the ONE edge vocabulary.
+ *
+ * W6 turned two ╌ dotted rows into a rounded box, reasoning that "the
+ * box already says input lives here". That is reversed here, and the
+ * reason is not taste: a rule is a DELIMITER and a box is a CONTAINER,
+ * and the screen was carrying six edge vocabularies at once (this box,
+ * the panel's │ gutter and └── tail, the diff gutter, the quote's ▏, the
+ * table's ├─┼─┤ rails, the markdown rule's ─). One dashed rule replaces
+ * the ones that separate; the │ gutter survives where it SCOPES.
+ *
+ * Row-neutral by construction: CHROME_ROWS is still 4, so every gate
+ * keyed on H − 4 is untouched, and the input row gains the two columns
+ * the walls were taking.
+ */
 export function boxTop(W) {
-    return `\x1b[2m╭${"─".repeat(Math.max(0, W - 2))}╮\x1b[0m`;
+    return `\x1b[2m\u256d${"\u2500".repeat(Math.max(0, W - 2))}\u256e\x1b[0m`;
 }
 /** W6 — the box: the chrome's bottom rail. */
 export function boxBottom(W) {
-    return `\x1b[2m╰${"─".repeat(Math.max(0, W - 2))}╯\x1b[0m`;
+    return `\x1b[2m\u2570${"\u2500".repeat(Math.max(0, W - 2))}\u256f\x1b[0m`;
 }
 /** The terminal label + rhythm gap (the pipe path's v2c bytes — the
  *  exact render the passthrough needs). */

package/dist/ground.d.ts

@@ -0,0 +1,46 @@
+/**
+ * DC-3 §1 — the GROUND: is the terminal light or dark.
+ *
+ * Every colour in the palette is chosen against a background, and until
+ * now kiso had no way to know what that background was: `palette()`
+ * returned one constant, its greys were picked on a dark terminal, and
+ * on a white one the inline-code token measured 1.54:1 against a 4.5:1
+ * floor (finding DC-3).
+ *
+ * This module is the answer, and it is deliberately PURE. The terminal's
+ * reply arrives as a string and the environment arrives as fields, so
+ * the whole decision is testable without a terminal and the terminal
+ * work is reduced to plumbing.
+ *
+ * `unknown` is a real answer, not a failure. It means the caller must
+ * use the mark that is correct on ANY ground — reverse video rather than
+ * a wash, the terminal's own dim rather than a chosen grey. A design
+ * that degrades is the price of never painting light-mode paint onto a
+ * dark screen.
+ */
+export type Ground = "light" | "dark" | "unknown";
+export interface Rgb {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+export declare function parseOscColor(body: string): Rgb | null;
+/** The WCAG relative luminance — the same formula the contrast ratios in
+ *  `packages/tui/design.md` §2 are computed with, so the ground and the
+ *  floor cannot drift apart. */
+export declare function relativeLuminance({ r, g, b }: Rgb): number;
+export declare function groundFrom(rgb: Rgb): Exclude<Ground, "unknown">;
+export interface GroundInputs {
+    /** KISO_THEME — an explicit answer from the human. */
+    readonly theme?: string | undefined;
+    /** The body of the terminal's OSC 11 answer, if one arrived. */
+    readonly osc?: string | undefined;
+    /** The COLORFGBG environment variable, if it is set. */
+    readonly colorfgbg?: string | undefined;
+}
+/**
+ * The ladder, first hit wins. Every rung that cannot answer falls
+ * through rather than guessing, and the bottom of the ladder is
+ * `unknown` — see the module comment for why that is a result.
+ */
+export declare function resolveGround({ theme, osc, colorfgbg }: GroundInputs): Ground;

package/dist/ground.js

@@ -0,0 +1,76 @@
+/**
+ * DC-3 §1 — the GROUND: is the terminal light or dark.
+ *
+ * Every colour in the palette is chosen against a background, and until
+ * now kiso had no way to know what that background was: `palette()`
+ * returned one constant, its greys were picked on a dark terminal, and
+ * on a white one the inline-code token measured 1.54:1 against a 4.5:1
+ * floor (finding DC-3).
+ *
+ * This module is the answer, and it is deliberately PURE. The terminal's
+ * reply arrives as a string and the environment arrives as fields, so
+ * the whole decision is testable without a terminal and the terminal
+ * work is reduced to plumbing.
+ *
+ * `unknown` is a real answer, not a failure. It means the caller must
+ * use the mark that is correct on ANY ground — reverse video rather than
+ * a wash, the terminal's own dim rather than a chosen grey. A design
+ * that degrades is the price of never painting light-mode paint onto a
+ * dark screen.
+ */
+/** `<n>;rgb:R/G/B` with 1–4 hex digits per component — the body of an
+ *  OSC 10/11 answer, already stripped of its introducer and terminator
+ *  by the editor (DC-7). Anything else is null: a guess about the
+ *  ground is worse than admitting there isn't one. */
+const OSC_RGB = /^\d+;rgb:([0-9a-f]{1,4})\/([0-9a-f]{1,4})\/([0-9a-f]{1,4})$/i;
+export function parseOscColor(body) {
+    const m = OSC_RGB.exec(body.trim());
+    if (m === null)
+        return null;
+    // a component is n hex digits of a full-scale value, so it scales by
+    // its own maximum — `f` is full white exactly as `ffff` is.
+    const comp = (h) => Math.round((Number.parseInt(h, 16) / (16 ** h.length - 1)) * 255);
+    return { r: comp(m[1]), g: comp(m[2]), b: comp(m[3]) };
+}
+/** The WCAG relative luminance — the same formula the contrast ratios in
+ *  `packages/tui/design.md` §2 are computed with, so the ground and the
+ *  floor cannot drift apart. */
+export function relativeLuminance({ r, g, b }) {
+    const lin = (v) => {
+        const c = v / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+export function groundFrom(rgb) {
+    return relativeLuminance(rgb) > 0.5 ? "light" : "dark";
+}
+/** COLORFGBG is `fg;bg` or `fg;default;bg` — the BACKGROUND is the last
+ *  field, as an ANSI index. 0–6 and 8 are the dark half of the sixteen;
+ *  7 and 9–15 are the light half. Absent on most terminals, which is why
+ *  it sits below the question kiso can actually ask. */
+function fromColorFgBg(value) {
+    const fields = value.split(";");
+    const bg = Number.parseInt(fields[fields.length - 1] ?? "", 10);
+    if (!Number.isInteger(bg) || bg < 0 || bg > 15)
+        return "unknown";
+    return bg === 7 || bg >= 9 ? "light" : "dark";
+}
+/**
+ * The ladder, first hit wins. Every rung that cannot answer falls
+ * through rather than guessing, and the bottom of the ladder is
+ * `unknown` — see the module comment for why that is a result.
+ */
+export function resolveGround({ theme, osc, colorfgbg }) {
+    const explicit = theme?.trim().toLowerCase();
+    if (explicit === "light" || explicit === "dark")
+        return explicit;
+    if (osc !== undefined && osc !== "") {
+        const rgb = parseOscColor(osc);
+        if (rgb !== null)
+            return groundFrom(rgb);
+    }
+    if (colorfgbg !== undefined && colorfgbg !== "")
+        return fromColorFgBg(colorfgbg);
+    return "unknown";
+}

package/dist/index.d.ts

@@ -14,4 +14,7 @@ export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWi
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, type TrustArtifact, } from "./strings.js";
 export { extensionsBannerText, helpRows, unansweredAskView, type BannerExtension } from "./strings.js";
 export { displayVerb } from "./strings.js";
-export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, relativeTime, renderResumeList, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, type Palette, type ResumeMeta, } from "./render.js";
+export { bannerLines, COLOR_OFF, COLOR_DARK, COLOR_LIGHT, COLOR_NEUTRAL, COLOR_ON, currentGround, setGround, escapeTerminal, foldResult, foldThinking, kUnit, palette, relativeTime, renderResumeList, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, type Palette, type ResumeMeta, } from "./render.js";
+/** DC-3 — the ground: is the terminal light or dark. Pure; see the
+ *  module comment for why `unknown` is a result and not a failure. */
+export { groundFrom, parseOscColor, relativeLuminance, resolveGround, type Ground, type GroundInputs, type Rgb } from "./ground.js";

package/dist/index.js

@@ -28,4 +28,7 @@ export { extensionsBannerText, helpRows, unansweredAskView } from "./strings.js"
 // TUI2-R2pre ④: the ONE display-verb table — the screen names the act,
 // the tool table names the call.
 export { displayVerb } from "./strings.js";
-export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, relativeTime, renderResumeList, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.js";
+export { bannerLines, COLOR_OFF, COLOR_DARK, COLOR_LIGHT, COLOR_NEUTRAL, COLOR_ON, currentGround, setGround, escapeTerminal, foldResult, foldThinking, kUnit, palette, relativeTime, renderResumeList, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.js";
+/** DC-3 — the ground: is the terminal light or dark. Pure; see the
+ *  module comment for why `unknown` is a result and not a failure. */
+export { groundFrom, parseOscColor, relativeLuminance, resolveGround } from "./ground.js";

package/dist/md.d.ts

@@ -38,7 +38,7 @@
  */
 /** The block kinds. `fence-open`/`fence-line` are separate kinds on
  *  purpose: a fence's rows must be able to freeze ONE AT A TIME. */
-export type MdKind = "para" | "heading" | "list" | "table" | "quote" | "rule" | "fence-open" | "fence-line";
+export type MdKind = "para" | "heading" | "list" | "table" | "quote" | "rule" | "fence-open" | "fence-line" | "fence-close";
 /** One block: its SOURCE lines, never a rendered form. The render is a
  *  pure function of (block, width), which is what makes the freeze
  *  property a property of the scanner alone. */

package/dist/md.js

@@ -41,6 +41,10 @@ import { breakable, charWidth, displayWidth } from "./width.js";
 import { escapeTerminal } from "./render.js";
 import { visibleWidth } from "./components.js";
 // ---- line classification -------------------------------------------
+/** E2 — the rail a fenced block is drawn with. Three backticks: what
+ *  the model wrote, and what a human gets back when they copy the block
+ *  out of the terminal. */
+const RAIL = "\u0060\u0060\u0060";
 const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
 /** ATX only, and the space is REQUIRED: `#hashtag` is prose. */
 const HEADING = /^ {0,3}(#{1,6}) +(\S.*)$/;
@@ -164,11 +168,16 @@ export class MdStream {
     }
     #line(line) {
         if (this.#fence !== null) {
-            // the closer emits no block: a bottom border is drawn only by an
-            // actual close, and under committed lines a phantom one would be
-            // a lie the force-commit path could freeze.
+            // E2: the closer emits its OWN block now. The rule it used to
+            // obey — "a bottom border is drawn only by an actual close, and
+            // under committed lines a phantom one would be a lie the
+            // force-commit path could freeze" — is UNCHANGED and is why this
+            // is safe: the rail appears here, on an actual close, and never
+            // before. An unterminated fence still draws no bottom, which is
+            // the truth about an unterminated fence.
             if (closesFence(line, this.#fence)) {
                 this.#fence = null;
+                this.#push({ kind: "fence-close", lines: [line], gap: false, lang: "" });
                 return;
             }
             this.#push({ kind: "fence-line", lines: [line], gap: false, lang: "" });
@@ -230,22 +239,38 @@ function blockBody(b, W) {
     const p = palette();
     switch (b.kind) {
         case "heading": {
-            // the marker is stripped, the numbering kept, and the levels are
-            // NOT differentiated by colour — attributes only. A `**bold**`
-            // inside a heading is therefore a no-op, which is the mono
-            // discipline paying for itself: the nested-style restore machinery
-            // both reference implementations need for this exact input has
-            // nothing to restore here.
+            // DC-4: the LEVEL is information and it used to be discarded —
+            // `#`, `##` and `###` all rendered as the same bold line, so a
+            // structured answer arrived flat. Levels are NOT differentiated
+            // by colour: 1 adds an underline, 2 is bold alone, and 3 and
+            // below print their own `###`, because attributes have run out
+            // and a marker is the only carrier that survives a pipe. A
+            // `**bold**` inside a heading is still a no-op, which is the mono
+            // discipline paying for itself.
             const m = HEADING.exec(b.lines[0] ?? "");
-            return wrap(`${p.bold}${inlineSpans(m?.[2] ?? b.lines[0] ?? "", p.bold)}${p.reset}`, W, "", "");
+            const level = (m?.[1] ?? "#").length;
+            const text = m?.[2] ?? b.lines[0] ?? "";
+            const style = level === 1 ? `${p.bold}${p.underline}` : p.bold;
+            const marker = level >= 3 ? `${"#".repeat(level)} ` : "";
+            return wrap(`${style}${marker}${inlineSpans(text, style)}${p.reset}`, W, "", "");
         }
         case "rule":
-            return [`${p.dim}${"─".repeat(Math.min(W, 28))}${p.reset}`];
+            // R2: the dashed rule, at the block's own width. The 28 was a
+            // guess that read as a short line rather than a divider, and ─
+            // belonged to the box vocabulary this round is collapsing.
+            return [`${p.dim}${"\u254c".repeat(Math.max(1, W))}${p.reset}`];
         case "fence-open":
-            // the dim gutter names the block; the language tag rides the
-            // opening row. Zero highlighting — which is exactly what makes a
-            // fence body line committable on its own.
-            return [`${p.dim}│${b.lang === "" ? "" : ` ${b.lang}`}${p.reset}`];
+            // E2: the RAIL, not a gutter. A block drawn with ``` is still a
+            // fenced block when a human selects it and pastes it somewhere
+            // else; a block drawn with a gutter is not. Zero highlighting —
+            // which is exactly what makes a fence body line committable on
+            // its own.
+            return [`${p.dim}${RAIL}${b.lang}${p.reset}`];
+        case "fence-close":
+            // only ever reached by an ACTUAL close (see MdStream#line): an
+            // unterminated fence draws no bottom, which is the truth about
+            // an unterminated fence.
+            return [`${p.dim}${RAIL}${p.reset}`];
         case "fence-line": {
             // a fence body's INDENTATION is its content. The wrapper drops
             // leading spaces \u2014 right for prose, a lie for code \u2014 so the indent
@@ -253,12 +278,21 @@ function blockBody(b, W) {
             // under it rather than returning to the gutter.
             const src = (b.lines[0] ?? "").replace(/\t/g, "    ");
             const indent = /^ */.exec(src)[0];
-            const gutter = `${p.dim}\u2502${p.reset} `;
-            return foldLineWidth(`${p.code}${src.slice(indent.length)}${p.reset}`, W - visibleWidth(gutter), indent).map((r) => `${gutter}${r}`);
+            const gutter = "  "; // E2: the rails bound the block; the body just insets
+            // DC-3: a fenced BODY carries no colour token. It used to take
+            // `code` — 1.54:1 on a white terminal, applied to whole blocks,
+            // which made the code the model just wrote the least readable
+            // thing on screen. The `│` gutter already says "this block is
+            // verbatim"; saying it twice cost legibility and bought nothing.
+            return foldLineWidth(src.slice(indent.length), W - visibleWidth(gutter), indent).map((r) => `${gutter}${r}`);
         }
         case "quote": {
             const text = b.lines.map((l) => QUOTE.exec(l)?.[1] ?? l).join(" ");
-            const gutter = `${p.dim}\u258f${p.reset} `;
+            // R2: one gutter glyph. A quote and a fenced block both say "this
+            // text is not mine", and the screen was saying it two ways — ▏
+            // here and │ for code. The fences took their own ``` rails, so │
+            // is free and the quote takes it.
+            const gutter = `${p.dim}\u2502${p.reset} `;
             return wrap(`${p.dim}${inlineSpans(text, p.dim)}${p.reset}`, W - visibleWidth(gutter), "", "").map((r) => `${gutter}${r}`);
         }
         case "list":
@@ -310,7 +344,10 @@ export function inlineSpans(text, base) {
             if (end > i) {
                 // a code span's content is LITERAL — no markers inside it mean
                 // anything, which is what makes `x | y` survive a table split
-                out += `${p.code}${text.slice(i + 1, end)}${p.reset}${base}`;
+                // DC-3: inline code is a SURFACE (`wash`), closed with washEnd
+                // rather than a reset so the span composes inside a heading's
+                // or a quote's own style.
+                out += `${p.wash}${text.slice(i + 1, end)}${p.washEnd}${base}`;
                 i = end + 1;
                 continue;
             }
@@ -456,9 +493,12 @@ function listRows(b, W) {
         }
         flush();
         const depth = Math.min(5, Math.floor(m[1].length / 2));
-        // `•` normalization for bullets; a numbered list KEEPS its numbers
-        // (they are the author's meaning, not decoration).
-        const marker = /^\d/.test(m[2]) ? `${m[2]} ` : "• ";
+        // E1: normalization stays — `-`, `*` and `+` all render as ONE
+        // marker, so the model's arbitrary choice never leaks onto the
+        // screen — but the marker is `- ` rather than `•`, so a copied list
+        // is still a list. A numbered list KEEPS its numbers (they are the
+        // author's meaning, not decoration).
+        const marker = /^\d/.test(m[2]) ? `${m[2]} ` : "- ";
         lead = `${"  ".repeat(depth + 1)}${marker}`;
         text = m[3];
     }
@@ -484,17 +524,17 @@ function tableRows(b, W) {
     if (t === null)
         return b.lines.flatMap((l) => wrap(l, W, "", ""));
     const cols = t.header.map((h, i) => Math.max(cellWidth(h), ...t.rows.map((r) => cellWidth(r[i] ?? ""))));
-    // the drawn width: one rail, then each column as "│ cell " + its pad
-    const total = cols.reduce((n, w) => n + w + 3, 1);
+    // R2: no rails. The drawn width is two columns of inset plus the
+    // columns and their two-space gutters — a table is bounded by the
+    // blank lines above and below it, exactly as every other block on the
+    // screen is, and it was the last box left on a screen that has decided
+    // not to have boxes. Alignment does the work the rails were doing, and
+    // a copied table is closer to markdown without them.
+    const total = cols.reduce((n, w) => n + w + 2, 2);
     if (total > W)
         return recordRows(t, W);
-    const rail = `${p.dim}│${p.reset}`;
-    const row = (cells, bold) => `${rail}${cells.map((c, i) => ` ${pad(c, cols[i], t.align[i], bold)} `).join(rail)}${rail}`;
-    return [
-        row(t.header, true),
-        `${p.dim}├${cols.map((w) => "─".repeat(w + 2)).join("┼")}┤${p.reset}`,
-        ...t.rows.map((r) => row(r, false)),
-    ];
+    const row = (cells, bold) => `  ${cells.map((c, i) => pad(c, cols[i], t.align[i], bold)).join("  ")}`.replace(/\s+$/, "");
+    return [row(t.header, true), ...t.rows.map((r) => row(r, false))];
 }
 /** A cell's column count: what a human sees, styling removed. */
 function cellWidth(cell) {

package/dist/render.d.ts

@@ -5,6 +5,7 @@
  * produce the bytes a human sees. Colors are raw ANSI — zero
  * dependencies (the tui-cells package has none).
  */
+import type { Ground } from "./ground.js";
 /**
  * v2a — the palette, centralized (no hard-coded codes elsewhere); v5
  * (TUI v5 #16e, the v4.1 design): the decorative blue (38;5;75) is
@@ -42,6 +43,12 @@ export interface Palette {
      *  addressed to the human. This is the ruling's own set gaining its
      *  missing member, not a fourth colour. */
     readonly warn: string;
+    /** DC-3 — RETIRED as a tint; kept as an alias of `wash` so nothing
+     *  reading it gets the old absolute grey. It was 256-colour index 252
+     *  (#d0d0d0): 1.54:1 on a white terminal, against a 4.5:1 floor, and
+     *  five call sites shared it. Inline code is a SURFACE now — never a
+     *  foreground tint, and never applied to a whole fenced block, whose
+     *  `│` gutter already says the same thing more cheaply. */
     readonly code: string;
     /** TUI2-MD (MD-1, the owner's circle) — the markdown round's ONE new
      *  member. `*italic*` needs a rendering, and under the mono discipline
@@ -53,12 +60,44 @@ export interface Palette {
      *  SGR-0 that would strand the heading's own style. */
     readonly italic: string;
     readonly italicEnd: string;
+    /** DC-4 — the heading round's ONE new member, on the italic precedent:
+     *  SGR 4 is an ATTRIBUTE, so it costs the alphabet nothing chromatic
+     *  and a terminal without underlines simply draws the text. It carries
+     *  the level-1 heading; levels 3 and below carry their own `###`,
+     *  because attributes run out and a marker survives a pipe. */
+    readonly underline: string;
+    readonly underlineEnd: string;
     readonly rv: string;
     readonly rvEnd: string;
+    /** DC-3 — the VERBATIM surface: the human's own words, and inline
+     *  code. A background, so it needs the ground; with no ground it is
+     *  reverse video, which is correct on any ground and is rung 4 of the
+     *  ladder in `ground.ts`. Closed with 49 rather than SGR 0, for the
+     *  reason `rv` is closed with 27: a washed span sits inside other
+     *  spans and must end without stranding them. */
+    readonly wash: string;
+    readonly washEnd: string;
     readonly reset: string;
 }
+/**
+ * DC-3 — one table per ground.
+ *
+ * `dim` is the same in all three ON tables and that is the point: SGR 2
+ * is an ATTRIBUTE, it dims whatever the terminal's own foreground is, so
+ * it adapts to the ground instead of asserting one. Only the background
+ * genuinely needs to know, which is why `wash` is the only member that
+ * varies.
+ */
+export declare const COLOR_NEUTRAL: Palette;
+export declare const COLOR_LIGHT: Palette;
+export declare const COLOR_DARK: Palette;
+/** The historical name — the palette for a colour TTY whose ground has
+ *  not been established. Unchanged in every byte except `code`, which
+ *  was the defect. */
 export declare const COLOR_ON: Palette;
 export declare const COLOR_OFF: Palette;
+export declare function setGround(g: Ground): void;
+export declare function currentGround(): Ground;
 export declare function palette(): Palette;
 /**
  * E group/round 8: strip terminal-injection vectors from MODEL/TOOL text before it
@@ -113,6 +152,13 @@ export declare function renderTerminalGap(statusLine: string | null): string;
  * Pure.
  */
 export declare const TAGLINE = "the coding agent that survives kill -9";
+/** R2 — what the opening knows about the session. Optional because the
+ *  off-TTY caller prints a banner before a model is bound. */
+export interface BannerMeta {
+    readonly model: string;
+    readonly mode: string;
+    readonly cwd: string;
+}
 /** v3 §01 (W1): truncate a row at `width`, marking the hidden span
  *  " (+N)". W1: the width math is the charWidth authority (the banner's
  *  brick glyphs are 1 cell — the art's 38 columns clear 40), and the
@@ -129,7 +175,7 @@ export declare function truncateRow(row: string, width: number): string;
  *  text row does not repeat the name — then extensions — then the W5
  *  resume list (BIG only, W5). Every row truncates at the terminal width
  *  with a " (+N)" marker. Pure. */
-export declare function bannerLines(W: number, H: number, version: string, extensionsText: string, resume?: readonly ResumeMeta[], now?: number): string[];
+export declare function bannerLines(W: number, H: number, version: string, extensionsText: string, resume?: readonly ResumeMeta[], now?: number, meta?: BannerMeta | undefined): string[];
 /** W5 — the opening-screen resume list. Every field already exists
  *  behind renderSessionLine / `kiso sessions`: the relative time, the
  *  title, then the right-aligned "N events · M runs". The columns are

package/dist/render.js

@@ -6,8 +6,35 @@
  * dependencies (the tui-cells package has none).
  */
 import { charWidth, displayWidth } from "./width.js";
-export const COLOR_ON = { bold: "\x1b[1m", dim: "\x1b[2m", red: "\x1b[31m", green: "\x1b[32m", warn: "\x1b[33m", code: "\x1b[38;5;252m", italic: "\x1b[3m", italicEnd: "\x1b[23m", rv: "\x1b[7m", rvEnd: "\x1b[27m", reset: "\x1b[0m" };
-export const COLOR_OFF = { bold: "", dim: "", red: "", green: "", warn: "", code: "", italic: "", italicEnd: "", rv: "", rvEnd: "", reset: "" };
+const BASE = { bold: "\x1b[1m", dim: "\x1b[2m", red: "\x1b[31m", green: "\x1b[32m", warn: "\x1b[33m", italic: "\x1b[3m", italicEnd: "\x1b[23m", underline: "\x1b[4m", underlineEnd: "\x1b[24m", rv: "\x1b[7m", rvEnd: "\x1b[27m", reset: "\x1b[0m" };
+const withWash = (wash, washEnd) => ({ ...BASE, wash, washEnd, code: wash });
+/**
+ * DC-3 — one table per ground.
+ *
+ * `dim` is the same in all three ON tables and that is the point: SGR 2
+ * is an ATTRIBUTE, it dims whatever the terminal's own foreground is, so
+ * it adapts to the ground instead of asserting one. Only the background
+ * genuinely needs to know, which is why `wash` is the only member that
+ * varies.
+ */
+export const COLOR_NEUTRAL = withWash("\x1b[7m", "\x1b[27m");
+export const COLOR_LIGHT = withWash("\x1b[48;5;255m", "\x1b[49m");
+export const COLOR_DARK = withWash("\x1b[48;5;236m", "\x1b[49m");
+/** The historical name — the palette for a colour TTY whose ground has
+ *  not been established. Unchanged in every byte except `code`, which
+ *  was the defect. */
+export const COLOR_ON = COLOR_NEUTRAL;
+export const COLOR_OFF = { bold: "", dim: "", red: "", green: "", warn: "", code: "", italic: "", italicEnd: "", underline: "", underlineEnd: "", rv: "", rvEnd: "", wash: "", washEnd: "", reset: "" };
+/** DC-3 — the resolved ground, set once at startup when the terminal
+ *  answers (see `ground.ts`). It starts UNKNOWN and may stay that way
+ *  forever; that is a supported state, not a failure. */
+let ground = "unknown";
+export function setGround(g) {
+    ground = g;
+}
+export function currentGround() {
+    return ground;
+}
 export function palette() {
     // PH-1a (finding PH-F5): the no-color.org contract is "present AND
     // non-empty" — the old `=== undefined` check let an EMPTY `NO_COLOR=`
@@ -16,7 +43,9 @@ export function palette() {
     // UI with them. The v4-round plan recorded this as debugging pitfall ①;
     // it was a bug.
     const noColor = process.env.NO_COLOR;
-    return (noColor === undefined || noColor === "") && process.stdout.isTTY ? COLOR_ON : COLOR_OFF;
+    if (!((noColor === undefined || noColor === "") && process.stdout.isTTY))
+        return COLOR_OFF;
+    return ground === "light" ? COLOR_LIGHT : ground === "dark" ? COLOR_DARK : COLOR_NEUTRAL;
 }
 /**
  * E group/round 8: strip terminal-injection vectors from MODEL/TOOL text before it
@@ -162,13 +191,30 @@ export function renderTerminalGap(statusLine) {
  * Pure.
  */
 export const TAGLINE = "the coding agent that survives kill -9";
-/** TT-1B (VD-14) — the ONE wordmark, 2 rows. The 36x6 pixel art and the
- *  3-row compact logo both retire: a tall pixel banner's mid-scroll cut
- *  state renders as glyph garbage (VD-14 — frames 03/04/s2-05 of the
- *  2026-08-17 walkthrough), inherent to the height. This is the compact
- *  font with its base row folded into lower half-blocks — same alphabet,
- *  15 columns, and the cut window shrinks to nothing a reader catches. */
-const WORDMARK_ROWS = ["█ █ ▀█▀ █▀▀ █▀█", "█▀▄ ▄█▄ ▄▄█ █▄█"];
+/**
+ * R2 — the wordmark is retired (2026-08-27, the nineteen-screen review).
+ *
+ * TT-1B had already cut the 36x6 pixel art down to two rows because a
+ * tall banner's mid-scroll cut state renders as glyph garbage. The
+ * remaining two rows go now for a different reason: they say the word
+ * `kiso` in fifteen columns of block glyphs, and the word `kiso` says it
+ * in four. A rendered clover mark was tried first, at 4x2, 10x5, 14x7
+ * and 16x8, and rejected on measurement — below fourteen columns the
+ * centre star closes and the mark reads as a domino, and at fourteen it
+ * costs seven rows.
+ *
+ * What takes the room is not decoration. A first screen is asked three
+ * questions — what model, where am I, what is loaded — and it now
+ * answers them in one aligned column.
+ */
+/** R2 — the keys a first screen teaches. One dim row, and deliberately
+ *  NOT derived from KEY_BINDINGS: the sheet is the complete list and
+ *  this is the opening's five, chosen rather than generated. */
+const BANNER_KEYS = "esc interrupt · ctrl+c exit · / commands · ! bash · ctrl+r expand";
+/** R2 — the labels. Uppercase mono, dim, letter-spaced by the column
+ *  rather than by SGR: they mark sections and are never content. */
+const BANNER_LABELS = ["MODEL", "WORKSPACE", "EXTENSIONS"];
+const LABEL_STOP = Math.max(...BANNER_LABELS.map((l) => l.length)) + 2;
 /** v3 §01 (W1): truncate a row at `width`, marking the hidden span
  *  " (+N)". W1: the width math is the charWidth authority (the banner's
  *  brick glyphs are 1 cell — the art's 38 columns clear 40), and the
@@ -209,17 +255,45 @@ export function truncateRow(row, width) {
  *  text row does not repeat the name — then extensions — then the W5
  *  resume list (BIG only, W5). Every row truncates at the terminal width
  *  with a " (+N)" marker. Pure. */
-export function bannerLines(W, H, version, extensionsText, resume = [], now = Date.now()) {
-    const rows = [];
-    if (W >= 40 && H >= 14) {
-        for (const r of WORDMARK_ROWS)
-            rows.push(truncateRow(`  ${r}`, W));
+export function bannerLines(W, H, version, extensionsText, resume = [], now = Date.now(), meta) {
+    const rows = [truncateRow(`kiso ${version}`, W)];
+    const facts = [];
+    if (meta !== undefined) {
+        facts.push([BANNER_LABELS[0], `${meta.model}${meta.mode === "" ? "" : ` · ${meta.mode}`}`], [BANNER_LABELS[1], meta.cwd]);
     }
-    if (rows.length > 0)
-        rows.push("");
-    rows.push(truncateRow(`v${version} — ${TAGLINE}`, W));
     if (extensionsText !== "")
-        rows.push(truncateRow(extensionsText, W));
+        facts.push([BANNER_LABELS[2], extensionsText]);
+    if (facts.length > 0) {
+        rows.push("");
+        // The value column HANGS rather than truncating. The label costs
+        // columns the value used to have, and an extension list cut at the
+        // width would hide which extensions loaded — on the one screen whose
+        // job is to say what is loaded. Words wrap; a word longer than the
+        // column still truncates, with truncateRow's honest marker.
+        const room = Math.max(8, W - 2 - LABEL_STOP);
+        for (const [label, value] of facts) {
+            const lead = `  ${label}${" ".repeat(LABEL_STOP - label.length)}`;
+            const hang = " ".repeat(displayWidth(lead));
+            let line = "";
+            const out = [];
+            for (const word of value.split(" ")) {
+                if (line === "")
+                    line = word;
+                else if (displayWidth(`${line} ${word}`) <= room)
+                    line += ` ${word}`;
+                else {
+                    out.push(line);
+                    line = word;
+                }
+            }
+            if (line !== "")
+                out.push(line);
+            for (const [i, l] of out.entries())
+                rows.push(truncateRow(`${i === 0 ? lead : hang}${l}`, W));
+        }
+    }
+    if (meta !== undefined && W >= 40)
+        rows.push("", truncateRow(`  ${BANNER_KEYS}`, W));
     if (W >= 40 && H >= 20 && resume.length > 0) {
         rows.push("", ...renderResumeList(resume, W, now));
     }

package/dist/strings.js

@@ -276,7 +276,10 @@ export function keysSheetRows(W) {
     const p = palette();
     const cell = (i) => {
         const b = KEY_BINDINGS[i];
-        return b === undefined ? "" : `${p.code}${b.keys}${p.reset} ${b.what}`;
+        // DC-3: the key NAMES are the sheet's content, not a code span —
+        // they borrowed the inline-code tint and became the least readable
+        // thing on the one screen whose whole job is being read.
+        return b === undefined ? "" : `${p.bold}${b.keys}${p.reset} ${b.what}`;
     };
     const plainCell = (i) => {
         const b = KEY_BINDINGS[i];
@@ -299,13 +302,40 @@ export function keysSheetRows(W) {
         }
         rows.push(row);
     }
-    rows.push(`${p.dim}${PANEL_KEYS_ROW}${p.reset}`);
+    rows.push(`${p.dim}${panelKeysRow(W)}${p.reset}`);
     return rows.map((row) => cutRow(row, W));
 }
+/**
+ * DC-2 — the panel row degrades by CLAUSE.
+ *
+ * The row is 76 columns of independent clauses joined by ` · `. At 72 it
+ * used to lose the tail of the last one, so `t types` became `t`: the
+ * reader was told a key existed and not told what it did, on a row that
+ * still looked complete. Dropping a whole clause says less; it never
+ * says something false. `cutRow`'s ellipsis is the floor below this, for
+ * a width that cannot hold even the first clause.
+ */
+function panelKeysRow(W) {
+    const clauses = PANEL_KEYS_ROW.split(" \u00b7 ");
+    for (let n = clauses.length; n > 1; n -= 1) {
+        const row = clauses.slice(0, n).join(" \u00b7 ");
+        if (displayWidth(row) <= W)
+            return row;
+    }
+    return clauses[0];
+}
 /** One row, cut at the width — SGR-aware, the ellipsis after the reset
  *  (the cutLine convention; duplicated here rather than imported so the
  *  strings module keeps its no-components-dependency shape). */
 function cutRow(row, W) {
+    // DC-2: a cut is MARKED. This returned the surviving prefix with
+    // nothing to say it was a prefix, so a row that had lost its tail read
+    // as a whole row — the one thing the tree's own fold rule forbids
+    // ("the honest …, never a silent truncate"). The mark costs a column,
+    // so the cut lands one column earlier to pay for it.
+    if (displayWidth(row.replace(/\x1b\[[0-9;]*m/g, "")) <= W)
+        return row;
+    const limit = Math.max(0, W - 1);
     let out = "";
     let width = 0;
     for (let i = 0; i < row.length;) {
@@ -316,13 +346,13 @@ function cutRow(row, W) {
             continue;
         }
         const cw = displayWidth(row[i]);
-        if (width + cw > W)
-            return `${out}${palette().reset}`;
+        if (width + cw > limit)
+            break;
         out += row[i];
         width += cw;
         i += 1;
     }
-    return out;
+    return `${out}${palette().reset}\u2026`;
 }
 /** 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
@@ -343,24 +373,38 @@ export function keysHelpRow() {
  */
 export function helpRows() {
     const p = palette();
-    const cmd = (name, desc) => `${p.bold}${name}${p.reset}    ${desc}`;
-    return [
-        cmd("/help", "print this list of commands"),
-        cmd("/think", "show the last full thinking block"),
-        cmd("/last", "show the most recent tool call's input and output"),
-        cmd("/status", "show session id, event count, and context estimate"),
-        cmd("/mode", "show the approval tier; /mode <name> switches (manual/default/accept-edits/plan/bypass)"),
-        cmd("/model", "list model profiles; /model <name|provider/model> switches"),
-        cmd("/compact", "summarize the older conversation to free context"),
-        cmd("/clear", "start a fresh conversation (the old session stays resumable)"),
-        cmd("/resume", "switch to another session; /resume <id> goes directly"),
-        // TUI2-R1 (D): DELIBERATELY UNCHANGED. Deriving this sentence from
-        // KEY_BINDINGS would be an improvement and it would also move an
-        // assertion outside the round's two declared supersession classes,
-        // so the sheet is the derived surface and this row keeps its bytes.
-        // `keysHelpRow()` exists for the round that is allowed to make the
-        // swap; until then the drift guard is the test that every binding
-        // in the table is mentioned here.
-        `${cmd("exit", "leave the session")}\n${cmd("keys", "enter sends · ctrl+J newline (shift+enter where encoded) · esc stops the run · alt+⏎ stops it and sends this instead · @ files · 1-4 answers an ask")}`,
+    // DC-1: ONE description column. The gap used to be four spaces after
+    // the name whatever the name's length, so `/help`'s description began
+    // three columns left of `/compact`'s and the second column wandered
+    // down the list. displayWidth is the authority, as everywhere else.
+    const table = [
+        ["/help", "print this list of commands"],
+        ["/think", "show the last full thinking block"],
+        ["/last", "show the most recent tool call's input and output"],
+        ["/status", "show session id, event count, and context estimate"],
+        ["/mode", "show the approval tier; /mode <name> switches (manual/default/accept-edits/plan/bypass)"],
+        ["/model", "list model profiles; /model <name|provider/model> switches"],
+        ["/compact", "summarize the older conversation to free context"],
+        ["/clear", "start a fresh conversation (the old session stays resumable)"],
+        ["/resume", "switch to another session; /resume <id> goes directly"],
+        ["exit", "leave the session"],
+        // TUI2-R1 (D): the SENTENCE is deliberately unchanged. Deriving it
+        // from KEY_BINDINGS would be an improvement and it would also move
+        // an assertion outside the round's declared supersession classes,
+        // so the sheet stays the derived surface and this row keeps its
+        // words. `keysHelpRow()` exists for the round allowed to swap it;
+        // until then the drift guard is the test that every binding in the
+        // table is mentioned here. DC-1 changes the PADDING, not the words.
+        ["keys", "enter sends \u00b7 ctrl+J newline (shift+enter where encoded) \u00b7 esc stops the run \u00b7 alt+\u23ce stops it and sends this instead \u00b7 @ files \u00b7 1-4 answers an ask"],
     ];
+    const stop = Math.max(...table.map(([name]) => displayWidth(name))) + 4;
+    const cmd = (name, desc) => `${p.bold}${name}${p.reset}${" ".repeat(stop - displayWidth(name))}${desc}`;
+    const rows = table.slice(0, -2).map(([name, desc]) => cmd(name, desc));
+    // the last call carries its own newline exactly as it did inline:
+    // bodyLog splits on \n, so `exit` and `keys` land as two rows from one
+    // call — the shape the KC1/KC2/KC3 gestures were added to, unchanged.
+    const [exitName, exitDesc] = table[table.length - 2];
+    const [keysName, keysDesc] = table[table.length - 1];
+    rows.push(`${cmd(exitName, exitDesc)}\n${cmd(keysName, keysDesc)}`);
+    return rows;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@vincemakes/kiso-tui-cells",
-	"version": "0.16.2",
-	"description": "kiso tui-cells \u2014 the components cell renderer (components, diff, width, the render slice). Zero runtime dependencies: input is data, output is bytes.",
+	"version": "0.16.3",
+	"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",
 	"exports": {